Direct Staking Guide for Third-Party Integrators

Overview

Traditionally, staking Layer 1 (L1) assets from a Layer 2 (L2) network has been a complex process for users. It often involves manually bridging assets back to the L1, staking them, and then bridging the resulting liquid staking tokens (LSTs) or liquid restaking tokens (LRTs) back to the L2. This process is slow, expensive, and creates a fragmented user experience.

Chainlink's Cross-Chain Interoperability Protocol (CCIP) and its Programmable Token Transfers feature address this problem. This guide explains how to integrate with direct staking solutions that allow users to stake an L1 asset from an L2 and receive the representative LST or LRT directly on that same L2 in a single transaction. This pattern is used by protocols including Lido, Frax, and EigenPie.

Throughout this guide, we will use Lido's direct staking implementation as a practical example to demonstrate how to integrate this solution.

Before you begin

Before you start integrating a direct staking solution into your frontend or application, please review the following requirements and resources:

• Familiarize yourself with the architecture, workflow, and cross-chain mechanics by reading the technical blog post: Scaling Staking Protocols Cross-Chain – Chainlink Blog.
• You should be comfortable building web applications that interact with blockchain networks using JavaScript or TypeScript. Experience with popular Web3 libraries (such as ethers.js) is recommended.
• Confirm that your integration targets the correct contract addresses for the protocol you are integrating. This guide provides addresses for the Lido example.
• For a practical reference, consider reviewing applications that have already integrated Lido direct staking:
  • XSwap
  • Interport

Key Concepts

Slow Stake (Direct Approach)

This method is ideal when an L2 liquidity pool is depleted or when a protocol prefers not to manage one. A user's (W)ETH is securely bridged to L1, staked, and the resulting LST is then bridged back to the user on the L2. The slowStake function in the CustomSender contract handles this entire cross-chain workflow.

Estimated time: ~40-60mins

Fast Stake (Liquidity Pool Approach)

This method provides immediate execution. Users swap their (W)ETH for the corresponding LST from a pre-existing liquidity pool on the L2. The fastStake function in the CustomSender contract facilitates this swap using a Chainlink Price Feed for exchange rate determination.

The (W)ETH that accumulates in the pool is then periodically sent to L1 in batches to be staked. The newly minted LSTs are sent back to the L2 to replenish the pool. This replenishing process is often managed by Chainlink Automation to improve cost-efficiency by batching transactions.

Estimated time: Instant for amounts less than the total available liquidity

Integration Guide

As a developer building offchain components, you'll primarily interact with the Custom Sender contract (proxy address), which serves as the main entry point for all staking operations.

Core Functions

The Custom Sender contract provides two key functions:

• fastStake(): Instant token swaps using L2 liquidity pools
• slowStake(): Cross-chain staking when pools lack liquidity

Contract Addresses

The following contract addresses are for the Lido protocol as an example implementation. When integrating a different protocol, ensure you are using their deployed contract addresses.

Network	Custom Sender Contract Address (Proxy)	Oracle Pool Address (Reference Only)
Optimism	0x328de900860816d29D1367F6903a24D8ed40C997	0x6F357d53d6bE3238180316BA5F8f11467e164588
Base	0x328de900860816d29D1367F6903a24D8ed40C997	0x6F357d53d6bE3238180316BA5F8f11467e164588
Arbitrum	0x72229141D4B016682d3618ECe47c046f30Da4AD1	0x9c27c304cFdf0D9177002ff186A4aE0A5489Aace

Available Use Cases

The chainlink-csr repository provides protocol-agnostic implementations for direct staking operations. These implementations include fee encoding, allowance management, and cross-chain tracking functionality.

Core Estimation Functions

Pool Monitoring & Analysis

Transaction Execution

Allowance Management

Complete Integration Examples

The chainlink-csr repository provides comprehensive implementation examples demonstrating different patterns:

Fast Stake Implementation

Slow Stake Implementation

Complete implementations covering all four payment combinations:

Utility and Analysis

Key Implementation Details

This section provides implementation guidance for integrating direct staking functionality into your offchain components. There are two main staking methods:

Fast Staking:

• Stake ETH or WETH for instant swaps using L2 liquidity pools
• Simple payment: just the staking amount (no additional fees for users)

Slow Staking:

• Stake ETH or WETH via cross-chain bridging when pools lack liquidity
• Complex payment structure: staking amount + cross-chain fees
• CCIP fees (L2→L1): Paid in ETH or LINK tokens
• Bridge fees (L1→L2): Always paid in ETH

Fast Stake Pool Management

• Dynamic pool discovery: Call getOraclePool() on Custom Sender to retrieve pool address
• Liquidity validation: Check pool token balances to ensure sufficient liquidity for the desired transaction amount
• Pool health monitoring: Monitor pool composition ratios (WETH vs wstETH balances) to assess pool health

Reference Implementation: See getPoolBalances() in the chainlink-csr repository for a pool monitoring implementation that handles supported chains and provides balance analysis.

Fast Stake Exchange Rate & Fee Calculations

• Get pool fee: Call getFee() on the Oracle Pool to retrieve the current fee rate
• Get price oracle: Call getOracle() on the Oracle Pool to get the price oracle address
• Fetch exchange rate: Call getLatestAnswer() on the price oracle for the current rate
• Understand oracle data: The oracle returns how much ETH/WETH is needed to get 1 wstETH (e.g., 1.2054 means you need 1.2054 ETH to get 1 wstETH)
• Fee application order: Pool fees are applied to input tokens before price conversion
• Account for slippage: Calculate minimum acceptable output to protect against price changes during transaction execution: minAmountOut = expectedOutput * (1 - slippageTolerance) (e.g., for 2% tolerance: minAmountOut = expectedOutput * 0.98)

Reference Implementations:

• estimateFastStake() - Reproduces onchain math for fee calculations and price conversions with liquidity validation
• getTradingRate() - Fetches current exchange rates, oracle pricing, and pool fees for display in your UI

Slow Stake Fee Management & Encoding

Slow stake involves two types of fees that must be calculated and encoded before calling the slowStake() function:

1. CCIP fees for bridging from your L2 to Ethereum (paid in ETH or LINK)
2. Bridge fees for the return journey from Ethereum back to your L2 (paid in ETH)

Implementation approach: The repository provides ready-to-use functions that handle all the complex encoding for you. Most developers can use these utilities without understanding the low-level implementation.

Payment Methods:

• Staking with native ETH: Use address(0) as token parameter, send ETH value with transaction
• Staking with WETH: Use WETH token address, requires prior WETH allowance approval
• Fee payments: Choose between all-ETH (ccipFees + bridgeFees) or ETH+LINK (bridgeFees in ETH, ccipFees in LINK)

Reference Implementations:

• estimateSlowStakeFees() - Fee estimation with encoding for supported bridge types and payment methods
• executeSlowStake() - Full execution flow with automatic allowance management and cross-chain tracking

Token Allowance Management

ERC-20 tokens (WETH, LINK) require explicit approval before the Custom Sender contract can transfer them on your behalf. Native ETH payments don't require allowances.

Allowance Scenarios:

• Fast Stake with WETH: Requires WETH allowance equal to staking amount
• Slow Stake with WETH + CCIP fees in ETH: Requires WETH allowance for staking amount only (CCIP fees and Destination→Origin bridge fees both paid in native ETH)
• Slow Stake with WETH + CCIP fees in LINK: Requires both WETH allowance (for staking) and LINK allowance (for CCIP fees). Destination→Origin bridge fees still paid in native ETH
• Native ETH payments: No allowances needed (uses {value: amount} in transaction for all costs)

Best Practices:

• Pre-flight checks: Always verify allowances before prompting user transactions
• Approval amount options: Let users choose between unlimited (MaxUint256) for convenience or exact amounts for security
• Balance validation: Check both allowance and actual token balance sufficiency
• Error handling: Provide clear guidance when allowances are insufficient

Reference Implementation: See checkTokenAllowance() for allowance checking that detects the staking token from the Custom Sender contract and provides allowance status analysis.

Error Handling & Fallbacks

Fast Stake Error Scenarios

• OraclePoolInsufficientTokenOut: Pool lacks sufficient LST tokens for the swap

  • User Action: Display clear message about liquidity shortage and suggest Slow Stake as alternative
  • Prevention: Query Oracle Pool balance before transaction to show real-time availability

• OraclePoolInvalidPrice: Oracle reports invalid or decreased exchange rate (potential slashing event)

  • System Action: Immediately pause all Fast Stake operations for the protocol
  • User Action: Inform users that Fast Stake is temporarily unavailable and suggest Slow Stake as alternative

Slow Stake Tracking & Monitoring

• CCIP message tracking: Use message ID from transaction receipt to track Origin→Destination progress via CCIP Explorer
• Bridge completion timing:
  • Base/Optimism: Destination→Origin bridge typically completes in ~3 minutes
  • Arbitrum: Destination→Origin bridge typically takes ~8-9 minutes
• Native bridge limitations: Destination→Origin transfers via native bridges don't provide trackable message IDs

Balance & Allowance Errors

• ETH balance errors: Show specific shortfall amounts and required totals (staking + fees)
• WETH balance errors: Display both current balance and required amount for staking
• LINK balance errors: Show LINK balance vs required CCIP fee amount
• Allowance errors: Guide users through approval process with clear explanations

Slippage Protection Implementation

User configuration: Let users choose their slippage tolerance (typically 1-5%). For added protection against oracle price updates, you can recommend using 3.18% APR as a buffer in your calculations.

minAmountOut = expectedOutput * (1 - slippageTolerance)

Proactive Monitoring

• Pool health checks: Regularly query Oracle Pool balance to disable Fast Stake when liquidity is low
• Oracle price validation: Handle OraclePoolInvalidPrice errors and implement automatic system pausing
• Contract address verification: Always use proxy addresses (not implementation addresses) to avoid integration errors during upgrades

Tutorial: Staking with Lido on Base Mainnet

This tutorial guides you through the process of using the offchain library to interact with the Lido Direct Staking solution on Base Mainnet. You will learn how to check pool status, estimate transaction outcomes, and execute both Fast and Slow stakes.

yarn example:lido:pool

🔍 Checking Base (Chain ID: 8453)
Explorer: https://basescan.org

📋 Contract Info:
  Pool Address: 0x6F357d53d6bE3238180316BA5F8f11467e164588
  Sender Address: 0x328de900860816d29D1367F6903a24D8ed40C997

💰 WETH (Wrapped Ether):
  Address: 0x4200000000000000000000000000000000000006
  Balance: 0.152201 WETH
  Decimals: 18

🪙 wstETH (Wrapped liquid staked Ether 2.0):
  Address: 0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452
  Balance: 31.432578849217100358 wstETH
  Decimals: 18

📊 Pool Composition:
  Balance Ratio: 206.520 wstETH/WETH
  Status: ✅ Pool appears healthy

yarn example:lido:trading

🔍 Checking Base (Chain ID: 8453)
Explorer: https://basescan.org

🔄 Trading Pair: WETH → wstETH

🔮 Oracle Information:
  Oracle Price: 1.205291056439143428 (WETH per wstETH)
  Heartbeat: 86400 seconds (1 day)

💰 Fee Information:
  Fee Rate: 0.00%

📊 Exchange Rates:
  Oracle Rate: 1 wstETH = 1.205291056439143428 WETH
  Effective Rate: 1 WETH = 0.82967511843517208 wstETH
  Impact: After 0.00% fee

yarn example:lido:estimate-faststake

🔍 Testing Lido Fast Stake Estimation on Base
Explorer: https://basescan.org

💰 Estimating 0.1 WETH...

🏊 Pool Liquidity:
  Available wstETH: 31.432578849217100358
  Sufficient Liquidity: ✅ Yes

🎯 Expected Output:
  You'll receive: 0.082967511843517208 wstETH

yarn example:lido:fast-stake-native

🚀 FastStake with Native ETH on Base
✅ Transaction confirmed in block 31511221

🎉 Transaction Successful!
════════════════════════════════════════════════════════════════════════════════
📊 Transaction Details:
  TX Hash: 0xb70e3baf935dc1784c38bf67972b45a51a969896695fd5478c1e61affc1e387e

💱 Staking Summary:
  Input: 0.001 ETH (native)
  Output: 0.000829675118435172 wstETH

yarn example:lido:estimate-slowstake

🔍 Estimating fees for Base...
✅ Fee estimation completed!

💸 Fee Breakdown:
  Staking Amount: 0.01 ETH
  CCIP Fee (O→D): 0.003116936361252889 ETH
  Bridge Fee (D→O): 0.0 ETH

💰 Requirements:
  ETH Required: 0.013116936361252889 ETH

yarn example:lido:slow-stake-native

🎉 SlowStake Transaction Successful!
📊 Transaction Details:
  TX Hash: 0x4aa7d4e4ff650febe32aec89b3132efc582d7d30e42343ec1c99d1ac2dfe67e2
  Message ID: 0x3e44ae54221139386ca4e22bcfe6600b7d47bc6af446e72ad549ede0a9a2c752

📍 How to Track Your Cross-Chain Transaction:
🔗 Step 1: Track CCIP Message (Origin → Destination)
   Monitor: https://ccip.chain.link/msg/0x3e44ae54221139386ca4e22bcfe6600b7d47bc6af446e72ad549ede0a9a2c752
   Wait for status to show "Success" (usually 10-20 minutes)

What's Next?

This tutorial covered the basic scenarios using native ETH, but the chainlink-csr repository provides many more implementation patterns and payment combinations. You can explore further by:

Additional Fast Stake Scenarios

• Wrapped Native Token Fast Stake - Use WETH instead of native ETH, which includes automatic allowance management

  yarn example:lido:fast-stake-wrapped
  

Additional Slow Stake Payment Combinations

This tutorial only showed native ETH staking with native ETH CCIP fees, but there are three more combinations available:

• Native ETH + LINK CCIP - Stake ETH but pay CCIP fees with LINK tokens

  yarn example:lido:slow-stake-native-link
  

• WETH + Native ETH CCIP - Stake WETH with CCIP fees paid in ETH

  yarn example:lido:slow-stake-wrapped-native
  

• WETH + LINK CCIP - Stake WETH with CCIP fees paid in LINK

  yarn example:lido:slow-stake-wrapped-link
  

Additional Analysis Tools

• Allowance Management - Check token allowances across all supported chains

  yarn example:lido:allowance
  

• Multi-Chain Fee Comparison - Compare slow stake fees across Arbitrum, Optimism, and Base

  yarn example:lido:estimate-slowstake
  

Building Your Own Integration

The chainlink-csr repository provides reference implementations and utilities that you can adapt for your own applications:

• Reference patterns - Use the example files as templates to understand the required transaction flows and error handling
• Utility functions - Leverage the core estimation, validation, and contract interaction utilities in your own code
• Contract interfaces - Generated TypeScript types provide the necessary contract ABIs and type definitions
• Implementation guidance - Each example demonstrates proper allowance management, fee calculation, and cross-chain tracking patterns

Note that this is not a ready-to-use SDK - you'll need to adapt the reference implementations to fit your specific application architecture and requirements.