Release: develop -> main - #133
Open
github-actions[bot] wants to merge 7 commits into
Open
Conversation
* docs: add kernel.v1 wire-contract completeness proposal Record two places where the published kernel.v1 gRPC contract cannot be driven from its .proto alone, and propose a single additive amendment: - Pull carries no ownership-vs-grant session discriminator, so a client built from the contract cannot open a session GetAccountState accepts (the node bridges this out-of-band via an x-zkcoins-session-authority metadata key today). - Issuance/TransitionRequest lack the creator/genesis base pubkey that minting and genesis receives genuinely need; the node proto already carries these fields, diverging from the normative contract. The recommendation is a single additive pre-step-7 amendment permitted by the §1.7.8 between-step-3-and-step-7 rule (with GET /v1/token/<id>/provenance as the stated precedent), touching no circuit element, vector, or digest. * docs: refine v1 wire-completeness proposal after review - Extend to both wire levels: the §7.5 REST TransitionRequest/issuance and the §7.8 kernel.v1 gRPC messages omit the same creator/genesis pubkey fields, and both the api JSON and the node proto already carry them undocumented. - Correct the framing: the SDK and third-party clients speak §7.5 REST only, not kernel.v1 gRPC. - Present the resolution as fair options with trade-offs (add the fields / derive at bootstrap entrust / defer to v2 / document the divergence) rather than a single settled recommendation. - Ground the additive-amendment case in the §1.7.8 between-step-3-and-7 rule, with the provenance read as the stated precedent; note it touches no circuit element, vector, or digest and moves no trust boundary.
Deploying zkcoins-docs with
|
| Latest commit: |
9fcdacc
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e330b8b6.zkcoins-docs.pages.dev |
| Branch Preview URL: | https://develop.zkcoins-docs.pages.dev |
…l-session authority (§7.5, §7.8) (#134) * spec: complete the v1 wire contracts (§7.5 REST, §7.8 kernel.v1) Follow-up to the #132 decision record. Adds issuance.creator_pubkey and a top-level genesis_pubkey to the §7.5 TransitionRequest, ratifies Issuance.creator_pubkey=7 and TransitionRequest.genesis_pubkey=12 in the §7.8 kernel.v1 proto, and adds the new PullRequest.authority closed string that retires the x-zkcoins-session-authority metadata key. Additive §7 change under the §1.7.8 between-step-3-and-step-7 rule: touches no circuit element, no pinned vector, and no digest, and moves no trust boundary. The reference node/api already carry the two pubkey fields. * spec: bind genesis_pubkey presence to InitialProof semantics Define the genesis receive by proof semantics — an InitialProof with prev_proof absent and prev_account_state the canonical empty account (§2.1 clause 1, §2.3.3) — rather than node-local "first transition on this node" / "registered account" framing, which §6.3 node portability makes ambiguous. Use modal-only bold emphasis per the document convention.
* docs: specify optional Marmot/MLS group-chat overlay
Adopt Marmot transport v1 and RFC 9420 as an off-by-default group_chat
feature. Keep mandatory NIP-17 one-to-one messaging unchanged.
* docs: close group-chat review contradictions
Separate MLS leaf CSPRNG from key-schedule epoch secrets, carve
application-message retention out of Requirement 12, require wallet
with group_chat, and restore the Bitcoin-bridge risks row.
* docs: add group member-remove route and permanence carve-outs
Specify POST /v1/groups/:id/members/remove for V.13 admin remove,
align D19 op-signing language, and mention the Marmot application-
message exception in every Data Permanence summary.
* docs: wire group-chat REST to kernel.v1 and close error codes
Add ListGroups…PublishKeyPackage RPCs, the group_members_remove
discovery key, not_group_admin, and distinguish admin-only
membership from self-leave.
* docs: close group-chat error-mapping contract
Add feature_disabled and invitee_not_ready to the closed machine
codes, emit them from kernel.v1 without remapping, and gate wire
processing on the kernel part rather than the API feature.
* docs: bind group-chat routes to ownership pull sessions
Group RPCs take session and chan_bind like account/state. A grant
session is 401 unauthorized; an expired token is 410 session_expired.
* docs: pin invite/remove success bodies and mention group_chat in README
Invite and remove return {invited:true} and {removed:true} from GroupAck.
README lists group_chat with the other optional API features.
* docs: pin group-chat check order, list fields, and publish success
Decide feature/auth/kernel checks in order, leave list payloads
without members, pin created_at to the inner application event,
and treat HTTP 200 as persist plus first publish attempt.
* docs: tighten G-09, 10002, list order, and unknown KeyPackage slots
Align G-09 with the session-then-kernel check order, require kind
10002 in V.13, sort GroupMessageList, and map unknown slot d to 404.
* docs: close remaining group-chat error and list ambiguities
Put nk in G-03, omit list members/relays, reject empty KeyPackage d,
and order invite failures as group, admin, then inbox readiness.
* docs: mark Marmot group chat as v2, not a v1 feature
Record the overlay as a later protocol version, like Passkeys.
v1 must not advertise or serve it; group REST moves to /v2/groups*.
* docs: keep feature_disabled general and move group RPCs to kernel.v2
Restore the v1 meaning of feature_disabled. Record group procedures
as a kernel.v2 preview so the kernel.v1 contract stays closed.
… develop) (#137) * docs(mandate): the api serves testnet and mainnet in parallel; app selects network at runtime The api layer is a per-network multiplexer: one kernel.v1 upstream per served network, a /v1/{network}/... path-prefix selector, and a network-less GET /v1/networks discovery. Networks run in parallel, not as a testnet->mainnet cutover; the node stays single-network and the api multiplexes above it. The app gains a runtime network switch with strictly network-scoped custody and history. * docs(spec): define the §7.5 multi-network projection (path prefix, discovery, fail-closed routing) Addresses the review of the mandate-only amendment: the network selector is a §7 wire addition and belongs in specification.md §7.5, not asserted in the mandate alone. Adds a normative 'Multi-network projection' subsection to §7.5 — the /v1/{network}/ path segment, the network-less GET /v1/networks discovery, per-network /health/ready, 404 network_unavailable vs 503 dependency_unavailable, the mandatory upstream Info.network identity check (anti network-confusion), and strict per-network scoping of custody/sessions/idempotency. Adds 'networks' to the GET / closed key set. The mandate now references §7.5 instead of originating the contract, calls the kernel upstream (not the node §7.5 surface) single-network, points /v1/{network}/info at the §7.5 /v1/info body, and includes regtest in the app network switch so the regtest A-to-Z gate is addressable. * docs(spec): close review round 2 on the §7.5 multi-network projection Extends the network path prefix to the §7.6 publisher and §7.7 bootstrap endpoints; distinguishes admission (permanent, gate passed) from live readiness so an admitted network stays in GET /v1/networks during transient not-ready; requires the GET / endpoints map to use {network} URI templates in a multi-network deployment; constrains a shared Blossom origin to deployment-global admission/quota (else a per-network origin with network-bound upload auth); ties discovery eligibility to the ready-to-serve health-ready criterion, distinct from step-10 activation; and converts the remaining indicative-mood rules to RFC-2119 MUST/MUST NOT. * docs(spec): close review round 3 — network state model + network_unavailable/network_not_ready codes Restructures the §7.5 Multi-network projection around explicit network states (not-served -> 404 network_unavailable; served-not-ready incl. not-yet-admitted -> 503 network_not_ready with the reason on /v1/{network}/health/ready; ready -> serve), adds both codes to the closed machine_code table, carves the content-addressed Blossom keys out of the {network} URI-template rule and drops the unsatisfiable per-network upload-auth binding in favour of distinct per-network origins, clarifies the single-network unprefixed form is a distinct served route (not a fallback), converts the remaining indicative rules to MUST, and updates the runbook step-9 predicate to the prefixed /v1/mainnet routes. * docs(spec): close review round 4 — §7.8 kernel readiness enforcement for network_not_ready The §7.5 503 network_not_ready promise is now backed end-to-end: §7.8 gains a kernel-authoritative readiness rule (a kernel MUST return UNAVAILABLE/network_not_ready from every consensus-dependent procedure when not ready), and network_not_ready/503 is added to the UNAVAILABLE column for GetAccountState, SubscribeReceipts, Publish, SubmitTransition, AttestBalance and the four procedures previously carrying the informal 'not-ready -> 503' note — closing the stale-read TOCTOU; network_unavailable stays API-only. Also converts the last three indicative rules in the §7.5 projection to MUST/MUST NOT/MAY. * docs(spec): close review round 5 — readiness enforcement vs async jobs and GetInfo duality GetInfo MUST always succeed with Info.ready/ready_reason (the API derives both /v1/{network}/info and /health/ready from that one call, and the upstream-identity check needs Info.network on a not-ready upstream) — its per-procedure network_not_ready cell is removed. A SubmitTransition/AttestBalance job's consensus-dependent work runs after the accepting RPC, so the kernel MUST NOT advance/deliver/publish/complete a consensus-dependent job phase while not ready (pause until ready); SignTransition gains a network_not_ready cell. The §7.6 publish HTTP-status table and endpoint description gain the served-but-not-ready -> 503 network_not_ready row, matching the kernel cell. * docs(spec): close review round 6 — publisher batch queue honours the readiness lock The round-5 readiness rule covered SubmitTransition/AttestBalance job phases, but the permissionless Publish hand-off has no job_id: its accept-time 503 gate only guards acceptance, while half-aggregation and inscription happen later (batch_eta). Extend the §7.8 readiness rule so an already-accepted Publish hand-off MUST NOT be half-aggregated or inscribed while the network is not ready — held in the batch queue until ready, with block_anchor freshness re-validated before inscription. * docs(spec): scope the Publish readiness hold to existing publisher semantics; qualify §3.4 staleness The round-6 readiness clause introduced a re-validation step whose failure case was undefined (an accepted, job_id-less Publish hand-off could be held then dropped with no terminal signal). Rather than grow the multi-network PR into the pre-existing publisher-hand-off best-effort/staleness model, the readiness hold now defers to the unchanged §7.6 accept/inscription and §3.5 block_anchor-freshness semantics (best-effort inscription is a pre-existing publisher property). §3.4's 'no risk of going stale' is qualified as contention-only; the §3.5 freshness bound still applies. The deeper publisher post-accept staleness terminal-state question is pre-existing and left to a focused follow-up, not this PR. * docs(spec): close review round 7 — path inventory, admitted discovery, readiness error body Pin /v1/{network}/health/ready as the mandatory probe, keep unprefixed /health/ready as a single-network MAY, and list only admitted networks on GET /v1/networks. The generic error body covers 404 network_unavailable on the readiness path; not-ready consensus RPCs emit only network_not_ready. * docs(spec): close review round 8 — A-to-Z N-10, prefixed attest/grants, readiness residuals Add the V.9 N-10 fail-stop as a numbered A-to-Z assertion, target attest/grant calls at /v1/regtest, and keep GetInfo plus the readiness body available on a not-ready upstream. Qualify leftover /health/ready mentions as the single-network MAY form. * docs(mandate): run V.9 N-10 fail-stop after recovery and grant controls A ≥6-block reorg has no recovery path, so the A-to-Z suite cannot require restore/send/attest/grant on the same instance after N-10. * docs(spec): pin error precedence for network_unavailable, feature_disabled, network_not_ready Unserved networks fail before feature checks. A disabled feature on a served network fails before readiness. Only enabled consensus-dependent endpoints return 503 network_not_ready. * docs(spec): register feature_disabled in the closed §7.5 machine_code table Error precedence already dispatches this API-only 404 for a served network whose feature is off. The closed enumeration now lists it. --------- Co-authored-by: TaprootFreak <142087526+TaprootFreak@users.noreply.github.com>
TaprootFreakAI
approved these changes
Aug 17, 2026
…idge (#138) * Risks: zkBTC is the specified effectively-trustless BTC bridge Replace the outdated claim that a trustless BTC bridge is an open research problem. Point to zk-coins/zkbtc: growth-only operator set, self-operator, optional gatekeeper. * Tighten the zkBTC risks paragraph against this catalog Keep the pointer to zk-coins/zkbtc. Add join-before-first-mint and sound circuit/graph crypto. Stop numbering a token standard that this protocol catalog does not yet list. * Risks: pin the zkBTC spec URL and scope Attack A Point the BTC-backing paragraph at spec/ZKBTC_TOKEN.md §1.1.1, name the private-fork residual, and keep the join-mitigation limited to the Sybil-pool drain. * Risks: qualify Attack A close and split the 1:1 citation Attack A stays Bitcoin-class unless a designated gatekeeper honestly performs R-04. Point 1:1 backing at the zkbtc spec; keep §1.1.1 for the effectively-trustless claim.
* Remove external-audit as a v1 assurance step v1 assurance is the conformance harness and the in-spec soundness argument. There is no human-gated audit step. * Point the Assurance Roadmap citation at the living page The old commit URL still required an external audit. The living /assurance page is the policy. * Cite zk-BTC/zkbtc for the zkBTC specification The token-standard repo moved to the zk-BTC org. * Align the Assurance Roadmap summary with v1 release gates Paper reductions are a quality goal, not a v1 gate. Release-gating artefacts are the in-spec soundness argument and the harness. * Align snapshot maintenance note with v1 audit policy The register note claimed the pinned snapshot is not edited while this branch already corrected superseded v1-gate wording. Allow those corrections, close F-05 fork-audit as a v1 gate, and drop the leftover obtain-external-audit action in P3. * Drop stale audit-gate citations from the register note The note still pointed at §8 required-actions, P3 step 4, and §10 as if they still said obtain-an-external-audit. Those sentences were already rewritten on this branch. * Point the §3.7 residual at the V.11 differential-test §1.7.8 no longer flags a human cryptographic review. The fork-burial soundness paragraph still did, so it now names the mandatory differential-test instead.
* Describe v1 assurance as harness and in-spec soundness Living assurance, conformance, and residual-review wording now points at those artefacts without extra restatements. * Drop the leftover Gate-C assurance aside Keep the sentence on harness and in-spec arguments only. * Tighten leftover living asides after review Keep Gate C as the executable V.11 path and drop the non-action item from the P3 list.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automatic Release PR
Commits: 1 new commit(s)