StakeWise 以太坊质押技能

在 StakeWise V3 上质押 ETH，获得 osETH（流动性质押代币）。在保持 ETH 流动性的同时赚取质押奖励。

该技能的功能

• 质押 ETH → 获得 osETH 代币（自动处理状态更新）
• 赎回 ETH → 销毁 osETH 换回 ETH
• 查询已质押仓位 → 查看金库份额及已获奖励
• 监控金库状态 → 检查是否需要 keeper 状态更新
• 查询收获证明（harvest proofs） → 从子图（subgraph）获取存款对应的 Merkle 证明

必需的凭据

请设置以下环境变量，或直接编辑脚本文件：

export STAKEWISE_VAULT="0x8A93A876912c9F03F88Bc9114847cf5b63c89f56"
export KEEPER="0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5"
export PRIVATE_KEY="your_private_key"
export MY_ADDRESS="your_address"
export RPC_URL="https://ethereum-rpc.publicnode.com"

快速开始

# 质押 0.1 ETH（自动处理状态更新）
node scripts/stake.mjs 0.1

# 查询已质押仓位
node scripts/position.js

# 赎回 0.05 osETH
node scripts/unstake.js 0.05

# 检查是否需要状态更新
node scripts/check-state.js

StakeWise V3 工作原理

架构概览

StakeWise V3 使用 keeper-oracle 模式 进行状态更新：

User (EOA/UP)
    ↓
Vault Contract
    ↓
Keeper (Oracle) - 验证并处理奖励
    ↓
osETH Token - 流动性质押代币

核心组件

状态更新机制

为何需要状态更新？

• StakeWise 通过验证者在链下累积奖励
• Keeper 定期执行“收获（harvest）”并将状态发布至链上
• 用户仅可在状态最新时进行存款操作

何时需要状态更新？

const vault = new ethers.Contract(vaultAddress, vaultAbi, provider);
const needsUpdate = await vault.isStateUpdateRequired();
// 返回 true 表示必须先更新状态，再执行存款

质押流程（含状态更新）

步骤 1：检查状态
    用户
      ↓
    vault.isStateUpdateRequired()
      ↓
    返回：true（需更新）

步骤 2：向子图查询收获参数
    用户
      ↓
    向 StakeWise 子图发起 POST 请求
      ↓
    返回：rewardsRoot、reward、unlockedMevReward、proof[]

步骤 3：更新状态并存款
    用户
      ↓
    vault.updateStateAndDeposit(harvestParams, receiver, referrer)
      ↓
    Keeper 验证收获结果
      ↓
    Vault 向 receiver 铸造 osETH
      ↓
    用户收到 osETH

详细用法

质押 ETH（含完整状态更新流程）

import { ethers } from 'ethers';
import fetch from 'node-fetch';

// 初始化
const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

// Vault ABI（最小化定义）
const VAULT_ABI = [
  'function isStateUpdateRequired() view returns (bool)',
  'function updateStateAndDeposit(tuple(bytes32 rewardsRoot, uint256 reward, uint256 unlockedMevReward, bytes32[] proof) harvestParams, address receiver, address referrer) external payable',
  'function deposit(address receiver, address referrer) external payable'
];

const vault = new ethers.Contract(
  process.env.STAKEWISE_VAULT,
  VAULT_ABI,
  wallet
);

// 质押金额
const stakeAmount = ethers.parseEther('0.1'); // 0.1 ETH

// 步骤 1：检查是否需要状态更新
const needsUpdate = await vault.isStateUpdateRequired();
console.log('状态更新是否必需：', needsUpdate);

if (needsUpdate) {
  // 步骤 2：向子图查询收获参数
  const subgraphQuery = {
    query: `
      query getHarvestProofs($vault: String!) {
        harvestProofs(
          where: { vault: $vault }
          orderBy: blockNumber
          orderDirection: desc
          first: 1
        ) {
          rewardsRoot
          reward
          unlockedMevReward
          proof
        }
      }
    `,
    variables: {
      vault: process.env.STAKEWISE_VAULT.toLowerCase()
    }
  };

  const response = await fetch('https://graphs.stakewise.io/mainnet-a/subgraphs/name/stakewise/prod', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(subgraphQuery)
  });

  const data = await response.json();
  const harvestProof = data.data.harvestProofs[0];

  // 步骤 3：调用 updateStateAndDeposit
  const harvestParams = {
    rewardsRoot: harvestProof.rewardsRoot,
    reward: BigInt(harvestProof.reward),
    unlockedMevReward: BigInt(harvestProof.unlockedMevReward),
    proof: harvestProof.proof
  };

  const tx = await vault.updateStateAndDeposit(
    harvestParams,
    process.env.MY_ADDRESS,  // 接收方
    ethers.ZeroAddress,       // 推荐人（可选）
    { value: stakeAmount }
  );

  const receipt = await tx.wait();
  console.log(`已质押 ${ethers.formatEther(stakeAmount)} ETH，并完成状态更新`);
  console.log(`交易哈希：${receipt.hash}`);
} else {
  // 简单存款（无需状态更新）
  const tx = await vault.deposit(
    process.env.MY_ADDRESS,
    ethers.ZeroAddress,
    { value: stakeAmount }
  );

  const receipt = await tx.wait();
  console.log(`已质押 ${ethers.formatEther(stakeAmount)} ETH`);
  console.log(`交易哈希：${receipt.hash}`);
}

