README
¶
bcommon
bcommon is a Go library of building blocks for BSV overlay applications that publish and verify committed records: the codec a record is written in, the roots and store references it commits to, the derivation and PushDrop outputs that lock it, the carrier and mined transactions that put it on chain, the clients a producer and a reader talk to, and the SPV check a reader runs. An application supplies its own schema, derivation, tags and wallet profile as parameters; nothing here names one.
Status: pre-1.0. Every application pins an exact tag, and the API may change between v0 minor versions. One tag versions both languages. See docs/versioning.md.
| Package | What it provides |
|---|---|
cbor |
Deterministic CBOR, an RFC 8949 subset; the decoder refuses anything non-canonical |
commit |
RFC 6962 Merkle roots, inclusion paths and their verification |
store |
Store reference entries, manifests, and the rule that computes a store's root from its entry and its members' commitments |
pushdrop |
BRC-42/43 derivation under counterparty Anyone, and tagged PushDrop locks, unlockers and decoding |
carrier |
An unmineable carrier transaction that commits a payload, and the funding lock, decode and sweep it spends from |
mint |
Builders for a state transition, a funding tree and a payment, with a fee loop that signs to measure the size and rebuilds at the rate until the fee covers it |
funding |
Funding-tree state kept between runs, and the BEEF kept for transactions spent before they mine |
guard |
A bounds check on a BRC-74 BUMP before the SDK allocates for it |
nodeapi |
A Teranode JSON-RPC and asset API client with bounded responses and a txid-in-proof check |
bwallet |
An embedded BRC-100 wallet backend and coin pool, a Signer, and BRC-29 derivations, keyed by an application profile |
wirewallet |
A BRC-100 wallet over the wallet wire, loopback only, and a handler that serves one |
publish |
The settlement leg (EF to an ingress, hex to a node RPC, arcade) and the BEEF object leg to an overlay host, which never share a socket, plus a transition journal |
headers |
A chain tracker over the header API of overlay-bridge |
hostset |
Host sources and quorum fan-out across the addresses behind one overlay host |
lookup |
A BRC-24 lookup client for output-list answers |
resolve |
BRC-169 handle resolution and BRC-180 overlay discovery, under a strict HTTPS client policy |
knownkeys |
The grammar and store of a pinned-key file: pin, rotate, retire, forget |
verify |
The refusal vocabulary, SPV verdicts on one transaction, and the carrier check a reader runs |
goldentest |
Test helpers: a fixed key, hex and transaction parsing that fail the test, and a stub chain tracker |
The TypeScript package under ts/, @lightwebinc/bcommon, holds the
twins an overlay topic manager or lookup service needs, tested against the
same vectors as the Go packages. It has two entry points:
| Entry point | What it provides |
|---|---|
@lightwebinc/bcommon |
Deterministic CBOR, store refs entries, the reader's BRC-42 derivation, PushDrop field signatures, the funding decode, the carrier check, and the overlay engine interfaces a module satisfies. It imports nothing but its peer @bsv/sdk and nothing from node:, so a browser can load it as well as a host |
@lightwebinc/bcommon/testing |
Test helpers for Node: a counting host, restore rows and storage, BEEF built as the engine builds it, a minter over a test key, and a simulator that calls a lookup service in the engine's order |
Requirements: Go 1.26.2 or later, and github.com/bsv-blockchain/go-sdk
pinned at exactly v1.5.2, the library's only direct dependency. See
docs/dependencies.md. The TypeScript package needs
Node 24 and @bsv/sdk 2.7.1 exactly, as a peer; make ts-test builds and
tests it, and nothing in the Go build needs Node.
Vectors: the tests compare the library's output byte for byte with vectors from an independent generator. See docs/vectors.md.
Registry: the derivation protocols, tags, record magic, topics and baskets that applications built on bcommon have chosen, so that no two collide, are in docs/registry.md.
Licence: Apache-2.0 (LICENSE). Third-party notices are in NOTICE and LICENSE-THIRD-PARTY.
Documentation
¶
Overview ¶
Package bcommon is the root of a library of building blocks for BSV overlay applications that publish and verify committed records: a deterministic CBOR codec, RFC 6962 roots, store references and manifests, BRC-42/43 derivation and tagged PushDrop outputs, a non-final carrier that commits a payload to the chain, transaction builders with a fee loop, funding-tree state, node, arcade and wallet clients, a header source, host sets with quorum fan-out, BRC-24 lookup, BRC-169 and BRC-180 resolution, a pinned-key file, and SPV verdicts. Each subdirectory that holds Go code is one package; this root package holds no code of its own.
An application supplies what makes these packages its own: the payload schema, the derivation protocol and key ids, the output tags, the wallet profile, the RPC id and the pin file's header all arrive as parameters rather than defaults. A default derivation or wallet profile would quietly re-key an application that forgot to pass one.
testdata is not a package. Its fixtures directory holds response bodies vendored from the services the network packages talk to, and its vectors directory the vectors an independent generator (tools/vectors) writes, which the packages' tests compare their own output against byte for byte. Both are kept at the root so every package reads them by the same relative path.
Imports ¶
Every package here, in production code and in tests, imports only the standard library, github.com/bsv-blockchain/go-sdk and other packages of this module. One outside dependency is what an application pinning this library takes on, so a second one would be a cost to every application at once. TestBoundary and TestBoundaryFiles enforce the rule. The vector generator in tools/vectors is a separate module that nothing here imports, held to a rule of its own: it may add an independent CBOR encoder, and it may never import this module.
Versioning ¶
The library is pre-1.0. An application pins an exact tag and moves to a newer one deliberately, because a v0 minor version may change the API.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bwallet is an embedded BRC-100 wallet backend for an application that publishes on chain, and the Signer through which such an application signs with it or with any other wallet.Interface.
|
Package bwallet is an embedded BRC-100 wallet backend for an application that publishes on chain, and the Signer through which such an application signs with it or with any other wallet.Interface. |
|
Package carrier is an object's transport: one transaction that is never mined, whose record output holds the object's payload as a signed PushDrop [payload] under the producer's derivation, and whose txid is the commitment a mined token can carry.
|
Package carrier is an object's transport: one transaction that is never mined, whose record output holds the object's payload as a signed PushDrop [payload] under the producer's derivation, and whose txid is the commitment a mined token can carry. |
|
Package cbor is the deterministic CBOR that committed records are written in.
|
Package cbor is the deterministic CBOR that committed records are written in. |
|
Package commit computes RFC 6962 Merkle roots and inclusion paths: the root a store reference commits to, one per named store, over the commitments (carrier txids) of that store's members.
|
Package commit computes RFC 6962 Merkle roots and inclusion paths: the root a store reference commits to, one per named store, over the commitments (carrier txids) of that store's members. |
|
Package funding keeps a producer's funding tree between runs, and the transactions it published before they mined.
|
Package funding keeps a producer's funding tree between runs, and the transactions it published before they mined. |
|
Package goldentest holds the helpers a package's tests share when they check themselves against a committed test vector: a fixed test key, hex and transaction parsing that fail the test rather than return an error, and a chain tracker that knows only the roots the test hands it.
|
Package goldentest holds the helpers a package's tests share when they check themselves against a committed test vector: a fixed test key, hex and transaction parsing that fail the test rather than return an error, and a chain tracker that knows only the roots the test hands it. |
|
Package guard checks a BRC-74 BUMP someone else supplied before the SDK is allowed to allocate for it.
|
Package guard checks a BRC-74 BUMP someone else supplied before the SDK is allowed to allocate for it. |
|
Package headers is a chain tracker over the header read API of an overlay bridge (github.com/lightwebinc/overlay-bridge).
|
Package headers is a chain tracker over the header read API of an overlay bridge (github.com/lightwebinc/overlay-bridge). |
|
Package hostset chooses which address answers for an overlay host.
|
Package hostset chooses which address answers for an overlay host. |
|
Package knownkeys reads and writes a pin store: the key each address was last seen with, one line per record.
|
Package knownkeys reads and writes a pin store: the key each address was last seen with, one line per record. |
|
Package lookup asks an overlay host a BRC-24 question and returns its output-list answer.
|
Package lookup asks an overlay host a BRC-24 question and returns its output-list answer. |
|
Package mint builds the mined transactions an application's state lives on: a transition of its state token, a funding tree, and a plain payment, each with a fee input and a change output supplied by the caller.
|
Package mint builds the mined transactions an application's state lives on: a transition of its state token, a funding tree, and a plain payment, each with a fee input and a change output supplied by the caller. |
|
Package nodeapi talks to a Teranode node over HTTP: JSON-RPC for mining and direct submission, the asset API for reading what got mined.
|
Package nodeapi talks to a Teranode node over HTTP: JSON-RPC for mining and direct submission, the asset API for reading what got mined. |
|
Package publish is the publisher's dual submission: one signed transaction, two encodings, two transports, and never one writer for both.
|
Package publish is the publisher's dual submission: one signed transaction, two encodings, two transports, and never one writer for both. |
|
Package pushdrop is the key derivation an application locks its PushDrop outputs under, and the tagged PushDrop those outputs carry: a leading tag field, the application's own fields, and the wallet's signature over them.
|
Package pushdrop is the key derivation an application locks its PushDrop outputs under, and the tagged PushDrop those outputs carry: a leading tag field, the application's own fields, and the wallet's signature over them. |
|
Package resolve turns a user@domain into an identity key and the overlay host that serves it, using only the two documents a domain publishes about itself: its BRC-180 manifest and its BRC-169 handle-resolution endpoint.
|
Package resolve turns a user@domain into an identity key and the overlay host that serves it, using only the two documents a domain publishes about itself: its BRC-180 manifest and its BRC-169 handle-resolution endpoint. |
|
Package store is how a record commits to a set of other records and how a reader opens that set: the refs entry that names a store and commits to its root, the manifest that lists a store's members, and the rule that computes the root from the entry and the members' commitments.
|
Package store is how a record commits to a set of other records and how a reader opens that set: the refs entry that names a store and commits to its root, the manifest that lists a store's members, and the rule that computes the root from the entry and the members' commitments. |
|
Package verify is what a reader shares with every other reader: the outcome vocabulary it reports (codes.go), the verdict on one transaction against the reader's own headers (Check), and the check every carrier a host answers gets before a reader believes it (VerifyCarrier).
|
Package verify is what a reader shares with every other reader: the outcome vocabulary it reports (codes.go), the verdict on one transaction against the reader's own headers (Check), and the check every carrier a host answers gets before a reader believes it (VerifyCarrier). |
|
Package wirewallet reaches a BRC-100 wallet over the wallet wire, the binary substrate both SDKs implement, and answers the one question an application asks a wallet before anything else: whose identity is this.
|
Package wirewallet reaches a BRC-100 wallet over the wallet wire, the binary substrate both SDKs implement, and answers the one question an application asks a wallet before anything else: whose identity is this. |