README
¶
borg
[!WARNING] Experimental software. borg is part of bstack, the applications and patterns built on BSV Layered Multicast. It is published to be built on and improved. Interfaces, formats and behavior may change rapidly between releases; pin an exact version.
Organizations and groups on Bitcoin, replicated by overlay hosts. An organization 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
%%{init: {"flowchart": {"diagramPadding": 48}}}%%
flowchart LR
O["borg (organization)"] -->|"grants, policy records, tokens, wraps"| H["overlay hosts<br/>tm_borg_<name>_<suffix>, ls_borg"]
O -->|"one small tx per change"| B[("BSV blockchain")]
M["borg (member)"] -->|"open, roll, member, policy"| H
M -->|headers| S["header source<br/>woc:main"]
B -.-> S
H -. "records + proofs" .-> M
- Membership is a certificate. Each member holds a BRC-52 certificate issued by the organization's key, with a role, a scope and an expiry. Its revocation outpoint is the output that funds it, so one mined spend revokes it for every verifier and retracts it from every host.
- Roles decide. A role names the permissions it carries, and a binding gives it to a group or to one key. Both ride the organization's own chain beside the roll, so a service reads what a subject may do out of the same committed order that says who the subject is, and can prove what it decided and the state it decided against.
- 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, and
borg fillrepairs a host that missed something.
Install
$ go install github.com/lightwebinc/borg/cmd/borg@latest
Or download a static binary for Linux or macOS (amd64, arm64) from Releases, or run the image:
$ docker run --rm -v borg-home:/home/nonroot/.borg ghcr.io/lightwebinc/borg -version
Example: an organization on mainnet
You need BSV in a wallet you control and overlay hosts that carry the borg module (host.md). No node is needed: headers, transactions, proofs and spends come from WhatsOnChain and broadcasts go through GorillaPool's public arcade by default, every proof checked against the headers; a node of your own is the better option where you have one. Nothing is mined for you: the organization is funded with a payment you send.
$ borg -network main init
identity 02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5
fund address 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2 (main)
$ # send about 20,000 sat from your own wallet to the fund address
$ borg fund -txid <txid of that payment> # once mined; or fund -beef FILE at once
$ borg hall new example
$ borg org create 'Example' -member <alice key> -member <bob key>
$ borg group create engineering -member <alice key> -member <bob key>
A member, with org, hall and hosts in their config, opens the group's key with borg open engineering. The full walk,
on mainnet or testnet, is docs/examples.md; a private
sandbox that needs no coin is QUICKSTART.md.
Documentation
| If you want to | Read |
|---|---|
| Run it on mainnet or testnet, step by step | docs/examples.md |
| Try it on one machine with no coin (a private regtest chain) | QUICKSTART.md |
| Run an organization, or use one as a member | docs/user-guide.md |
| Set every key, flag and environment variable | docs/configuration.md |
| Look up a command or an exit code | docs/usage.md |
| See how the pieces fit | docs/architecture.md |
| Run a host: the module, its configuration, its index and its terms route | docs/host.md |
| Know the defaults and caps, and what things cost | docs/limits.md |
| Implement a compatible organization, member client or host | docs/spec.md |
| Know what cannot change once published | docs/frozen.md |
| Read borg's chains from another Go program | docs/packages.md |
| See what comes next, and what is left open on purpose | docs/roadmap.md |
Build and test
$ (cd host && npm ci) # once
$ make verify # gofmt, vet, dependency set, licenses, typecheck, vectors, tests
$ make borg # the command, bin/borg
$ make module # the host module, host/bundle/borg-module.js
$ make docker-build # the images, locally
Go 1.27.2 or later and Node 24 (NODE=/path/to/node selects one 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. The end-to-end targets
(make e2e, make e2e-client, make quickstart-check) need Docker and a
reference overlay host; see the Makefile.
The TypeScript codec ships as a package of its own for other applications'
pages and helpers (bchat's verifies groups and opens epochs with it): npm pack in host/, from a clean clone at a tag, writes
lightwebinc-borg-host-<version>.tgz (the version equals the tag), holding
only the codec files (admit, beef, borgrec, chain, epoch,
merkle, query, scope, script, util), imported as
@lightwebinc/borg-host/codec/<file>.js. bcommon's TypeScript package is
its peer. A consumer vendors the tarball and pins it by its hash in its
lockfile, as with bcommon's.
License
Apache 2.0; see LICENSE, NOTICE and LICENSE-THIRD-PARTY.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package borgrec is the byte-level contract of borg: the organization and group records that ride mined chain tokens, the membership grant and the epoch-key wrap that ride unmined carriers, the hall and scope grammars, the BRC-369 epoch key, and the lookup question classes.
|
Package borgrec is the byte-level contract of borg: the organization and group records that ride mined chain tokens, the membership grant and the epoch-key wrap that ride unmined carriers, the hall and scope grammars, the BRC-369 epoch key, and the lookup question classes. |
|
cmd
|
|
|
borg
command
Command borg runs an organization and its groups on overlay hosts, and reads them as a member: it creates an identity home and halls, begins an organization and issues its members BRC-52 grants, keeps the roll on a chain of mined tokens, creates groups whose every removal begins a new epoch with a fresh key wrapped only to the members who remain, revokes by the roll and by sweep, opens a group's epoch key as a member, reads the roll and memberships from one or several hosts checking every answer itself, pays a host's 402 for the priced history question, and settles the payments a host accepted as its payee.
|
Command borg runs an organization and its groups on overlay hosts, and reads them as a member: it creates an identity home and halls, begins an organization and issues its members BRC-52 grants, keeps the roll on a chain of mined tokens, creates groups whose every removal begins a new epoch with a fresh key wrapped only to the members who remain, revokes by the roll and by sweep, opens a group's epoch key as a member, reads the roll and memberships from one or several hosts checking every answer itself, pays a host's 402 for the priced history question, and settles the payments a host accepted as its payee. |
|
devchain
command
Command devchain is a local stand-in chain for trying borg without a node, a settlement service or any coin: bcommon devkit's devchain (a node's JSON-RPC at /rpc, its asset API under /api/v1/ and a header source at /v1/root/<height> and /v1/tip, every transaction mined at once).
|
Command devchain is a local stand-in chain for trying borg without a node, a settlement service or any coin: bcommon devkit's devchain (a node's JSON-RPC at /rpc, its asset API under /api/v1/ and a header source at /v1/root/<height> and /v1/tip, every transaction mined at once). |
|
vectors
command
Command vectors writes the golden vectors under testdata/vectors, or with -check compares them byte for byte and writes nothing (bcommon devkit's vectors runner over this repository's generator).
|
Command vectors writes the golden vectors under testdata/vectors, or with -check compares them byte for byte and writes nothing (bcommon devkit's vectors runner over this repository's generator). |
|
Package enforce is the whole of borg's decision procedure (docs/spec.md section 13) behind one call, for a service that decides on a requester's behalf: the organization's latest token and the subject's grants, groups and policy records, each verified against the service's own headers, folded into a verdict, signed into a receipt and handed back.
|
Package enforce is the whole of borg's decision procedure (docs/spec.md section 13) behind one call, for a service that decides on a requester's behalf: the organization's latest token and the subject's grants, groups and policy records, each verified against the service's own headers, folded into a verdict, signed into a receipt and handed back. |
|
internal
|
|
|
config
Package config resolves the borg command's settings: flags, then BORG_* in the environment, then the config file, then the built-in default.
|
Package config resolves the borg command's settings: flags, then BORG_* in the environment, then the config file, then the built-in default. |
|
engine
Package engine is a borg publisher: the organization's tooling (docs/spec.md sections 7, 9 and 12), run from one identity's home.
|
Package engine is a borg publisher: the organization's tooling (docs/spec.md sections 7, 9 and 12), run from one identity's home. |
|
state
Package state is an identity's durable record in its home: the funding trees its carriers and chains spend, the organization it runs (its own chain, its grants, its groups and every epoch key it sampled), the objects persisted before they are published, the sweeps it built, and, for a member, the epoch keys it opened, the grants it holds and the latest token of each chain it has verified.
|
Package state is an identity's durable record in its home: the funding trees its carriers and chains spend, the organization it runs (its own chain, its grants, its groups and every epoch key it sampled), the objects persisted before they are published, the sweeps it built, and, for a member, the epoch keys it opened, the grants it holds and the latest token of each chain it has verified. |
|
testchain
Package testchain is the local stand-ins this module's tests run against: the shared chain, and this application's host.
|
Package testchain is the local stand-ins this module's tests run against: the shared chain, and this application's host. |
|
vectors
Package vectors generates the golden vectors under testdata/vectors from the codec in borgrec.
|
Package vectors generates the golden vectors under testdata/vectors from the codec in borgrec. |
|
Package reader asks overlay hosts the ls_borg questions and checks every answer itself (docs/spec.md sections 10.2, 12 and 13): a token's record, lock and field signature and its proof against the reader's own headers; a carrier by the host's own admission rules and by SPV through its funding parent; a sweep by its proof.
|
Package reader asks overlay hosts the ls_borg questions and checks every answer itself (docs/spec.md sections 10.2, 12 and 13): a token's record, lock and field signature and its proof against the reader's own headers; a carrier by the host's own admission rules and by SPV through its funding parent; a sweep by its proof. |
Click to show internal directories.
Click to hide internal directories.