# STONE 迁移前端接口文档

本文是前端开发的统一接口入口，覆盖 Bridge 迁移说明板块、四链 STONE 赎回及 Ethereum 领取。内容依据当前仓库的 HTTP 服务和 Solidity 源码整理，更新日期：2026-11-17。页面布局和交互要求见 [页面调整清单](frontend-changes.md)，完整钱包流程见 [前端接入规范](frontend-integration.md)。

本文不代表正式环境已经部署或完成联调。服务域名、四个 B 和 Ethereum Claim 的正式地址仍需部署方提供。示例中的 `<...>` / `0x...` 是占位符，不是可直接提交的地址、root 或 proof。产品页面文案使用英文，本文的中文说明用于开发对接。

## 1. 接口总览

| 前端用途 | 接口 | 调用方 / 网络 |
| --- | --- | --- |
| 判断是否显示迁移说明，获取四链提示余额 | `GET /v1/migration/notice` | 浏览器 → 后端，无需钱包切链 |
| 获取当前 root 对应的个人累计结算额度及证明 | `GET /v1/proof` | 浏览器 → 后端 |
| 联调时检查 HTTP 进程存活 | `GET /healthz` | 可选，不用于判断领取是否可用 |
| 获取余额、额度并授权 | STONE：`balanceOf` / `allowance` / `approve` | 所选源链 |
| 提交赎回 | B：`redeem` | 所选源链，由付款钱包发交易 |
| 获取累计赎回额 | 四个 B：`totalRedeemedByRecipient` | 四条源链，按 Ethereum 收款地址查询 |
| 获取当前结算版本和已领取额 | Claim：`epoch` / `merkleRoot` / `claimed` / `paused` | Ethereum |
| 领取已结算的未领取份额 | Claim：`claim` | Ethereum，由领取地址本人发交易 |

合约 A 以及 Safe 的注资、发布 root、暂停等管理接口属于操作端，不进入本次用户前端；分别见 [A 合约](contract-a.md)、[B 操作说明](redemption-runbook.md) 和 [Claim 操作说明](claim-runbook.md)。前端不需要发起 LayerZero 消息或获取 LayerZero 费用报价。

## 2. 网络配置与数据约定

### 2.1 网络及合约地址

| 网络 | EVM chainId | STONE token | 用户迁移合约 |
| --- | --- | --- | --- |
| Manta | 169 | `0xEc901DA9c68E90798BbBb74c11406A32A70652C3` | B，待提供 |
| Scroll | 534352 | `0x80137510979822322193FC997d400D5A6C747bf7` | B，待提供 |
| Mode | 34443 | `0x80137510979822322193FC997d400D5A6C747bf7` | B，待提供 |
| Zircuit | 48900 | `0x80137510979822322193FC997d400D5A6C747bf7` | B，待提供 |
| Ethereum | 1 | `0x7122985656e38BDC0302Db86685bb972b145bD3C` | Claim，待提供 |

以上都是 EVM chainId。Ethereum 使用 `1`，不能填 LayerZero 的 `101`。每条源链分别配置并验证该链 B，不能直接套用其他链地址；独立部署的合约地址字符串可以恰好相同。

前端还需配置 `API_BASE_URL`（两个业务 HTTP 接口共用）、五链读取 RPC、交易浏览器、交易确认策略，以及正式公告外链。`API_BASE_URL` 不是原型网址。缺少 B / Claim 地址时按尚未配置处理，不用零地址或旧合约地址代替。浏览器只使用公开配置，不打包后端 RPC 密钥或管理私钥。

### 2.2 地址与金额

| 名称 / 类型 | 定义 |
| --- | --- |
| `sender` | 源链付款钱包，即 `redeem` 的 `msg.sender` |
| `ethereumRecipient` | 本次赎回指定的 Ethereum 收款地址，默认 sender，可修改 |
| `account` | 当前连接的钱包；说明板块和领取区均查询此地址 |
| `Address` | `0x` 加 40 位十六进制字符；请求地址须非零。比较时按地址字节，不区分大小写 |
| `Bytes32` | `0x` 加 64 位十六进制字符 |
| STONE 金额 | 18 位小数的原始 `uint256` 单位；HTTP 用十进制字符串，合约调用用 `bigint` |
| `epoch` | 累计结算版本，HTTP 用十进制字符串，合约调用用 `bigint` |
| `null` | 未知或不可用，不等于零；proof 的 `null` 另见第 5 节 |

