第10巻　内部設計書(2) ― I/F契約とデータ辞書

本巻は docs/specs/30_internal_design.md の第12章(I/F契約・データ辞書)を収める。前巻→第9巻の続き、続きは→第11巻。

第12章 I/F契約・データ辞書

本章以降（第12〜16章）は、実装・検証のための静的参照（スキーマ、型、制約、コード表、レーン詳細）である。

本章は規範（Normative） であり、実装・運用・監査・契約の前提として固定される。
ここに無いものは「実装しても良いが、制度・接続の共通基盤として保証しない」。

採番について（旧付録記号の廃止）：かつて独立していた付録A〜Iは本章以下の章番号ベースの節番号（12.1, 13.1, …）へ移行済みである。旧記号は本書群では使用しない。対応は次のとおり。

旧記号	現節	内容
付録A（A.0〜A.2）	§12.1〜§12.3	I/F契約：cmd/event一覧・共通ヘッダ・データ辞書
（新設）	§12.4〜§12.6	冪等キーのスコープ・seq の粒度・署名対象と正規化
付録D（D.0〜D.2）	§12.7〜§12.9	パラメータ統制・対象カテゴリ・PR-* 台帳
付録E	§13.1〜§13.6	主要メッセージのボディ定義
付録F	§14.1〜§14.3	LSM（Bulk向け流動性節約）詳細
付録G	§15.1〜§15.6	HTLC（hashlock+timelock）詳細
付録H	§16.1〜§16.3	Raft運用（合意ログ）詳細
付録I	20_method_design.md §10.10	CASE（例外収束）運用テンプレ
付録B・付録C	廃止	用語は 10_requirements.md 序章「Zenith 独自用語ミニディクショナリー」を参照

12.1 cmd/event一覧（正本）

本表は ZC ⇄ 参加行のあいだで交換する cmd/event 名の正本である。他文書のシーケンス図・本文が
名指すメッセージは、すべて本表に存在しなければならない。

FinalityLog の event_type とは別の語彙である。 本表は「線の上を流れる電文」の名前を固定する。

FinalityLog に追記される監査イベントの語彙はこれより広く（ZC 内部のライフサイクル事実を含む）、

その正本は src/types/api/messaging.ts#FinalityEventType である。両者の関係は §12.1.6 に示す。

12.1.1 取引ライフサイクル（TX / GTID / RTP / PSPR / CASE）

12.1.2 HTLC・クロスチェーン・条件付き決済

12.1.3 外部清算（IGS／DNS／中央銀行レール）

12.1.4 所有権・システム運用

12.1.5 図中略記と正式名の対応（規範）

20_method_design.md 第2章のシーケンス図は、可読性のため UPPER_SNAKE の略記と
CMD/EVT 接頭辞を用いる。正式名は本節（§12.1）であり、図中表記は略記に過ぎない。
両者の対応は次のとおり固定する（図に新しいメッセージを描く場合は、本表と §12.1.1〜§12.1.4
への追加を同じ変更で行う）。

12.1.6 FinalityLog の event_type との関係（規範）

§12.1 の cmd/event（I/F 語彙）と、FinalityLog に追記される event_type（監査語彙）は
別の集合であり、部分的にしか重ならない。混同すると「この電文名で監査ログを引けるはずだ」
という誤った期待を生むため、関係を明示する。

  §12.1 cmd/event（I/F 語彙）        FinalityEventType（監査語彙）
  ┌──────────────────┐
  │ NameCheckRequested        │      ZC 内部のライフサイクル事実
  │ PayerExecRequested        │      （PreCheckPassed / HReserved /
  │ GtLegReadyRequested   …   │       Suspended / Settled / DnsKicked …）
  │                ┌──────────┼──────────────────┐
  │                │  同名で FinalityLog にも記録される（下記 1.）  │
  │                └──────────┼──────────────────┘
  └──────────────────┘

1. 同名で FinalityLog にも記録されるもの（30 件）

