borg

README

borg

Organisations and groups on Bitcoin, replicated by overlay hosts. An organisation issues each member a certificate; a group's membership is a chain of mined tokens; and every removal from a group begins a new epoch whose key the removed member never receives.

How it works

• Membership is a certificate. Each member holds a BRC-52 certificate issued by the organisation's key, with a role, a scope and an expiry. Its revocation outpoint is the output that funds it on the plane, so one mined spend revokes it for every verifier and retracts it from every host.
• Changes are ordered by the chain. The roll and each group are chains of mined tokens, one per change. Two changes made at once spend the same output and only one is ever mined: no coordinator, no merge.
• Removal is a rekey, checked by every host. A transition that removes anyone must begin a new epoch with a new key commitment, or no host admits it. The new key is random, committed before anyone holds it (BRC-369), and wrapped only to the members who remain.
• Hosts are replicas, not authorities. A host can withhold; it cannot forge. Roots over the roll and over each group's members make withholding visible.
• Two ways to reach the hosts. On the multicast plane a publisher submits each object once and every subscribed host receives it; without it, the publisher submits to each host itself.
• Everything is at the hosts. A host that missed something is filled from the others by anyone (borg fill), and a second home of the organisation rebuilds its state from them (borg org sync), opening each epoch key from a wrap like any member.

Documentation

If you want to	Read
Try it on one machine in minutes	QUICKSTART.md
Run an organisation, or use one as a member	docs/user-guide.md
Look up a command, a setting or an exit code	docs/usage.md
Implement a compatible organisation, member client or host	docs/spec.md (the specification)
Know what cannot change once published	docs/frozen.md
Know the defaults and caps, and why each is set where it is	docs/limits.md
Run a host: the module, its configuration, its index and its terms route	docs/host.md
Read borg's chains from another Go program	docs/packages.md

Build and test

$ (cd host && npm ci)   # once
$ make verify           # gofmt, vet, dependency set, licences, typecheck, vectors, tests
$ make borg             # the command, bin/borg
$ make vectors          # regenerate both vector sets
$ make module           # the host module, host/bundle/borg-module.js
$ make e2e REFERENCE_HOST=/path/to/reference-host          # the module on a local reference host (Docker)
$ make e2e-client REFERENCE_HOST=/path/to/reference-host   # the command against two local reference hosts (Docker)
$ make docker-build docker-build-host REFERENCE_HOST_IMAGE=<image>   # the images, locally
$ make quickstart-check # QUICKSTART.md, run as written, on those images

Go 1.27.1 or later and Node 24; NODE=/path/to/node selects a Node 24 binary that is not on PATH. The golden vectors in testdata/vectors are generated by the Go codec (borgrec), and testdata/ts by the TypeScript codec in host/; each side's tests read the other's, byte for byte. Two direct Go dependencies, asserted by make verify: go-sdk at exactly v1.5.2 and bcommon, whose TypeScript package at the same version is vendored under host/vendor.

License

Apache 2.0; see LICENSE.