bcommon

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.

Packages

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 structural walk of a BRC-74 BUMP, a BEEF or a raw transaction before the SDK allocates for it, and a public key taken only in its canonical encoding
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
producer	A producer's orchestration: fee inputs and change from a coin pool, settlement, the funding-tree lifecycle, the one kept copy of each unproven transaction, and proof collection that republishes what has mined
headers	A chain tracker over WhatsOnChain, chaintracks or an overlay-bridge, checking proof of work
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
termsafe	Text someone else wrote, filtered before it reaches a terminal, and the same rules checked before a producer publishes text
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

Install

Go, pinned to an exact tag, the latest in docs/versioning.md:

go get github.com/lightwebinc/bcommon@v0.4.0

TypeScript: the package is packed from the same tag and vendored, so the application's lockfile pins its bytes, and the application supplies the @bsv/sdk peer at the exact version the package names:

git clone --depth 1 --branch v0.4.0 https://github.com/lightwebinc/bcommon
cd bcommon/ts && npm ci && npm pack    # writes lightwebinc-bcommon-0.4.0.tgz
# in the application, with the tarball copied to vendor/
npm install ./vendor/lightwebinc-bcommon-0.4.0.tgz @bsv/sdk@2.7.1

Usage

A record body in canonical CBOR, its RFC 6962 commitment, and the key a reader expects the record's output to be locked to, from the producer's identity key alone:

import (
	"crypto/sha256"

	"github.com/bsv-blockchain/go-sdk/wallet"

	"github.com/lightwebinc/bcommon/cbor"
	"github.com/lightwebinc/bcommon/commit"
	"github.com/lightwebinc/bcommon/pushdrop"
)

// A placeholder: an application registers its own in docs/registry.md.
var record = pushdrop.Derivation{
	Protocol: wallet.Protocol{SecurityLevel: wallet.SecurityLevelEveryApp, Protocol: "example app"},
	KeyID:    "record",
}

body, err := cbor.Encode(cbor.Map{{Key: "name", Val: "example"}})
root := commit.Root([][32]byte{sha256.Sum256(body)})
key, err := record.ExpectedLockingKey(identity) // identity is an *ec.PublicKey

The same derivation on the TypeScript side, in a topic manager:

import { readerLockingKey } from '@lightwebinc/bcommon'

const key = readerLockingKey([1, 'example app'], 'record', identityHex)

docs/examples.md walks through deriving and decoding a PushDrop lock, building a funding tree and a carrier on an in-process test chain, verifying a carrier from a BEEF, guarding a proof, RFC 6962 proofs, stores and CBOR, paying fees and minting the next funding tree as a producer, and filtering text for a terminal. Every Go example there is an Example test that go test compiles and checks.

Documentation

• Architecture: the package layers and import graph, what each package owns, the parse-and-guard rule, application-supplied constants, and the Go and TypeScript twins
• Configuration: every caller-supplied parameter and option struct, the defaults, and the values frozen once used on chain
• Examples: offline how-to, backed by compiled example tests
• Registry: the derivation protocols, tags, record magic, topics and baskets that applications built on bcommon have chosen, so that no two collide
• Vectors: the tests compare the library's output byte for byte with vectors from an independent generator
• Dependencies: the one direct dependency and why its version is exact
• Versioning: exact tags, one tag for both languages, and what a v0 minor may change

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.

Build and test

make verify     # formatting, vet, the dependency rule, licences, vectors, build, tests
make ts-test    # the TypeScript package: type-check, build, tests (Node 24)

Every Go target runs with GOWORK=off, so what is checked is what a tag ships.

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, the producer's orchestration of fees, funding trees and proofs around them, a header source, host sets with quorum fan-out, BRC-24 lookup, BRC-169 and BRC-180 resolution, a pinned-key file, SPV verdicts, and a filter for text that reaches a terminal. 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.

Nor does any package take on what belongs to an application's command: flags, logging, the environment, the user's configuration directories, the standard streams, other processes or the process's exit. Settings and output arrive as parameters. TestNoProcessConcerns enforces it.

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.