# Multicast Transaction Frame Format Jeff Harris () ## Abstract This BRC specifies the wire format for transporting BSV transactions over IPv6 multicast and TCP/UDP unicast. The format extends the legacy BRC-12 frame with additional fields for flow identification, sequence tracking, and subtree identification. All fields are 8-byte aligned for efficient memory access on 64-bit architectures. ## Copyright This BRC is licensed under the Open BSV License. ## Motivation As BSV transaction throughput scales to billions of transactions per second, efficient distribution infrastructure becomes critical. IPv6 multicast provides a scalable one-to-many transport mechanism, but globally scalable transaction distribution requires: 1. **Deterministic sharding** — routing transactions to specific multicast groups based on transaction ID 2. **Sequence tracking** — detecting and recovering from frame loss via hash-chain NACK-based retransmission 3. **Subtree identification** — filtering batches of related transactions at the network layer 4. **Flow identification** — stable per-flow hashing for gap tracking and NACK-based retransmission This frame format addresses these requirements while maintaining compatibility with the existing BRC-12 transaction payload format. It uses a 92-byte header that provides the metadata necessary for high-throughput multicast distribution with best-effort reliability, complementing the legacy 44-byte header defined in BRC-12. **Conceptual Attribution:** The IPv6 multicast transaction broadcast architecture from which this software draws inspiration was articulated by Dr. Craig S. Wright in [Multicast Within Multicast: Anycast, Sharded Resends, and Hierarchical Distribution for Transaction and Block Propagation](https://singulargrit.substack.com/p/multicast-within-multicast-anycast). ## Specification ### Frame Structure Overview A frame consists of a 92-byte header followed by a variable-length payload containing a BRC-12 raw transaction. All multi-byte integers are big-endian. All fields from offset 8 onward are 8-byte aligned. ### Header Format (92 bytes) ``` | Offset | Size | Alignment | Field | Description | |--------|------|-----------|-----------------------|------------------------------------------------| | 0 | 4 | — | Network Magic | `0xE3E1F3E8` (BSV mainnet P2P magic) | | 4 | 2 | — | Protocol Version | `0x02BF` (703, BSV large-block baseline) | | 6 | 1 | — | Frame Version | `0x02` | | 7 | 1 | — | Reserved | Must be `0x00` | | 8 | 32 | 8-byte | Transaction ID | Raw 256-bit TXID (internal byte order) | | 40 | 8 | 8-byte | HashKey | Stable per-flow XXH64 identifier; `0` = unset | | 48 | 8 | 8-byte | SeqNum | Monotonic per-flow counter; `0` = unset | | 56 | 32 | 8-byte | Subtree ID | 32-byte batch identifier; zeros = unset | | 88 | 4 | 8-byte | Payload Length | `uint32` BE | | 92 | * | — | Payload | BRC-12 raw transaction bytes | ``` ### Field Definitions #### Network Magic (bytes 0–3) The value `0xE3E1F3E8` (BSV mainnet P2P network magic). This enables standard BSV firewall rules and network monitoring tools to correctly classify shard frames. Frames with incorrect magic are rejected. #### Protocol Version (bytes 4–5) The value `0x02BF` (703 in decimal), representing the BSV node protocol version that introduced the large-block policy. This field is informational; receivers do not validate it. #### Frame Version (byte 6) The value `0x02` for frames following this specification. The legacy format defined in BRC-12 uses `0x01` (see Compatibility section). Any other value causes the frame to be rejected. #### Reserved (byte 7) Must be `0x00`. Reserved for future protocol extensions. #### Transaction ID (bytes 8–39) The 32-byte transaction hash in internal byte order (as used in BSV P2P protocol), **not** the reversed display order used by block explorers. #### HashKey (bytes 40–47) A 64-bit unsigned integer (big-endian) containing a stable per-flow identifier computed as: ``` HashKey = XXH64(senderIPv6 [16B] ∥ groupIdx [4B BE] ∥ subtreeID [32B]) ``` The 52-byte hash input combines the sender's IPv6 address, the derived multicast group index, and the subtree identifier to produce an 8-byte key that is constant for all frames in a flow. This enables per-flow gap tracking, NACK dispatch, and cache lookup without carrying the full 52 bytes in every frame. This field is stamped in-place by the ingress proxy (`bitcoin-shard-proxy`) before multicast forwarding. Senders (generators) set it to `0`; a value of `0` indicates the frame has not been stamped and gap tracking is skipped. #### SeqNum (bytes 48–55) A 64-bit unsigned integer (big-endian) containing a monotonic counter per flow, starting at 1. Incremented by 1 for each frame in a `(sender, group, subtree)` flow. Used by receivers to detect gaps: a gap is detected when the incoming `SeqNum` advances by more than 1 from the last-seen value for the same `HashKey`. The pair `(HashKey, SeqNum)` forms the 16-byte cache key used by retry endpoints for NACK-based retransmission. This field is stamped in-place by the ingress proxy alongside `HashKey`. A value of `0` indicates the frame has not been stamped. #### Subtree ID (bytes 56–87) A 32-byte opaque batch identifier. A subtree is an ordered set of related transactions sharing a common batch context. This field enables downstream subscribers to filter frames by batch at the application layer. All-zero bytes indicate the field is unset. #### Payload Length (bytes 88–91) A 32-bit unsigned integer (big-endian) specifying the number of payload bytes immediately following the header. It is up to the application to determine the maximum allowed payload size. #### Payload (byte 92 onward) Raw serialized BSV transaction in BRC-12 format: version (4 bytes LE) + input vector + output vector + locktime (4 bytes LE). No additional envelope wraps the transaction. ### Alignment Verification ``` | Field | Offset | Offset % 8 | |-----------------------|--------|------------| | Transaction ID | 8 | 0 ✓ | | HashKey | 40 | 0 ✓ | | SeqNum | 48 | 0 ✓ | | Subtree ID | 56 | 0 ✓ | | Payload Length | 88 | 0 ✓ | | Payload | 92 | 4 | ``` ### Compatibility with BRC-12 Legacy Format Legacy BRC-12 frames (Frame Version `0x01`) use a 44-byte header with no `HashKey`, `SeqNum`, or subtree fields: | Offset | Size | Field | | ------ | ---- | ------------------------------- | | 0 | 4 | Network Magic | | 4 | 2 | Protocol Version | | 6 | 1 | Frame Version (`0x01` = legacy) | | 7 | 1 | Reserved | | 8 | 32 | Transaction ID | | 40 | 4 | Payload Length | | 44 | \* | Payload | ### TCP Transport When transported over TCP, frames are concatenated end-to-end with no additional envelope. The reader: 1. Reads 44 bytes (sufficient for legacy header or BRC-124 header start) 2. Inspects byte 6 (Frame Version) * **Version 0x01 (legacy):** header complete; read `PayLen` at bytes 40–43 * **Version 0x02 (BRC-124):** read 48 more bytes; read `PayLen` at bytes 88–91 3. Reads exactly `PayLen` bytes 4. Processes the complete frame ### Error Handling | Condition | UDP Behavior | TCP Behavior | | ------------------------ | ------------ | ----------------- | | Bad magic | Silent drop | Connection closed | | Unknown frame version | Silent drop | Connection closed | | Payload length too large | Silent drop | Connection closed | | Truncated datagram | Silent drop | Connection closed | A frame following this specification carrying a 200-byte transaction: ``` // Header (92 bytes) E3E1F3E8 // Network Magic 02BF // Protocol Version 02 // Frame Version 00 // Reserved 11c6900eee6e68d191cd25034a5f872ed29e3b69273906a10e021f39ed866471 // TXID A1B2C3D400000001 // HashKey (XXH64 of sender+group+subtree) 00000000000004D2 // SeqNum = 1234 baadf498a00ca5a44d1c4d9d103b49017f53cd8cb2a70a9c67fc884ecdd622b5 // Subtree ID 000000C8 // Payload Length (200) // Payload (200 bytes of BRC-12 transaction data) 0200000001...00000000 ``` ### Legacy Frame Hex Dump The same transaction in legacy (BRC-12) format: ``` // Header (44 bytes) E3E1F3E8 // Network Magic 02BF // Protocol Version 01 // Frame Version (0x01 = legacy) 00 // Reserved 11c6900eee6e68d191cd25034a5f872ed29e3b69273906a10e021f39ed866471 // TXID 000000C8 // Payload Length (200) // Payload (200 bytes) 0200000001...00000000 ``` ## References * [BRC-12: Raw Transaction Format](/transactions/0012.md) — Payload format for transaction data * [BRC-74: BSV Unified Merkle Path (BUMP) Format](/transactions/0074.md) — Merkle proof format used for transaction verification * [BRC-119: SubTree Unified Merkle Path (STUMP) Format](/transactions/0119.md) — Defines the Subtree ID concept referenced in this frame format * [bitcoin-shard-common](https://github.com/lightwebinc/bitcoin-shard-common) — Reference implementation (Go) ## Constants Reference | Name | Value | Hex | Description | | ------------------ | ---------- | ------------ | ----------------------------- | | `MagicBSV` | 3811983336 | `0xE3E1F3E8` | BSV mainnet P2P magic | | `ProtoVer` | 703 | `0x02BF` | Protocol version | | `FrameVerLegacy` | 1 | `0x01` | Legacy BRC-12 frame version | | `FrameVerBRC124` | 2 | `0x02` | Current BRC-124 frame version | | `HeaderSizeLegacy` | 44 | `0x2C` | Legacy header size in bytes | | `HeaderSize` | 92 | `0x5C` | BRC-124 header size in bytes | ## Implementations * **Go**: [bitcoin-shard-common/frame](https://github.com/lightwebinc/bitcoin-shard-common/tree/main/frame) — `Encode()`, `Decode()`, wire constants * **Proxy:** [bitcoin-shard-proxy](https://github.com/lightwebinc/bitcoin-shard-proxy) — HashKey / SeqNum stamping (`forwarder/forwarder.go`) * **Services**: [bitcoin-shard-listener](https://github.com/lightwebinc/bitcoin-shard-listener), [bitcoin-multicast](https://github.com/lightwebinc/bitcoin-multicast) — Network multicast infrastructure --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/transactions/0124.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.