T14 · Web3 フロントエンド

現実の問題

ユーザーが「交換」を押します。

ウォレットが開き、確認すると閉じます。ページには回転するアイコンと「処理中」が表示されます。

そして十数秒が過ぎます。アプリに慣れた人には長い時間です。止まったかと疑い、別アプリへ移って戻り、もう一度ボタンを押すほど長いのです。

その間、画面は実際には何も分かっていません。

• 署名したのか？ウォレットで拒否したのに、ページは回り続けるかもしれません。
• ブロードキャストした取引はメモリプールへ入ったか？手数料が低く、止まっていないか？
• ブロックへ入ったか？入れば成功なのか？
• ウォレットで「高速化」を押した後、手元のハッシュはまだ有効か？

一つでも答えを誤れば、事実と違う状態を表示します。最も高くつく誤りは、失敗した取引を成功と表示することです。

UI の細部ではありません。Web2 の要求は数百ミリ秒で成否が分かります。チェーンの取引には 6 種類の状態と、十数秒から数分の中間状態があり、中間状態は後戻りもします。Web2 と同じ感覚で画面を作ると誤ります。

思考実験

取引を HTTP 要求ではなく、書留郵便として考えます。

投函した時点から、次のことが起きます。

• 手元に受付番号がある。これがあって初めて照会でき、なければ何もできません。
• 郵便が仕分け場で待つ。郵送料が高ければ前へ進み、低ければ何日も待つかもしれません。
• 郵便がある車へ載る。しかし輸送中で、事故や返送の可能性があります。
• 車が到着する。ようやく結果が分かり、配達完了と配達失敗による返送の 2 つがあります。

最後が鍵です。到着することと、配達に成功することは別です。

チェーンでは、取引がブロックへ入るのは、マイナー／検証者が実行したことを示すだけで、成功したとは限りません。実行中にエラーとなってもブロックへ入り、手数料は消費され、レシートには失敗と記録されます。

T1 でも説明しましたが、この分野で最もよくあるバグなので繰り返します。

成否は、ブロックにあるかではなく、レシートの status を確認します。

書留にはない性質もあります。同じ番号で、別の郵便へ置き換えられます。 同じ nonce の取引が最終的にチェーンへ入るのは一つです。ウォレットの高速化やキャンセルは、同じ nonce で新しい取引を送ります。元のハッシュでは、その後レシートを取得できなくなります。

それを待ち続ける画面は、永遠に回転します。

あなたが決める

十数秒の待機画面を、どう設計しますか？

結果を観察する

違いは、最初の 3 つが画面を描き、4 つ目がモデルを作ることです。

画面中心だと、例外ごとに if が増え、5 つ目には誰も状態の総数を説明できなくなります。モデルなら、例外を状態機械のノードとして追加できます。

取引の状態は、6 つに整理できます。

見落としがちなルールを 2 つ加えます。

署名拒否は失敗ではありません。 エラーを出さず待機へ戻します。赤いエラーは、単に考えを変えたユーザーに、悪いことをしたと感じさせます。

成功から後戻りすることもあります。 チェーン先端の再編成が起きます（T1 の最後の実例）。確認数が不足したまま成功と表示すると、再編成後に虚偽になります。十分な確認数に達するまで、成功は本当の終状態ではありません。

モデルを作る

主経路は一直線です。

型で状態を記述します。言語より重要なのは、各状態の持つデータが異なることです。ブール値ではなく、ユニオン型を使う理由です。

type TxState =
  | { kind: 'idle' }
  | { kind: 'awaitingSignature'; intent: TxIntent }
  | { kind: 'broadcast';  hash: string; nonce: number; submittedAt: number }
  | { kind: 'pending';    hash: string; nonce: number; blockNumber: number; confirmations: number }
  | { kind: 'confirmed';  hash: string; blockNumber: number; confirmations: number }
  | { kind: 'failed';     hash?: string; reason: FailureReason }
  | { kind: 'replaced';   originalHash: string; replacementHash: string; by: 'speedup' | 'cancel' | 'unknown' };

type FailureReason =
  | 'userRejected'        // ウォレットで拒否。厳密には失敗ではない
  | 'insufficientFunds'   // 手数料または送金額の残高不足
  | 'reverted'            // チェーンへ入ったが実行が巻き戻された
  | 'slippage'            // 見積期限切れやスリッページ超過。reverted の一種
  | 'nonceConflict'       // nonce を別の取引が使った
  | 'dropped'             // 長時間ブロックへ入らず、メモリプールから除外された
  | 'unknown';

isLoading、isSuccess、isError の 3 ブール値では、不可能な isLoading && isSuccess も型として有効で、いつか分岐で現れます。ユニオン型は不正な状態を表現不可能にします。最も実際的な利点です。

遷移表

各遷移は、個別にテストできるケースです。

最後の 2 行が表の価値です。状態機械は後戻りを許す必要があります。 前進だけでは再編成時に誤った終状態に固まり、成功表示が永久に修正されません。

間違えやすい 3 点

第一に、nonce を中心に、ハッシュを補助として追跡します。 高速化やキャンセルでハッシュは変わり、nonce は変わりません。そのアドレスの確定済み nonce が対象 nonce を超えたのに、対象ハッシュのレシートがなければ、置換済みです。実際に入った同 nonce のハッシュを探し、追跡を続けます。

第二に、待機は中断、再開できるようにします。 更新、タブ終了、端末変更が起きます。追跡対象をローカルへ永続化し、読み込み時に未完了の取引の追跡を再開します。メモリだけなら、一度の更新で失われます。

第三に、送信済みではなく、署名待ちでボタンを無効にします。 両者の間の数秒に再度押すと、二つ目の署名要求が出ます。この隙間では重複送信が必然的に起きます。まれな出来事ではありません。

エラーの変換表

低水準のエラーを、説明と行動へ変えます。3 列目が最も重要です。

文言の必須ルールは 2 つです。

• レシート取得前に成功と伝えません。 提出済み、送信済み、確認中は使えても、成功は使えません。
• 理由なしに「失敗。再試行してください」と書きません。 再び失敗し、もう一度手数料を失う可能性が高いからです。

何と呼ぶか

実践

AI Lab

第 1 段階：
チェーンの取引を作成してから確定するまでの、全失敗状況を列挙してください。
各状況の条件、ユーザーが見る現象、具体的な判定フィールドを示してください。
署名拒否、手数料不足、巻き戻し、スリッページ超過、nonce 衝突、
メモリプールからの除外、同 nonce の新取引による置換を含めてください。

第 2 段階：
各状況について、一般ユーザー向けの日本語メッセージを作ってください。
- 20 文字以内
- 何が起きたか分かる
- 今できる行動を示す
その後、文言が、取引成功、着金済み、引き落とし済み、取り消し可能という
誤解を生まないか、一つずつ自己点検してください。

実例

変数を一つ変える

持ち帰る問い

章末チェック