@chorus-one/ethereum/dist/cjs/staker.d.ts

All-in-one toolkit for building staking dApps on Ethereum network

import type { Signer } from '@chorus-one/signer';
import { Hex } from 'viem';
import { Networks } from './lib/types/networks';
import { Transaction } from './lib/types/transaction';
import { EthereumTxStatus } from './lib/types/txStatus';
/**
 * This class provides the functionality to stake, unstake, and withdraw for Ethereum network.
 *
 * It also provides the ability to retrieve staking information and rewards for an account.
 */
export declare class EthereumStaker {
    private connector;
    /**
     * 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 EthereumStaker instance.
     *
     * @param params - Initialization configuration
     * @param params.network - The network to connect to
     * @param params.rpcUrl - (Optional) The URL of the RPC endpoint. If not provided, the public RPC URL for the network will be used.
     *
     * @returns  An instance of EthereumStaker.
     */
    constructor(params: {
        network: Networks;
        rpcUrl?: string;
    });
    /**
     * Initializes the EthereumStaker instance and connects to the Ethereum network.
     *
     * @returns A promise which resolves once the EthereumStaker instance has been initialized.
     */
    init(): Promise<void>;
    /**
     * Builds a staking transaction.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator (wallet) address to stake from
     * @param params.validatorAddress - The validator (vault) address to stake with
     * @param params.amount - The amount to stake, specified in `ETH`. E.g. "1" - 1 ETH
     * @param params.referrer - (Optional) The address of the referrer. This is used to track the origin of transactions,
     * providing insights into which sources or campaigns are driving activity. This can be useful for analytics and
     * optimizing user acquisition strategies
     *
     * @returns Returns a promise that resolves to an Ethereum staking transaction.
     */
    buildStakeTx(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
        amount: string;
        referrer?: Hex;
    }): Promise<{
        tx: Transaction;
    }>;
    /**
     * Builds an unstaking transaction.
     *
     * The unstake transaction effectively moves the user's assets into an unstake queue where they remain until they
     * become eligible for withdrawal. This queue is a safeguard mechanism that ensures the liquidity and stability of
     * the vault by managing the flow of assets. To check the status of these assets, use the `getUnstakeQueue`
     * method.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator (wallet) address that is unstaking
     * @param params.validatorAddress - The validator (vault) address to unstake from
     * @param params.amount - The amount to unstake, specified in `ETH`. E.g. "1" - 1 ETH
     *
     * @returns Returns a promise that resolves to an Ethereum unstaking transaction.
     */
    buildUnstakeTx(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
        amount: string;
    }): Promise<{
        tx: Transaction;
    }>;
    /**
     * Builds a withdrawal transaction.
     *
     * This method is the final step in the unstaking process. Once assets in the unstake queue have reached a
     * withdrawable state (as determined by the `getUnstakeQueue` method), the `buildWithdrawTx` method prepares the
     * transaction data necessary for transferring these assets back into the user's wallet.
     *
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to withdraw from
     * @param params.positionTickets - (Optional) An array of position tickets to withdraw. If not provided, all withdrawable
     * assets will be withdrawn. (see `getUnstakeQueue`)
     *
     * @returns Returns a promise that resolves to an Ethereum withdrawal transaction.
     */
    buildWithdrawTx(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
        positionTickets?: string[];
    }): Promise<{
        tx: Transaction;
    }>;
    /**
     * Builds a mint transaction.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to mint shares for
     * @param params.amount - The amount to mint, specified in `osETH`. E.g. "1" - 1 osETH
     * @param params.referrer - (Optional) The address of the referrer. This is used to track the origin of transactions,
     * providing insights into which sources or campaigns are driving activity. This can be useful for analytics and
     * optimizing user acquisition strategies
     *
     * @returns Returns a promise that resolves to an Ethereum mint transaction.
     */
    buildMintTx(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
        amount: string;
        referrer?: Hex;
    }): Promise<{
        tx: Transaction;
    }>;
    /**
     * Builds a burn transaction.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to burn shares from
     * @param params.amount - The amount to burn, specified in `osETH`. E.g. "1" - 1 osETH
     *
     * @returns Returns a promise that resolves to an Ethereum burn transaction.
     */
    buildBurnTx(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
        amount: string;
    }): Promise<{
        tx: Transaction;
    }>;
    /**
     * Retrieves the staking information for a specified vault, including TVL, APY, description, logo.
     *
     * @param params - Parameters for the request
     * @param params.validatorAddress - The validator (vault) address
     *
     * @returns Returns a promise that resolves to the staking information for the specified vault.
     */
    getVault({ validatorAddress }: {
        validatorAddress: Hex;
    }): Promise<{
        vault: import(".").Vault;
    }>;
    /**
     * Retrieves the staking information for a specified delegator.
     *
     * The staking information includes the current balance and the maximum amount that can be unstaked.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to gather staking information from
     *
     * @returns Returns a promise that resolves to the staking information for the delegator.
     */
    getStake(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
    }): Promise<{
        balance: string;
        maxUnstake: string;
    }>;
    /**
     * Retrieves the rewards history for a specified delegator.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to gather rewards data from
     * @param params.startTime - The start time of the rewards data to retrieve, specified in milliseconds
     * @param params.endTime - The end time of the rewards data to retrieve, specified in milliseconds
     *
     * @returns Returns a promise that resolves to the rewards data for the specified delegator.
     */
    getRewardsHistory(params: {
        startTime: number;
        endTime: number;
        delegatorAddress: Hex;
        validatorAddress: Hex;
    }): Promise<{
        timestamp: number;
        /**
         * @deprecated Use `totalRewards` instead.
         */
        amount: string;
        totalRewards: string;
        dailyRewards: string;
    }[]>;
    /**
     * Retrieves the transaction history for a specified delegator.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to gather transaction data from
     *
     * @returns Returns a promise that resolves to the transaction history for the specified delegator.
     */
    getTxHistory(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
    }): Promise<{
        timestamp: number;
        type: import("./lib/types/transactionHistory").VaultActionType;
        amount: string;
        txHash: string;
    }[]>;
    /**
     * Retrieves the unstake queue for a specified delegator.
     *
     * After initiating an unstake request using the `buildUnstakeTx` method, assets are placed into an unstake
     * queue.
     *
     * The `getUnstakeQueue` method allows users to query the queue to check the current state of their unstake requests,
     * including their positionTicket, the amount of assets that are withdrawable, and the total amount.
     *
     * To prepare the transaction for withdrawing these assets, use the `buildWithdrawTx` method.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to gather the unstake queue from
     *
     * @returns Returns a promise that resolves to the unstake queue for the specified delegator.
     */
    getUnstakeQueue(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
    }): Promise<{
        positionTicket: string;
        exitQueueIndex: string | undefined;
        timestamp: number;
        isWithdrawable: boolean;
        totalAmount: string;
        withdrawableAmount: string;
        withdrawalTimestamp: number | undefined;
    }[]>;
    /**
     * Retrieves the mint information for a specified delegator.
     *
     * The mint information includes the current balance of minted `osETH` and the maximum amount of that can be minted.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - The validator (vault) address to gather mint data from
     *
     * @returns Returns a promise that resolves to the mint information
     */
    getMint(params: {
        delegatorAddress: Hex;
        validatorAddress: Hex;
    }): Promise<{
        balance: string;
        maxMint: string;
    }>;
    /**
     * Retrieves the mint health for a specified stake and mint amount.
     *
     * Position health tracks the value of osETH minted by stakers relative to the value of their ETH stake in the vault.
     * Healthy positions have minted osETH that is well-collateralized by staked ETH. As the proportion of minted osETH
     * increases relative to staked ETH, position health deteriorates.
     *
     * Factors affecting position health include yield discrepancies (APY) between the vault and osETH, which can result
     * from:
     * - Differences in fee structures.
     * - Variations in attestation performance.
     * - The ratio of unbounded ETH to the vault's total value locked (TVL).
     * - Delays in validator activation on the Beacon Chain.
     * - Losses due to maximal extractable value (MEV) strategies.
     *
     * Risky positions may enter redemption processes, while positions deemed unhealthy are subject to liquidation.
     *
     * @param params - Parameters for the request
     * @param params.stakeAmount - The amount of ETH staked
     * @param params.mintAmount - The amount of osETH minted
     * @param params.validatorAddress - The validator (vault) address
     *
     * @returns Returns a promise that resolves to the mint health status('healthy' | 'risky' )
     */
    getMintHealth(params: {
        stakeAmount: string;
        mintAmount: string;
        validatorAddress: Hex;
    }): Promise<{
        health: "healthy" | "risky";
    }>;
    /**
     * 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 the `maxPriorityFeePerGas` estimated by the RPC.
     *
     * @returns A promise that resolves to an object containing the signed transaction.
     */
    sign(params: {
        signer: Signer;
        signerAddress: Hex;
        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 final execution outcome of the broadcast transaction.
     */
    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<EthereumTxStatus>;
    private parseEther;
}