`1 STONE = 1000000000000000000` 原始单位。金额和 epoch 不转成 JavaScript `Number`。解析用户输入的赎回数量时，拒绝负数、零、科学计数法、超过 18 位小数或超出 uint256 范围的值，不静默取整。查询返回的零余额、零额度和初始 epoch=0 都是合法值；epoch 不适用金额的小数换算。B 接受任意正的原始单位，包括 `1 wei`，不套用 A 的 `0.01 STONE` 操作额度限制。

修改 `ethereumRecipient` 不会改变说明板块或领取区的 `account`。给其他地址赎回的权益属于那个收款地址，不加入付款钱包的个人额度。地址格式正确不代表用户能够在 Ethereum 上控制它；领取地址为合约钱包时，必须能以该合约自己的地址调用 Claim。

## 3. HTTP 公共约定

- 请求地址：`API_BASE_URL + path`，生产环境使用 HTTPS。接口只读，不需要钱包签名、登录凭证或请求体。
- 业务使用 `GET`；也支持 `HEAD`，但 HEAD 仍执行查询，只省略响应体。允许来源的 `OPTIONS` 预检返回 `204`、无响应体，不执行业务查询。
- JSON 响应使用 `Content-Type: application/json; charset=utf-8`，并有 `Cache-Control: no-store`。这不排除后端内部缓存。
- 浏览器跨域需要服务端配置精确 Origin 白名单。默认未配置时 GET / HEAD 不返回允许跨域的响应头；不等于接口返回 403。配置白名单后，不允许的 Origin 返回 403。OPTIONS 必须有被允许的 Origin。
- 允许来源会收到 `Access-Control-Expose-Headers: Retry-After`。不要求发送 Cookie、Authorization 或其他自定义请求头。
- 正常业务 503 返回 `Retry-After: 5`，前端按秒重试。网络、网关和非 JSON 错误也按不可用处理，不能假定每个失败都有标准错误体。
- notice 与 proof 的查询参数均须恰好出现一次，不接受额外参数；参数错误返回 400。

公共错误体：

```json
{ "error": { "code": "INVALID_QUERY", "message": "..." } }
```

| HTTP | `error.code` | 含义与处理 |
| --- | --- | --- |
| 400 | `INVALID_QUERY` | 参数缺失、重复、格式不合法或多余参数；修正调用 |
| 400 | `INVALID_REQUEST` | 请求 URL 格式或长度不合法；修正调用 |
| 403 | `ORIGIN_NOT_ALLOWED` | Origin 未允许；检查部署白名单 |
| 404 | `NOT_FOUND` | 接口路径错误，不表示该用户没有权益 |
| 405 | `METHOD_NOT_ALLOWED` | 方法不支持；业务查询使用 GET |

前端应按状态码和 `error.code` 处理，不依赖 `message` 文案匹配。HTTP 成功之后仍须验证结构、账户及版本。

## 4. 迁移说明板块及四链余额

### 4.1 请求

