README
¶
shard-common
Shared protocol primitives for the BSV transaction sharding pipeline. Imported
by shard-proxy, shard-listener, retry-endpoint, subtx-generator, and
shard-manifest.
Packages
| Package | Purpose |
|---|---|
frame |
Wire format codec: BRC-12/124/128 frames, BRC-127 announce, BRC-130 fragments, BRC-131 blocks, BRC-132 subtree data, BRC-134 anchor txs, BRC-135 block headers, BRC-137 shard manifest |
shard |
TxID → IPv6 multicast group derivation (consistent-hash); control groups |
seqhash |
XXH64 per-flow HashKey computation |
sequence |
Per-shard monotonic counters (sync/atomic, zero-alloc) |
txidset |
Two-tier TxID dedup (LRU + optional Redis SETNX); fail-open on Redis errors |
netjoin |
IPv6 multicast Join/Leave — branches IPV6_JOIN_GROUP (ASM) and MCAST_JOIN_SOURCE_GROUP (SSM, RFC 3678) by source-list presence; token-bucket Limiter and Jitter helper for cold-start storm protection at scale. Powers the SSM join sites in every receiver. |
bootstrap |
DNS-resolving source-set tracker for SSM (S,G) bootstrap lists: fail-closed startup, last-good retention on refresh failures, diff-callback for join/leave plumbing. |
The shard package also exposes the SSM addressing helpers: SourceMode
(asm|ssm), Scope (site|global), and Prefix(mode, scope) which yields
FF05 (ASM site), FF35 (SSM site), FF3E (SSM global) and rejects ASM
at global scope per RFC 8815.
The frame.ShardManifest codec implements BRC-137's SSM extensions:
Flags.SourceModeSSM (bit 3), Flags.SourcesValid (bit 4), SourceCount
at bytes [42:44], and the trailing SourceCount × 16-byte sources
payload appended after the groups payload. See the
SSM Support Plan
for the system-level design.
Documentation
- Wire Protocol Specification — BRC-124/BRC-128 frame format, legacy BRC-12, shard derivation, proxy forward rules
Requirements
- Go 1.25 or later
Build
go build ./...
go test ./...
License
Apache 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bootstrap maintains a live set of IPv6 source addresses resolved from a list of DNS names and/or IPv6 literals.
|
Package bootstrap maintains a live set of IPv6 source addresses resolved from a list of DNS names and/or IPv6 literals. |
|
BRC-135 block header frame encode/decode.
|
BRC-135 block header frame encode/decode. |
|
Package netjoin provides socket-level helpers for joining IPv6 multicast groups, branching between ASM ([IPV6_JOIN_GROUP]) and SSM ([MCAST_JOIN_SOURCE_GROUP], RFC 3678) by the presence of a source list.
|
Package netjoin provides socket-level helpers for joining IPv6 multicast groups, branching between ASM ([IPV6_JOIN_GROUP]) and SSM ([MCAST_JOIN_SOURCE_GROUP], RFC 3678) by the presence of a source list. |
|
Package seqhash provides the hash function used to compute HashKey values in BRC-124/BRC-128 frames.
|
Package seqhash provides the hash function used to compute HashKey values in BRC-124/BRC-128 frames. |
|
Package sequence provides per-shard monotonic sequence counters.
|
Package sequence provides per-shard monotonic sequence counters. |
|
Package shard derives IPv6 multicast group addresses from BSV transaction IDs for deterministic packet-level sharding across the BSV sharding pipeline.
|
Package shard derives IPv6 multicast group addresses from BSV transaction IDs for deterministic packet-level sharding across the BSV sharding pipeline. |
|
Package txidset implements a two-tier TxID claim store used by both the proxy ingress dedup gate and the listener per-deployment egress dedup gate.
|
Package txidset implements a two-tier TxID claim store used by both the proxy ingress dedup gate and the listener per-deployment egress dedup gate. |
Click to show internal directories.
Click to hide internal directories.