跳到主要内容

RPC 确认与故障恢复

确认必须分别回答三个问题:输出是否已进入本地索引、交易执行是否成功、所在规范区块达到何种原生确认等级。

原生最终性与索引进度​

invisi_getStatus 返回 indexedHead 和 finality.latest/safe/finalized。每个原生头都有 status 和 block;status 是 available、unsupported、unavailable 或 inconsistent。

  • unsupported:上游明确不支持方法或标签。
  • unavailable:暂时无法取得有效头,包括网络错误或 null。
  • inconsistent:链头或已接受的最终历史冲突。
  • available:当前可用的原生头,停滞时高度可以不变。

服务不会把固定区块深度或等待时间换算成 safe/finalized。原生头可能领先索引;缺少最终性能力也不等于所有读取都不可用。应用按业务要求比较交易区块与所需头,不以索引高度替代。

请求受信 Note 确认​

以下只读示例需要 POSIX shell、curl 和 jq。设置 PROTOCOL_RPC_URL 为完整可信链路由,NOTE_COMMITMENT 为来自本地收款材料重算的完整、非零、规范 BN254 标量承诺。jq 负责安全构造 JSON。

: "${PROTOCOL_RPC_URL:?Set the full trusted chain RPC URL}"
: "${NOTE_COMMITMENT:?Set the full expected Note commitment}"
jq -n --arg commitment "$NOTE_COMMITMENT" \
'{jsonrpc:"2.0",id:"note-1",method:"invisi_getNote",params:[$commitment,{finality:"finalized"}]}' |
curl --fail-with-body -sS "$PROTOCOL_RPC_URL" \
-H 'Content-Type: application/json' --data-binary @-

仅接受 safe 或 finalized;latest、null 和未知 selector 字段均拒绝。成功的确认响应包含版本、部署、indexedHead、status、reason、output、membership 和 confirmation。

status:"confirmed" 时 reason 为 null,confirmation 包含 finality、verifiedAt 和 finalityHead。验证锚点取索引头和原生最终性头中较低者;服务验证成功回执、规范区块、路径和该锚点的合约根,再重新核验规范性与最终性。

status:"pending" 时 output、membership、confirmation 都为 null。不能将这些 null 保存为永久不存在。

reason应用处理
not_observed未观察到,保留订单并继续核对预期承诺
pending_index等待索引赶上
confirmation_pending等待所需原生层级
finality_unsupported换用具备能力的可信来源或明确调整业务政策
finality_unavailable暂停确认,有限退避重试
finality_inconsistent停止自动核销,核查可信链来源

RPC 错误不是 pending,也不能被转换为 confirmed。服务确认不包含商户订单、私密 opening 或本地一次核销状态;应用仍需自行原子记录收款与履约。

单笔交易可用性​

invisi_getTransactionNoteUpdates 和 Credit 对应方法返回 status、indexedHead,以及可选区块和 receiptStatus。

status含义
not_found未取得已挖出回执;可能未知或仍 pending
pending_index已有规范回执,本地规范索引尚未就绪
indexed可读取该交易的已索引投影

索引完成前 notes / states / transitions 为 null;完成后是数组,包括空数组。receiptStatus 0 表示回滚,1 表示执行成功,与索引可用性独立。无关或回滚交易可返回空数组。结算操作查询的 operations 始终初始化为空数组,且使用独立 failed 状态,不要套用同一 null 契约。

错误与重试​

先检查 HTTP,再检查 JSON-RPC。HTTP 429 尊重 Retry-After,使用有限指数退避与抖动。HTTP 413 缩小请求;415 修正 Content-Type;404 核对路由与活动链。后端默认没有 CORS/认证,浏览器接入需确认运营者网关策略。

JSON-RPC -32601 表示未知方法,-32602 表示参数解码失败,-32000 表示语义、存储或上游拒绝;公开错误会净化,不能按后台错误文本分类。不要无限重试错误参数。

单体请求上限 1 MiB,批次最多 20 调用,批次响应预算 16 MiB。批响应按 id 匹配,不能依赖顺序。需要确认时使用带 id 的请求;通知没有响应。发生重组时重新获取可信锚点、回滚本地孤块投影,再继续同步。