Staking Precompile

Watch the video walkthrough for this topic in the Video Tutorials section.

Address: 0x0000000000000000000000000000000000001005 The Sei staking precompile lets EVM applications interact directly with the Sei native staking module through standard smart contract calls. Your dApps can use it for delegation, undelegation, redelegation, validator management, and staking queries. They do not need a separate Cosmos SDK integration.

What is a precompile? A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently.

How does the staking precompile work?

The staking precompile at address 0x0000000000000000000000000000000000001005 exposes transaction functions such as delegate(), undelegate(), redelegate(), createValidator(), and editValidator(). It also exposes query functions such as validators(), delegatorDelegations(), pool(), and params().

EVM contracts and dApps can call staking functions like any other smart contract method.
Operations run at the Cosmos SDK level, which makes them efficient and secure.
You do not need separate wallet integrations or complex cross-chain interactions.
Staking operations emit Delegate, Undelegate, Redelegate, DelegationRewardsWithdrawn, ValidatorCreated, and ValidatorEdited events.

Use cases

DeFi integration: Build liquid staking protocols and yield farming strategies.
Delegation services: Create user-friendly interfaces for staking operations.
Portfolio management: Automate staking strategies and delegation rebalancing.
Validator management: Create and manage validators programmatically.

What you’ll learn in this guide

This guide shows how to:

Call delegation, undelegation, and redelegation functions directly from your EVM contracts and dApps
Use the correct decimal precision for each operation, to avoid common formatting errors
Create validators and edit their parameters programmatically
Use the query functions to fetch validators, delegations, unbonding information, pool statistics, and staking parameters
Listen for staking events, to track staking operations for indexing and notifications
Build portfolio tools for staking management applications, with automated rebalancing and delegation tracking
Understand unbonding periods, slashing mechanics, and validator selection, so that you can stake safely

Events

The staking precompile emits these events:

/**
 * @notice Emitted when tokens are delegated to a validator
 * @param delegator The address of the delegator
 * @param validator The validator address
 * @param amount The amount delegated in base units
 */
event Delegate(address indexed delegator, string validator, uint256 amount);

/**
 * @notice Emitted when a delegator withdraws staking rewards
 * @param delegator The address of the delegator
 * @param validator The validator address
 * @param amount The amount withdrawn in base units
 */
event DelegationRewardsWithdrawn(
    address indexed delegator,
    string validator,
    uint256 amount
);

/**
 * @notice Emitted when tokens are redelegated from one validator to another
 * @param delegator The address of the delegator
 * @param srcValidator The source validator address
 * @param dstValidator The destination validator address
 * @param amount The amount redelegated in base units
 */
event Redelegate(
    address indexed delegator,
    string srcValidator,
    string dstValidator,
    uint256 amount
);

/**
 * @notice Emitted when tokens are undelegated from a validator
 * @param delegator The address of the delegator
 * @param validator The validator address
 * @param amount The amount undelegated in base units
 */
event Undelegate(
    address indexed delegator,
    string validator,
    uint256 amount
);

/**
 * @notice Emitted when a new validator is created
 * @param creator The address of the validator creator
 * @param validatorAddress The validator address
 * @param moniker The validator moniker
 */
event ValidatorCreated(
    address indexed creator,
    string validatorAddress,
    string moniker
);

/**
 * @notice Emitted when a validator is edited
 * @param editor The address of the validator editor
 * @param validatorAddress The validator address
 * @param moniker The new validator moniker
 */
event ValidatorEdited(
    address indexed editor,
    string validatorAddress,
    string moniker
);

Listening for events

Your dApp can listen for these events to track staking operations:

// Listen for delegation events
staking.on('Delegate', (delegator, validator, amount) => {
  console.log(`${delegator} delegated ${amount} to ${validator}`);
});

staking.on('DelegationRewardsWithdrawn', (delegator, validator, amount) => {
  console.log(`${delegator} withdrew ${amount} from ${validator}`);
});

// Listen for redelegation events
staking.on('Redelegate', (delegator, srcValidator, dstValidator, amount) => {
  console.log(`${delegator} redelegated ${amount} from ${srcValidator} to ${dstValidator}`);
});

// Listen for undelegation events
staking.on('Undelegate', (delegator, validator, amount) => {
  console.log(`${delegator} undelegated ${amount} from ${validator}`);
});

// Listen for validator creation events
staking.on('ValidatorCreated', (creator, validatorAddress, moniker) => {
  console.log(`New validator ${moniker} created at ${validatorAddress} by ${creator}`);
});

// Listen for validator edit events
staking.on('ValidatorEdited', (editor, validatorAddress, moniker) => {
  console.log(`Validator ${validatorAddress} edited by ${editor}, new moniker: ${moniker}`);
});

Functions

The staking precompile exposes these functions:

Transaction functions

/// Delegates Sei to the specified validator.
/// @dev This function truncates msg.value to 6 decimal places for interaction with the staking module
/// @param valAddress The Sei address of the validator.
/// @return Whether the delegation was successful.
function delegate(
    string memory valAddress
) payable external returns (bool success);

/// Redelegates Sei from one validator to another.
/// @dev The amount should be in 6 decimal precision, not 18. 1 SEI = 1_000_000 uSEI
/// @param srcAddress The Sei address of the validator to move delegations from.
/// @param dstAddress The Sei address of the validator to move delegations to.
/// @param amount The amount of Sei to move from srcAddress to dstAddress.
/// @return Whether the redelegation was successful.
function redelegate(
    string memory srcAddress,
    string memory dstAddress,
    uint256 amount
) external returns (bool success);

/// Undelegates Sei from the specified validator.
/// @dev The amount should be in 6 decimal precision, not 18. 1 SEI = 1_000_000 uSEI
/// @param valAddress The Sei address of the validator to undelegate from.
/// @param amount The amount of Sei to undelegate.
/// @return Whether the undelegation was successful.
function undelegate(
    string memory valAddress,
    uint256 amount
) external returns (bool success);