查询已质押仓位

const OSETH_ABI = [
  'function balanceOf(address) view returns (uint256)',
  'function convertToAssets(uint256 shares) view returns (uint256)'
];

// 从 Vault 获取 osETH 代币地址
const osEthAddress = await vault.osToken();
const osEth = new ethers.Contract(osEthAddress, OSETH_ABI, provider);

const osEthBalance = await osEth.balanceOf(process.env.MY_ADDRESS);
const underlyingEth = await osEth.convertToAssets(osEthBalance);

console.log(`osETH 余额：${ethers.formatEther(osEthBalance)}`);
console.log(`等价 ETH：${ethers.formatEther(underlyingEth)}`);

赎回 ETH

const VAULT_FULL_ABI = [
  'function redeem(uint256 shares, address receiver, address owner) returns (uint256 assets)',
  'function maxRedeem(address owner) view returns (uint256)'
];

const vaultFull = new ethers.Contract(
  process.env.STAKEWISE_VAULT,
  VAULT_FULL_ABI,
  wallet
);

// 查询最大可赎回份额
const maxShares = await vaultFull.maxRedeem(process.env.MY_ADDRESS);
console.log(`最大可赎回 osETH：${ethers.formatEther(maxShares)}`);

// 赎回指定份额
const sharesToRedeem = ethers.parseEther('0.05');
const tx = await vaultFull.redeem(
  sharesToRedeem,
  process.env.MY_ADDRESS,  // 接收方
  process.env.MY_ADDRESS   // 所有者
);

const receipt = await tx.wait();
console.log(`已赎回 ${ethers.formatEther(sharesToRedeem)} osETH，换得 ETH`);
console.log(`交易哈希：${receipt.hash}`);

子图（Subgraph）查询

获取最新收获证明（harvest proof）

const query = {
  query: `
    query {
      harvestProofs(
        orderBy: blockNumber
        orderDirection: desc
        first: 1
      ) {
        id
        vault
        rewardsRoot
        reward
        unlockedMevReward
        proof
        blockNumber
      }
    }
  `
};

const response = await fetch('https://graphs.stakewise.io/mainnet-a/subgraphs/name/stakewise/prod', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(query)
});

const data = await response.json();
console.log(data.data.harvestProofs[0]);

获取金库（Vault）状态

const query = {
  query: `
    query {
      vaults(first: 1) {
        id
        address
        totalAssets
        totalShares
        apr
      }
    }
  `
};

常见问题

“状态更新必需（State update required）”

• Keeper 尚未发布近期奖励数据
• 请向子图查询最新的收获证明（harvest proof）
• 应使用 updateStateAndDeposit() 替代 deposit()

“收获证明无效（Invalid harvest proof）”

• 证明可能已过期
• 务必在执行存款前立即查询子图
• 每份证明均与特定区块绑定

“份额不足（Insufficient shares）”

• 尝试赎回的 osETH 数量超出当前持有量
• 请检查余额：osETH.balanceOf(yourAddress)

“金库已暂停（Vault is paused）”

• 可能触发了紧急暂停机制
• 可通过 vault.paused() 检查状态
• 需等待 StakeWise 团队解除暂停

重要说明

• 年化收益率（APY）不固定：取决于以太坊验证者奖励，通常为 3–5%
• osETH 支持重定基（rebasing）：随着奖励累积，余额自动增长
• 依赖 Keeper：存款操作要求状态有效（Keeper 必须处于活跃状态）
• Gas 成本差异：状态更新所需 Gas 高于简单存款
• MEV 奖励：收获内容中包含 MEV 提取奖励

参考资料

• StakeWise 应用：https://app.stakewise.io
• StakeWise 文档：https://docs.stakewise.io
• 子图（Subgraph）：https://graphs.stakewise.io/mainnet-a/subgraphs/name/stakewise/prod
• Vault 地址：0x8A93A876912c9F03F88Bc9114847cf5b63c89f56
• Keeper 地址：0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5