Skip to content

docs: close the minor requirement gaps left open by the audit - #84

Merged
TaprootFreak merged 1 commit into
developfrom
docs/close-minor-requirement-gaps
Jul 10, 2026
Merged

docs: close the minor requirement gaps left open by the audit#84
TaprootFreak merged 1 commit into
developfrom
docs/close-minor-requirement-gaps

Conversation

@TaprootFreak

Copy link
Copy Markdown
Contributor

Why

The requirement re-audit left seven requirements at partial — but all with minor, documentary gaps: mechanisms the spec already has, just never made explicit, plus two v1 limits where requirements.md and the spec had drifted. This closes those. No design change.

What

Requirement 3 (Trustless) — the requirement names "freeze", "any setup procedure" and "trusted hardware" as parties/properties the spec never spelled out:

  • §6.6: derive freeze/censorship resistance explicitly (permissionless publishing + self-publish, a censoring publisher collects nothing, no node can lock a wallet in; availability under the k-replication DA bound named as the one honest limit), and state the trust base is software + keys + Bitcoin — no trusted hardware / secure enclave / HSM / TEE.
  • §1.7.9: FRI is transparent — no trusted setup, ceremony, SRS/CRS, or toxic waste.

Requirement 5 (Custody):

  • §4.5: during emergency recovery the wallet hands the rebuilt node only the operational bundle; seed + SPEND branch are re-derived wallet-side and never leave it.
  • §1.2: note the custody trade-off of a platform-synced passkey seed source (strict custody SHOULD use a device-bound passkey or a BIP-39 mnemonic).

Requirement 9 (Selective disclosure):

  • §5.6: an explorer MUST be self-hostable (was SHOULD) — aligns §5.6 with §6.1 and the requirement.
  • requirements.md clause 9: reconcile two v1 limits with the spec — the balance attestation is point-in-time as of the latest anchored state (§5.7), and a non-batched-mint disclosure verifies against its recursive mint proof rather than an on-chain anchor (§3.10 mint-verified). "Current balance" stays the stated goal; the spec: close the remaining open design decisions #79 anchor note is untouched.

Requirement 10 (Node portability):

  • §6.3: name the two node-switch residuals — the node-local, best-effort grant revocation set (re-instruct on switch), and an abandoned node's retained operational bundle (a privacy residual, not lock-in or a custody break; the switch itself is complete).

Requirement 8 (Multi-asset):

  • §6.5: clarify that an asset's name/decimals are IssuanceTerms display metadata, never on-chain (only name_hash/decimals bind into asset_id).

Explicitly out of scope (design decisions, left open)

Not documentary — these need a design decision and are not in this PR:

  • Publisher-identity on-chain linkage: making per-batch rotation a MUST (Req 2).
  • An IssuanceTerms delivery channel so a receiver learns a new asset's name/decimals (Req 8).
  • The recipient-own-node DA edge in emergency recovery (Req 6).

Scope

19 lines in specification.md, 1 clause in requirements.md. Reviewed on two lenses (correctness/no-overreach + consistency) — both clean; no test vectors affected.

Documentary consistency only — no design change. Closes the minor gaps the
requirement re-audit left in the 'partial' requirements, by making
mechanisms the spec already has explicit and reconciling two v1 limits.

- §6.6 threat model: derive censorship/freeze resistance explicitly as a
  Requirement 3 property (permissionless publishing + self-publish, a
  censoring publisher collects nothing, no node can lock a wallet in;
  availability under the k-replication DA bound named as the one honest
  limit), and state the trust base is software + keys + Bitcoin — no
  trusted hardware / secure enclave / HSM / TEE.
- §1.7.9: FRI is a transparent proof system — no trusted setup, ceremony,
  SRS/CRS, or toxic waste (Requirement 3's 'any setup procedure').
- §4.5: during emergency recovery the wallet hands the rebuilt node only
  the operational bundle; the seed and SPEND branch are re-derived
  wallet-side and never leave it (Requirement 5).
- §1.2: note the custody trade-off of a platform-synced passkey seed
  source; strict custody SHOULD use a device-bound passkey or a BIP-39
  mnemonic.
- §5.6: an explorer MUST be self-hostable (was SHOULD) — aligns with §6.1
  and Requirement 9.
- §6.3: name the two node-switch residuals — the node-local best-effort
  grant revocation set (re-instruct on switch) and the abandoned node's
  retained operational bundle (a privacy residual, not lock-in or a
  custody break).
- requirements.md clause 9: reconcile two v1 limits with the spec — the
  balance attestation is point-in-time as of the latest anchored state
  (§5.7), and a non-batched mint disclosure verifies against its recursive
  mint proof rather than an on-chain anchor (§3.10 mint-verified).
- §6.5: clarify that an asset's name/decimals are IssuanceTerms display
  metadata, never on-chain (only name_hash/decimals bind into asset_id).

Out of scope (design decisions, left open): publisher-identity linkage
rotation (Req 2), an IssuanceTerms delivery channel (Req 8), the
recipient-own-node DA edge (Req 6).
@TaprootFreak

Copy link
Copy Markdown
Contributor Author

Ready for review. Two review passes (correctness/no-overreach + consistency in parallel each round); both clean on the first pass, so no rework was needed.

Every added sentence was checked against the actual spec mechanism it claims (freeze resistance against §3.4 permissionless publishing + §6.3 no-lock-in, with the DA availability bound named honestly as the one limit; FRI transparency; the recovery custody actor; the two portability residuals against §5.2/§5.8), and the requirements.md clause-9 reconciliation was checked to align — not weaken — the requirement ("current balance" stays the goal; the #79 anchor note is untouched). The three design decisions remain explicitly out of scope.

@TaprootFreak
TaprootFreak marked this pull request as ready for review July 10, 2026 22:13
@TaprootFreak
TaprootFreak merged commit b2a9f82 into develop Jul 10, 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