Skip to content

fix(cross-chain): A1 — CCTP burn 再開安全化 (marker fail-closed・決定表・手動照合/hash 貼付け・掟 15 要レビュー) - #440

Merged
cipherwebllc merged 3 commits into
mainfrom
fix/review5-a1-cctp-burn-resume
Sep 4, 2026
Merged

fix(cross-chain): A1 — CCTP burn 再開安全化 (marker fail-closed・決定表・手動照合/hash 貼付け・掟 15 要レビュー)#440
cipherwebllc merged 3 commits into
mainfrom
fix/review5-a1-cctp-burn-resume

Conversation

@cipherwebllc

@cipherwebllc cipherwebllc commented Sep 3, 2026

Copy link
Copy Markdown
Owner

背景

第 5 回全コードベースレビュー (plans/full-review-2026-09-02.md) の A1 = CCTP burn の再開安全性。cross-chain USDC (Base 等 → 受取チェーン) の burn 境界に「着弾したか」の再確認が無く、応答喪失で二重 burn・revert で恒久 wedge になり得た。設計 = plans/a1-cctp-burn-resume.md (user 裁定: ①auto 再 burn は flag OFF ②手動照合パネルを出す ③hash 貼付け可 ④CCTP のみ)。

⚠️ 掟 15 (money-path): 実装 (Opus) → 敵対検証 (別 Opus・8 指摘) → 修正 (Opus) → Fable 監査 の 3 段を経ているが、merge 前に user の明示レビューが必要。決済状態の真実は on-chain (receipt / DepositForBurn log / nonce) のみで、人間の申告 (二段確認・hash 貼付け) は入口に過ぎず採否は on-chain 事実が決める。

変更 (2 commit)

1. A1 本体 (89441f9)

  • lib/crossChain/burnMarker.ts (新規): burn-intent marker (block / nonceLatest / noncePending / params) を broadcast 前 に fail-closed で永続化 (saveResumeStateStrict = 読み戻し検証)。決定表 classifyBurnState (設計 §4・22 行) を純粋関数で実装。DepositForBurn log 走査は ≤2000 block chunk・MAX_SCAN_CALLS 24・MAX_SCAN_SPAN_BLOCKS 24000。候補受理は amount / destinationDomain / mintRecipient / burnToken / depositor 一致 + tx.nonce ≥ marker.nonceLatest (過去の同額 burn を掴まない)。
  • lib/crossChain/execute.ts: burn 前に resolveBurnSlot で receipt / nonce / log を実測 → wait / manual なら wallet popup を出さず CrossChainBurnUnresolvedError で停止。自動再 burn は NEXT_PUBLIC_CROSS_CHAIN_BURN_AUTORESUME (既定 OFF) のときだけ。
  • hooks/useCrossChainPayment.ts + components/CrossChainBurnUnresolvedPanel.tsx (next/dynamic): 手動照合パネル (wait = 数分後に再確認 / manual = explorer で USDC 残高を確認する二段確認)。
  • .env.local.example / README: flag 追記。i18n CrossChainHint 12 キー。

