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,seqhashpackagesgithub.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.
License
See LICENSE file.
Documentation
¶
Overview ¶
Command bitcoin-retry-endpoint caches multicast BSV transaction frames and retransmits them on demand via NACK requests.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package beacon implements the ADVERT beacon sender for bitcoin-retry-endpoint.
|
Package beacon implements the ADVERT beacon sender for bitcoin-retry-endpoint. |
|
Package cache provides a modular cache backend for storing multicast BSV transaction frames with configurable TTL.
|
Package cache provides a modular cache backend for storing multicast BSV transaction frames with configurable TTL. |
|
memory
Package memory provides an in-memory cache backend for testing and as a fallback when Redis is unavailable.
|
Package memory provides an in-memory cache backend for testing and as a fallback when Redis is unavailable. |
|
redis
Package redis provides a Redis cache backend for frame storage.
|
Package redis provides a Redis cache backend for frame storage. |
|
Package config loads and validates runtime configuration for bitcoin-retry-endpoint.
|
Package config loads and validates runtime configuration for bitcoin-retry-endpoint. |
|
Package ingress implements the multicast receive worker for bitcoin-retry-endpoint.
|
Package ingress implements the multicast receive worker for bitcoin-retry-endpoint. |
|
Package metrics initialises an OpenTelemetry MeterProvider backed by both a Prometheus exporter (for scraping) and an optional OTLP gRPC exporter (for push-based delivery to any OTel-compatible backend).
|
Package metrics initialises an OpenTelemetry MeterProvider backed by both a Prometheus exporter (for scraping) and an optional OTLP gRPC exporter (for push-based delivery to any OTel-compatible backend). |
|
Package ratelimit provides four-tier rate limiting for NACK requests:
|
Package ratelimit provides four-tier rate limiting for NACK requests: |
|
Package retransmit handles retransmitting cached frames to the multicast network.
|
Package retransmit handles retransmitting cached frames to the multicast network. |
|
Package server implements the UDP NACK receiver for bitcoin-retry-endpoint.
|
Package server implements the UDP NACK receiver for bitcoin-retry-endpoint. |
Click to show internal directories.
Click to hide internal directories.