Skip to content

verification-source-contract.md

Latest commit

 

History

History
108 lines (79 loc) · 4.33 KB

verification-source-contract.md

File metadata and controls

108 lines (79 loc) · 4.33 KB

Verification Source Contract

This document defines the shared trust/source contract used by core, CLI, and desktop output.

Source of truth

  • packages/core/src/lib/trust/sources.ts
  • packages/core/src/lib/trust/types.ts
  • packages/core/src/lib/verify/index.ts

Stable IDs

Use constants from VERIFICATION_SOURCE_IDS and GENERATION_SOURCE_IDS instead of hardcoded strings.

Why:

  1. Shared IDs keep CLI/UI/tests aligned.
  2. Refactors remain compile-safe when IDs evolve.

Context builder

Always construct context via createVerificationSourceContext(...).

This enforces defaults from DEFAULT_VERIFICATION_SOURCE_CONTEXT and avoids field drift at call sites.

Consensus trust matrix

Consensus trust for consensus-proof is derived from:

  • hasConsensusProof
  • consensusVerified
  • consensusMode (beacon, opstack, linea)

Rules:

  1. hasConsensusProof=false:
    • source status: disabled
    • trust: rpc-sourced
    • summary/detail explain proof omission and fallback trust
  2. hasConsensusProof=true, consensusVerified=false:
    • source status: enabled
    • trust: rpc-sourced
    • summary/detail explain included-but-not-upgraded proof
  3. hasConsensusProof=true, consensusVerified=true:
    • source status: enabled
    • trust:
      • beacon -> consensus-verified-beacon
      • opstack -> consensus-verified-opstack
      • linea -> consensus-verified-linea

For OP Stack and Linea, summary/detail must preserve the non-equivalence boundary to Beacon light-client finality.

Desktop UI rule:

  • Chain state is finalized must consume the core consensusTrustDecisionReason.
  • Even when consensusVerification.valid === true, any non-null trust decision reason (for example state-root-mismatch-policy-proof or block-number-mismatch-policy-proof) must downgrade the safety check from check to warning/error according to isWarningConsensusTrustDecisionReason(...).

Decoded calldata trust matrix

decoded-calldata trust is derived from decodedCalldataVerification:

  1. self-verified -> trust self-verified
  2. partial -> trust api-sourced with partial-verification wording
  3. mismatch -> trust api-sourced with explicit mismatch wording
  4. api-only or omitted -> trust api-sourced

Simulation trust matrix

simulation trust is derived from witness + replay outcomes:

  1. no simulation artifact -> source disabled
  2. simulation without witness -> trust rpc-sourced
  3. simulation + witness, but witness verification fails -> trust rpc-sourced
  4. simulation + witness verified, replay not run/failed/mismatch -> trust rpc-sourced
  5. simulation + witness verified, replay executes and matches, and structural simulation verification passes -> trust remains rpc-sourced until replay world-state accounts are fully state-root proven

Notes:

  • In witness-only packages, replay-complete inputs are attached so simulation effects can be re-derived locally during verification; packaged simulation effects are retained for replay/effect comparison.
  • simulationWitness.simulationDigest must always be computed from the exact packaged simulation payload (including witness-only stripped projections).
  • Desktop Simulation outcome must not return a success/check state for witness-only packages unless both witness verification and replay verification succeed.
  • Witness-only replay requires complete replay inputs: world-state accounts and pinned block environment (timestamp/gas/basefee/beneficiary, plus optional prevrandao/difficulty). If block context is missing, replay must fail closed.
  • Replay currently supports operation=0 (CALL) only. For operation=1 (DELEGATECALL), generator must keep packaged simulation effects and export cannot be labeled fully-verifiable.
  • Log equality checks apply when packaged logs are present; witness-only replay still enforces success/return-data/gas policy checks.
  • Replay success currently proves deterministic consistency against provided witness inputs, not full cryptographic completeness for all replay world-state accounts. Do not label simulation as proof-verified under this model.

Required tests

When changing this contract, update and run:

  • packages/core/src/lib/trust/__tests__/sources.test.ts
  • packages/core/src/lib/verify/__tests__/report.test.ts
  • packages/cli/src/cli.output.test.ts (if output wording or IDs change)