2. 敵対検証の 8 指摘への修正 (3445578)

  • D1 (blocker): 二段確認 (manual override) は pendingAhead === false を 実測済み のときだけ開く (undefined = 未計測は拒否・型で区別)。走査を range / ratelimited で打ち切った場合も「見ていない」ので開かない。旧 state (row 3) も getTransactionCount(pending/latest) を実測してから判定。設計からの逸脱: row 20 (走査 cap 超過) は二段確認でも開かない → 自己救済は hash 貼付け (D4) かサポート経由。
  • D2: 別オプション実行時に burnUnresolved をリセット。wait パネルに「もう一度確認する」ボタン (親の Pay ボタンが disabled で再確認手段が無かった)。
  • D3: fee slot (OpenPay 利用料の burn) の未確定が merchant の mint を人質に取らない。fee は自動再 burn せず feeBurnUnresolved を resume state / 結果に記録して二次通知 (「追加のお支払いは不要」)。
  • D4: hash 貼付け再開 verifyBurnTxHash — receipt success + TokenMessenger の DepositForBurn log が marker と完全一致 + tx.nonce ≥ marker.nonceLatest のときだけ採用 (transport 障害は unavailable・不一致は state 不変)。
  • D5: 候補の getTransaction / getTransactionReceipt も call 上限に計上・候補単位の notfound は skip。
  • D6: rate limit (−32005 / 429 / 文言) を range より先に判定 → row 22 = wait (chunk 縮小しない)。errorText は message / details / shortMessage / metaMessages を cause 連鎖で読む。QuickNode の blocks range 文言を追加。
  • D7: 旧 state の再開が source RPC receipt 読取に依存するようになったことをコメントで受容明記。
  • D9: mount 時に isCommitted を stored burnIntent / burnTxHash / attestation から復元。
  • テスト: fixture の receipt を hash キー化 (merchant / fee 取り違え検出)・errorStorageBlocked 描画テスト追加。i18n CrossChainHint +12 キー・burnWaitBody 文言更新。

検証 (origin/main 9582f46 に rebase 後・Fable 実行)

  • npm run typecheck exit 0 / eslint 変更ファイル 0 errors (既存 warning 2 = CrossChainHint.tsx:134,140 exhaustive-deps・本 PR 以前から)
  • full vitest: Test Files 473 passed / Tests 9497 passed (main 比 +216・末尾 5 行で確認)
  • npm run build exit 0 / bundle budget 全ルート OK (pay 441/442・tip 438/438・create 388/392・[handle] 478/479・checkout 444/446・shared 230/250)
  • 敵対検証で d146946 に対し赤になることを確認した新テスト: ゲート外し 8 件・hook/UI 5 件・fee 非ブロック 2 件

user に判断をお願いしたい点

  1. row 20 (走査 cap 超過) を二段確認でも開かない (敵対検証の指摘どおり厳格化)。設計 §4 では二段確認で開く想定だったが「走査していない」状態で人間申告のみを根拠に burn するのは掟 15 に反するため閉じた。自己救済は hash 貼付けのみ。→ この逸脱を受容するか。
  2. flag NEXT_PUBLIC_CROSS_CHAIN_BURN_AUTORESUME は既定 OFF のまま (点灯は別途)。
  3. 新規 i18n 12 キー (可視文言・ja/en) — 代表: 「もう一度確認する」「送金済みの取引 ID (tx hash) を貼り付ける」「お支払いは完了しました。利用料ぶんの送金だけ状況を確認できなかったため、店舗側で後ほど照合します。追加のお支払いは不要です。」

🤖 Generated with Claude Code

https://claude.ai/code/session_015CNMEwurCJNTrzvr2qypSd

cipherwebllc and others added 2 commits September 4, 2026 08:31
@cipherwebllc @claude
fix(cross-chain): A1 — CCTP burn 再開安全化 (marker fail-closed + 決定表判定・au…
89441f9 
…to 再 burn は flag OFF)

全コードベースレビュー第5回 P1-A1。CCTP path の burn だけ「hash の有無」しか見ておらず、
2 つの事故が同時に成立していた:

(i)  burn() を broadcast した後、hash を永続化する前に reject / タブ閉じ → 再開時に
     `needMerchantBurn = !state.burnTxHash` が true になり **二重 burn (二重支払い)**。
(ii) hash は残ったが tx が revert / 置換された → Iris attestation が永久に出ず **恒久 wedge**。

mint 側は txAlreadySucceeded で landed を検証しているのに burn 側だけ非対称だったのが本質。

## 対処

broadcast の直前に「送るつもり」= burn-intent marker を fail-closed で永続化し、再開時は
marker + on-chain の事実 (receipt / pending vs latest nonce / DepositForBurn log の有界走査)
だけで分岐する。曖昧な状態は自動で再 burn せず wait / manual (人間の二段確認) に倒す。