集合の正は下記の列挙であり、CI が実装の列挙型と機械照合する。

PaymentInitiated / PayerExecConfirmed / PayeeExecConfirmed / DecidedCancel /
NoDebitRecordedProofSubmitted / CreditFailedProofSubmitted / HUnlockAuthorized /
MisrecordCorrected / RtpRequested /
LsmRunCommitted / LsmRunFallback / HtlcLocked / HtlcClaimRejected /
HtlcConditionsEvaluated / CrossChainLocked / OnchainProofObserved /
OnchainFinalityClassified / BenefitAttested / DnsHoldRequested / DnsHoldActivated / DnsResumed /
DnsIntradayCutoff / OwnershipTransferred / OwnershipReclaimed /
SystemQuorumLossActivated / SystemQuorumLossCleared / SystemBcpActivated /
SystemBcpDeactivated / DataAccessViolationDetected / ClosedDomainAccessGranted

2. I/F 語彙のみ（FinalityLog には別名で、または個別には記録されない）
：NameCheckRequested / PayerExecRequested / GtLegReadyRequested 等の要求・応答電文。
これらの結果は状態遷移イベント（PreCheckPassed・HReserved・DecidedToSettle 等）として
記録される。

3. 監査語彙のみ（線の上を流れない ZC 内部事実）
：PreCheckPassed / PreCheckFailed / HReserved / DecidedToSettle / Suspended /
Settled / Cancelled / FailedExecution / GtidRegistered / GtidDecided / GtidSettled /
DnsKicked / DnsSettled / DnsHoldActivated / DnsRingfencePromoted / IgsDeferred /
HtlcCreated / HtlcFulfillRequested / HtlcAuthRequested / FinalityCosigned /
WatcherEquivocationDetected 等。

規範

• FinalityLog の event_type 列の値域は src/types/api/messaging.ts#FinalityEventType を正とする
  （31_schema.md § FinalityLog）。本書 §12.1 はこの列の値域ではない。
• 上記 1. の集合は「§12.1 の名前 ∩ FinalityEventType」と一致しなければならない
  （test/invariants/spec_refs.test.ts が機械照合する）。§12.1 に新しい EVENT を足し、
  それを同名で FinalityLog にも記録するなら、1. のリストと FinalityEventType の両方を
  同じ変更で更新すること。

12.2 共通ヘッダ（全cmd/event：固定）

{
  "schema_version": "1.0",
  "message_type": "COMMAND|EVENT",
  "name": "PaymentInitiated|PayerExecRequested|...",
  "message_id": "uuid",
  "occurred_at": "RFC3339",
  "idempotency_key": "string",
  "command_seq": 123,
  "event_seq": 456,
  "correlation_id": "uuid",
  "causation_id": "uuid",
  "producer": { "org_id": "string", "system_id": "string" },
  "signature": {
    "alg": "POLICY_DEFINED",
    "canonicalization": "FIXED",
    "signed_fields": ["..."],
    "value": "base64"
  }
}

規範（固定）

• command_seq / event_seq は 永続・単調増加（巻戻り不可） 。欠番は許容するが再利用不可。
• **COMMANDは command_seq 必須 / event_seq はnullまたは省略。EVENTは event_seq 必須 / command_seq はnullまたは省略。 ** （両方を同時必須にしない）
• 粒度： 送信者×aggregate（§12.5）。
• correlation_id は業務トレース単位で継承。 causation_id は直前因果。
• 署名は 対象範囲と正規化を固定（§12.6）。

12.3 データ辞書（最小十分：揉めどころ固定）

12.3.1 識別子

12.3.2 金額

12.3.3 Proof参照（bank_proof_ref：固定）

b証憑（PAYEE_EXEC_PROOF）は、単なるACKではなく、銀行内部の台帳記録を指し示すものでなければならない。