/// Create a new validator. Delegation amount must be provided as value in wei.
/// @param pubKeyHex Ed25519 public key in hex format (64 characters)
/// @param moniker Validator display name
/// @param commissionRate Initial commission rate (e.g. "0.05" for 5%)
/// @param commissionMaxRate Maximum commission rate (e.g. "0.20" for 20%)
/// @param commissionMaxChangeRate Maximum commission change rate per day (e.g. "0.01" for 1%)
/// @param minSelfDelegation Minimum self-delegation amount in base units
/// @return success True if validator creation was successful
function createValidator(
    string memory pubKeyHex,
    string memory moniker,
    string memory commissionRate,
    string memory commissionMaxRate,
    string memory commissionMaxChangeRate,
    uint256 minSelfDelegation
) external payable returns (bool success);

/// Edit an existing validator's parameters
/// @param moniker New validator display name
/// @param commissionRate New commission rate (e.g. "0.10" for 10%)
///                      Pass empty string "" to not change commission rate
///                      Note: Commission can only be changed once per 24 hours
/// @param minSelfDelegation New minimum self-delegation amount
///                         Pass 0 to not change minimum self-delegation
///                         Note: Can only increase, cannot decrease below current value
/// @return success True if validator edit was successful
function editValidator(
    string memory moniker,
    string memory commissionRate,
    uint256 minSelfDelegation
) external returns (bool success);

Query functions

struct Delegation {
    Balance balance;
    DelegationDetails delegation;
}

struct Balance {
    uint256 amount;  // Staked balance in usei (6 decimals)
    string denom;    // Token denomination (e.g., "usei")
}

struct DelegationDetails {
    string delegator_address;
    uint256 shares;    // Delegation shares (18 decimal precision)
    uint256 decimals;  // Precision for shares field (always 18)
    string validator_address;
}

struct Validator {
    string operatorAddress;      // Validator's operator address (seivaloper...)
    string consensusPubkey;      // Consensus public key
    bool jailed;                 // Whether the validator is jailed
    int32 status;                // Bonding status (1=Unbonded, 2=Unbonding, 3=Bonded)
    string tokens;               // Total tokens delegated
    string delegatorShares;      // Total delegator shares
    string description;          // Validator description/metadata
    int64 unbondingHeight;       // Height at which unbonding started
    int64 unbondingTime;         // Time at which unbonding completes
    string commissionRate;       // Current commission rate
    string commissionMaxRate;    // Maximum commission rate
    string commissionMaxChangeRate; // Maximum daily commission change rate
    int64 commissionUpdateTime;  // Last commission update timestamp
    string minSelfDelegation;    // Minimum self-delegation requirement
}

struct ValidatorsResponse {
    Validator[] validators;      // Array of validators
    bytes nextKey;               // Pagination key for next page
}

struct DelegationsResponse {
    Delegation[] delegations;    // Array of delegations
    bytes nextKey;               // Pagination key for next page
}

struct UnbondingDelegationEntry {
    int64 creationHeight;        // Height when unbonding was initiated
    int64 completionTime;        // Timestamp when unbonding completes
    string initialBalance;       // Initial unbonding balance
    string balance;              // Current unbonding balance
}

struct UnbondingDelegation {
    string delegatorAddress;     // Delegator's address
    string validatorAddress;     // Validator's address
    UnbondingDelegationEntry[] entries; // Unbonding entries
}

struct UnbondingDelegationsResponse {
    UnbondingDelegation[] unbondingDelegations; // Array of unbonding delegations
    bytes nextKey;               // Pagination key for next page
}

struct RedelegationEntry {
    int64 creationHeight;        // Height when redelegation was initiated
    int64 completionTime;        // Timestamp when redelegation completes
    string initialBalance;       // Initial redelegation balance
    string sharesDst;            // Shares at destination validator
}

struct Redelegation {
    string delegatorAddress;     // Delegator's address
    string validatorSrcAddress;  // Source validator address
    string validatorDstAddress;  // Destination validator address
    RedelegationEntry[] entries; // Redelegation entries
}

struct RedelegationsResponse {
    Redelegation[] redelegations; // Array of redelegations
    bytes nextKey;               // Pagination key for next page
}

struct HistoricalInfo {
    int64 height;                // Block height
    Validator[] validators;      // Validators at that height
}

struct Pool {
    string notBondedTokens;      // Total tokens not bonded
    string bondedTokens;         // Total tokens bonded
}

struct Params {
    uint64 unbondingTime;        // Unbonding duration in seconds
    uint32 maxValidators;        // Maximum number of validators
    uint32 maxEntries;           // Max unbonding/redelegation entries
    uint32 historicalEntries;    // Number of historical entries to keep
    string bondDenom;            // Bond token denomination
    string minCommissionRate;    // Minimum commission rate
    string maxVotingPowerRatio;  // Maximum voting power ratio
    string maxVotingPowerEnforcementThreshold; // Enforcement threshold
}

/// Queries delegation for a given delegator and validator address.
/// @param delegator The address of the delegator.
/// @param valAddress The Sei address of the validator.
/// @return The delegation information.
/// @dev balance.amount is in usei (6 decimals). To calculate SEI: amount / 1e6
/// @dev shares uses 18 decimal precision. To calculate actual shares: shares / 1e18
function delegation(
    address delegator,
    string memory valAddress
) external view returns (Delegation delegation);

/// Get list of validators with optional status filter
/// @param status Filter by validator status ("BOND_STATUS_BONDED", "BOND_STATUS_UNBONDING", "BOND_STATUS_UNBONDED", or "" for all)
/// @param nextKey Pagination key (use empty bytes for first page)
/// @return response List of validators with pagination info
function validators(
    string memory status,
    bytes memory nextKey
) external view returns (ValidatorsResponse memory response);

