bitcoin-retry-endpoint

README

bitcoin-retry-endpoint

Caching endpoint for NACK-based retransmission in the BSV multicast pipeline. Receives BRC-124/BRC-128 frames from the multicast fabric, caches them, and retransmits on demand to bitcoin-shard-listener nodes that detect sequence gaps.

bitcoin-shard-proxy ──multicast──▶ FF05::<shard>:9001
                                         │
                          ┌──────────────┤
                          │              │
                          ▼              ▼
               bitcoin-shard-listener  bitcoin-retry-endpoint
               (gap detected → NACK) ──UDP──▶ [nack-addr]:9300
                          │                   │
                          ◀── ACK / MISS ─────┘

Documentation

• Architecture — pipeline overview, ingress, cache, NACK server, retransmit, beacon, NACK bind address, package structure
• Configuration — all flags, environment variables, defaults, deployment examples
• BRC-126 — Retransmission Protocol
• NACK Retransmission Flow
• BRC-124 Frame Format

Dependencies

• github.com/lightwebinc/bitcoin-shard-common — frame, shard, seqhash packages
• github.com/coocood/freecache — GC-free in-memory cache
• Prometheus client + OpenTelemetry SDK

Requirements

• Go 1.25 or later
• Linux kernel 3.9+ (for SO_REUSEPORT)
• IPv6 enabled on the multicast fabric interface
• Multicast routing configured for the same scope as proxy and listeners

Build

go build -o bitcoin-retry-endpoint .

Run

# In-memory cache (single node)
./bitcoin-retry-endpoint \
  -mc-iface eth0 \
  -egress-iface eth0 \
  -shard-bits 16

# Redis cache (multi-node with cross-instance dedup)
./bitcoin-retry-endpoint \
  -mc-iface enp6s0 \
  -egress-iface enp6s0 \
  -shard-bits 16 \
  -cache-backend redis \
  -redis-addr redis.local:6379 \
  -nack-addr fd20::24

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

NACK_ADDR (required in production)

NACK_ADDR (or --nack-addr) must be set to the specific routable IPv6 address that this endpoint advertises in beacons and that listeners send NACKs to.

If left empty the kernel binds the NACK socket to [::] and the default source-address selection rules may pick a SLAAC address (e.g. fd20::216:3eff:fe4c:8a01) for outgoing ACK responses. Listeners then either:

• discard the ACK because they use a connected socket bound to the advertised address (the SLAAC source does not match), or
• drop the ACK at the firewall because the allow-list only contains the advertised address.

Either path silently breaks NACK recovery. See bitcoin-shard-listener/nack/nack.go and the SLAAC source-address-mismatch fix history.

Container image

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

Helm chart

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

• Repository: lightwebinc/bitcoin-retry-endpoint-helm
• HTTPS:

  helm repo add bre https://lightwebinc.github.io/bitcoin-retry-endpoint-helm
  helm install retry-node-1 bre/bitcoin-retry-endpoint \
    --set config.nackAddr=fd20::24
  

• OCI: helm install retry-node-1 oci://ghcr.io/lightwebinc/charts/bitcoin-retry-endpoint --version 0.1.0

config.nackAddr is effectively required — the chart emits a helm.sh/chart-warnings annotation when empty. The chart does not bundle a Redis subchart; operators install Redis separately when config.cacheBackend=redis. See the chart README for the full reference.

License

See LICENSE file.

Documentation

Overview

Command bitcoin-retry-endpoint caches multicast BSV transaction frames and retransmits them on demand via NACK requests.