Certrelay

Certificate relay network for the Spaces protocol. Stores and serves cryptographic proofs that bind human-readable names to owner keys anchored to Bitcoin.

Overview

Certrelay consists of two components:

  • relay — HTTP server that verifies certificates, stores them in SQLite, and gossips with peers
  • fabric — Client library available in Rust, JavaScript, Go, Python, Kotlin, and Swift

The protocol is plain HTTP — relays are queryable from browsers, mobile apps, and any language with an HTTP client. All verification is done client-side against Bitcoin's chain state.

Fabric Client

For documentation on using Fabric to resolve handles, publish records, and verify identities, see spacesprotocol.org/docs.

Running a Relay

cargo install --git https://github.com/spacesprotocol/certrelay.git --bin certrelay
certrelay

On first run, certrelay will:

  1. Download a checkpoint (~8MB)
  2. Build hash indexes (~2 min)
  3. Start an embedded Bitcoin light client (yuki) and spaced node
  4. Sync to the chain tip and start serving

No external Bitcoin node required. Data is stored in ~/.certrelay by default.

Configuration

FlagEnvDefaultDescription
--chainCERTRELAY_CHAINmainnetNetwork (mainnet, testnet4)
--data-dirCERTRELAY_DATA_DIR~/.certrelayData directory
--bindCERTRELAY_BIND127.0.0.1Bind address
--portCERTRELAY_PORT7778 (mainnet) / 7779 (other)Listen port
--self-urlCERTRELAY_SELF_URL-Public URL for peer announcements
--spaced-rpc-urlCERTRELAY_SPACED_RPC_URL-External spaced RPC (skips embedded node)
--remote-ip-headerCERTRELAY_REMOTE_IP_HEADER-Header for client IP behind reverse proxy
--is-bootstrapCERTRELAY_BOOTSTRAPfalseRun as a bootstrap node
--skip-checkpoint-sync-falseSkip checkpoint download, sync from scratch

Public relay behind a reverse proxy

certrelay \
  --bind 0.0.0.0 \
  --self-url https://relay.example.com \
  --remote-ip-header x-forwarded-for

Using an external spaced node

certrelay --spaced-rpc-url http://user:password@127.0.0.1:12888

License

MIT