/// Get validator information for a given validator address
/// @param validatorAddress The validator address
/// @return validator Validator details
function validator(
    string memory validatorAddress
) external view returns (Validator memory validator);

/// Get delegations for a specific validator
/// @param validatorAddress The validator address
/// @param nextKey Pagination key
/// @return response Delegations response with pagination
function validatorDelegations(
    string memory validatorAddress,
    bytes memory nextKey
) external view returns (DelegationsResponse memory response);

/// Get unbonding delegations for a specific validator
/// @param validatorAddress The validator address
/// @param nextKey Pagination key
/// @return response Unbonding delegations response with pagination
function validatorUnbondingDelegations(
    string memory validatorAddress,
    bytes memory nextKey
) external view returns (UnbondingDelegationsResponse memory response);

/// Get unbonding delegation information for a delegator and validator pair
/// @param delegator The delegator's address
/// @param validatorAddress The validator address
/// @return unbondingDelegation Unbonding delegation details
function unbondingDelegation(
    address delegator,
    string memory validatorAddress
) external view returns (UnbondingDelegation memory unbondingDelegation);

/// Get all delegations for a delegator
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Delegations response with pagination
function delegatorDelegations(
    address delegator,
    bytes memory nextKey
) external view returns (DelegationsResponse memory response);

/// Get validator information for a delegator and validator pair
/// @param delegator The delegator's address
/// @param validatorAddress The validator address
/// @return validator Validator details
function delegatorValidator(
    address delegator,
    string memory validatorAddress
) external view returns (Validator memory validator);

/// Get all unbonding delegations for a delegator
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Unbonding delegations response with pagination
function delegatorUnbondingDelegations(
    address delegator,
    bytes memory nextKey
) external view returns (UnbondingDelegationsResponse memory response);

/// Get redelegations with optional filters
/// @param delegator The delegator's address (empty string for all)
/// @param srcValidator The source validator address (empty string for all)
/// @param dstValidator The destination validator address (empty string for all)
/// @param nextKey Pagination key
/// @return response Redelegations response with pagination
function redelegations(
    string memory delegator,
    string memory srcValidator,
    string memory dstValidator,
    bytes memory nextKey
) external view returns (RedelegationsResponse memory response);

/// Get all validators that a delegator has delegated to
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Validators response with pagination
function delegatorValidators(
    address delegator,
    bytes memory nextKey
) external view returns (ValidatorsResponse memory response);

/// Get historical info for a given height
/// @param height The block height
/// @return historicalInfo Historical validator set info
function historicalInfo(
    int64 height
) external view returns (HistoricalInfo memory historicalInfo);

/// Get staking pool information (bonded and unbonded token totals)
/// @return pool Pool details
function pool() external view returns (Pool memory pool);

/// Get staking module parameters
/// @return params Staking parameters
function params() external view returns (Params memory params);

Precision in the delegation() response:The response uses two different precision scales:

balance.amount: The staked token amount, in 6 decimals (usei)
delegation.shares: The amount of shares in the validator pool, in 18 decimals
delegation.decimals: Always returns 18 (the precision of the shares, NOT of the balance)

To convert to SEI for display:

Balance: balance.amount / 1e6
Shares: delegation.shares / 1e18

Using the precompile

Setup

Prerequisites

Before you start, make sure that you have:

Node.js (v18 or higher)
The npm or yarn package manager
An EVM-compatible wallet
SEI tokens for gas and staking operations

Install dependencies

Install the required packages to interact with Sei precompiles:

# Install ethers.js for smart contract interactions
npm install ethers

# Install @sei-js/precompiles for precompile addresses and ABIs
npm install @sei-js/precompiles@^3

Import precompile components

// Import Staking precompile address and ABI
// View the entire ABI here: https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/staking/legacy/v66/abi.json
import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

Precompile address: The staking precompile is deployed at 0x0000000000000000000000000000000000001005.

Contract initialization

Set up your provider, signer, and contract instance:

// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the staking precompile
const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);

Critical: understanding decimal precision

Decimal precision is one of the most important concepts to understand when you work with the Sei staking precompile.

Mixed decimal precision system

The staking precompile uses different decimal precision for different operations, because it bridges EVM and Cosmos standards:

Function	Input/Output	Decimal precision	Example
delegate()	msg.value (input)	18 decimals (wei)	`ethers.parseUnits('1', 18)`
undelegate()	amount (input)	6 decimals (uSEI)	`1000000` (represents 1 SEI)
redelegate()	amount (input)	6 decimals (uSEI)	`500000` (represents 0.5 SEI)
createValidator()	msg.value (input)	18 decimals (wei)	`ethers.parseUnits('1000', 18)`
delegation()	return values (output)	Mixed (balance 6, shares 18)	`balance.amount=1000000`, `shares=1000000000000000000`

Granularity for delegate():To avoid unintended truncation, always send amounts that are a multiple of 1e12 wei (the last 12 digits are zero). The precompile truncates msg.value to 6 decimals (uSEI).

OK: 1_000_000_000_000 wei (0.000001000000 SEI)
NOT OK: 1_000_000_000_001 wei (0.000001000000000001 SEI)
NOT OK: 1_000_000_330_000 wei (0.000001000000330000 SEI)

Examples:

Delegate 10 SEI → 10000000000000000000 wei (18 decimals)
Undelegate 10 SEI → 10000000 uSEI (6 decimals)

How this works in practice

delegate() function (uses 18 decimals):

delegate(): Accepts msg.value in wei (18 decimals)

undelegate() and redelegate() functions (use 6 decimals):

undelegate(): Expects the amount parameter in 6 decimals (uSEI)
redelegate(): Expects the amount parameter in 6 decimals (uSEI)

Read and query operations (return 6 decimals):

