@chorus-one/polygon 1.0.0

package/dist/cjs/staker.d.ts

@@ -0,0 +1,335 @@
+import { type Address, type Hex } from 'viem';
+import type { Signer } from '@chorus-one/signer';
+import type { Transaction, PolygonNetworkConfig, PolygonTxStatus, StakeInfo, UnbondInfo } from './types';
+export declare class PolygonStaker {
+    private readonly rpcUrl?;
+    private readonly contracts;
+    private readonly publicClient;
+    private readonly chain;
+    private withdrawalDelayCache;
+    private readonly validatorPrecisionCache;
+    /**
+     * 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 Returns an array containing the derived address.
+     */
+    static getAddressDerivationFn: () => (publicKey: Uint8Array) => Promise<Array<string>>;
+    /**
+     * Creates a PolygonStaker instance
+     *
+     * @param params - Initialization configuration
+     * @param params.network - Network to use: 'mainnet' (Ethereum L1) or 'testnet' (Sepolia L1)
+     * @param params.rpcUrl - Optional RPC endpoint URL override. If not provided, uses viem's default for the network.
+     *
+     * @returns An instance of PolygonStaker
+     */
+    constructor(params: PolygonNetworkConfig);
+    /** @deprecated No longer required. Kept for backward compatibility. */
+    init(): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.amount - The amount to approve in POL (will be converted to wei internally). Pass "max" for unlimited approval.
+     *
+     * @returns Returns a promise that resolves to an approval transaction
+     */
+    buildApproveTx(params: {
+        amount: string;
+    }): 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.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.delegatorAddress - The delegator's Ethereum address
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.amount - The amount to stake in POL
+     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
+     * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+     * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
+     *
+     * @returns Returns a promise that resolves to a Polygon staking transaction
+     */
+    buildStakeTx(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        amount: string;
+        slippageBps?: number;
+        minSharesToMint?: bigint;
+        referrer?: string;
+    }): 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.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.delegatorAddress - The delegator's address
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
+     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
+     * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+     * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
+     *
+     * @returns Returns a promise that resolves to a Polygon unstaking transaction
+     */
+    buildUnstakeTx(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        amount: string;
+        slippageBps?: number;
+        maximumSharesToBurn?: bigint;
+        referrer?: string;
+    }): 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.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.delegatorAddress - The delegator's address that will receive the funds
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.unbondNonce - The specific unbond nonce to withdraw
+     *
+     * @returns Returns a promise that resolves to a Polygon withdrawal transaction
+     */
+    buildWithdrawTx(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        unbondNonce: bigint;
+    }): Promise<{
+        tx: Transaction;
+    }>;
+    /**
+     * Builds a claim rewards transaction
+     *
+     * Claims accumulated delegation rewards and sends them to the delegator's wallet.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.delegatorAddress - The delegator's address that will receive the rewards
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
+     *
+     * @returns Returns a promise that resolves to a Polygon claim rewards transaction
+     */
+    buildClaimRewardsTx(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        referrer?: string;
+    }): Promise<{
+        tx: Transaction;
+    }>;
+    /**
+     * Builds a compound (restake) rewards transaction
+     *
+     * Restakes accumulated rewards back into the validator, increasing delegation without new tokens.
+     *
+     * @param params - Parameters for building the transaction
+     * @param params.delegatorAddress - The delegator's address
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
+     *
+     * @returns Returns a promise that resolves to a Polygon compound transaction
+     */
+    buildCompoundTx(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        referrer?: string;
+    }): Promise<{
+        tx: Transaction;
+    }>;
+    /**
+     * Retrieves the delegator's staking information for a specific validator
+     *
+     * @param params - Parameters for the query
+     * @param params.delegatorAddress - Ethereum address of the delegator
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     *
+     * @returns 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
+     */
+    getStake(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+    }): Promise<StakeInfo>;
+    /**
+     * 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.
+     *
+     * @param params - Parameters for the query
+     * @param params.delegatorAddress - Ethereum address of the delegator
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     *
+     * @returns Promise resolving to the latest unbond nonce (0n if no unstakes performed)
+     */
+    getUnbondNonce(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+    }): Promise<bigint>;
+    /**
+     * 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.
+     *
+     * @param params - Parameters for the query
+     * @param params.delegatorAddress - Ethereum address of the delegator
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.unbondNonce - The specific unbond nonce to query (1, 2, 3, etc.)
+     *
+     * @returns 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
+     */
+    getUnbond(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        unbondNonce: bigint;
+    }): 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.
+     *
+     * @param params - Parameters for the query
+     * @param params.delegatorAddress - Ethereum address of the delegator
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     * @param params.unbondNonces - Array of unbond nonces to query (1, 2, 3, etc.)
+     *
+     * @returns Promise resolving to array of unbond information (same order as input nonces)
+     */
+    getUnbonds(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+        unbondNonces: bigint[];
+    }): Promise<UnbondInfo[]>;
+    /**
+     * Retrieves pending liquid rewards for a delegator
+     *
+     * @param params - Parameters for the query
+     * @param params.delegatorAddress - Ethereum address of the delegator
+     * @param params.validatorShareAddress - The validator's ValidatorShare contract address
+     *
+     * @returns Promise resolving to the pending rewards in POL
+     */
+    getLiquidRewards(params: {
+        delegatorAddress: Address;
+        validatorShareAddress: Address;
+    }): Promise<string>;
+    /**
+     * Retrieves the current POL allowance for the StakeManager contract
+     *
+     * @param ownerAddress - The token owner's address
+     *
+     * @returns Promise resolving to the current allowance in POL
+     */
+    getAllowance(ownerAddress: Address): Promise<string>;
+    /**
+     * Retrieves the current checkpoint epoch from the StakeManager
+     *
+     * @returns Promise resolving to the current epoch number
+     */
+    getEpoch(): 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 resolving to the withdrawal delay in epochs
+     */
+    getWithdrawalDelay(): Promise<bigint>;
+    /**
+     * Retrieves the exchange rate precision for a validator
+     *
+     * Foundation validators (ID < 8) use precision of 100, others use 10^29.
+     *
+     * @param validatorShareAddress - The validator's ValidatorShare contract address
+     *
+     * @returns Promise resolving to the precision constant
+     */
+    getExchangeRatePrecision(validatorShareAddress: Address): Promise<bigint>;
+    /**
+     * Retrieves the current exchange rate for a validator
+     *
+     * @param validatorShareAddress - The validator's ValidatorShare contract address
+     *
+     * @returns Promise resolving to the exchange rate
+     */
+    private getExchangeRate;
+    /**
+     * Signs a transaction using the provided signer.
+     *
+     * @param params - Parameters for the signing process
+     * @param params.signer - A signer instance
+     * @param params.signerAddress - The address of the signer
+     * @param params.tx - The transaction to sign
+     * @param params.baseFeeMultiplier - (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
+     * @param params.defaultPriorityFee - (Optional) This overrides the `maxPriorityFeePerGas` estimated by the RPC
+     *
+     * @returns A promise that resolves to an object containing the signed transaction
+     */
+    sign(params: {
+        signer: Signer;
+        signerAddress: Address;
+        tx: Transaction;
+        baseFeeMultiplier?: number;
+        defaultPriorityFee?: string;
+    }): Promise<{
+        signedTx: Hex;
+    }>;
+    /**
+     * Broadcasts a signed transaction to the network.
+     *
+     * @param params - Parameters for the broadcast process
+     * @param params.signedTx - The signed transaction to broadcast
+     *
+     * @returns A promise that resolves to the transaction hash
+     */
+    broadcast(params: {
+        signedTx: Hex;
+    }): Promise<{
+        txHash: Hex;
+    }>;
+    /**
+     * Retrieves the status of a transaction using the transaction hash.
+     *
+     * @param params - Parameters for the transaction status request
+     * @param params.txHash - The transaction hash to query
+     *
+     * @returns A promise that resolves to an object containing the transaction status
+     */
+    getTxStatus(params: {
+        txHash: Hex;
+    }): Promise<PolygonTxStatus>;
+    private parseAmount;
+}