Skip to content

Direct-Spend Wallet Blueprint for the Frozen TRQ1 Lane

Date: 2026-04-04
Status: Internal build blueprint
Scope: Smallest outside-package wallet/app layer that can reproduce the demonstrated Chipnet direct-spend flow cleanly

1. Purpose

This document defines the package and module blueprint for the next build phase.

The target is a new outside-package application shell that wraps standalone/prover-runtime without widening its boundary and reproduces the demonstrated live Chipnet direct-spend flow for the frozen lane.

This blueprint is aligned to the current Phase 3A, 3B, 3C, and 3D outputs and to the current Model C design position:

  • direct self-sovereign spend is the base path
  • optional aggregation is later and non-mandatory
  • no mandatory aggregator dependence is assumed
  • no shared global bottleneck is assumed
  • preferred long-term direction is isolated or shardable lineages first, optional aggregation later

2. Authoritative boundary statement

standalone/prover-runtime proves and verifies the frozen lane; packages/direct-spend-wallet is the smallest app shell that performs host-side checks, transaction orchestration, scan/recovery, and persistence for that same lane.

This boundary is the main design guardrail for the next build phase.

2.1 What stays inside standalone/prover-runtime

Keep the runtime narrow and publishable:

  • estimateProofSize(...)
  • proveSpend(...)
  • verifySpend(...)
  • strict PIv1 / PBv1 handling
  • deterministic request/report serialization
  • lane-scoped parity and conformance helpers
  • frozen backendId=2 / TRQ1 conformance support

2.2 What stays outside the runtime

The outside-package app shell must own:

  • wallet state and key access
  • protocol planning adapters
  • host-side validation
  • tx assembly / signing / broadcast
  • receive-path discovery and recovery
  • note persistence and replay
  • live evidence capture

2.3 Frozen lane assumptions

All implementation work under this blueprint remains aligned to:

  • backendId=2
  • TRQ1
  • fixed-statement canonical path
  • Stage-B structural/kernel-facing lane
  • no ABI widening
  • no verifier-visible witness aliases
  • no aggregation dependency
  • no public launch language

3. Package layout

Recommended monorepo structure for the next build phase:

standalone/
  prover-runtime/

packages/
  direct-spend-wallet/
  direct-spend-wallet-demo/      # optional thin demo/evidence harness

Legacy packages remain temporarily as migration sources, not as the final public build surface.

These legacy areas may continue to be wrapped or mined for logic:

  • planner logic
  • wallet note persistence logic
  • chain access / Electrum plumbing
  • tx building/signing helpers
  • host-side validation code paths
  • current e2e and Chipnet runner logic

4. Smallest outside-package layer

The smallest clean answer is:

a thin direct-spend-wallet package outside standalone/prover-runtime that owns planning, host-side checks, tx assembly/sign/broadcast, note scan/recovery, and persistence for the frozen backendId=2 / TRQ1 Chipnet lane.

This shell has six responsibilities.

4.1 Wallet state and keys

  • receiver identity (A, B)
  • sender wallet context
  • deterministic note records
  • spend/nullifier tracking
  • tracked protocol state outpoints
  • replay/reorg metadata

4.2 Protocol planning

  • prepare the canonical transition inputs
  • derive PIv1
  • build RRE1, encrypted payload bytes, hints bytes
  • compute the output-fingerprint bind material expected by the host path

4.3 Host-side validation

  • transcript binding recomputation
  • OFm2/v2 recomputation
  • continuation-shell checks
  • malformed-carrier rejection
  • routing and compatibility checks
  • token/state parity checks where required by the current boundary
  • fail closed on any mismatch

4.4 Transaction orchestration

  • assemble entry / send / exit transactions
  • sign them
  • broadcast them
  • capture txids and benchmark evidence

4.5 Recovery and scan

  • parse candidate confidential transitions
  • parse and validate RRE1
  • test ownership locally
  • decrypt only after ownership match
  • recompute commitments and verify roots before persistence

4.6 Persistence and replay

  • persist wallet-note records
  • support deterministic replay from chain data plus wallet keys
  • maintain the minimal state needed to reproduce the accepted Chipnet flow

5. New package: packages/direct-spend-wallet

5.1 Public surface

Recommended first public surface:

  • prepareEntry(...)
  • prepareConfidentialSend(...)
  • prepareExit(...)
  • signPreparedTx(...)
  • broadcastPreparedTx(...)
  • scanForInboundNotes(...)
  • recoverInboundNotes(...)
  • persistWalletState(...)
  • replayWalletState(...)
  • captureRunEvidence(...)