{
  "bank_proof_ref": {
    "issuer_bank_id": "B001",
    "proof_type": "PAYEE_EXEC_PROOF",
    "proof_id": "core_journal_id_12345",
    "recorded_at": "RFC3339",
    "retrieval_hint": "...",
    "custody_detail": {
      "is_custody": true,
      "reason_code": "ACCOUNT_CLOSED",
      "custody_account_ref": "segregated_custody_acct_001"
    }
  }
}

• 規範 ：proof_id は後日の監査において、銀行の勘定系元帳（GL）と突合可能でなければならない。
• custody_detail は Custody 発生時のみ付与し、Custodyでない場合は省略してよい。

proof_type の値域（規範）

proof_type は自由文字列ではなく、次の閉じた集合とする。追加は本表の更新を伴う。

現行の値域（実装の正: src/types/primitives.ts#ProofType: PAYER_EXEC_PROOF | PAYER_HV_ISOLATION_PROOF | PAYEE_EXEC_PROOF | NO_DEBIT_RECORDED_PROOF | ONCHAIN_ESCROW_LOCK_PROOF | ONCHAIN_RELEASE_PROOF | CREDIT_FAILED_PROOF | EXT_REFUND_PROOF）

規範（proof_type と venue は直交する別軸） ：SettlementProofRef は

BankProofRef の別名であって proof_type の値ではない。「どの決済場で確定したか」は

venue 列（BANK_LEDGER / IGS_BOJ / ONCHAIN / ATTESTATION / CB_TOKEN、

実装の正: src/types/primitives.ts#ProofVenue）が担い、proof_type は

「その証憑が何を証明しているか」を担う。両者を同じ列挙に混ぜてはならない

（契約は 32_api_contracts.md § SettlementProofRef）。

規範（HV の起動条件） ：高額即時レーンにおいて、PayerExecConfirmed の

bank_proof_ref.proof_type が PAYER_HV_ISOLATION_PROOF でない場合、ZC は

ExtInstructionSent（中銀決済依頼）を発行してはならない。外形上の状態は

PAYER_EXEC_CONFIRMED（a）と同一であるため、区別は proof_type だけが担う。

12.4 idempotency_key のスコープ（規範）

冪等キーは「どの論理コマンドの再送か」を一意に決める。スコープを取り違えると
txid / gtid / leg / attempt が混線し、別々の指図が同一要求として吸収される——
本節はその混線を構造的に防ぐためにキー空間を固定する。

書式（固定）

TX:{txid}:{name}:{issuer}
GT:{gtid}:{name}:{issuer}
LEG:{gtid}:{leg_id}:{name}:{issuer}
RTP:{rtp_id}:{attempt_id}:{name}:{issuer}
CASE:{case_id}:{name}:{issuer}

規範

1. 同一キー＝同一要求 ：同一 idempotency_key の再送に対し、受信側は副作用を
   1 回だけ発生させ、保存済みの応答を返す（32_api_contracts.md § 冪等性）。
2. 識別子部の省略禁止 ：LEG から leg_id を、RTP から attempt_id を落として
   はならない。落とすと同一 gtid の別 leg、同一 rtp_id の別 attempt が同一要求として
   吸収され、片方の指図が黙って消える。
3. {issuer} の省略禁止 ：発行主体が異なれば別のキーである。省略すると、ZC 発行の
   コマンドと参加行発行のイベントが衝突し得る。
4. キーの再利用禁止 ：ボディが異なる同一キーの再使用は 409 IDEMPOTENCY_KEY_CONFLICT
   （ボディ同一性はリクエスト全体の SHA-256 で判定。src/shared/idempotency.ts）。
5. 単発キーの例外 ：署名リプレイ防止用の sig:{key_id}:{nonce} はボディ比較の対象外
   （ハッシュ未保存・常に非衝突）。

実装: src/shared/idempotency.ts（acquireIdempotency / completeIdempotency /
resolveIdempotency）、テーブルは 31_schema.md § IdempotencyKeys。

12.5 command_seq / event_seq の粒度（規範）

seq は「どの範囲で単調であることを契約するか」を決める。全体順序は要求しない
（20_method_design.md §5.1）。