delegation(): Returns balance.amount in 6-decimal uSEI and delegation.shares in 18-decimal precision
The Distribution precompile handles rewards. Its rewards() query returns 18-decimal DecCoins, but withdrawn amounts (events) are 6-decimal uSEI.

Why this mixed system exists

delegate() EVM compatibility: Uses the standard 18-decimal wei format, for consistency with EVM msg.value
Cosmos integration for other operations: undelegate() and redelegate() use 6-decimal uSEI precision to match native Cosmos operations
Staking query consistency: Query balances in the staking precompile use 6-decimal uSEI (but shares is 18-decimal), for consistent reading

Best practice: different conversion for different functions

When you work with user input, use the appropriate conversion for each function:

// Best practice for handling user input amounts
function prepareAmountForDelegate(seiAmount: number): bigint {
  // For delegate() - convert to 18 decimals (wei)
  const fixedAmount = seiAmount.toFixed(6);
  return ethers.parseUnits(fixedAmount, 18);
}

function prepareAmountForUndelegateRedelegate(seiAmount: number): bigint {
  // For undelegate() and redelegate() - convert to 6 decimals (uSEI)
  return ethers.parseUnits(seiAmount.toFixed(6), 6);
}

// Usage examples
const userInputAmount = 1.23456789; // User enters this

// For delegate()
const delegateAmount = prepareAmountForDelegate(userInputAmount); // 18 decimals

// For undelegate() and redelegate()
const undelegateAmount = prepareAmountForUndelegateRedelegate(userInputAmount); // 6 decimals

Normalization guidelines (clients and indexers)

Normalize to a single unit for analytics and reconciliation:
- Display: convert to SEI (wei / 1e18, uSEI / 1e6)
- Storage and aggregation: prefer uSEI (6 decimals)
Reconcile delegate amounts with undelegate, redelegate, and rewards amounts: Convert the delegate msg.value from wei to uSEI with integer division by 1e12 (floor). This matches the internal truncation in the precompile.
Enforce granularity at the source: Construct msg.value as a multiple of 1e12 wei. To do this, format user input to 6 decimals before you call parseUnits.

// Convert delegate msg.value (wei) to uSEI (6 decimals) for reconciliation
function weiToUseiForDelegate(valueWei: bigint): bigint {
  return valueWei / 1_000_000_000_000n; // floor to 6-decimal granularity
}

// Convert uSEI to SEI for display
function useiToSeiString(amountUsei: bigint): string {
  return ethers.formatUnits(amountUsei, 6);
}

// Ensure msg.value is a multiple of 1e12 wei (last 12 digits zero)
function normalizeWeiForDelegate(valueWei: bigint): bigint {
  return (valueWei / 1_000_000_000_000n) * 1_000_000_000_000n;
}

Decimal conversion helpers

Use these helper functions to avoid precision errors:

// Helper functions for amount conversion
class SeiAmountConverter {
  // Convert SEI to wei (18 decimals) - ONLY for delegate()
  static seiToWei(seiAmount: number): bigint {
    return ethers.parseUnits(seiAmount.toFixed(6), 18);
  }

  // Convert SEI to uSEI (6 decimals) - for undelegate() and redelegate()
  static seiToUsei(seiAmount: number): bigint {
    return ethers.parseUnits(seiAmount.toFixed(6), 6);
  }

  // Convert reading results (6 decimals) to SEI
  static useiToSei(useiAmount: number | bigint): number {
    return Number(useiAmount) / 1000000;
  }

  // Convert wei to SEI (18 decimals) - for delegate operations
  static weiToSei(weiAmount: bigint): number {
    return Number(ethers.formatEther(weiAmount));
  }
}

// Usage examples - Use correct decimals for each function
const delegateAmount = SeiAmountConverter.seiToWei(1); // For delegate() - 18 decimals
const undelegateAmount = SeiAmountConverter.seiToUsei(0.5); // For undelegate() - 6 decimals
const redelegateAmount = SeiAmountConverter.seiToUsei(2); // For redelegate() - 6 decimals

Step-by-step guide: Using the staking precompile

Delegate tokens

JavaScript
Solidity

// Sei validator address you want to delegate to (seivaloper... format)
const validatorAddress = 'seivaloper1xyz...';

const amount = 1; // Amount in SEI to delegate

const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision for msg.value

// Delegate 1 SEI - Uses 18 decimals for msg.value
const amountToDelegate = ethers.parseUnits(amountTrimmed, 18);

const tx = await staking.delegate(validatorAddress, { value: amountToDelegate });

const receipt = await tx.wait();
console.log('Delegation completed:', receipt);

function delegateToValidator(string memory validatorAddress) external payable {
        require(msg.value > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).delegate{value: msg.value}(validatorAddress);
        require(success, "Delegation failed");
        
        emit Delegated(msg.sender, validatorAddress, msg.value);
    }

Undelegate tokens

JavaScript
Solidity

// Undelegate 1 SEI from a validator - Uses 6 decimals for amount parameter
const validatorAddress = 'seivaloper1xyz...';

const amount = 1; // Amount in SEI to undelegate
const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
const amountToUndelegate = ethers.parseUnits(amountTrimmed, 6); // 1 SEI in 6 decimals

const tx = await staking.undelegate(validatorAddress, amountToUndelegate);
const receipt = await tx.wait();

console.log('Undelegation started:', receipt);

function undelegateFromValidator(
        string memory validatorAddress, 
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).undelegate(validatorAddress, amount);
        require(success, "Undelegation failed");
        
        emit Undelegated(msg.sender, validatorAddress, amount);
    }
    

Undelegated tokens have a 21-day unbonding period. During this period, you cannot transfer them, and they do not earn rewards.

Redelegate tokens

JavaScript
Solidity

