bitcoin-shard-proxy

README

bitcoin-shard-proxy

A high-throughput proxy that receives Bitcoin SV (BSV Blockchain) transaction frames (BRC-124, BRC-128, or legacy BRC-12) over UDP (or TCP for reliable delivery), derives an IPv6 multicast group address from the transaction ID, and retransmits to subscribers of the corresponding group. Further traffic segmentation is provided via subtree-level sharding. Reliable delivery to multicast receivers is supported via monotonic transmission flow sequencing. The TCP ingress also forwards BRC-127 SubtreeAnnounce datagrams to the control-plane multicast group.

Inspiration: Multicast within Multicast: Anycast, Multicast as the Only Viable Architecture

sender  ──UDP/TCP──►  bitcoin-shard-proxy  ──UDP multicast──►  FF05::<shard>  (iface 0)
                      (forwarder pipeline) └─────────────────►  FF05::<shard>  (iface 1)
                                                                 (subset of subscribers)

Documentation

• Architecture — system overview, multi-CPU design, graceful shutdown, package structure
• Configuration — all flags, environment variables, ingress modes, drain timeout

Dependencies

• github.com/lightwebinc/bitcoin-shard-common — frame, shard, seqhash packages

Requirements

• Go 1.25 or later
• Linux kernel 3.9+, FreeBSD 12.3+ (for SO_REUSEPORT), MacOS
• IPv6 enabled on the egress interface(s)
• Multicast routing / MLD snooping configured for your subscriber fabric
• Bitcoin SV ingress transaction packets in BRC-12 (legacy) or BRC-124/BRC-128 frame format.

Build

make            # builds bitcoin-shard-proxy, send-test-frames, recv-test-frames
make test       # runs unit tests
make test-e2e   # end-to-end test (builds all binaries, runs test/run-e2e.sh)
make clean      # removes built binaries

Run

./bitcoin-shard-proxy \
  -iface            eth0 \
  -shard-bits       16   \
  -scope            site \
  -udp-listen-port  9000 \
  -egress-port      9001

With TCP ingress enabled:

./bitcoin-shard-proxy \
  -iface            eth0 \
  -udp-listen-port  9000 \
  -tcp-listen-port  9100

See docs/configuration.md for all flags and environment variable equivalents.

Container image

The Dockerfile produces a gcr.io/distroless/static:nonroot image with the single static binary at /usr/local/bin/bitcoin-shard-proxy. No in-image ENV defaults are set — configure via Helm values.yaml, container environment variables, or CLI flags.

Helm chart

A Kubernetes Helm chart is published from a dedicated chart repository:

• Repository: lightwebinc/bitcoin-shard-proxy-helm
• HTTPS:

  helm repo add bsp https://lightwebinc.github.io/bitcoin-shard-proxy-helm
  helm install proxy bsp/bitcoin-shard-proxy
  

• OCI: helm install proxy oci://ghcr.io/lightwebinc/charts/bitcoin-shard-proxy --version 0.1.0

Every flag accepted by this binary is exposed under .config in the chart's values.yaml. See the chart README for the full reference and values.schema.json for validation rules.

License

Apache 2.0 - See LICENSE file.

Documentation

Overview

Command bitcoin-shard-proxy accepts BSV transaction datagrams on a UDP IPv6 socket, derives a multicast group address from the transaction ID's top N bits, and retransmits each datagram verbatim to the derived group.

Multiple worker goroutines — one per CPU by default — each bind an independent SO_REUSEPORT socket to the listen port. The kernel distributes incoming datagrams across them, providing CPU-local processing with no userspace coordination on the ingress path.

Quick start

bitcoin-shard-proxy -iface eth0,eth1 -shard-bits 8 -scope site

Configuration

All flags have environment variable equivalents; see config.Load for the full mapping. The most important parameters:

• -shard-bits (SHARD_BITS): controls how many bits of the txid prefix are used as the multicast group key. Range 1–15. 8 → 256 groups (fits any managed switch) 12 → 4096 groups 15 → 32768 groups (maximum; top of 16-bit space reserved for control)

• -mc-group-id (MC_GROUP_ID): IANA group-id occupying bytes 12–13 of the address. Default 0x000B (IANA Bitcoin allocation "FF0X::B"). Operators MAY override for testing/private deployments.

• -scope (MC_SCOPE): multicast scope. Use "site" for closed subscriber fabrics; "global" only if subscribers span BGP domains.

• -iface (MULTICAST_IF): comma-separated NIC names over which multicast datagrams are sent (e.g. eth0,eth1). Each datagram is forwarded to all listed interfaces in order. All names must exist on the host; the proxy exits immediately if any are not found.

Graceful shutdown

The proxy catches SIGINT (Ctrl-C) and SIGTERM (sent by systemd, container orchestrators, etc.). Shutdown proceeds in two phases:

1. Draining: /readyz immediately returns 503, then the process sleeps -drain-timeout (DRAIN_TIMEOUT) to allow load-balancer health checks to propagate and stop sending new connections. Defaults to 0 (disabled).

2. Quiescing: the done channel is closed, each worker's ingress socket is closed (unblocking ReadFrom), and main waits for all goroutines to exit before the process returns.