@chorus-one/ethereum
Version:
All-in-one toolkit for building staking dApps on Ethereum network
451 lines (450 loc) • 19.1 kB
TypeScript
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';
import { BatchDetailsDepositData, BatchDetailsResponse, CreateBatchResponse, ListBatchesResponse } from './lib/types/nativeStaking';
/**
* 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;
private nativeStakingConnector?;
private network;
private rpcUrl?;
/**
* 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 an 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.
* @param params.nativeStakingApiToken - (Optional) API token for native staking operations. Required for native staking methods.
*
* @returns An instance of EthereumStaker.
*/
constructor(params: {
network: Networks;
rpcUrl?: string;
nativeStakingApiToken?: 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;
isClaimed?: boolean;
}): 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";
}>;
/**
* Creates a batch of validators for native Ethereum staking.
*
* This method creates a new batch of validators using the Chorus One Native Staking API.
* Each validator requires 32 ETH to be deposited. The batch will generate deposit data
* that can be used to deposit validators on the Ethereum network.
*
* @param params - Parameters for creating the validator batch
* @param params.batchId - Unique identifier for the batch
* @param params.withdrawalAddress - The withdrawal address that will control the staked funds.Must be 0x02 compounding credentials for compounding validators.
* @param params.feeRecipientAddress - The address that will receive MEV rewards
* @param params.numberOfValidators - Number of validators to create (each requires 32 ETH)
* @param params.isCompounding - (Optional) Whether to create compounding validators (0x02 withdrawal credentials). Default is false.
* @param params.depositGweiPerValidator - (Optional) The deposit in gwei per validator. Default is 32000000000 gwei i.e. 32ETH.
*
* @returns Returns a promise that resolves to the batch creation response.
*/
createValidatorBatch(params: {
batchId: string;
withdrawalAddress: Hex;
feeRecipientAddress: Hex;
numberOfValidators: number;
isCompounding?: boolean;
depositGweiPerValidator?: bigint;
}): Promise<CreateBatchResponse>;
/**
* Lists all validator batches for the authenticated tenant.
*
* This method retrieves all validator batches that have been created for the current tenant.
*
* @returns Returns a promise that resolves to an array of validator batches.
*/
listValidatorBatches(): Promise<ListBatchesResponse>;
/**
* Gets the status of a validator batch.
*
* This method retrieves the current status of a validator batch, including the deposit data
* for each validator when ready.
*
* @param params - Parameters for getting batch status
* @param params.batchId - The batch identifier
*
* @returns Returns a promise that resolves to the batch information.
*/
getValidatorBatchStatus(params: {
batchId: string;
}): Promise<BatchDetailsResponse>;
/**
* Exports deposit data in the format required by the Ethereum Staking Launchpad.
*
* This method the deposit data for each validator in the batch, which can be used to deposit
* validators with the oficial Ethereum Staking Launchpad or other depositing tools.
*
* @param params - Parameters for exporting deposit data
* @param params.batchData - Pre-fetched batch of validators
*
* @returns Returns a promise that resolves to an array of deposit data objects.
*/
exportDepositData({ batchData }: {
batchData: BatchDetailsResponse;
}): Promise<{
depositData: BatchDetailsDepositData[];
}>;
/**
* Builds deposit transactions for native Ethereum staking.
*
* This method creates transactions for depositing validators to the Ethereum deposit contract.
* Each validator requires exactly 32 ETH to be deposited along with the deposit data.
*
* @param params - Parameters for building deposit transactions
* @param params.batchData - Pre-fetched batch of validators
*
* @returns Returns a promise that resolves to an array of deposit transactions.
*/
buildDepositTx({ batchData }: {
batchData: BatchDetailsResponse;
}): Promise<{
transactions: Transaction[];
}>;
/**
* Encodes the deposit function call for the Ethereum deposit contract.
*/
private encodeDepositFunction;
/**
* Builds a withdrawal request transaction for a validator based on EIP-7002.
*
* This method creates a transaction that triggers a full validator exit through
* the execution layer withdrawal credentials (0x01) as specified in EIP-7002.
*
* @param params - Parameters for building the withdrawal transaction
* @param params.validatorPubkey - The validator public key (48 bytes)
* @param params.value - (Optional) The amount of ETH to send with the transaction. Default is 1 wei.
*
* @returns Returns a promise that resolves to a withdrawal transaction.
*/
buildValidatorExitTx(params: {
validatorPubkey: string;
value?: bigint;
}): Promise<{
tx: Transaction;
}>;
/**
* 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;
}