// Redelegate 0.5 SEI from one validator to another - Uses 6 decimals for amount parameter
const srcValidator = 'seivaloper1abc...';
const dstValidator = 'seivaloper1xyz...';

const amount = 0.5; // Amount in SEI to redelegate
const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
const amountToRedelegate = ethers.parseUnits(amountTrimmed, 6); // 0.5 SEI in 6 decimals

const tx = await staking.redelegate(srcValidator, dstValidator, amountToRedelegate);
const receipt = await tx.wait();

console.log('Redelegation completed:', receipt);

function redelegateBetweenValidators(
        string memory fromValidator,
        string memory toValidator,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).redelegate(fromValidator, toValidator, amount);
        require(success, "Redelegation failed");
        
        emit Redelegated(msg.sender, fromValidator, toValidator, amount);
    }

Redelegation restrictions:

A maximum of 7 redelegations per validator pair in each 21-day period
After you redelegate from Validator A to Validator B, you cannot redelegate from Validator B to another validator for 21 days
Each redelegation has its own 21-day cooldown period

Query a delegation

JavaScript
Solidity

// Get your EVM address as the delegator
const delegator = await signer.getAddress();

try {
  const delegationInfo = await staking.delegation(delegator, validatorAddress);

  console.log('Delegation details:', {
    amount: delegationInfo.balance.amount.toString(),
    denom: delegationInfo.balance.denom,
    shares: delegationInfo.delegation.shares.toString(),
    decimals: delegationInfo.delegation.decimals.toString(),
    delegator_address: delegationInfo.delegation.delegator_address,
    validator_address: delegationInfo.delegation.validator_address
  });

  // Convert delegation amount from uSEI to SEI for readable display
  const delegationAmountSei = ethers.formatUnits(delegationInfo.balance.amount, 6);
  console.log('Delegation amount (SEI):', delegationAmountSei);
} catch (error) {
  if (error.message.includes('delegation not found') || error.message.includes('no delegation')) {
    console.log('No delegation found for this validator');
  } else {
    console.error('Error querying delegation:', error);
  }
}

function getDelegationInfo(
        address delegator,
        string memory validatorAddress
    ) external view returns (IStakingPrecompile.Delegation memory) {
        return ISTAKING(0x0000000000000000000000000000000000001005).delegation(delegator, validatorAddress);
    }

Create a validator

Proceed only if you understand the responsibilities of running a validator node. To create a validator, you need significant SEI for self-delegation and a correctly configured validator infrastructure.

JavaScript
Solidity

// Ed25519 public key in hex format (64 characters)
// This comes from your validator node's priv_validator_key.json
const pubKeyHex = 'your_ed25519_public_key_hex_64_chars';
const moniker = 'MyValidator';

// Commission rates as decimal strings
const commissionRate = '0.05'; // 5% commission
const commissionMaxRate = '0.20'; // Maximum 20% commission
const commissionMaxChangeRate = '0.01'; // Can change by 1% per day max

// Minimum self-delegation in base units (uSEI)
const minSelfDelegation = BigInt(1000000); // 1 SEI minimum

// Initial self-delegation amount in wei (18 decimals)
const selfDelegationAmount = ethers.parseUnits('1000', 18); // 1000 SEI

const tx = await staking.createValidator(pubKeyHex, moniker, commissionRate, commissionMaxRate, commissionMaxChangeRate, minSelfDelegation, { value: selfDelegationAmount });

const receipt = await tx.wait();
console.log('Validator created:', receipt);

function createNewValidator(
    string memory pubKeyHex,
    string memory moniker,
    string memory commissionRate,
    string memory commissionMaxRate,
    string memory commissionMaxChangeRate,
    uint256 minSelfDelegation
) external payable {
    require(msg.value > 0, "Self-delegation required");

    bool success = STAKING.createValidator{value: msg.value}(
        pubKeyHex,
        moniker,
        commissionRate,
        commissionMaxRate,
        commissionMaxChangeRate,
        minSelfDelegation
    );
    require(success, "Validator creation failed");
}

Edit a validator

// Update validator parameters
const newMoniker = 'MyUpdatedValidator';
const newCommissionRate = '0.08'; // 8% commission (or "" to keep current)
const newMinSelfDelegation = BigInt(2000000); // 2 SEI (or 0 to keep current)

const tx = await staking.editValidator(newMoniker, newCommissionRate, newMinSelfDelegation);

const receipt = await tx.wait();
console.log('Validator updated:', receipt);

Edit validator constraints: You can change the commission only once every 24 hours. You can only increase minSelfDelegation, never decrease it. To keep the current rate, pass an empty string "" for commissionRate. To keep the current value, pass 0 for minSelfDelegation.

Query validators

// Get all bonded validators
const bondedValidators = await staking.validators('BOND_STATUS_BONDED', '0x');
console.log('Bonded validators:', bondedValidators.validators);

// Get all validators (no filter)
const allValidators = await staking.validators('', '0x');
console.log('Total validators:', allValidators.validators.length);

// Pagination - get next page if available
if (allValidators.nextKey.length > 0) {
  const nextPage = await staking.validators('', allValidators.nextKey);
  console.log('Next page validators:', nextPage.validators);
}

Query a specific validator

const validatorAddress = 'seivaloper1xyz...';
const validatorInfo = await staking.validator(validatorAddress);

console.log('Validator details:', {
  moniker: validatorInfo.description,
  tokens: validatorInfo.tokens,
  commission: validatorInfo.commissionRate,
  jailed: validatorInfo.jailed,
  status: validatorInfo.status // 1=Unbonded, 2=Unbonding, 3=Bonded
});

Query all delegations for an address

const delegator = await signer.getAddress();

// Get all delegations for the connected wallet
const myDelegations = await staking.delegatorDelegations(delegator, '0x');

console.log('My delegations:');
for (const del of myDelegations.delegations) {
  const amountSei = ethers.formatUnits(del.balance.amount, 6);
  console.log(`  ${del.delegation.validator_address}: ${amountSei} SEI`);
}

