Skip to content

docs: rewrite proof-system page to current accumulator model - #42

Merged
TaprootFreak merged 3 commits into
developfrom
docs/proof-system-rewrite
Jun 6, 2026
Merged

docs: rewrite proof-system page to current accumulator model#42
TaprootFreak merged 3 commits into
developfrom
docs/proof-system-rewrite

Conversation

@TaprootFreak

Copy link
Copy Markdown
Contributor

Summary

Rewrites docs/architecture/proof-system.md, which still described the superseded v0 design (a global account-keyed Commitment-SMT plus a Merkle Mountain Range of per-block roots) and carried only a one-line "superseded" pointer note from #32.

The page now reflects the current normative model:

  • Two PCD circuits — the per-account compliance circuit C (produces InitialProof / AccountUpdateProof) and the publisher's batch-aggregation circuit C_batch (produces AggregateBatchProof).
  • Three proof types (table updated with a circuit column), incl. AggregateBatchProof.
  • Data structures: removes the global Commitment-SMT and the MMR; keeps the two structures the spec defines — the per-account coin-history SMT and the global nullifier accumulator (the only global structure), with the §1.6 privacy-vs-rebuildability rationale.
  • Anchoring: accumulator transitions anchored on Bitcoin via BatchInscription (prev_root → new_root); per-transition validity attested off-chain by the k = 3-replicated BatchBundle's AggregateBatchProof.
  • Drops the now-obsolete superseded-design note and updates the hierarchy diagram, prover, and performance sections accordingly.

