Execute Bifrost vETH liquid staking operations: mint, redeem, and claim.

Contract & Network

vETH is deployed on Ethereum and three L2 networks. The same contract address is used across all chains.

Configuration

On first run, ask the user whether they want to configure custom settings. If not, use the defaults above.

Environment Variables

Wallet Setup

Two signing modes. Default is manual signing (no setup needed).

Default: Manual Signing

Output complete transaction details (to, value, data, gas, chainId). User signs with their own wallet (MetaMask, Ledger, CLI, etc.).

Option: Agent-Side Signing

Set BIFROST_PRIVATE_KEY as an environment variable, or import via Foundry keystore:

cast wallet import bifrost-agent --interactive

When BIFROST_PRIVATE_KEY is set, the agent can sign and broadcast transactions directly using cast send.

Quick Reference

Write Operations

Pre-Execution Query Functions

How to Call

Read queries — use eth_call (no gas):

# Method A: cast (preferred)
cast call  \
  "()()"  \
  --rpc-url 
# Method B: curl (if cast unavailable)
curl -s -X POST  \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_call","params":[{"to":"","data":""},"latest"]}'

If previewDeposit or previewRedeem fails, fall back to convertToShares / convertToAssets (same encoding).

Write transactions — use cast send (requires wallet):

# Mint vETH (stake native ETH)
cast send  \
  "depositWithETH()" --value  \
  --rpc-url  --private-key 
# Redeem vETH (unstake)
cast send  \
  "redeem(uint256,address,address)"    \
  --rpc-url  --private-key 
# Claim ETH (withdraw completed redemptions)
cast send  \
  "withdrawCompleteToETH()" \
  --rpc-url  --private-key 

Calldata Encoding (for manual signing output)

• uint256: convert wei to hex, left-pad to 64 chars
• address: remove 0x prefix, left-pad to 64 chars
• canWithdrawalAmount returns 3 × uint256 (192 hex chars): (totalAvailableAmount, pendingDeleteIndex, pendingDeleteAmount). First 64 chars = claimable ETH amount

API 1: Mint vETH (Stake ETH)

Pre-Execution

• Query rate: previewDeposit(amount) → expected vETH
• Check wallet: BIFROST_PRIVATE_KEY env var or Foundry keystore bifrost-agent
• Display preview and wait for CONFIRM

Transaction

Manual Signing Output

To:       
Value:    {wei} ({amount} ETH)
Data:     0x1166dab6
ChainId:  {chainId}

API 2: Redeem vETH (Unstake)

Pre-Execution

• Check balanceOf(user) ≥ redeem amount
• Query previewRedeem(shares) → expected ETH
• Check maxRedeem(user)
• Display preview (warn: ETH enters queue, NOT instant) and wait for CONFIRM

Transaction

API 3: Claim Redeemed ETH

Pre-Execution

• Check canWithdrawalAmount(user) — first return value = claimable amount
• If 0: inform user redemption may still be processing
• If > 0: display claimable amount and wait for CONFIRM

Transaction

Agent Behavior

• Environment check: on first interaction, ask user if they want to configure BIFROST_CHAIN, BIFROST_RPC_URL, or BIFROST_PRIVATE_KEY. If not, use Ethereum Mainnet defaults with manual signing mode
• RPC selection: use BIFROST_RPC_URL if set; otherwise use per-chain default RPC. Fall back to per-chain fallback RPC on failure
• Multi-chain awareness: when user specifies a chain (e.g. "on Base", "on Arbitrum"), switch to that chain's RPC, WETH address, and chainId accordingly
• Wallet detection: check BIFROST_PRIVATE_KEY env var or Foundry keystore bifrost-agent. If found, ask user whether to use it. If not, output tx data for manual signing
• CONFIRM required: display transaction preview (amount, rate, expected output, chain) and require user to type CONFIRM before any write
• Private key import requires CONFIRM: show security warning first, require CONFIRM before accepting key
• Key retention is user-controlled: after tx, ask user whether to keep or delete the key
• Balance pre-check: verify sufficient ETH/vETH before building tx
• Prefer cast, fall back to curl: use pre-computed calldata from selector table if cast fails
• No credential display: never echo private keys; truncate addresses (first 6 + last 4)
• Post-completion tip: if no wallet configured, suggest "set up wallet" after operation
• After successful tx, provide block explorer link: https://etherscan.io/tx/{hash} (Ethereum), https://basescan.org/tx/{hash} (Base), https://optimistic.etherscan.io/tx/{hash} (Optimism), https://arbiscan.io/tx/{hash} (Arbitrum)
• Useful links: direct users to Bifrost vETH page or Bifrost App when relevant

Security

• Private keys are opt-in only — default outputs unsigned tx data
• Explicit CONFIRM for every write operation
• Validate amounts against balance and protocol limits
• Recommend dedicated wallet with limited funds for agent-side signing

Error Handling

Notes

• depositWithETH() wraps ETH → WETH internally via WETH.deposit(). No ERC-20 approval needed. For direct WETH deposits, use deposit(uint256,address) instead (requires WETH approval)
• withdrawCompleteToETH() internally calls withdrawCompleteTo(address(this)) to receive WETH, then unwraps to ETH via WETH.withdraw(), then sends ETH to caller. If ETH transfer fails, use withdrawComplete() to receive WETH instead
• Redemption is NOT instant — redeem() / withdraw() add entries to the withdrawal queue, processed in batches via Bifrost cross-chain mechanism
• All write functions are protected by whenNotPaused and nonReentrant (ReentrancyGuardUpgradeable)
• Gas estimates are approximate; use cast estimate for accuracy