Query unbonding delegations

const delegator = await signer.getAddress();

// Get all unbonding delegations
const unbonding = await staking.delegatorUnbondingDelegations(delegator, '0x');

console.log('Unbonding delegations:');
for (const ud of unbonding.unbondingDelegations) {
  console.log(`Validator: ${ud.validatorAddress}`);
  for (const entry of ud.entries) {
    const completionDate = new Date(Number(entry.completionTime) * 1000);
    console.log(`  Amount: ${entry.balance}, Completes: ${completionDate.toISOString()}`);
  }
}

// Query specific unbonding delegation
const validatorAddress = 'seivaloper1xyz...';
const specificUnbonding = await staking.unbondingDelegation(delegator, validatorAddress);

Query redelegations

// Get all redelegations for a specific delegator
const delegatorAddress = await signer.getAddress();
const delegatorBech32 = 'sei1...'; // Convert EVM address to Bech32 format

const redelegations = await staking.redelegations(
  delegatorBech32, // delegator filter (empty string for all)
  '', // source validator filter (empty string for all)
  '', // destination validator filter (empty string for all)
  '0x' // pagination key
);

console.log('Active redelegations:');
for (const redel of redelegations.redelegations) {
  console.log(`From ${redel.validatorSrcAddress} to ${redel.validatorDstAddress}`);
  for (const entry of redel.entries) {
    const completionDate = new Date(Number(entry.completionTime) * 1000);
    console.log(`  Amount: ${entry.initialBalance}, Completes: ${completionDate.toISOString()}`);
  }
}

Query staking pool and parameters

// Get staking pool totals
const pool = await staking.pool();
console.log('Staking Pool:', {
  bondedTokens: pool.bondedTokens,
  notBondedTokens: pool.notBondedTokens
});

// Get staking parameters
const params = await staking.params();
console.log('Staking Parameters:', {
  unbondingTime: `${Number(params.unbondingTime) / 86400} days`,
  maxValidators: params.maxValidators,
  bondDenom: params.bondDenom,
  minCommissionRate: params.minCommissionRate
});

Query historical validator info

// Get validator set at a specific block height
const blockHeight = 1000000n;
const historicalInfo = await staking.historicalInfo(blockHeight);

console.log(`Validators at block ${blockHeight}:`);
for (const val of historicalInfo.validators) {
  console.log(`  ${val.operatorAddress}: ${val.tokens} tokens`);
}

Advanced usage examples

Portfolio rebalancing

async function rebalanceStaking(
  fromValidator: string,
  toValidator: string,
  amount: number // Amount in SEI
) {
  try {
    // Convert to 6 decimal precision for redelegate (uses 6 decimals)
    const amountIn6Decimals = ethers.parseUnits(amount.toFixed(6), 6);

    const tx = await staking.redelegate(fromValidator, toValidator, amountIn6Decimals);

    const receipt = await tx.wait();
    console.log('Rebalancing completed:', receipt);

    return receipt;
  } catch (error) {
    console.error('Rebalancing failed:', error);
    throw error;
  }
}

Complete integration example

JavaScript
Solidity

async function stakingExample() {
  // Setup
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);

  const delegator = await signer.getAddress();
  const validatorAddress = 'seivaloper1xyz...';

  try {
    // 1. Check current delegation (with error handling)
    console.log('=== Checking Current Delegation ===');
    try {
      const currentDelegation = await staking.delegation(delegator, validatorAddress);
      const currentAmountSei = ethers.formatUnits(currentDelegation.balance.amount, 6);
      console.log('Current delegation amount (SEI):', currentAmountSei);
    } catch (error) {
      if (error.message.includes('delegation not found') || error.message.includes('no delegation')) {
        console.log('No existing delegation found for this validator');
      } else {
        throw error; // Re-throw if it's a different error
      }
    }

    // 2. Delegate additional tokens (uses 18 decimals)
    console.log('=== Delegating Tokens ===');
    const amount = 1;
    const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
    const amountToDelegate = ethers.parseUnits(amountTrimmed, 18);
    const delegateTx = await staking.delegate(validatorAddress, {
      value: amountToDelegate,
      gasLimit: 300000
    });
    await delegateTx.wait();
    console.log('Delegation successful:', delegateTx.hash);

    // 3. Check updated delegation
    const updatedDelegation = await staking.delegation(delegator, validatorAddress);
    const updatedAmountSei = ethers.formatUnits(updatedDelegation.balance.amount, 6);
    console.log('Updated delegation amount (SEI):', updatedAmountSei);

    // 4. Undelegate partial amount (uses 6 decimals)
    console.log('=== Undelegating Tokens ===');
    const undelegateAmount = ethers.parseUnits('0.5', 6); // 0.5 SEI in 6 decimals
    const undelegateTx = await staking.undelegate(validatorAddress, undelegateAmount);
    await undelegateTx.wait();
    console.log('Undelegation successful:', undelegateTx.hash);
  } catch (error) {
    console.error('Operation failed:', error);
  }
}