• 粒度＝送信者 × aggregate 。すなわち (producer.org_id, aggregate) の組ごとに
  独立したカウンタを持つ。aggregate の表記は §12.4 の先頭トークン＋識別子部と同一
  （TX:{txid}／GT:{gtid}／LEG:{gtid}:{leg_id}／RTP:{rtp_id}:{attempt_id}／
  CASE:{case_id}／BANK:{bank_id}／PSPR:{pspr_ref}／WINDOW:{window_id}／
  DNS:{business_date}／GLOBAL）。
• 永続・単調増加・巻戻り不可 。プロセス再起動をまたいでも巻き戻らないこと。
• 欠番は許容、再利用は禁止 。欠番は配送欠落・破棄として説明できるが、再利用は
  「同じ seq で別の内容」を生み監査が破綻する。
• COMMAND は command_seq 必須／event_seq は null または省略。EVENT は event_seq
  必須／command_seq は null または省略（両方を同時必須にしない。§12.2）。
• 受信側の検証義務 ：Kafka 等のキー順序に依存する場合でも、アプリ層で seq を検証する
  （20_method_design.md §5.5）。ギャップは許容、巻戻りは拒否。

ZC 内部の event_seq との関係 ：上記は参加行との I/F 契約上の粒度である。

ZC が FinalityLog へ書く event_seq は、これとは別に FinalitySeq 単一行の

UPDATE ... RETURNING で大域単調に採番される（§4 不変条件、§7.2）。両者を混同しないこと。

12.6 署名対象（signed_fields）と正規化（canonicalization）（規範）

署名は「アルゴリズム」より先に「何を署名するか」と「どうバイト列に落とすか」を
固定する。ここが揺れると、後日の監査・訴訟で「その署名は何を保証していたのか」が
争点になる。

12.6.1 署名対象（signed_fields）

最小必須集合（すべての cmd/event で署名対象に含める）

規範

1. signature.signed_fields には、実際に署名対象としたフィールドの完全な列挙を
   JSON Pointer 形式（/amount/value 等）で昇順に記載する。
2. 署名対象外のフィールドを増やしてはならない。 新フィールドを加法的に追加する場合
   （32_api_contracts.md § スキーマ進化 の「加法的・任意」）も、そのフィールドが業務上の
   意味を持つなら署名対象へ入れる。「任意フィールドだから署名しない」は禁止する——
   署名されない業務フィールドは、経路上で書き換えても検出できない。
3. signed_fields に列挙されていないフィールドは、受信側が業務判断に用いてはならない。

12.6.2 正規化（canonicalization）

signature.canonicalization の値は FIXED とし、次の手順を指す。

1. signed_fields の各 JSON Pointer が指す値を、列挙順に取り出す。
2. 各値を次のとおり文字列化する。
   • 文字列: そのまま（Unicode 正規化は NFC）
   • 整数: 十進表記、先行ゼロなし、負号は -
   • 真偽: true / false
   • null / 不在: 空文字列
   • 配列・オブジェクト: 本手順を再帰適用し、要素を , で連結
3. 得られた文字列を |（U+007C）で連結する（FinalityLog の entry_hash と同じ区切り。
   20_method_design.md §8.2.1）。
4. UTF-8 でエンコードしたバイト列を署名対象とする。

規範

• 浮動小数点は署名対象に含めない（金額は整数、レートは整数固定小数。20_method_design.md §17.3.1）。
• JSON のキー順・空白・エスケープ表現は正規化の入力にしない（値だけを順序どおり連結する）。
  これにより JSON シリアライザの実装差が署名の可否を左右しない。
• 本手順は破壊的変更の対象としない。 変更が必要な場合は canonicalization に
  新しい値（FIXED_V2 等）を導入し、32_api_contracts.md § スキーマ進化 の n / n-1
  併存受理に従って移行する。

12.6.3 検証側の義務

