bitrouter-registry

Static v0 P2P registry for BitRouter.

The repository source of truth is:

• nodes/*.json - provider-signed node advertisements.
• tombstones/*.json - provider-signed retire/delete proofs.
• v0/registry.json - committed generated aggregate, readable through GitHub raw content.

The scripts follow the P2P signed envelope rules in engineering/p2p/001-03-protocol-conventions.md and the registry design in engineering/p2p/008-03-bitrouter-registry.md: Ed25519 identities are ed25519:<base58btc(32 bytes)>, payload hashes are sha256:<base58btc(32 bytes)>, and signatures cover:

bitrouter-signature-input/0\n
JCS({
  "type": envelope.type,
  "payload": envelope.payload,
  "protected": proof.protected
})

Install

bun install

Validate and generate

bun run validate
bun run generate

CI should verify that generated files are committed:

bun install --frozen-lockfile
bun run validate
bun run generate
git diff --exit-code

v0/registry.json uses updated_at for the registry content timestamp. The generator preserves an existing updated_at value so a valid committed registry is not changed just because CI reruns generation.

Development key generation

For local testing only, manage.ts can generate a simple Ed25519 key file:

bun run manage keygen --out .keys/dev-provider.json

This writes a JSON file containing a 32-byte Ed25519 secret key and its public identity. .keys/ is ignored by git. This is a convenience format for local signing only; production node operators should use their own key management and must not commit provider private keys.

Sign and place node files

Create a node config JSON containing the unsigned payload fields. If provider_id, node_id, or endpoint_id are omitted, the development command uses the key's public identity for the simple single-node case.

bun run manage add --config examples/node-config.json --key .keys/dev-provider.json
bun run generate
bun run validate

Update an existing node:

bun run manage update --node <node_id> --config examples/node-config.json --key .keys/dev-provider.json
bun run generate

Retire a node with a signed tombstone:

bun run manage tombstone --node <node_id> --key .keys/dev-provider.json --reason retired
bun run generate

tombstone writes tombstones/<node_id>-<seq>.json and removes the matching nodes/<node_id>.json unless --keep-node is passed. Validation rejects a tombstoned node that still appears in nodes/.

Default registry URL

https://raw.githubusercontent.com/bitrouter/bitrouter-registry/main/v0/registry.json