PolygonStaker
polygon/src.PolygonStaker
Table of contents
Constructors
Methods
Constructors
constructor
• new PolygonStaker(params): PolygonStaker
Creates a PolygonStaker instance
Parameters
Returns
An instance of PolygonStaker
Methods
getAddressDerivationFn
▸ getAddressDerivationFn(): (publicKey: Uint8Array) => Promise<string[]>
This static method is used to derive an address from a public key.
It can be used for signer initialization, e.g. FireblocksSigner or LocalSigner.
Returns
fn
Returns an array containing the derived address.
▸ (publicKey): Promise<string[]>
Parameters
publicKey
Uint8Array
Returns
Promise<string[]>
init
▸ init(): Promise<void>
Returns
Promise<void>
Deprecated
No longer required. Kept for backward compatibility.
buildApproveTx
▸ buildApproveTx(params): Promise<{ tx: Transaction }>
Builds a token approval transaction
Approves the StakeManager contract to spend POL tokens on behalf of the delegator. This must be called before staking if the current allowance is insufficient.
Parameters
params
Object
Parameters for building the transaction
params.amount
string
The amount to approve in POL (will be converted to wei internally). Pass "max" for unlimited approval.
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to an approval transaction
buildStakeTx
▸ buildStakeTx(params): Promise<{ tx: Transaction }>
Builds a staking (delegation) transaction
Delegates POL tokens to a validator via their ValidatorShare contract. Requires prior token approval to the StakeManager contract.
Parameters
params
Object
Parameters for building the transaction
params.delegatorAddress
`0x${string}`
The delegator's Ethereum address
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.amount
string
The amount to stake in POL
params.slippageBps?
number
(Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
params.minSharesToMint?
bigint
(Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
params.referrer?
string
(Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to a Polygon staking transaction
buildUnstakeTx
▸ buildUnstakeTx(params): Promise<{ tx: Transaction }>
Builds an unstaking transaction
Creates an unbond request to unstake POL tokens from a validator. After the unbonding period (~80 checkpoints, approximately 3-4 days), call buildWithdrawTx() to claim funds.
Parameters
params
Object
Parameters for building the transaction
params.delegatorAddress
`0x${string}`
The delegator's address
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.amount
string
The amount to unstake in POL (will be converted to wei internally)
params.slippageBps?
number
(Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
params.maximumSharesToBurn?
bigint
(Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
params.referrer?
string
(Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to a Polygon unstaking transaction
buildWithdrawTx
▸ buildWithdrawTx(params): Promise<{ tx: Transaction }>
Builds a withdraw transaction
Claims unstaked POL tokens after the unbonding period has elapsed. Use getUnbond() to check if the unbonding period is complete.
Note: Each unstake creates a separate unbond with its own nonce (1, 2, 3, etc.). Withdrawals must be done per-nonce. To withdraw all pending unbonds, iterate through nonces from 1 to getUnbondNonce() and withdraw each eligible one.
Parameters
params
Object
Parameters for building the transaction
params.delegatorAddress
`0x${string}`
The delegator's address that will receive the funds
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.unbondNonce
bigint
The specific unbond nonce to withdraw
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to a Polygon withdrawal transaction
buildClaimRewardsTx
▸ buildClaimRewardsTx(params): Promise<{ tx: Transaction }>
Builds a claim rewards transaction
Claims accumulated delegation rewards and sends them to the delegator's wallet.
Parameters
params
Object
Parameters for building the transaction
params.delegatorAddress
`0x${string}`
The delegator's address that will receive the rewards
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.referrer?
string
(Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to a Polygon claim rewards transaction
buildCompoundTx
▸ buildCompoundTx(params): Promise<{ tx: Transaction }>
Builds a compound (restake) rewards transaction
Restakes accumulated rewards back into the validator, increasing delegation without new tokens.
Parameters
params
Object
Parameters for building the transaction
params.delegatorAddress
`0x${string}`
The delegator's address
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.referrer?
string
(Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
Returns
Promise<{ tx: Transaction }>
Returns a promise that resolves to a Polygon compound transaction
getStake
▸ getStake(params): Promise<StakeInfo>
Retrieves the delegator's staking information for a specific validator
Parameters
params
Object
Parameters for the query
params.delegatorAddress
`0x${string}`
Ethereum address of the delegator
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
Returns
Promise<StakeInfo>
Promise resolving to stake information:
balance: Total staked amount formatted in POL
shares: Total shares held by the delegator
exchangeRate: Current exchange rate between shares and POL
getUnbondNonce
▸ getUnbondNonce(params): Promise<bigint>
Retrieves the latest unbond nonce for a delegator
Each unstake operation creates a new unbond request with an incrementing nonce. Nonces start at 1 and increment with each unstake. Note: a nonce having existed does not mean it is still pending — claimed unbonds are deleted, but the counter is never decremented.
Parameters
params
Object
Parameters for the query
params.delegatorAddress
`0x${string}`
Ethereum address of the delegator
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
Returns
Promise<bigint>
Promise resolving to the latest unbond nonce (0n if no unstakes performed)
getUnbond
▸ getUnbond(params): Promise<UnbondInfo>
Retrieves unbond request information for a specific nonce
Use this to check the status of individual unbond requests. For fetching multiple unbonds efficiently, use getUnbonds() instead.
Parameters
params
Object
Parameters for the query
params.delegatorAddress
`0x${string}`
Ethereum address of the delegator
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.unbondNonce
bigint
The specific unbond nonce to query (1, 2, 3, etc.)
Returns
Promise<UnbondInfo>
Promise resolving to unbond information:
amount: Amount pending unbonding in POL
isWithdrawable: Whether the unbond can be withdrawn now
shares: Shares amount pending unbonding (0n if already withdrawn or doesn't exist)
withdrawEpoch: Epoch number when the unbond started
getUnbonds
▸ getUnbonds(params): Promise<UnbondInfo[]>
Retrieves unbond request information for multiple nonces efficiently
This method batches all contract reads into a single RPC call, making it much more efficient than calling getUnbond() multiple times.
Parameters
params
Object
Parameters for the query
params.delegatorAddress
`0x${string}`
Ethereum address of the delegator
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
params.unbondNonces
bigint[]
Array of unbond nonces to query (1, 2, 3, etc.)
Returns
Promise<UnbondInfo[]>
Promise resolving to array of unbond information (same order as input nonces)
getLiquidRewards
▸ getLiquidRewards(params): Promise<string>
Retrieves pending liquid rewards for a delegator
Parameters
params
Object
Parameters for the query
params.delegatorAddress
`0x${string}`
Ethereum address of the delegator
params.validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
Returns
Promise<string>
Promise resolving to the pending rewards in POL
getAllowance
▸ getAllowance(ownerAddress): Promise<string>
Retrieves the current POL allowance for the StakeManager contract
Parameters
ownerAddress
`0x${string}`
The token owner's address
Returns
Promise<string>
Promise resolving to the current allowance in POL
getEpoch
▸ getEpoch(): Promise<bigint>
Retrieves the current checkpoint epoch from the StakeManager
Returns
Promise<bigint>
Promise resolving to the current epoch number
getWithdrawalDelay
▸ getWithdrawalDelay(): Promise<bigint>
Retrieves the withdrawal delay from the StakeManager
The withdrawal delay is the number of epochs that must pass after an unbond request before the funds can be withdrawn (~80 checkpoints, approximately 3-4 days).
Returns
Promise<bigint>
Promise resolving to the withdrawal delay in epochs
getExchangeRatePrecision
▸ getExchangeRatePrecision(validatorShareAddress): Promise<bigint>
Retrieves the exchange rate precision for a validator
Foundation validators (ID < 8) use precision of 100, others use 10^29.
Parameters
validatorShareAddress
`0x${string}`
The validator's ValidatorShare contract address
Returns
Promise<bigint>
Promise resolving to the precision constant
sign
▸ sign(params): Promise<{ signedTx: `0x${string}` }>
Signs a transaction using the provided signer.
Parameters
params
Object
Parameters for the signing process
params.signer
Signer
A signer instance
params.signerAddress
`0x${string}`
The address of the signer
params.baseFeeMultiplier?
number
(Optional) The multiplier for fees, which is used to manage fee fluctuations, is applied to the base fee per gas from the latest block to determine the final maxFeePerGas. The default value is 1.2
params.defaultPriorityFee?
string
(Optional) This overrides the maxPriorityFeePerGas estimated by the RPC
Returns
Promise<{ signedTx: `0x${string}` }>
A promise that resolves to an object containing the signed transaction
broadcast
▸ broadcast(params): Promise<{ txHash: `0x${string}` }>
Broadcasts a signed transaction to the network.
Parameters
params
Object
Parameters for the broadcast process
params.signedTx
`0x${string}`
The signed transaction to broadcast
Returns
Promise<{ txHash: `0x${string}` }>
A promise that resolves to the transaction hash
getTxStatus
▸ getTxStatus(params): Promise<PolygonTxStatus>
Retrieves the status of a transaction using the transaction hash.
Parameters
params
Object
Parameters for the transaction status request
params.txHash
`0x${string}`
The transaction hash to query
Returns
Promise<PolygonTxStatus>
A promise that resolves to an object containing the transaction status
Last updated
Was this helpful?