> For the complete documentation index, see [llms.txt](https://hub.bsvblockchain.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.bsvblockchain.org/brc/transactions/0131.md).

# Multicast Block Announcement Frame Format

Jeff Harris (<jeff@lightweb.net>)

## Abstract

This BRC specifies the wire format for distributing block-level metadata over the IPv6 multicast fabric. A new frame version (`0x04`) reuses the BRC-124 92-byte header layout and carries either a block announcement (block header + coinbase TxID + subtree hashes) or a coinbase transaction, delivered to all subscribers via a dedicated control-plane multicast group (`FF0E::B:FFFE`).

## Copyright

This BRC is licensed under the Open BSV License.

## Motivation

The multicast fabric defined in BRC-124 shards transaction delivery across deterministic IPv6 multicast groups. Block events require a complementary distribution path:

1. **Block announcements** must reach every subscriber — miners, exchanges, and overlay services — so they can update block templates, advance chain state, and validate received transactions against the new tip.
2. **Coinbase transactions** must be delivered to all subscribers regardless of shard assignment, since every node needs the coinbase to reconstruct the block Merkle root.
3. Both events must carry the same sequencing and reliability guarantees (HashKey/SeqNum stamping and NACK-based retransmission) as ordinary transaction frames, so existing retry infrastructure works without modification.

Defining a new `FrameVer` byte satisfies these requirements with minimal protocol surface: the BRC-124 header layout is fully preserved, the same proxy/listener/retry machinery applies, and the only routing change is substituting the shard-derived multicast group with the dedicated control group.

## Specification

### Frame Header Format (92 bytes)

The BRC-131 header is layout-identical to the BRC-124 header. All multi-byte integers are big-endian.

| Offset | Size | Alignment | Field          | Description                                        |
| ------ | ---- | --------- | -------------- | -------------------------------------------------- |
| 0      | 4    | —         | Network Magic  | 0xE3E1F3E8 (BSV mainnet P2P magic)                 |
| 4      | 2    | —         | Protocol Ver   | 0x02BF (703, BSV large-block baseline)             |
| 6      | 1    | —         | Frame Version  | 0x04 — BRC-131 block control                       |
| 7      | 1    | —         | MsgType        | 0x01 = BlockAnnounce; 0x02 = CoinbaseTx            |
| 8      | 32   | 8-byte    | ContentID      | BlockHash (announce) or CoinbaseTxID (coinbase)    |
| 40     | 8    | 8-byte    | HashKey        | XXH64(senderIPv6 ∥ flowIdx ∥ zeros); proxy-stamped |
| 48     | 8    | 8-byte    | SeqNum         | Per-sender monotonic counter; stamped by proxy     |
| 56     | 32   | 8-byte    | Reserved32     | All zeros                                          |
| 88     | 4    | 8-byte    | Payload Length | uint32 BE                                          |
| 92     | \*   | —         | Payload        | MsgType-specific (see below)                       |

**Distinction from BRC-124:** Byte 7 carries `MsgType` rather than `Reserved=0x00`. The 32 bytes at 56–87 are always zeros (no subtree ID; block frames address all subscribers).

### Field Definitions

#### Network Magic (bytes 0–3)

The value `0xE3E1F3E8` (BSV mainnet P2P magic). Frames with incorrect magic are rejected.

#### Protocol Version (bytes 4–5)

`0x02BF` (703). Informational; receivers do not validate.

#### Frame Version (byte 6)

`0x04` for BRC-131 frames. Any other value causes the frame to be handled by a different decoder.

#### MsgType (byte 7)

Identifies the payload type:

| Value  | Constant           | Payload                                           |
| ------ | ------------------ | ------------------------------------------------- |
| `0x01` | `BlockMsgAnnounce` | Block header + CoinbaseTxID + subtree root hashes |
| `0x02` | `BlockMsgCoinbase` | Raw serialized coinbase transaction bytes         |

Any other value is rejected.

#### ContentID (bytes 8–39)

A 32-byte identifier:

* **BlockAnnounce:** the block hash in internal byte order (not reversed display order).
* **CoinbaseTx:** SHA256d of the raw coinbase transaction bytes (the CoinbaseTxID).

#### HashKey (bytes 40–47)

`uint64` big-endian. XXH64 of `(senderIPv6[16] ∥ flowIdx[4] ∥ zeroSubtreeID[32])` where `flowIdx` is a 4-byte big-endian value selected by `MsgType`, so the two payload types form independent flows on the shared egress group:

* **BlockAnnounce** (`MsgType 0x01`): `flowIdx = 0x0000FFFE` (`GroupBlockBroadcast`).
* **CoinbaseTx** (`MsgType 0x02`): `flowIdx = 0x0000FFF8` (`GroupCoinbaseFlow`, a virtual HashKey index — see [BRC-129](/brc/transactions/0129.md) and [BRC-133](/brc/transactions/0133.md)).

Stamped in-place by the proxy if zero on arrival.

#### SeqNum (bytes 48–55)

`uint64` big-endian. Monotonic per-sender counter for the `(HashKey, flowIdx)` flow. Stamped in-place by the proxy if zero on arrival. Used by listeners and retry endpoints as the secondary cache key.

#### Reserved32 (bytes 56–87)

All zero bytes. Block control frames have no subtree ID; the field is reserved for future use.

#### Payload Length (bytes 88–91)

`uint32` big-endian. Number of payload bytes immediately following the header.

#### Payload (byte 92 onward)

MsgType-specific (see below).

### BlockAnnounce Payload (MsgType 0x01)

| Offset | Size   | Field         | Description                                       |
| ------ | ------ | ------------- | ------------------------------------------------- |
| 0      | 80     | BlockHeader   | Standard 80-byte BSV block header                 |
| 80     | 32     | CoinbaseTxID  | SHA256d of the coinbase transaction (internal BO) |
| 112    | 4      | SubtreeCount  | Number of subtree root hashes (uint32 BE); ≥ 0    |
| 116    | 32 × N | SubtreeHashes | Ordered list of N subtree Merkle root hashes      |

**Minimum payload size:** 116 bytes (N = 0). **Total payload size:** 116 + 32 × N bytes.

The `ContentID` in the frame header is the 32-byte block hash. The `SubtreeHashes` are the ordered Merkle roots of the sharded transaction subtrees included in this block, matching the producer's subtree enumeration. The count may be zero for empty blocks or blocks with no sharded subtrees.

### CoinbaseTx Payload (MsgType 0x02)

The payload is the raw serialized coinbase transaction — the same encoding as a BRC-12 transaction payload (version LE32 + inputs + outputs + locktime LE32), with no additional envelope.

The `ContentID` in the frame header is the SHA256d of these raw bytes (the CoinbaseTxID), identical to the `CoinbaseTxID` field in the corresponding `BlockAnnounce` frame.

### Control-Plane Multicast Group

BRC-131 frames are distributed exclusively on the **GroupBlockBroadcast** group:

| Index  | Scope  | IPv6 Address | Constant            |
| ------ | ------ | ------------ | ------------------- |
| 0xFFFE | global | FF0E::B:FFFE | GroupBlockBroadcast |

The global scope (`FF0E`) ensures block announcements cross site boundaries. The group index `0xFFFE` is in the reserved control-plane range and is never used as a shard group for any `shard_bits` ≤ 12.

### Sequence Tracking and Retransmission

BRC-131 frames use the same XXH64 hash-chain sequencing as BRC-124:

* **HashKey** is computed as `XXH64(senderIPv6 ∥ flowIdx ∥ zeroSubtreeID)` where `flowIdx = 0x0000FFFE` for BlockAnnounce and `0x0000FFF8` for CoinbaseTx (see the HashKey field definition).
* **SeqNum** is a monotonic per-sender counter for the `(HashKey, flowIdx)` flow.
* The proxy stamps both fields in-place if `SeqNum == 0` on arrival.
* Listeners detect gaps by comparing consecutive `SeqNum` values on the control flow and dispatch BRC-126 NACKs to retry endpoints.
* Retry endpoints cache BRC-131 frames by `HashKey ∥ SeqNum` and retransmit to `FF0E::B:FFFE` on NACK. **The retransmit destination is the control group, not the shard group derived from ContentID.**

### TCP Transport

The read sequence is identical to BRC-124:

1. Read 44 bytes (sufficient for legacy header or BRC-131 start).
2. Inspect `FrameVer` at byte 6.
   * **Version 0x04 (BRC-131):** read 48 more bytes to complete the 92-byte header; `PayLen` is at bytes 88–91.
3. Read exactly `PayLen` bytes.
4. Process the complete frame.

### Fragmentation (BRC-130 Extension)

When `len(Payload) > fragDataSize`, the proxy fragments the frame using BRC-130. The `OrigFrameVer` field at byte 100 of the BRC-130 fragment header is set to `0x04`. The `MsgType` byte is preserved in the BRC-130 fragment's byte 7. Fragment gap tracking uses the `(HashKey, flowIdx, zeroSubtreeID)` flow identically to BRC-124 fragments.

Block announcements for typical blocks fit well within a 9000-byte jumbo frame (116 + 32 × 128 = 4212 bytes for 128 subtrees). Fragmentation is primarily relevant for large `CoinbaseTx` payloads.

### Error Handling

| Condition                | UDP Behavior | TCP Behavior      |
| ------------------------ | ------------ | ----------------- |
| Bad magic                | Silent drop  | Connection closed |
| FrameVer ≠ 0x04          | Not BRC-131  | Not BRC-131       |
| Unknown MsgType          | Silent drop  | Connection closed |
| Payload length too large | Silent drop  | Connection closed |
| Truncated datagram       | Silent drop  | Connection closed |
| SeqNum == 0 at listener  | Discard      | Discard           |

## Examples

### BlockAnnounce Frame (N=2 subtrees)

```
// Header (92 bytes)
E3E1F3E8                                                          // Network Magic
02BF                                                              // Protocol Version
04                                                                // Frame Version (BRC-131)
01                                                                // MsgType (BlockAnnounce)
<32-byte block hash>                                              // ContentID
<8-byte HashKey>                                                  // Proxy-stamped XXH64
<8-byte SeqNum>                                                   // Proxy-stamped monotonic
0000000000000000000000000000000000000000000000000000000000000000  // Reserved32
000000B4                                                          // PayloadLen = 180 (116 + 2×32)

// Payload (148 bytes)
<80-byte block header>                                            // BlockHeader
<32-byte coinbase TxID>                                           // CoinbaseTxID
00000002                                                          // SubtreeCount = 2
<32-byte subtree hash 0>                                          // SubtreeHashes[0]
<32-byte subtree hash 1>                                          // SubtreeHashes[1]
```

### CoinbaseTx Frame

```
// Header (92 bytes)
E3E1F3E8                                                          // Network Magic
02BF                                                              // Protocol Version
04                                                                // Frame Version (BRC-131)
02                                                                // MsgType (CoinbaseTx)
<32-byte CoinbaseTxID>                                            // ContentID = SHA256d(payload)
<8-byte HashKey>                                                  // Proxy-stamped XXH64
<8-byte SeqNum>                                                   // Proxy-stamped monotonic
0000000000000000000000000000000000000000000000000000000000000000  // Reserved32
<4-byte PayloadLen>                                               // Coinbase tx byte count

// Payload
<raw coinbase transaction bytes>
```

## Alignment Verification

| Field          | Offset | Offset % 8 |
| -------------- | ------ | ---------- |
| ContentID      | 8      | 0 ✓        |
| HashKey        | 40     | 0 ✓        |
| SeqNum         | 48     | 0 ✓        |
| Reserved32     | 56     | 0 ✓        |
| Payload Length | 88     | 0 ✓        |
| Payload        | 92     | 4          |

## Constants Reference

| Name                    | Value | Hex    | Description                                  |
| ----------------------- | ----- | ------ | -------------------------------------------- |
| FrameVerV4              | 4     | 0x04   | BRC-131 block control frame version          |
| BlockMsgAnnounce        | 1     | 0x01   | MsgType: block announcement                  |
| BlockMsgCoinbase        | 2     | 0x02   | MsgType: coinbase transaction                |
| GroupBlockBroadcast     | 65534 | 0xFFFE | Control-plane group index for block frames   |
| BlockHeaderSize         | 80    | 0x50   | Standard BSV block header size (bytes)       |
| BlockAnnounceMinPayload | 116   | 0x74   | Minimum BlockAnnounce payload (N=0 subtrees) |
| HeaderSize              | 92    | 0x5C   | BRC-131 header size (identical to BRC-124)   |

## References

* [BRC-12: Raw Transaction Format](/brc/transactions/0012.md) — Coinbase payload encoding
* [BRC-124: Multicast Transaction Frame Format](/brc/transactions/0124.md) — Header layout reused by BRC-131
* [BRC-126: Multicast Retransmission Protocol](/brc/transactions/0126.md) — NACK/ACK/MISS used for block frame retransmission
* [BRC-129: Multicast Group Address Assignments](/brc/transactions/0129.md) — GroupBlockBroadcast index allocation
* [BRC-130: Multicast Transaction Frame Fragmentation](/brc/transactions/0130.md) — BRC-130 fragmentation with OrigFrameVer=0x04
* [BRC-119: SubTree Unified Merkle Path (STUMP) Format](/brc/transactions/0119.md) — Defines the subtree concept referenced in BlockAnnounce


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://hub.bsvblockchain.org/brc/transactions/0131.md?ask=<question>
```

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.