• 署名検証はメッセージ単位で行う（20_method_design.md §7.1 ゼロトラスト）。
• 鍵は KeyRegistry（31_schema.md § KeyRegistry）で解決し、revoked_at は非遡及
  （occurred_at < revoked_at の署名は有効。10_requirements.md §3.3.4）。
• 失敗時の reason_code は 32_api_contracts.md § エラーカタログ の
  EXTERNAL_SIGNATURE_INVALID / KEY_NOT_FOUND / KEY_REVOKED / KEY_EXPIRED /
  SIGNATURE_REPLAYED / TIMESTAMP_SKEW に写す。

実装: src/shared/external_signature.ts（外部主体の検証）、src/shared/zc_signature.ts
（ZC egress の非対称署名）、src/shared/hmac.ts（旧方式の後方互換パス）。

12.6.4 共有 HMAC のローテーション重複窓（規範）

ZC_HMAC_SECRET は全参加者が同じ値を持つ対称鍵であり、非対称鍵（§12.6.3）と違って
key_id 単位の差し替えができない。重複窓が無ければ交換は全か無かの切替になり、ZC が新しい
値で検証を始めた瞬間に旧値で署名している相手が全て 401 になる——結果として運用上は決して
ローテーションされないという、共有鍵にとって最悪の定常状態に落ち着く。したがって次を規範と
する。

• 署名は常に現行値のみ。旧値で署名してはならない（対外的な切替は瞬時に完了する）。
• 検証は旧値も受理する。ただし期限まで。旧値は ZC_HMAC_SECRET_PREVIOUS、期限は
  ZC_HMAC_SECRET_PREVIOUS_UNTIL（RFC3339）で与える。期限到来後は再デプロイなしに
  受理をやめる（窓は時計が閉じるのであって、人が変数を消し忘れないことに依存しない）。
• 期限の無い旧値は無効とする（fail-closed）。期限の無い 2 本目は重複窓ではなく
  「生きた鍵が 2 本ある」状態であり、本項が防ごうとしているものそのものである。解釈不能な
  期限も同じく無効として扱い、いずれの場合も警告を残す。
• 同じ扱いは bearer / API キーとしての比較（X-Api-Key・Authorization）にも適用する。
  比較は定数時間で行い、どの値に一致したかを応答時間から区別できないようにする
  （窓の開いている間、捕獲した鍵が現行か退役中かを attacker に教えないため）。

実装: src/shared/secret_rotation.ts。

