Skip to content

Wallet Integration Spec

This page defines the integration boundary for external wallet or application implementers using the published direct-spend lane.

Protocol Rules vs Wallet Policy

  • Protocol rules: authoritative continuation object, verifier boundary formats, and bounded acceptance semantics.
  • Wallet policy: key management, fee policy, selection heuristics, scanning cadence, and operational preferences.

Wallet policy must not redefine protocol authority semantics.

Authoritative Protocol Source

  • The authoritative spend source is the latest continuation output.
  • A recovered note grants private authority to advance that continuation output.
  • Integration must not model the recovered note as a separate transparent on-chain source.

Recovery, Discovery, And Tracking

A reference receive path includes:

  1. candidate discovery
  2. ownership test
  3. payload decrypt
  4. note validation
  5. state persistence and continuation tracking

The Receiver Recovery Envelope 1 (RRE1) and related note material are protocol objects used by recovery logic. Reusable Payment Address (RPA) usage remains transport-level and non-normative for protocol authority.

Required Integration Responsibilities

  1. select continuation input as the protocol authority source
  2. construct proving request with valid Public Inputs version 1 (PIv1) and witness material
  3. invoke runtime prove/verify path for the published lane
  4. carry runtime-produced Proof Blob version 1 (PBv1) bytes unchanged into transaction assembly
  5. enforce host checks fail-closed before broadcast
  6. persist next continuation state for follow-on spend
  7. classify artifacts truthfully (hidden semantics vs public observables)

Authority/Economics Separation

Supplemental transparent inputs may satisfy shell/fee feasibility. They do not replace protocol authority inputs.

Current Truth And Limits

  • Current truth: first-hop and follow-on direct-spend flows are live-validated in the bounded lane.
  • Proof-enforced semantics: bounded transition semantics are enforced by the published statement.
  • Artifact-described behavior: wallet evidence and telemetry are descriptive outputs.
  • Public observables: shell economics and graph-level information remain public.
  • Future optional aggregation: later service layers may reduce observability but are not required for base conformance.

Code Mapping