- marker 書込 (`saveResumeStateStrict`・read-back 検証つき) が失敗したら **burn しない**。
  lib/circlePending.ts と同型の fail-closed。書けなければ isCommitted も立てないので、
  親フォームの通常決済は使えたまま (掟 13: 何の波及を断つ防御かをコメントで明示)。
- 判定は決定表 21 行 (plans/a1-cctp-burn-resume.md §4) を純粋関数 classifyBurnState に閉じた。
  「最古の一致 log を採る」ような選択は一切しない。0 / 1 / 複数 をそのまま扱い、複数一致は manual。
- 過去の同額 burn の誤検出は「候補 tx の nonce >= marker.nonceLatest」で構造的に排除する
  (過去 burn は必ず nonce が小さい)。merchant / fee が同額・同宛先の病的ケースも nonce で分離。
- getLogs は chunk 2000 (range error で 1000→500→250→100 に自動縮小)・call 上限 24・chain 別
  の span cap。超過は throw せず manual に倒す (provider 上限で恒久 wedge にしない)。
- transport 障害 (RPC ダウン) は握り潰さず throw する。「観測できなかった」を「起きていない」に
  潰すと二重 burn になるため (execute.ts の CR-2 と同じ区別)。

## flag / UI (user 決定ぶん)

- `NEXT_PUBLIC_CROSS_CHAIN_BURN_AUTORESUME` 既定 **OFF**。row 9/12/18 の自動再 burn だけを
  ゲートし、marker 書込・revert 検出・log 走査・adopt は常時 ON (flag OFF が「二重 burn バグを
  残す設定」にならないようにするため)。点灯は manual 到達率を観測してから (user 承認事項)。
- manual パネル (買い手が Explorer で自分の USDC が減っていないことを確認 → 二段確認 → 再送金)
  を同梱。CrossChainBurnUnresolvedPanel は next/dynamic で遅延ロードし、/pay 438kB・/tip 436kB
  の予算に載せない (予算据え置き・実測とも増減なし)。
- 一致 burn が複数見つかった場合だけは二段確認でも開かない (人間の申告より on-chain を優先)。

## 掟

- 掟 12: money-path の制御フロー変更を含むため掟 15 を適用 (merge 前に user レビュー)。
  Gateway path・settleMint・txAlreadySucceeded・calldata 生成は不変。
- 掟 9: .env.local.example / README env テーブルを同時更新。
- 掟 5: messages/ja.json・en.json の CrossChainHint namespace に 13 key を明示追加。
- 掟 6: 共有 hook (useCrossChainPayment) 変更のため full vitest 実施 (470 file / 9281 test green)。

Refs: plans/a1-cctp-burn-resume.md

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015CNMEwurCJNTrzvr2qypSd
@cipherwebllc @claude
fix(cross-chain): A1 レビュー指摘 — manual override の実測必須化・fee 非ブロック化・burn …
3445578 
…hash 貼付け再開

d146946 (A1) の敵対的レビュー 8 件を修正。最大の穴は「二段確認さえ通れば burn」で、
決定表の row 3/4 は pendingAhead 判定より **前** に返るため、mempool に burn が居ても
再送金できてしまっていた (= 二重支払い)。

## D1 (出荷ブロッカー): manual → burn は「実測が揃っている」ことを条件にする

- classifyBurnState の入力に `pendingAhead: boolean | undefined` (undefined = 未計測) と
  `timeGapSatisfied` を追加。canManuallyReburn() が override の可否を一元判定する:
  ① mempool 空を **実測済み** ② 走査したなら一致 0 件 ('range'/'ratelimited' は「見ていない」
  ので不可) ③ marker があるなら MIN_GAP_MS 経過。