5.2 Initial module map

packages/direct-spend-wallet/
  src/
    types/
    keys/
    state/
    planner/
    runtime/
    host-checks/
    tx/
    recovery/
    evidence/
    flows/
    demo/

6. Detailed module blueprint

6.1 src/types/

Purpose: - package-local interfaces - stable internal contracts - avoid leaking legacy naming through the new package boundary

Suggested files: - wallet_types_v1.ts - transition_plan_types_v1.ts - recovery_types_v1.ts - evidence_types_v1.ts

6.2 src/keys/

Purpose: - hold receiver identity (A, B) - hold sender wallet context - standardize key access for send and receive flows

Suggested files: - receiver_identity_v1.ts - sender_context_v1.ts - key_derivation_policy_v1.ts

Primary duties: - scan/spend key access - one-time owner key support for receive path - compatibility with protocol draft’s stealth-compatible identity model

6.3 src/state/

Purpose: - own deterministic wallet state and replay state - make lineage/root tracking first-class

Suggested files: - wallet_state_v1.ts - wallet_note_record_v1.ts - tracked_state_cell_v1.ts - replay_checkpoint_v1.ts - persist_wallet_state_v1.ts

Required stored concepts: - note status - protocol state outpoint - tracked lineage - relevant roots - spent/nullified status - reorg metadata - discovery source

6.4 src/planner/

Purpose: - wrap existing planner logic - keep the planner pure - adapt wallet intent and protocol state references into deterministic transition plans

Suggested files: - direct_spend_planner_adapter_v1.ts - prepare_entry_plan_v1.ts - prepare_send_plan_v1.ts - prepare_exit_plan_v1.ts

Planner output should include: - PIv1 bytes - encrypted payload bytes - RRE1 hints bytes - output-fingerprint bind material - state transition refs - prevout/session refs

No proving, signing, broadcast, or persistence should happen here.

6.5 src/runtime/

Purpose: - wrap standalone/prover-runtime - keep the frozen lane assertions strict - prevent silent fallback

Suggested files: - prover_runtime_adapter_v1.ts - frozen_lane_assertions_v1.ts

Responsibilities: - call estimateProofSize - call proveSpend - call verifySpend - assert backendId=2 - assert TRQ1 - reject unsupported runtime drift

6.6 src/host-checks/

Purpose: - implement the real trust seam outside the runtime - keep fail-closed behavior explicit and reproducible

Suggested files: - fail_closed_host_checks_v1.ts - transcript_bind_v1.ts - output_fingerprint_v1.ts - continuation_shell_v1.ts - malformed_carrier_v1.ts - routing_compatibility_v1.ts - token_state_parity_v1.ts

Execution order should enforce: 1. transcript binding recomputation 2. OFm2/v2 recomputation 3. continuation-shell checks 4. malformed-carrier rejection 5. routing/compatibility checks 6. token/state parity where required 7. terminal failure on first mismatch

6.7 src/tx/

Purpose: - own tx assembly, signing, and broadcast - remain downstream of proven runtime success and host-check success

Suggested files: - direct_spend_tx_orchestrator_v1.ts - assemble_entry_v1.ts - assemble_send_v1.ts - assemble_exit_v1.ts - sign_tx_v1.ts - broadcast_tx_v1.ts - chipnet_runner_v1.ts

Responsibilities: - build entry/send/exit txs - sign txs - submit via Chipnet runner - return txids and broadcast result - never continue after failed upstream gate

6.8 src/recovery/

Purpose: - make the receive path a first-class standardized subsystem

Suggested files: - receive_path_v1.ts - candidate_discovery_v1.ts - candidate_index_schema_v1.ts - ownership_test_v1.ts - note_decrypt_v1.ts - note_validate_v1.ts - lineage_tracking_v1.ts - replay_v1.ts

Receive-path contract

The receive flow must remain fully local and deterministic:

  1. get candidates from chain scan, block-filter-assisted scan, or advisory index feed
  2. parse candidate transition
  3. parse RRE1
  4. ownership test with (A, B)
  5. decrypt payload if matched
  6. recompute note commitment and roots
  7. persist validated wallet-note record

Required standardization items

Near-term receive-path improvements to include in the roadmap:

  • add strong block-filter-assisted candidate reduction
  • standardize public candidate indexing for RRE1 and protocol outpoints
  • make lineage/root tracking first-class in wallet state
  • persist enough note metadata to narrow rescans after first discovery

Discovery modes

Support three discovery modes under one receive interface:

  • direct chain scan
  • block-filter-assisted scan
  • optional public candidate/index server feed

Public candidate indexing schema

Standardize these public fields where candidate indexing is used:

  • txid
  • height
  • vin
  • protocol_outpoint
  • rre_version
  • tx_ephemeral_pubkey_R
  • recipient_note_count
  • envelope_offset
  • envelope_length
  • optional raw RRE1_SECTION

Authority rule

Even with candidate reduction and public indexing:

  • ownership determination remains local
  • decryption happens only after ownership match
  • note validity remains local
  • spendability remains local
  • no public recipient marker is introduced

6.9 src/evidence/

Purpose: - tie the next build phase to live evidence instead of theory

Suggested files: - chipnet_run_artifacts_v1.ts - benchmark_capture_v1.ts - accepted_path_report_v1.ts

Canonical artifact outputs: - tx hex - tx bytes - proof blob bytes - fee - sats/byte - acceptance result - visibility timing - receiver recovery timing - wrong-key recovery result

6.10 src/flows/

Purpose: - define high-level application flows without broadening the protocol boundary

Suggested files: - invisible_entry_then_send_v1.ts - existing_note_send_v1.ts - direct_exit_v1.ts

Invisible protocol entry rule

Do not force users through an explicit legacy “join pool” mental model.

Flow rule: - if wallet already has a spendable protocol note, go straight to confidential send - if wallet only has ordinary BCH, perform internal protocol entry, materialize sender-owned note/state, then continue into confidential send

6.11 src/demo/

Purpose: - provide a deterministic minimal harness for canonical-flow reproduction - stay narrow and evidence-focused

Suggested files: - canonical_chipnet_flow_v1.ts - wrong_key_recovery_check_v1.ts - demo_fixture_runner_v1.ts

7. Expanded development roadmap

Phase 0 — boundary freeze

Goal

Freeze package responsibility before implementation.

Deliverables

  • one boundary-freeze note
  • package ownership table
  • module map
  • frozen lane assumptions
  • what stays in runtime vs outside runtime vs legacy

Acceptance

  • standalone/prover-runtime remains narrow
  • packages/direct-spend-wallet is explicitly defined as the outside-package shell
  • no planner, chain, or persistence concerns drift back into runtime

Phase 1 — extract the minimum happy path

Goal

Support only the already-demonstrated live lane:

  • frozen lane: backendId=2, TRQ1
  • fixed-statement canonical path
  • direct self-sovereign spend
  • accepted Chipnet entry/import and send shape
  • receiver recovery succeeds
  • wrong-key recovery fails closed

Deliverables

  • minimal wallet state model
  • planner adapter
  • runtime adapter
  • tx runner path for the canonical flow
  • receive/recovery path for the canonical flow

Acceptance

  • reproduces the accepted canonical flow only
  • does not generalize early
  • stays aligned with the current claim boundary

Phase 2 — implement the app shell in strict order

Build order

  1. wallet state model
  2. planner adapter
  3. runtime adapter
  4. host-check pipeline
  5. tx assembly/sign/broadcast
  6. recovery/scan
  7. persistence/replay

Why this order matters

The host-check pipeline is the real seam. Transcript binding, OFm2/v2, continuation-shell checks, malformed-carrier rejection, and parity remain load-bearing outside the proving slice today.

Acceptance

  • each layer composes in order
  • no downstream action occurs after upstream failure
  • no silent fallback

Phase 3 — make invisible protocol entry first-class

Goal

Provide one coherent user path for direct confidential send.

Deliverables

  • direct send from existing note path
  • invisible entry path when only ordinary BCH is available
  • internal materialization of sender-owned note/state before confidential send

Acceptance

  • no manual “join/import” mental model required for the minimal app shell
  • no verifier/protocol redesign introduced

Phase 4 — standardize the receive path

Goal

Make receive a formal subsystem, not an afterthought.

Deliverables

  1. strong block-filter-assisted candidate reduction
  2. standardized public candidate indexing for RRE1 and protocol outpoints
  3. lineage/root tracking as first-class wallet state
  4. enough persisted note metadata to narrow rescans after first discovery
  5. deterministic replay and reorg-safe rebuilding of note state

Acceptance

  • ownership testing remains local
  • no public recipient marker
  • no trusted server truth
  • candidate set narrows over time
  • replay from chain data plus keys remains authoritative

Phase 5 — add reproducible Chipnet evidence capture

Goal

Emit structured evidence for every canonical run.

Deliverables

  • canonical artifact generator
  • benchmark capture
  • wrong-key recovery evidence
  • accepted-path reporting

Acceptance

  • live runs emit structured artifacts
  • evidence is suitable for deterministic comparison
  • next build phase remains tied to live execution evidence

Issue 1

Boundary freeze for packages/direct-spend-wallet MVP

Define: - package boundary - ownership table - module list - frozen lane assumptions - what is wrapped vs migrated from legacy code

Issue 2

Implement minimal direct-spend-wallet happy path

Build: - wallet state - planner adapter - runtime adapter - host-check pipeline - tx assembly/sign/broadcast - minimal recovery path - persistence/replay

Issue 3

Receive-path standardization pack

Build: - candidate discovery modes - public candidate indexing schema - lineage/root tracking - narrowed-rescan persistence rules - replay/reorg conformance tests

Issue 4

Chipnet reproducibility/demo harness

Build: - deterministic demo runner - evidence capture - canonical accepted-path artifact generation

9. What not to do next

Do not start with:

  • aggregation
  • shared advancing pool design
  • verifier redesign
  • moving host checks inward
  • broad wallet SDK ambitions
  • multi-lane abstraction

Those are later.

The next build phase should stay focused on one wallet, one direct confidential flow, one frozen lane.

10. Codex prompt for the next build phase

Use this prompt to partner with Codex.

We are starting the next build phase.

I want you to produce a boundary-freeze note plus an executable issue ladder for a new package:

packages/direct-spend-wallet

Goal:
Define the smallest outside-package wallet/app layer that can reproduce the already-demonstrated Chipnet direct-spend flow cleanly while wrapping standalone/prover-runtime without widening its boundary.

Context to carry forward:
- Phase 3A, 3B, 3C, and 3D planning/hardening notes are complete
- standalone/prover-runtime is the narrow frozen proving/runtime surface
- direct self-sovereign spend is the base path
- optional aggregation is later and non-mandatory
- no mandatory shared pool or aggregator dependence is allowed
- frozen lane remains backendId=2, TRQ1, fixed-statement canonical path
- no ABI widening
- no verifier-visible witness aliases
- no public launch language

I want two outputs only:

1. A boundary-freeze note for packages/direct-spend-wallet
2. A smallest executable issue ladder to build it

The boundary-freeze note must define:
- what belongs inside packages/direct-spend-wallet
- what stays inside standalone/prover-runtime
- what remains in legacy packages temporarily
- the minimal end-to-end flow to reproduce
- the module/package map
- the receive-path standardization responsibilities
- the invisible protocol entry rule
- the live evidence capture responsibilities
- explicit non-goals

The issue ladder should be minimal and executable.
I expect something close to:
- one MVP boundary freeze issue
- one minimal happy-path implementation issue
- one receive-path standardization issue
- one Chipnet reproducibility/demo issue

But decide based on the actual repo shape.

Important receive-path requirements to include:
- strong block-filter-assisted candidate reduction
- standardized public candidate indexing for RRE1 and protocol outpoints
- lineage/root tracking as first-class wallet state
- enough note metadata persistence to narrow rescans after first discovery
- ownership/validity decisions remain local

Important boundary rule:
standalone/prover-runtime proves and verifies the frozen lane; packages/direct-spend-wallet performs host-side checks, transaction orchestration, scan/recovery, and persistence for that same lane.

Output I want back:
1. path to the new boundary-freeze note
2. concise inside/outside split
3. proposed issue ladder with titles, scope, and acceptance criteria
4. the single issue that should be executed first

Do not implement code yet.
Do not widen scope.
Do not start aggregation work.
Do not redesign the verifier.

11. Bottom line

This blueprint defines the next build effort clearly:

  • standalone/prover-runtime stays narrow and publishable
  • packages/direct-spend-wallet becomes the smallest clean outside-package layer
  • the receive path becomes a formal subsystem
  • invisible protocol entry becomes part of the shell
  • live Chipnet evidence capture is built in from the start

This is the smallest package/module plan that can reproduce the demonstrated live flow without cheating on the current trust boundary.