Contract example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IStakingPrecompile {
    // Events
    event Delegate(address indexed delegator, string validator, uint256 amount);
    event Redelegate(address indexed delegator, string srcValidator, string dstValidator, uint256 amount);
    event Undelegate(address indexed delegator, string validator, uint256 amount);
    event ValidatorCreated(address indexed creator, string validatorAddress, string moniker);
    event ValidatorEdited(address indexed editor, string validatorAddress, string moniker);

    // Structs
    struct Delegation {
        Balance balance;
        DelegationDetails delegation;
    }

    struct Balance {
        uint256 amount;
        string denom;
    }

    struct DelegationDetails {
        string delegator_address;
        uint256 shares;
        uint256 decimals;
        string validator_address;
    }

    struct Validator {
        string operatorAddress;
        string consensusPubkey;
        bool jailed;
        int32 status;
        string tokens;
        string delegatorShares;
        string description;
        int64 unbondingHeight;
        int64 unbondingTime;
        string commissionRate;
        string commissionMaxRate;
        string commissionMaxChangeRate;
        int64 commissionUpdateTime;
        string minSelfDelegation;
    }

    struct ValidatorsResponse {
        Validator[] validators;
        bytes nextKey;
    }

    struct Pool {
        string notBondedTokens;
        string bondedTokens;
    }

    struct Params {
        uint64 unbondingTime;
        uint32 maxValidators;
        uint32 maxEntries;
        uint32 historicalEntries;
        string bondDenom;
        string minCommissionRate;
        string maxVotingPowerRatio;
        string maxVotingPowerEnforcementThreshold;
    }

    // Transaction functions
    function delegate(string memory valAddress) payable external returns (bool success);

    function undelegate(
        string memory valAddress,
        uint256 amount
    ) external returns (bool success);

    function redelegate(
        string memory srcAddress,
        string memory dstAddress,
        uint256 amount
    ) external returns (bool success);

    function createValidator(
        string memory pubKeyHex,
        string memory moniker,
        string memory commissionRate,
        string memory commissionMaxRate,
        string memory commissionMaxChangeRate,
        uint256 minSelfDelegation
    ) external payable returns (bool success);

    function editValidator(
        string memory moniker,
        string memory commissionRate,
        uint256 minSelfDelegation
    ) external returns (bool success);

    // Query functions
    function delegation(
        address delegator,
        string memory valAddress
    ) external view returns (Delegation memory);

    function validators(
        string memory status,
        bytes memory nextKey
    ) external view returns (ValidatorsResponse memory);

    function validator(
        string memory validatorAddress
    ) external view returns (Validator memory);

    function pool() external view returns (Pool memory);

    function params() external view returns (Params memory);
}

contract StakingManager {
    IStakingPrecompile constant STAKING = IStakingPrecompile(0x0000000000000000000000000000000000001005);

    event Delegated(address indexed user, string validator, uint256 amount);
    event Undelegated(address indexed user, string validator, uint256 amount);
    event Redelegated(address indexed user, string fromValidator, string toValidator, uint256 amount);

    // Delegate user's SEI to a validator
    function delegateToValidator(string memory validatorAddress) external payable {
        require(msg.value > 0, "Amount must be greater than 0");

        bool success = STAKING.delegate{value: msg.value}(validatorAddress);
        require(success, "Delegation failed");

        emit Delegated(msg.sender, validatorAddress, msg.value);
    }

    // Undelegate SEI from a validator (amount in 6 decimal precision - uSEI)
    function undelegateFromValidator(
        string memory validatorAddress,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");

        bool success = STAKING.undelegate(validatorAddress, amount);
        require(success, "Undelegation failed");

        emit Undelegated(msg.sender, validatorAddress, amount);
    }

    // Redelegate SEI between validators (amount in 6 decimal precision - uSEI)
    function redelegateBetweenValidators(
        string memory fromValidator,
        string memory toValidator,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");

        bool success = STAKING.redelegate(fromValidator, toValidator, amount);
        require(success, "Redelegation failed");

        emit Redelegated(msg.sender, fromValidator, toValidator, amount);
    }

    // Get delegation info for a user and validator
    function getDelegationInfo(
        address delegator,
        string memory validatorAddress
    ) external view returns (IStakingPrecompile.Delegation memory) {
        return STAKING.delegation(delegator, validatorAddress);
    }

    // Helper function to convert SEI to uSEI (6 decimals)
    function seiToUsei(uint256 seiAmount) public pure returns (uint256) {
        return seiAmount * 1e6;
    }

    // Helper function to convert uSEI to SEI
    function useiToSei(uint256 useiAmount) public pure returns (uint256) {
        return useiAmount / 1e6;
    }
}

This is a simplified example for demonstration purposes. When someone delegates through this contract, the delegation is recorded under the contract address, not under the user’s address. Maintain a correct mapping in the contract to track user delegations.

Client integration example

import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const StakingManager = await ethers.getContractFactory('StakingManager');
  console.log('Deploying StakingManager...');
  const stakingManager = await StakingManager.deploy();

  await stakingManager.waitForDeployment();
  console.log('StakingManager deployed to:', await stakingManager.getAddress());

  const validatorAddress = 'seival......123';

  const amount = 1;
  const trimmedAmount = amount.toFixed(6);
  const formattedAmount = ethers.parseEther(trimmedAmount.toString());

  const delegate = await stakingManager.delegateToValidator(validatorAddress, { value: formattedAmount });

  await delegate.wait();
  console.log('Delegation transaction hash:', delegate.hash);

  // Use deployer address for querying delegation
  const queryDelegation = await stakingManager.getDelegationInfo(deployer.address, validatorAddress);
  console.log('Delegation Info:', queryDelegation);

  const undelegateAmount = ethers.parseUnits(trimmedAmount.toString(), 6);
  const undelegate = await stakingManager.undelegateFromValidator(validatorAddress, undelegateAmount);

  await undelegate.wait();
  console.log('Undelegation transaction hash:', undelegate.hash);

  const redelegate = await stakingManager.redelegateBetweenValidators(
    validatorAddress,
    'seival.....123', // Replace with the new validator address
    undelegateAmount
  );

  await redelegate.wait();
  console.log('Redelegation transaction hash:', redelegate.hash);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Security considerations & risks

Unbonding period

21-day lock: For 21 days, undelegated tokens cannot be transferred and do not earn rewards.
No exceptions: After the unbonding starts, you cannot cancel it.
Planning: Consider the unbonding period when you manage liquidity needs.

Validator selection criteria

