@chorus-one/ton/dist/cjs/TonPoolStaker.d.ts

All-in-one tooling for building staking dApps on TON

import { TonBaseStaker } from './TonBaseStaker';
import { UnsignedTx, Election, PoolStatus, TonTxStatus } from './types';
export declare class TonPoolStaker extends TonBaseStaker {
    /**
     * Builds a staking transaction for TON Pool contract. It uses 2 pool solution, and picks the best pool
     * to stake to automatically.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator address
     * @param params.validatorAddressPair - The validator address pair to stake to
     * @param params.amount - The amount to stake, specified in `TON`
     * @param params.preferredStrategy - (Optional) The stake allocation strategy. Default is `balanced`.
     * * `balanced` - automatically balances the stake between the two pools based on the current pool balances and user stakes
     * * `split` - splits the stake evenly between the two pools
     * * `single` - stakes to a single pool
     * @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
     * @param params.validUntil - (Optional) The Unix timestamp when the transaction expires
     *
     * @returns Returns a promise that resolves to a TON nominator pool staking transaction.
     */
    buildStakeTx(params: {
        delegatorAddress: string;
        validatorAddressPair: [string, string];
        amount: string;
        preferredStrategy?: 'balanced' | 'split' | 'single';
        referrer?: string;
        validUntil?: number;
    }): Promise<{
        tx: UnsignedTx;
    }>;
    /**
     * Builds an unstaking transaction for TON Pool contract.
     *
     * @param params - Parameters for building the transaction
     * @param params.delegatorAddress - The delegator address
     * @param params.validatorAddressPair - The validator address pair to unstake from
     * @param params.amount - The amount to unstake, specified in `TON`. When disableStatefulCalculation is true, must be a tuple [string, string]
     * @param params.disableStatefulCalculation - (Optional) Disables stateful calculation where validator and user stake is taken into account
     * @param params.validUntil - (Optional) The Unix timestamp when the transaction expires
     *
     * @returns Returns a promise that resolves to a TON nominator pool unstaking transaction.
     */
    buildUnstakeTx<T extends boolean = false>(params: {
        delegatorAddress: string;
        validatorAddressPair: [string, string];
        amount: T extends true ? [string, string] : string;
        disableStatefulCalculation?: T;
        validUntil?: number;
    }): Promise<{
        tx: UnsignedTx;
    }>;
    /**
     * Retrieves the staking information for a specified delegator.
     *
     * @param params - Parameters for the request
     * @param params.delegatorAddress - The delegator (wallet) address
     * @param params.validatorAddress - (Optional) The validator address to gather staking information from
     *
     * @returns Returns a promise that resolves to the staking information for the specified delegator.
     */
    getStake(params: {
        delegatorAddress: string;
        validatorAddress: string;
    }): Promise<{
        balance: string;
        pendingDeposit: string;
        pendingWithdraw: string;
        withdraw: string;
    }>;
    /**
     * Retrieves the staking information for a specified pool, including minStake and fees information.
     *
     * @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 pool.
     */
    getPoolParams(params: {
        validatorAddress: string;
    }): Promise<{
        minStake: string;
        depositFee: string;
        withdrawFee: string;
        poolFee: string;
        receiptPrice: string;
    }>;
    /**
     * Retrieves the status of a transaction using the transaction hash.
     *
     * This method is intended to check for transactions made recently (within limit) and not for historical transactions.
     *
     * @param params - Parameters for the transaction status request
     * @param params.address - The account address to query
     * @param params.txHash - The transaction hash to query
     * @param params.limit - (Optional) The maximum number of transactions to fetch
     *
     * @returns A promise that resolves to an object containing the transaction status.
     */
    getTxStatus(params: {
        address: string;
        txHash: string;
        limit?: number;
    }): Promise<TonTxStatus>;
    private getPoolParamsUnformatted;
    /** @ignore */
    private getPoolDataForDelegator;
    getElectionMinStake(): Promise<bigint>;
    getPoolStatus(validatorAddress: string): Promise<PoolStatus>;
    getPastElections(electorContractAddress: string): Promise<Election[]>;
    /** @ignore */
    static selectPool(minStake: bigint, // minimum stake for participation (to be in the set)
    currentBalances: [bigint, bigint]): number;
    /** @ignore */
    static selectStrategy(preferredStrategy: string | undefined, amount: bigint, totalValidators: number, lowestMinStake: bigint): string;
    /**
     * Calculates optimal unstake amounts from two pools.
     * Tries strategies in order: keep both active → keep one active → deactivate both
     *
     * TODO: Add transaction simulation to catch false negatives thrown by SDK in case of bugs in calculation logic.
     *       Consider adding anonymous telemetry/logging.
     *
     * TODO: Add `getValidUnstakeRanges()` method to help integrators validate amounts upfront by knowing the valid amounts to unstake.
     *
     */
    static calculateUnstakePoolAmount(amount: bigint, // amount to unstake
    minElectionStake: bigint, // minimum stake for participation (to be in the set)
    [pool1Balance, pool2Balance]: [bigint, bigint], // current stake balances of the pools
    [pool1UserMaxUnstake, pool2UserMaxUnstake]: [bigint, bigint], // maximum user stake that can be unstaked from the pools
    [pool1MinStake, pool2MinStake]: [bigint, bigint], // min user stake per pool
    [pool1UserWithdraw, pool2UserWithdraw]: [bigint, bigint]): [bigint, bigint];
    /** @ignore */
    static calculateStakePoolAmount(amount: bigint, // amount to stake
    minStake: bigint, // minimum stake for participation (to be in the set)
    currentPoolBalances: [bigint, bigint], // current stake balances of the pools
    minPoolStakes: [bigint, bigint]): [bigint, bigint];
}