12.6.5 /api/* の外周認証（規範）

ZC Core API に到達した呼び出し元を認証するのは 資格情報だけである。リクエストヘッダは
呼び出し元が自由に設定できる以上、ヘッダから「これは自分のダッシュボードだ」と推論しては
ならない。特に Origin の不在を同一オリジンの証拠として扱ってはならない——Origin は
ブラウザのヘッダであり、curl・スクリプト・サーバ間呼び出しは既定で付けない。不在を許可条件に
すると、排除したかった呼び出し元だけが通るという反転が起きる（Sec-Fetch-Site も同様。
ページには設定できないがクライアントには設定できるので、非ブラウザの攻撃者には何も証明しない）。

鍵無しの経路は推論ではなく運用上の明示的な選択としてのみ残す：同梱のデモ用ダッシュボードの
ために ZC_ALLOW_UNAUTHENTICATED_UI="true" を設定したときに限り、同一オリジンの無資格
呼び出しを通す。既定は off——何も書かなかったデプロイは閉じている。有効時は 1 リクエスト
ごとに警告ログ（http.unauthenticated_ui_access）を残し、この設定を入れた配備は API を
公開したのだと読むこと。同一オリジン判定はブラウザ向けの礼儀であって、第二の要素ではない。

このフラグが、UI から鍵なしで取引する（/api/* の POST を含む）ための公式かつ唯一の経路
である。参照リファレンスとしては UI から手で動かせることに価値があるが、その手段は
隠れた迂回路（バックドア）ではなく、明示・opt-in・可視のフラグでなければならない——
規範として理由を固定する：リファレンスはコピーされるため、認証を迂回する隠れた経路を
コードに置くと、複製した配備がその迂回路ごと本番に出る（本章が塞いだ Origin 欠落の穴と
同型）。ゆえに鍵無し経路を追加する場合も、常にこの 3 条件——既定 off・明示的な env による
opt-in・1 リクエストごとの記録——を満たすこと。ハードコードされた常時許可、未文書の
マジックヘッダ、常に通る秘密値の類は置いてはならない。

なお /internal/* は X-Cron-Secret の定数時間比較で fail-closed（src/router/internal.ts）、
/bank/* の ZC→Bank ingress は署名検証（§12.6.3）で、それぞれ別の資格情報に依っている。

実装: src/shared/api_auth.ts（判定）、src/index.ts（適用）。

12.7 パラメータ統制（公開版）

• パラメータはカテゴリ単位で管理し、変更時は 変更証跡（evidence_ref） と周知期間を必須とする。
• 変更は「変更管理（合意・証跡）」「監督説明」「参加者運用」のいずれに属するかを明確化し、責任主体を固定する。

12.8 対象カテゴリ（例）

• Express：PSPR有効期限、同期受付の目標遅延
• Standard：名義確認/Authority Checkのタイムアウト、保留→CASEへの収束期限
• Decision：受理→DECIDED_* の最大待ち、取消/保留境界
• RTP：Attempt回数（PR-RTP-ATTEMPT-MAX）・推奨時刻（PR-RTP-ATTEMPT-SCHEDULE）（当日収束のための自動再挑戦）
• gtid：legs固定後の変更不可、収束タイムアウト、総額上限
• Vault：保持上限、削除トリガ、退避（Evict）運用
• Consensus/Delivery：過半数合意を満たすノード構成、配送モデル（at-least-once）、冪等（seq巻戻り禁止）
• Crisis：DNS_HOLD/IGS制御（igs_mode）、dns_recovery_reserve 算定の信頼度閾値（reserve_confidence）、公平性スロットリング（igs_throttle_budget）

設計規範（Vault保持と情報喪失リスクの排除）

Vaultは短期保持を基本としつつ、Decisionに必要な情報が保持上限超過で失われないよう、上限到達時は退避（Evict）して参照を残す。

退避時は参照IDを発行し、参加主体側またはWORM複製へ自動移送する。

これにより「Decisionに必要な情報が消える」事故を規範として禁止する。

12.9 PR-* パラメータ台帳

本文（10_requirements.md・20_method_design.md）中に PR-* として登場する規程パラメータの索引。値そのものは制度（規程）で確定し、公開版では非公開のものがある。「所定時間」「所定水準」等の伏せ字も本台帳のカテゴリに属する。

12.9.1 伏せ字の基準（規範）

公開版で値を伏せるか具体値を書くかは、担当者の裁量にせず次の基準で決める。

HV 閾値の位置づけ（規範）：HIGH_VALUE 自動エスカレーション閾値の最終フォールバック

（1 億円）は法令由来の値ではなく、ZC 運営が 4 眼承認で確定する制度パラメータである

（10_requirements.md §3.2.7）。したがって上表の中段（制度が確定するパラメータ）に属し、

PR-HV-THRESHOLD として本台帳に登録する。PR-SOFT-LIMIT と同じ「公開（例示値）」の扱い

——値そのものは公開する（顧客説明・接続認定で必要なため）が、変更は制度行為である。

規範 ：本文に「所定時間」「所定期間」「所定水準」等の伏せ字を書く場合は、必ず対応する
PR-* を本台帳に登録し、本文からはその名前で参照する。名前の無い伏せ字を残してはならない

（どのパラメータの話かが特定できず、変更管理の対象にならないため）。

値の変更は §12.7 のパラメータ統制（evidence_ref ＋周知期間）に従う。新規の PR-* を本文へ

追加する場合は本台帳にも同時登録する。