```http
GET /v1/migration/notice?account=<当前钱包地址>
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `account` | Address | 是 | 当前连接的钱包地址 |

不传 chainId、root 或合约地址；后端统一读取已配置的五条链，与钱包当前网络无关。

### 4.2 成功响应：HTTP 200

```json
{
  "account": "0x...",
  "showNotice": true,
  "checkedAt": "2026-11-17T08:00:00.000Z",
  "sourceBalances": [
    { "chainId": 169, "chain": "manta", "balance": "1000000000000000000" },
    { "chainId": 534352, "chain": "scroll", "balance": "0" },
    { "chainId": 34443, "chain": "mode", "balance": "0" },
    { "chainId": 48900, "chain": "zircuit", "balance": null }
  ]
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `account` | Address | 查询账户，服务规范化为校验和地址 |
| `showNotice` | boolean | 是否显示整个说明板块，包括公告链接和迁移箭头 |
| `checkedAt` | string | 本轮检查完成的 UTC ISO 时间；缓存命中保留原时间，不是链上最终确认时间 |
| `sourceBalances` | array | 固定四项，顺序为 Manta、Scroll、Mode、Zircuit |
| `sourceBalances[].chainId` | number | EVM chainId |
| `sourceBalances[].chain` | string | `manta` / `scroll` / `mode` / `zircuit` |
| `sourceBalances[].balance` | string 或 null | 直接持有的源链 STONE 原始余额；`"0"` 是成功读到零，null 是未知 |

该响应没有 `schemaVersion` 字段，不要与 proof 响应混用类型。只统计钱包直接持有的源链 STONE，不统计 DeFi 仓位或普通 Ethereum STONE 余额。

后端判断规则：

| 条件 | 结果 |
| --- | --- |
| 任一源链可靠读到 `balance > 0` | 200，`showNotice: true` |
| 完整取得四个 B 的个人累计赎回额之和 S1、Ethereum 已领取额 S3，且 `S1 > S3` | 200，`showNotice: true` |
| 必要查询全部有效，四链余额都是零，且 `S1 = S3` | 200，`showNotice: false` |
| 其余无法判断的情况 | 503，不返回 `showNotice` |

合法累计结算流程下，`待结算 + 可领取 = S1 - S3`，所以该接口不读取 proof。暂停不改变已有余额和权益。后端会尝试读取全部四链余额，不因一条链有正值而提前结束。示例中 Manta 的余额已经足以确认 true，因此 Zircuit 失败时仍可以返回 200。

### 4.3 无法判断：HTTP 503

```json
{
  "account": "0x...",
  "checkedAt": "2026-11-17T08:00:00.000Z",
  "sourceBalances": [
    { "chainId": 169, "chain": "manta", "balance": "0" },
    { "chainId": 534352, "chain": "scroll", "balance": null },
    { "chainId": 34443, "chain": "mode", "balance": "0" },
    { "chainId": 48900, "chain": "zircuit", "balance": "0" }
  ],
  "error": {
    "code": "MIGRATION_STATUS_UNAVAILABLE",
    "message": "Migration status is temporarily unavailable."
  }
}
```

503 保留成功读取的余额，失败项为 null；没有 `showNotice` 字段。未配置、繁忙或整轮失败时，四项可全部为 null。后端不会把 RPC 故障、明显滞后的节点、身份校验失败或异常金额关系伪装成零。

### 4.4 前端使用与缓存

仅 HTTP 200、结构和账户匹配且 `showNotice === true` 时显示板块。未连接钱包时不请求；加载中或无法判断时暂不显示。切换账户立即清除旧结果，并取消或丢弃迟到响应。

STONE Tab 可见时每 30 秒刷新，离开 Tab / 页面隐藏时停止轮询；赎回或领取成功后重新查询。服务内成功结果缓存 30 秒，包含部分余额 null 的 200；503 不缓存。实际展示更新还受轮询和查询耗时影响。

这些余额用于提示展示，不能代替赎回前的实时余额、allowance 或交易模拟。服务启动需配置 `--notice-config`；未配置时 notice 返回 503，proof 接口仍独立工作。详细部署说明见 [迁移提示接口](migration-notice-api.md)。

## 5. Merkle proof 与累计结算额度

### 5.1 请求

前端先从 Ethereum Claim 读取当前 epoch / merkleRoot，再请求对应版本：

```http
GET /v1/proof?chainId=1&claim=<Claim地址>&epoch=<当前epoch>&root=<当前merkleRoot>&account=<当前钱包地址>
```

| 参数 | 类型 | 必填 | 约束 |
| --- | --- | --- | --- |
| `chainId` | 查询文本 `1` | 是 | 固定 Ethereum EVM chainId |
| `claim` | Address | 是 | 当前配置的 Ethereum Claim 地址 |
| `epoch` | 十进制字符串 | 是 | 正整数、无前导零、范围 `1..2^256-1` |
| `root` | Bytes32 | 是 | 当前链上 merkleRoot，不能为零 |
| `account` | Address | 是 | 当前连接的领取钱包 |

接口没有 `latest`。后端验证文件与指定版本自洽，不负责证明该版本当前生效。epoch 为 0 且 root 为零时尚未发布首期，跳过 proof 请求，按第 9 节处理。

### 5.2 有记录：HTTP 200

```json
{
  "schemaVersion": 1,
  "chainId": 1,
  "claim": "<Claim地址>",
  "token": "0x7122985656e38BDC0302Db86685bb972b145bD3C",
  "epoch": "1",
  "root": "<当前bytes32 root>",
  "account": "<当前钱包地址>",
  "found": true,
  "cumulativeAmount": "70000000000000000000",
  "leaf": "<bytes32 leaf>",
  "proof": ["<bytes32 sibling>"]
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `schemaVersion` | number | 固定 1 |
| `chainId` | number | 固定 1 |
| `claim` / `token` / `account` | Address | 领取合约、Ethereum STONE、领取账户 |
| `epoch` / `root` | string / Bytes32 | 本条证明所属版本 |
| `found` | boolean | 已验证的完整版本中是否包含该地址 |
| `cumulativeAmount` | string | 累计已结算额度 S2，包含此前已领取部分；found=true 时为正 uint256 |
| `leaf` | Bytes32 | 本账户该累计额度的叶子，仅 found=true 存在 |
| `proof` | Bytes32[] 或 null | found=true 时为数组；单叶树的合法数组可以是 `[]` |

### 5.3 无记录：HTTP 200

```json
{
  "schemaVersion": 1,
  "chainId": 1,
  "claim": "<Claim地址>",
  "token": "0x7122985656e38BDC0302Db86685bb972b145bD3C",
  "epoch": "1",
  "root": "<当前bytes32 root>",
  "account": "<当前钱包地址>",
  "found": false,
  "cumulativeAmount": "0",
  "proof": null
}
```

只有指定版本文件存在、完整验证通过且确实不包含该地址时，才返回 found=false。这是服务对完整文件的查询结果，不是链上的非成员证明。此时没有 leaf，S2 为零，但用户仍可能有尚未结算的 S1。若链上 S3 已大于零，则与完整累计名单规则矛盾，应停止领取并核对版本。文件缺失或请求失败绝不等于 found=false。

### 5.4 proof 错误

以下均为 HTTP 503，结构为 `{"error":{"code":"...","message":"..."}}`：

| `error.code` | 含义 | 前端处理 |
| --- | --- | --- |
| `PROOF_VERSION_UNAVAILABLE` | 指定版本尚未安装 | 显示证明待同步，按 Retry-After 重试，不退回旧 root |
| `PROOF_ARTIFACT_UNAVAILABLE` | 文件无法打开读取 | 暂不可用，交由运维排查 |
| `PROOF_ARTIFACT_INVALID` | 文件过大、不完整、校验失败或读取过程中异常 | 暂不可用，不使用其中的金额或证明 |
| `PROOF_SERVICE_BUSY` | 不同版本的加载并发已满 | 稍后重试 |
| `PROOF_SERVICE_ERROR` | 其他服务异常 | 暂不可用，稍后重试 |

### 5.5 前端必须完成的校验

1. 检查 schemaVersion、chainId、Claim、token、epoch、root、account 与请求及本轮链上快照一致，found 必须为布尔值，cumulativeAmount 必须是规范十进制 uint256 字符串。
2. found=true 时要求 cumulativeAmount 大于零，leaf 为 bytes32、proof 为 bytes32 数组；按以下公式重算 leaf，必须等于响应 leaf，再验证 proof 得到的 root 等于链上当前 root。
3. found=false 时必须是 `cumulativeAmount: "0"`、`proof: null` 且没有 leaf。
4. proof 的缓存键为 `(chainId, claim, epoch, root, account)`，不能只按钱包地址缓存。钱包账户或配置变化时丢弃旧响应，root 换期后重新取 proof。

```text
inner = keccak256(abi.encode(
  uint256(1), address(Claim), address(EthereumSTONE),
  uint256(epoch), address(account), uint256(cumulativeAmount)
))
leaf = keccak256(inner 的 32 字节原值)

node = leaf
对 proof 的每个 sibling：
  将 node 与 sibling 按 bytes32 数值升序排列
  node = keccak256(较小值的 32 字节 || 较大值的 32 字节)
要求 node == 当前链上 merkleRoot
```

内层使用标准 `abi.encode`，不能使用 `abi.encodePacked`。外层哈希处理原始字节，不能哈希 `"0x..."` 文本。空数组 proof 仍需校验 leaf=root，不能因数组为空禁用合法领取。

可选调用 `Claim.leafFor(epoch, account, cumulativeAmount)` 核对本地 leaf；它不证明 proof 有效，也不证明该账户还有可领取差额。参考 [Merkle 实现](../scripts/claim-merkle.ts)，浏览器应使用纯计算实现，不直接导入其 Node.js 文件依赖。

## 6. 存活检查

```http
GET /healthz
```

HTTP 200：

```json
{
  "status": "ok",
  "note": "Process liveness only; no chain or publication check."
}
```

无需参数。该接口只说明 HTTP 进程存活，不验证 RPC、notice 配置、proof 文件、已发布 root 或可领取状态。用户页面不得据此启用领取按钮。

## 7. 合约读取接口

读取使用各链 RPC 的 `eth_call`，不要求用户钱包先切换网络。接入时核对实际 RPC chainId、合约有代码、STONE decimals=18，以及 B / Claim 的链和 token 身份。

B 和 Claim 部署后初始均为暂停；前端始终以链上当前 paused 状态为准，不按“已部署”或“已有 root”推断已开放。

### 7.1 STONE ERC20：各源链

| 方法签名 | 参数 | 返回 | 用途 |
| --- | --- | --- | --- |
| `decimals() view returns (uint8)` | 无 | 18 | 验证金额精度 |
| `balanceOf(address account) view returns (uint256)` | 当前付款钱包 | 原始余额 | 输入校验、MAX 和交易前刷新 |
| `allowance(address owner,address spender) view returns (uint256)` | owner=付款钱包；spender=当前源链 B | 当前授权额 | 判断是否需要 approve |

### 7.2 B：StoneRedemptionVault

| 方法签名 | 参数 | 返回 | 用途 |
| --- | --- | --- | --- |
| `stone() view returns (address)` | 无 | 该链 STONE 地址 | 验证配置 |
| `sourceChainId() view returns (uint256)` | 无 | 该 B 部署时的 EVM chainId | 验证网络 |
| `paused() view returns (bool)` | 无 | 是否暂停新赎回 | 控制授权 / 赎回入口 |
| `totalRedeemedByRecipient(address recipient) view returns (uint256)` | recipient=当前领取 account | 此收款人在该 B 的累计赎回额 | 四链求和得到 S1 |

该累计值包含已经结算及已经领取的历史份额，不是该链当前待结算额。查询键是 Ethereum recipient，不是历史交易的 sender。

### 7.3 Ethereum Claim：StoneCumulativeClaim

| 方法签名 | 参数 | 返回 | 用途 |
| --- | --- | --- | --- |
| `stone() view returns (address)` | 无 | Ethereum STONE 地址 | 验证配置 |
| `claimChainId() view returns (uint256)` | 无 | 应为 1 | 验证领取链及 leaf 域 |
| `paused() view returns (bool)` | 无 | 是否暂停领取 | 控制领取按钮 |
| `epoch() view returns (uint256)` | 无 | 当前结算版本；初始为 0 | proof 请求与缓存键 |
| `merkleRoot() view returns (bytes32)` | 无 | 当前 root；初始为零 | proof 请求和证明校验 |
| `claimed(address account) view returns (uint256)` | 当前领取钱包 | 该地址累计已领取额 S3 | 计算本次差额 |
| `leafFor(uint256 epochValue,address account,uint256 cumulativeAmount) view returns (bytes32)` | 版本、领取地址、完整累计额度 | 对应叶子 | 可选，用于核对 leaf 算法 |

Claim 没有个人 S2 的 getter；必须从当前版本 proof 得到 S2。`cumulativeTotal`、`totalClaimed`、`totalFunded` 是全局统计，不能用作个人额度。

同一轮 Ethereum 的 `stone/claimChainId/epoch/merkleRoot/claimed/paused` 固定在同一个区块读取。源链分别选择自己的有效区块；不同链同样的区块号不表示同一个时间点。

## 8. 用户写合约接口

所有写操作都由用户钱包发送，不经过后端代签。以下调用均不发送原生币 value；gas 由交易所在链的原生币支付，Ethereum 领取使用 ETH。

### 8.1 授权 STONE

```solidity
function approve(address spender, uint256 amount) external returns (bool);
```

| 项目 | 约定 |
| --- | --- |
| 目标合约 | 当前源链的 STONE token |
| 调用账户 | sender |
| `spender` | 当前源链 B 地址，不能使用旧桥接 spender |
| `amount` | 本次拟赎回的原始数量；默认仅授权本次数量 |
| 调用条件 | 账户和网络正确、B 未暂停、余额足够，且 allowance 小于拟赎回额 |
| 成功后 | 等待成功回执，再重读 allowance；授权成功不等于已经赎回 |

钱包写调用返回交易哈希，不是 Solidity 的 bool。approve 的错误由实际 STONE 合约及钱包 / RPC 返回，不能假定其使用 B / Claim 的错误 ABI。

### 8.2 在源链提交赎回

```solidity
function redeem(uint256 amount, address ethereumRecipient)
    external returns (uint256 requestId);
```

| 项目 | 约定 |
| --- | --- |
| 目标合约 / 网络 | 所选源链 B |
| 调用账户 | sender，合约从该地址转入 STONE |
| `amount` | 正的原始 uint256，不能大于实时余额或授权额 |
| `ethereumRecipient` | 有效非零 Ethereum 领取地址，可与 sender 不同 |
| 前置条件 | B 未暂停、余额和 allowance 足够；按实际 sender 模拟成功 |
| 链上效果 | STONE 永久锁入 B，增加 recipient 的累计赎回额，发出 RedemptionRequested |
| 后续 | 等待人工结算发布 root，再由 recipient 在 Ethereum 领取 |

赎回不可撤销、不可提回。直接向 B 转账不会登记赎回，应调用 redeem。`requestId` 从成功回执中的事件取得；钱包发送交易只返回交易哈希，模拟返回的 requestId 不是最终登记凭据。

成功后刷新源链余额、allowance、对应 recipient 的累计赎回及说明板块。给其他地址赎回时，成功提示展示实际收款地址及源链交易链接，当前钱包领取区仍查询原 account。

### 8.3 在 Ethereum 领取

```solidity
function claim(uint256 cumulativeAmount, bytes32[] calldata proof) external;
```

| 项目 | 约定 |
| --- | --- |
| 目标合约 / 网络 | Ethereum Claim，chainId=1 |
| 调用账户 | 当前领取 account，必须由该地址本人调用 |
| `cumulativeAmount` | 当前有效 proof 对应的完整累计额度 S2，不能传 S2−S3 |
| `proof` | 当前 epoch/root/account 对应的 bytes32 数组；单叶树可为空数组 |
| 前置条件 | Claim 未暂停、root 已发布、证明有效、S2>S3；使用实际账户模拟成功 |
| 支付金额 | S2−S3；合约把 claimed(account) 更新为 S2 |
| 收款地址 | 固定 msg.sender，没有 account/to/recipient 参数 |

Claim 不需要用户 approve STONE，不支持普通代领。合约钱包可以以自身地址领取；不能使用改变 msg.sender 的通用代理替 EOA 调用。

签名前重新读取 Ethereum 当前状态：即使 root 没变，也要刷新 claimed 和 paused。epoch/root 变化时重新获取并验证 proof，再由用户确认。签名或等待期间仍可能换期、暂停或发生另一笔领取；失败后刷新，不自动替换 proof 重发交易。

## 9. 金额计算与调用顺序

### 9.1 个人金额

| 展示值 | 数据来源 / 计算 |
| --- | --- |
| Total submitted，S1 | 四个 B 的 `totalRedeemedByRecipient(account)` 之和 |
| 累计已结算，S2 | 当前 root 的 proof 响应 `cumulativeAmount` |
| Total claimed，S3 | Ethereum Claim 的 `claimed(account)` |
| Pending settlement | `S1 - S2` |
| Claimable | `S2 - S3` |

例：S1=100、S2=70、S3=30 STONE，则待结算 30、可领取 40。领取完成后 S3=70，待结算仍为 30。两种状态可以同时存在，不能做成互斥页面。

| 情况 | 前端处理 |
| --- | --- |
| `epoch=0` 且 root=零，S3=0 | 尚未首期发布，S2=0，跳过 proof，待结算=S1，可领取=0 |
| epoch/root 只有一项为零，或首期前 S3 非零 | 状态异常，刷新并停止依赖该状态的领取 |
| 某条源链累计查询失败 | S1 和待结算未知，不用三链小计冒充 S1；有效 Ethereum 状态和 proof 仍可支持领取 |
| Ethereum 状态或 proof 失败 | 依赖它们的金额未知，暂停领取；源链赎回按自身条件独立判断 |
| `S1 < S2` | 待结算显示同步中，刷新源链；不能截断为零，也不单凭源链滞后阻止有效领取 |
| `S2 < S3` | 停止领取，核对当前版本和完整累计数据 |
| B 或 Claim 暂停 | 仅停止对应写操作，不把余额或权益归零 |

### 9.2 推荐顺序

1. Bridge STONE Tab：连接钱包后请求 notice，按 showNotice 展示入口。
2. 进入迁移页：读取所选源链的余额、allowance、B 身份及暂停状态；并行读取四个 B 的 recipient 累计额。
3. 获取 Ethereum 固定区块快照，按其中的 epoch/root 请求 proof，核对响应并验证证明，计算 S2/S3 及差额。
4. 赎回：切到源链 → 刷新账户和链上状态 → allowance 不足时 approve 并确认 → 模拟 redeem → 用户发送 → 验证回执事件并刷新。
5. 领取：切到 Ethereum → 刷新同区块状态 / proof → 验证差额 → 模拟 claim(S2, proof) → 用户发送 → 验证回执事件并刷新。

交易状态区分等待钱包确认、已发送、确认成功、用户取消和失败。回执超时不等于交易失败；保留哈希继续查询，替换 / 加速 / 取消时跟踪最终回执。钱包账户改变后取消或丢弃旧响应，重新建立账户及 proof 上下文。

## 10. 事件与交易结果

### 10.1 B：赎回登记

```solidity
event RedemptionRequested(
    uint256 indexed requestId,
    address indexed sender,
    address indexed recipient,
    uint256 amount,
    uint256 recipientTotal,
    uint256 totalRedeemed
);
```

`amount` 是本次赎回，`recipientTotal` 是该收款人在该 B 的累计额，`totalRedeemed` 是该 B 的全体用户累计额。登记唯一标识为 `(sourceChainId, B地址, requestId)`，不能只使用 requestId。

### 10.2 Claim：领取成功

```solidity
event Claimed(
    address indexed account,
    uint256 indexed epoch,
    uint256 amount,
    uint256 cumulativeAmount
);
```

`amount` 是本次实际支付差额，`cumulativeAmount` 是领取后的个人累计已领取额 S3，不要重复累加 cumulativeAmount。

### 10.3 可选状态监听

```solidity
// Claim：发布后使前端重新读取版本及 proof
event RootPublished(uint256 indexed epoch, bytes32 indexed root, uint256 cumulativeTotal);

// B 和 Claim：重新读取对应 paused 状态
event PauseStateChanged(address indexed admin, bool paused);
```

只解析预期网络、预期合约地址发出的日志，结合成功回执及实际参数确认。监听事件可以触发刷新，不能替代交易前重读。当前页面不要求逐笔历史接口，也不需要扫描全量日志才能查询个人状态。

## 11. 用户交易的合约错误

以下列出用户入口可能返回的自定义错误，完整 ABI 的 errors 可用于解码。钱包拒签、RPC 异常、token 读取异常、Solidity panic 或未知 revert 也须提供通用失败处理；不要认为每次失败都能解析为下表之一。

### 11.1 B：redeem

| 错误签名 | 含义 / 处理 |
| --- | --- |
| `RedemptionPaused()` | B 已暂停；刷新状态并禁用该链新赎回 |
| `ZeroAmount()` | 输入为零；修正金额 |
| `InvalidRecipient()` | 收款人为零地址；修正地址 |
| `TransferFailed()` | STONE transferFrom 失败或返回异常；刷新余额、allowance，不伪装成已登记 |
| `UnexpectedBalanceChange(uint256 balanceBefore,uint256 balanceAfter,uint256 expectedIncrease)` | B 实际到账增量不符；交易回滚，提示暂不可用并排查 |
| `ReentrantCall()` | 重入保护；停止本次操作并排查 |

### 11.2 Claim：claim

| 错误签名 | 含义 / 处理 |
| --- | --- |
| `ClaimPaused()` | 领取暂停；刷新并禁用领取 |
| `RootNotPublished()` | 尚无 root；等待首期结算 |
| `InvalidProof()` | 版本、账户、金额或证明不匹配；重新读取 epoch/root 并取 proof |
| `NothingToClaim()` | 累计额度不大于已领取额；刷新 claimed |
| `ClaimExceedsPublishedTotal()` | 本次差额超过全局剩余发布额度；停止领取并核对结算 |
| `InsufficientFunding(uint256 available,uint256 required)` | 支付时合约余额不足本次差额；提示暂不可用 |
| `TransferFailed()` | STONE 支付失败或返回异常；交易未完成 |
| `UnexpectedPaymentBalance()` | 合约扣款或收款人到账增量不符；交易回滚 |
| `ReentrantCall()` | 重入保护；停止本次操作并排查 |

`EpochMismatch` 是发布 root 的管理错误，不是用户 claim 的错误；用户拿旧 proof 领取时通常触发 `InvalidProof`。`ZeroAmount` 也不属于用户 claim 路径。不要按这些管理错误实现用户换期处理。

## 12. ABI 交付与联调前配置

B / Claim 的完整 ABI 取操作者构建的以下产物中的 `abi` 字段：

- `out/StoneRedemptionVault.sol/StoneRedemptionVault.json`
- `out/StoneCumulativeClaim.sol/StoneCumulativeClaim.json`

ABI 必须与实际部署版本对应。STONE 前端使用第 7.1 / 8.1 节列出的标准 ERC20 子集即可。涉及 custom error 解码时保留 B / Claim ABI 的 error 条目；不要把包含 Node.js 文件或管理逻辑的整个脚本模块导入浏览器。

联调前由部署方提供：API_BASE_URL 及允许的前端 Origin、五链前端 RPC、四个 B 地址、Ethereum Claim 地址、交易确认和浏览器配置，以及正式公告链接。公告只外链跳转，没有公告正文接口。

主要实现依据：

- [HTTP 路由](../scripts/proof-server.ts)、[proof 数据与校验](../scripts/proof-store.ts)、[notice 判断](../scripts/migration-notice.ts)。
- [B 合约](../src/StoneRedemptionVault.sol)、[Claim 合约](../src/StoneCumulativeClaim.sol)、[Merkle 编码](../scripts/claim-merkle.ts)。
- 后端部署见 [proof 服务说明](proof-service.md) 及 [notice 配置说明](migration-notice-api.md)。

本文仅整理并静态核对接口，没有运行服务、测试或真实钱包交易，也没有修改业务实现。
