docs(brc220): draft the certificate field values, as the reference writes them - #167
Merged
Merged
Conversation
…ites them
BRC-220 names the twelve fields a certificate carries and defines none of
their values. That is how this library, 8.3.0-9.8.0, and the reference
implementation computed identical proofHashes and could not verify each
other's certificates.
The draft proposes the values the reference writes: version "1.0", mode
"full"/"hybrid" with batching on anchor.type, encoding "hex"/"base64" for
publicKey and signature only, lowercase unprefixed hex, createdAt as ISO 8601
with zero milliseconds, the six anchor members, { hash, side } audit paths,
the byte order of the SPV fields, and the ECDSA byte forms. Where the
reference's verifier is more lenient than its writer (version is never
checked, base64 skips invalid characters, network is any string), the
difference is listed as an open point, not decided.
The examples are certificates the reference produced, and a test reads them
out of the document and checks them against that fixture. Not filed.
Two reader rules join the proposed text: a verifier refuses a version it does not implement, and a reader refuses base64 that is not base64. The reference adopts both, so the spec does not state a rule its own reference breaks. Hex may be read in upper case and with 0x. network gets two names, bsv-mainnet and a reserved bsv-testnet, and is descriptive, because the header the verifier obtains already fixes the chain. Legacy shapes stay out of the spec, and high-S stays accepted.
…the reader rules The proposed-text section is now generated from apps/0220.md as committed on the filing branch, so the two cannot differ. The ECDSA byte forms move into section Certificate, under the fields they describe: section Algorithms is where #246 edits, and a trial merge of #246 on top of this change is clean. The guard test now checks each MUST and MAY sentence twice: that it is in the text, and that this library does what it says. That includes not refusing the numeric version 1 of its own legacy format, which it implements.
codenlighten
force-pushed
the
docs/brc220-certificate-fields
branch
from
September 11, 2026 12:53
49bedd9 to
587bf90
Compare
codenlighten
added a commit
that referenced
this pull request
Sep 11, 2026
… height, and its fields are filed for BRC-220 (#169) Carries the base64 length rule and the optional header height from #168, and the certificate field definitions from #167, now filed upstream as bsv-blockchain/BRCs#247. The batch-leaf draft says that leafIndex counts from 0 and how i is written in the vector, as review of bsv-blockchain/BRCs#246 asked. Additive, or refuses only malformed input.
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
1 participant
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.
Adds
docs/BRC220_CERTIFICATE_FIELDS_AMENDMENT.md, a draft BRC-220 amendment that defines the certificate's field values. It is not filed upstream.BRC-220 §Certificate names twelve required fields and defines none of their values. That is how
@smartledger/bsv8.3.0–9.8.0 and the reference implementation computed identicalproofHashvalues and could not verify each other's certificates. The draft proposes the values the reference writes:version"1.0"mode"full"/"hybrid", with batching marked onanchor.typeencoding"hex"/"base64", applying topublicKeyandsignatureonlycreatedAtas ISO 8601 with zero millisecondsanchormembers{ hash, side }audit paths, with the fold ruleIt is drafted as a separate PR from bsv-blockchain/BRCs#246, which is under review and narrow.
How the claims were checked. Every value comes from the reference's source at
b926e3b: certificate assembly, the batcher, the confirmation poller and the schema. They agree with the reference's own protocol document. The behavioural claims were run against the reference's own code: a"version": "2.0"certificate passes all of its checks, unknown members pass its schema, anynetworkstring passes, and base64 invalid characters are silently skipped. Where its verifier is more lenient than its writer, the draft lists an open point for the author rather than deciding.Guarding the examples. The two examples are certificates the reference produced.
test/notaryhash/fields_amendment.jsreads them out of the markdown and checks them againsttest/data/notaryhash-reference-certs.json. It also verifies their signature andproofHash, folds the batch path by hand, and checks that every field and member has a table row.npm test: 4955 passing.