All cross-references point into the single-page spec (§1.1, §1.6, §2, §2.2, §2.3, §3.1, §3.7, §4.6) using precise subsection anchors (#37 link convention).

Test plan

  • npm run build clean locally (onBrokenLinks: throw + onBrokenAnchors: throw pass)
  • CI green
  • Quality reviewer PASS_CLEAN
  • Logic reviewer PASS_CLEAN (page matches spec §1.6 / §2.2 / §3.7)

Replace the superseded v0 description (global Commitment-SMT + Merkle
Mountain Range) with the normative model: two PCD circuits (per-account
compliance C, publisher batch-aggregation C_batch), three proof types
including AggregateBatchProof, and the nullifier accumulator as the only
global structure anchored on Bitcoin via BatchInscription roots plus the
off-chain k=3 BatchBundle. Removes the stale superseded-design note now
that the page reflects current spec sections 1.6, 2.2, and 3.7.
- Point BatchBundle links to the section that defines it (§4.6 data
  availability / replication) instead of §3.1 (the on-chain object,
  which defines the BatchInscription).
- Fix the requirement label: Requirement 10 is 'Node portability', not
  'rebuildability'.
@TaprootFreak
TaprootFreak marked this pull request as ready for review June 6, 2026 19:43

@TaprootFreak TaprootFreak left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Inhaltlich ein starker V2-Rewrite. Two-circuit-Modell sauber eingeführt, Three-Type-Tabelle mit Circuit-Spalte matcht §2.2, "What the batch proof binds" deckt alle relevanten Clauses ab (per-member soundness, S2C, nf-set integrity, accumulator transition, bundle-locator), Hierarchy-Diagramm clean, Cross-Refs konsequent auf Deep-Anchors (#37-Konvention). Obsolete Commitment-SMT + MMR sind raus.

Zwei substantive Befunde — beide im pseudo-Rust Code-Block für C (Z. 37-48):

1. Important — "Verify all incoming coins (BIP-340 Schnorr signatures, Merkle inclusion)" (Z. 42)

V2 §2.1 clause 2 ist explizit: eine per-transition-Signatur durch das current_pubkey Pkᵢ, nicht per-Coin. Spec-Zitat (§1.2-Verweis):

"Input authenticity. The whole transition is authorised by the account's single transition signature — there is no per-coin key and no per-coin signature."

Der Plural "Schnorr signatures" lässt es so aussehen, als gäbe es eine Sig pro Input-Coin. Vorschlag:

// 2. Verify the single per-transition BIP-340 signature by current_pubkey (Pkᵢ)
//    and each input coin's coin-history-SMT inclusion path

2. Minor — "new coin commitments" (Z. 45)

V2 verwendet nicht den Begriff "coin commitments" — Outputs sind Coin-Objekte mit coin.identifier, und der globale Akkumulator hat nur Nullifier, keine Commitments. Das ist V0/V1-Terminologie die in §1.6 explizit als obsolet markiert ist (MMR — deprecated; no Merkle Mountain Range is used in v1).

Vorschlag:

// 5. Derive the spent-coin nullifiers and the output coin identifiers

Lob

  • Die BatchBundle-Links für Off-Chain-Nullifiers sind präzise — das Privacy-Statement "What becomes public is only the spent-coin nullifiers (carried in the off-chain, k=3-replicated BatchBundle, not on Bitcoin)" ist genau richtig (Nullifier liegen in V2 NICHT on-chain, anders als V1).
  • Hierarchy-Diagramm zeigt clean die zwei Trees + die Anchor-Mechanik.
  • Cross-Refs alle Deep-Anchors, keine #X--section-top Drifts.

Nach Fix von #1 + #2 (10 Zeilen Code-Block-Update): ready to merge.

@TaprootFreak
TaprootFreak marked this pull request as draft June 6, 2026 21:21
- One per-transition BIP-340 signature by current_pubkey, not a
  per-coin signature (clause 2).
- Input coins are verified by coin-history-SMT inclusion at
  'received-unspent', not non-inclusion; global double-spend is enforced
  by the publisher's AggregateBatchProof and the receiver's accumulator
  non-membership check, not inside C (clauses 2, 4).
- Outputs are coin identifiers, not 'coin commitments' (clause 5).
- Add the per-transition spend-key rotation (clause 7).
@TaprootFreak
TaprootFreak marked this pull request as ready for review June 6, 2026 21:25
@TaprootFreak

Copy link
Copy Markdown
Contributor Author

Both findings fixed in ad8936d, and I extended the correction after re-checking the whole enforce() block against §2.1:

  1. Per-transition signature (your finding Release: develop -> main #1). The block now states the single per-transition BIP-340 signature by current_pubkey (Pkᵢ), with no per-coin signature — matching §2.1 clause 2.
  2. "coin commitments" (your finding Expand README with full project documentation #2). Replaced with "output coins and their identifiers" / output_coins_root — §2.1 clauses 5-6. No commitment terminology remains.

Two additional corrections the same block needed (not in the original review, but wrong against §2.1):

  1. Line 4 was "coin-history SMT non-inclusion" — that was backwards. §2.1 clause 2b + §1.7.6 verify an input by inclusion at leaf-state "received-unspent" (state 1), then flip it to spent. And the per-account proof makes no in-circuit global-non-membership claim (clause 4): global double-spend is caught by the publisher's AggregateBatchProof and the receiver's accumulator non-membership check. The block now says this explicitly.
  2. Added the spend-key rotation current_pubkey -> Pkᵢ₊₁ + send_counter increment (clause 7), which was missing.

Build green (anchors/links), CI green, and an independent logic pass confirms all six comment lines now map cleanly to §2.1 clauses 1-9. Back to ready.

@TaprootFreak TaprootFreak left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — ad8936d adressiert beide Befunde und macht den Code-Block schärfer als meine Vorschläge:

  • #1 (Schnorr-Plural): jetzt explizit "SINGLE per-transition BIP-340 signature by current_pubkey (Pkᵢ); … there is no per-coin signature".
  • #2 (coin commitments): "output coins and their identifiers" — V2-konsistent.
  • ➕ Clause 4 präzisiert dass C nur in-circuit coin-history-SMT non-inclusion macht; globaler Double-Spend-Schutz kommt aus AggregateBatchProof + Receiver-Non-Membership, NICHT aus C — exakte V2-Semantik aus §2.1 clause 4.
  • ➕ Clause 7 ergänzt (spend-key rotation Pkᵢ → Pkᵢ₊₁, send_counter++, coin-history-SMT update).
  • ➕ Balance-Check mit Mint: sum(inputs) + mint >= sum(outputs).
  • ➕ Reference-Tag "(the normative clauses are spec §2.1)" für saubere Pointer-Disziplin.

CI grün. Mergeable.

@TaprootFreak
TaprootFreak merged commit e488b5b into develop Jun 6, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant