bbox

README

bbox

A message box on Bitcoin, replicated by overlay hosts. A sender addresses an encrypted envelope to a recipient's identity key and a box; every host that carries the office holds it; the recipient lists its box from any host, verifies every envelope against block headers it checks itself, and acknowledges with a signed receipt that every host applies. A payment can travel inside an envelope, unbroadcast, for the recipient to internalize.

How it works

• Envelopes are never mined. Each rides an unmined carrier transaction that spends one output of the sender's mined funding tree, so it verifies by SPV, it is bound to the sender's key, and the sender can retract it by spending that output.
• Hosts are replicas, not authorities. A host can withhold an envelope; it cannot forge or alter one. Reading from several hosts shows a host that withholds.
• Content is a BRC-169 envelope, encrypted to the recipient under BRC-78. Who wrote to whom, and when, is public; what was written is not.
• 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.
• Reading is free. The base questions are free on every conforming host; a host may charge for history, never for the inbox, through a BRC-105 402 that the client pays and the host's payee settles.
• Retraction is a mined sweep. A sender takes an envelope back by spending its funding output; honest hosts stop answering it. It is not erasure.

Documentation

If you want to	Read
Try it on one machine in minutes, with no coin	QUICKSTART.md
Understand it and use it day to day: concepts, sending, reading, paying, retracting, troubleshooting	docs/user-guide.md
Look up a command, a flag, a setting or an exit code	docs/usage.md
Implement a compatible sender, reader 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, the terms route, settling, backups, metrics	docs/host.md
Send and read bbox envelopes from another Go program	docs/packages.md

Build and test

$ (cd host && npm ci)   # once
$ make verify           # gofmt, vet, dependency set, typecheck, vectors, tests
$ make vectors          # regenerate both vector sets
$ make module           # the host module, host/bundle/bbox-module.js
$ make bbox             # the command, bin/bbox
$ make e2e REFERENCE_HOST=/path/to/reference-host          # the module; needs Docker
$ make e2e-client REFERENCE_HOST=/path/to/reference-host   # the command on two hosts

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 (boxrec), 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.7.1 and bcommon, whose TypeScript package at the same version is vendored under host/vendor.

License

Apache 2.0; see LICENSE.