- row 3 (旧 state) / row 4 (block・nonce 欠落) / row 20 (cap 超過) はいずれもこの gate を通す。
  結果として row 20 は二段確認でも開かない (走査していないため) — 自己解決率より安全側を採る。
- resolveBurnSlot の legacy 分岐 (marker 無し) で pending/latest nonce を実測してから分類する。
  marker.block/nonce を欠く場合は log 走査を **行わず** scan=undefined にし、「走査できなかった」
  と「走査して 0 件」を型で区別する。

## D3: fee slot の未確定が merchant を人質に取らない (掟 13)

fee が wait/manual でも merchant の attestation → mint はそのまま進め、fee は
`feeBurnUnresolved` として resume state と実行結果に記録するだけにする (自動再 burn しない・
Iris poll もしない)。UI は成功パネルの二次通知で「追加の支払いは不要」を伝える。

## D4: burn の tx hash 貼付けによる再開

「USDC は減ったが hash が残らなかった」(row 4/20) の唯一の自己救済経路。買い手が貼った hash を
verifyBurnTxHash() が on-chain だけで検証し (receipt success + marker と一致する DepositForBurn
log + tx.nonce >= marker.nonceLatest + sender 一致)、通った場合のみ burnTxHash として採用して
続き (Iris poll → mint) に進む。不一致は state を変えず inline error。採用書込も fail-closed。

## その他

- D2: executeOption でも burnUnresolved を reset し、別種のエラーでは畳む (error が
  `error && !burnUnresolved` で隠れる問題)。wait パネルに「もう一度確認する」を追加 —
  親 Pay ボタンは wait 中 disabled なので、押す先が無いと文言が嘘になる。
- D5: 候補 tx の getTransaction/getTransactionReceipt も MAX_SCAN_CALLS の予算に載せ、
  候補単位の notfound (reorg) は走査全体を throw せずその候補だけ飛ばす。
- D6: rate limit (-32005 / 429 / compute units) を範囲超過と分離し、一過性として wait
  (row 22) に倒す。QuickNode の "limited to a 10,000 blocks range" と viem の metaMessages に
  対応。'limit exceeded' は両方の文面に出るため rate limit 判定を先に置く。
- D7: legacy resume (row 2) が source RPC の receipt 読みに依存するようになったこと (可用性
  コストの受容) を execute.ts のコメントに明記。
- D9: mount 時に resume state の marker/hash/attestation から isCommitted を復元する。
  再読込しただけで親フォームの直接決済が解禁される穴を塞ぐ。

## テスト

- burnMarker: mempool 不変条件を marker 無し / block=null にも拡張 (allowManualReburn=true でも
  burn にならない)、override 条件・row 22・provider 3 文面・候補読み取りの隔離・verifyBurnTxHash。
- execute: fixture の receipt を hash ごとに返すようにし (merchant/fee の取り違えを検出)、
  row 3 + 二段確認 + mempool 有り → burn 無し、fee 未確定でも merchant mint 完走を追加。
- CrossChainHint: mount 復元 (D9)、wait → 再確認で再判定 (D2)、hash 貼付けの採用/不一致/書式不正、
  errorStorageBlocked の描画。

掟 5: CrossChainHint namespace に 12 key 追加 (ja/en)・burnWaitBody を再確認導線に合わせて更新。
掟 12/15: money-path の制御フロー変更を含むため merge 前に user レビュー。

Refs: plans/a1-cctp-burn-resume.md

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015CNMEwurCJNTrzvr2qypSd
@vercel

vercel Bot commented Sep 3, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
openpay Ignored Ignored Preview Sep 4, 2026 12:15am UTC

Request Review

@cipherwebllc cipherwebllc mentioned this pull request Sep 3, 2026
Merged
@cipherwebllc
cipherwebllc merged commit bf5f080 into main Sep 4, 2026
6 of 8 checks passed
@cipherwebllc
cipherwebllc deleted the fix/review5-a1-cctp-burn-resume branch September 4, 2026 03:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cipherwebllc