Commission rate: Commission is typically 1% to 10%. A lower commission means more rewards for you.
Uptime: Look for validators with high uptime (99% or more).

Redelegation complexity

7-transaction limit: You can redelegate from the same validator to the same destination validator only 7 times in 21 days.
Serial blocking: After you redelegate from A to B, you cannot redelegate from B to C for 21 days.
Each redelegation starts its own 21-day timer.

Troubleshooting

Common issues and solutions

// Set appropriate gas limits for different operations
const delegateTx = await staking.delegate(validatorAddress, {
  value: amount,
  gasLimit: 300000
});

Error code reference

Error	Cause	Solution
`insufficient funds`	Not enough SEI for the operation	Check the balance and reduce the amount
`validator does not exist`	Invalid validator address	Verify the validator address format
`invalid delegation amount`	Amount formatting issue	Use the correct decimal precision
`commission rate too high`	Commission above the max rate	Lower the commission rate
`commission change too frequent`	Commission changed within 24 hours	Wait 24 hours between changes
`self delegation too low`	Below the minimum self-delegation	Increase the self-delegation amount
`too many redelegations`	Exceeded the limit of 7 redelegations	Wait for the earliest redelegation to expire

FAQ: precision and normalization

What are the base units and precision standards for SEI across operations?
- delegate(): Accepts msg.value in wei (18 decimals), but the precompile truncates it internally to 6-decimal uSEI. The effective granularity is 1 uSEI = 1e12 wei.
- undelegate() and redelegate(): Amounts use 6-decimal uSEI.
- Staking queries: Balances are 6-decimal uSEI, and shares are 18-decimal. The Distribution rewards() query returns 18-decimal DecCoins, but withdrawn amounts are 6-decimal uSEI.
Should applications normalize between 18 and 6 decimals?
- Yes. For reconciliation, convert delegate wei to uSEI with integer division by 1e12 (floor). For display, convert to SEI (wei → /1e18, uSEI → /1e6).
Is this behavior consistent and intentional?
- Yes. This behavior is intentional, and there is no plan to change it. Delegation uses EVM-native msg.value (18 decimals). Staking operations run in the Cosmos staking module, which uses 6-decimal uSEI.
Why does one chain use multiple decimal precisions?
- The precompile bridges EVM conventions (18-decimal msg.value) and the native 6-decimal accounting of the Cosmos staking module. At the same time, queries and writes other than delegate() stay consistent at 6 decimals.

Important notes

Remember this rule: delegate() uses 18 decimals, undelegate() and redelegate() use 6 decimals, and delegation() returns 6 decimals.

Decimal precision

delegate() uses 18 decimals (wei) for msg.value
undelegate() and redelegate() use 6 decimals (uSEI) for amount parameters
Query results return amounts in 6-decimal precision
Best practice: Use the appropriate conversion function for each operation
Rewards and claims (Distribution precompile): The rewards() query returns 18-decimal DecCoins. Withdrawn amounts (events) are 6-decimal uSEI.
Granularity: The msg.value of delegate() must be a multiple of 1e12 wei (the last 12 digits are zero). The precompile truncates it to 6 decimals internally.

Validator addresses

Use valid Sei validator addresses with the seivaloper1... prefix.
These are Cosmos-format addresses, not EVM addresses.

Staking risks

Unbonding: A 21-day waiting period applies to undelegated tokens.
Redelegation limits: Complex rules apply to redelegation frequency and serial redelegations.

Commission and rewards

Validators keep a commission percentage.
Rewards are distributed in proportion to delegation amounts.
Choose validators based on commission, uptime, and governance participation.

​How does the staking precompile work?

​Use cases

​What you’ll learn in this guide

​Events

​Listening for events

​Functions

​Transaction functions

​Query functions

​Using the precompile

​Setup

​Prerequisites

​Install dependencies

​Import precompile components

​Contract initialization

​Critical: understanding decimal precision

​Mixed decimal precision system

​How this works in practice

​Why this mixed system exists

​Best practice: different conversion for different functions

​Normalization guidelines (clients and indexers)

​Decimal conversion helpers

​Step-by-step guide: Using the staking precompile

​Delegate tokens

​Undelegate tokens

​Redelegate tokens

​Query a delegation

​Create a validator

​Edit a validator

​Query validators

​Query a specific validator

​Query all delegations for an address

​Query unbonding delegations

​Query redelegations

​Query staking pool and parameters

​Query historical validator info

​Advanced usage examples

​Portfolio rebalancing

​Complete integration example

​Security considerations & risks

​Unbonding period

​Validator selection criteria

​Redelegation complexity

​Troubleshooting

​Common issues and solutions

​Gas-related issues

​Error code reference

​FAQ: precision and normalization

​Important notes

​Decimal precision

​Validator addresses

​Staking risks

​Commission and rewards

How does the staking precompile work?

Use cases

What you’ll learn in this guide

Events

Listening for events

Functions

Transaction functions

Query functions

Using the precompile

Setup

Prerequisites

Install dependencies

Import precompile components

Contract initialization

Critical: understanding decimal precision

Mixed decimal precision system

How this works in practice

Why this mixed system exists

Best practice: different conversion for different functions

Normalization guidelines (clients and indexers)

Decimal conversion helpers

Step-by-step guide: Using the staking precompile

Delegate tokens

Undelegate tokens

Redelegate tokens

Query a delegation

Create a validator

Edit a validator

Query validators

Query a specific validator

Query all delegations for an address

Query unbonding delegations

Query redelegations

Query staking pool and parameters

Query historical validator info

Advanced usage examples

Portfolio rebalancing

Complete integration example

Security considerations & risks

Unbonding period

Validator selection criteria

Redelegation complexity

Troubleshooting

Common issues and solutions

Gas-related issues

Error code reference

FAQ: precision and normalization

Important notes

Decimal precision

Validator addresses

Staking risks

Commission and rewards