> 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/0127.md). # Multicast Subtree Group Announcement Frame Format Jeff Harris () ## Abstract This BRC specifies a periodic multicast announcement protocol that maps BRC-124 `SubtreeID` values to stable 128-bit group identifiers. Senders broadcast compact 64-byte datagrams on a reserved control-plane multicast group, allowing listeners to dynamically learn which subtree IDs belong to which groups and filter incoming transaction traffic accordingly — without static configuration. ## Copyright This BRC is licensed under the Open BSV License. ## Motivation BRC-124 frames carry a 32-byte `SubtreeID` that identifies the transaction subtree to which each frame belongs. Subtree IDs are derived deterministically by each block assembler and change with every new work candidate. Static subtree ID lists are impractical for listeners that want to subscribe to a logical class of transactions (a *subtree group*) across block boundaries. This BRC introduces: 1. **Subtree groups** — stable 128-bit identifiers that logically group related subtree IDs. A group ID is an XXH3-128 hash of a canonical group name, or any operator-assigned 128-bit value. 2. **SubtreeGroupAnnounce** — a periodic 64-byte control datagram sent by block assemblers announcing that a given `SubtreeID` is a member of a given group. 3. **Dynamic listener filtering** — listeners join a dedicated control-plane multicast group, process SubtreeGroupAnnounce datagrams, maintain a time-bounded registry, and pass transactions based on group membership. Subtrees are temporal: they are valid only for the duration of a work candidate. Announcements are sent periodically; entries not refreshed within their TTL are evicted automatically. ## Specification ### Control-Plane Group SubtreeGroupAnnounce datagrams are sent to the reserved control-plane multicast group index `0xFFFC` (`GroupSubtreeGroupAnnounce`), one slot below the BRC-126 beacon group (`0xFFFD`). Control-plane addresses use the IANA-aligned layout: bytes 0–1 carry the scope prefix, bytes 2–11 are zero (IANA 96-bit boundary), bytes 12–13 carry the IANA Bitcoin group-id (`0x000B`), and bytes 14–15 carry the group index. | Scope | Announce Group | | --------------- | -------------- | | Site (`0x05`) | `FF05::B:FFFC` | | Org (`0x08`) | `FF08::B:FFFC` | | Global (`0x0E`) | `FF0E::B:FFFC` | Operators MAY override the IANA group-id (`0x000B`) via the `-mc-group-id` configuration flag for private deployments; the resulting addresses change accordingly. ### SubtreeGroupAnnounce Wire Format (`MsgType 0x30`) — 64 bytes | Offset | Size | Field | Description | | ------ | ---- | ------------- | ------------------------------------------------------------- | | 0 | 4 | Network Magic | `0xE3E1F3E8` (BSV mainnet P2P magic) | | 4 | 2 | Protocol Ver | `0x02BF` (703, BSV large-block baseline) | | 6 | 1 | MsgType | `0x30` (SubtreeGroupAnnounce) | | 7 | 1 | Flags | Reserved; must be `0x00` | | 8 | 32 | SubtreeID | SHA-256 subtree root hash (from BRC-124 frame header) | | 40 | 16 | GroupID | 128-bit group identifier, big-endian | | 56 | 4 | Epoch | Unix timestamp (uint32 BE) when this announcement was created | | 60 | 2 | TTL | Validity in seconds (uint16 BE); `0` = use listener default | | 62 | 2 | Reserved | Must be `0x0000` | Total: **64 bytes**. Power-of-two message size; `GroupID` at offset 40 is 8-byte aligned. #### Flags (byte 7) All bits are reserved and must be zero. Future versions of this protocol may define flag bits. #### GroupID A GroupID is a 128-bit value uniquely identifying a logical subtree group. It is recommended to derive GroupIDs using XXH3-128 applied to a canonical group name string, as this provides hardware-accelerated, collision-resistant derivation. GroupIDs may also be assigned directly as opaque 128-bit values. #### TTL and Expiry A `TTL` value of `0` instructs the listener to apply its locally configured default TTL. Listeners SHOULD set the default TTL to at least 900 seconds (15 minutes) to accommodate block creation intervals. Senders SHOULD re-announce each (SubtreeID, GroupID) pair at an interval well below the effective TTL (recommended: every 10–30 seconds). #### Multi-Group Membership A single SubtreeID may belong to multiple groups. The sender emits one SubtreeGroupAnnounce datagram per (SubtreeID, GroupID) pair per announcement interval. ### Sender Behaviour 1. For each (SubtreeID, GroupID) pair, construct a 64-byte SubtreeGroupAnnounce datagram. 2. Send the datagram as a UDP packet to the SubtreeGroupAnnounce control group on the configured multicast scope(s). 3. Repeat at the configured announcement interval (recommended: 10–30 seconds). 4. On work reset (new block), stop announcing old SubtreeIDs. Listeners will evict them when the TTL expires. No retransmission or sequencing is required. Periodic re-announcement provides eventual consistency. ### Listener Behaviour 1. Join the SubtreeGroupAnnounce control-plane multicast group on the configured scope(s). 2. For each received datagram, validate the magic, ProtoVer, MsgType, and length. 3. If a sender include/exclude filter is configured, check the UDP source address before processing. 4. If the GroupID matches a subscribed group, record `(SubtreeID → expiry)` in the group registry. 5. Periodically evict entries whose expiry has passed. 6. On data-plane frame receipt, allow the frame if its SubtreeID is present in any subscribed group's registry. ### Sender Filtering Listeners MAY configure include and exclude filters on announcement source addresses (IPv6 addresses or CIDR prefixes). The evaluation order is: exclude first, then include. An empty include list accepts all non-excluded sources. *** ## Example SubtreeGroupAnnounce for SubtreeID `A3F1...9247`, GroupID `A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6`, Epoch `1746800000`, TTL `0` (use listener default): ``` E3E1F3E8 // Network Magic 02BF // Protocol Version 30 // MsgType = SubtreeGroupAnnounce 00 // Flags = 0 A3F1E8B04C7D2A9156E3F08B4D7C2E9A // SubtreeID bytes 0–15 1B5F3D8E6C0A4279B1D5E8F3C6A09247 // SubtreeID bytes 16–31 A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6 // GroupID (128-bit) 67E27D80 // Epoch = 1746800000 0000 // TTL = 0 (use listener default) 0000 // Reserved ``` *** ## Constants Reference | Name | Value | Hex | Description | | ----------------------------- | ---------- | ------------ | ------------------------------------------- | | `MagicBSV` | 3823236072 | `0xE3E1F3E8` | BSV mainnet P2P magic | | `ProtoVer` | 703 | `0x02BF` | Protocol version | | `MsgTypeSubtreeGroupAnnounce` | 48 | `0x30` | SubtreeGroupAnnounce datagram type | | `GroupSubtreeGroupAnnounce` | 65532 | `0xFFFC` | Control-plane subtree group announce group | | `GroupBeacon` | 65533 | `0xFFFD` | Control-plane beacon group (BRC-126) | | `SubtreeGroupAnnounceSize` | 64 | — | Fixed datagram size in bytes | | `DefaultAnnounceTTL` | 900 | — | Recommended listener default TTL (s) | | `DefaultAnnounceInterval` | 10 | — | Recommended sender re-announce interval (s) | *** ## References * [BRC-124: Multicast Transaction Frame Format](/brc/transactions/0124.md) — Data-plane frame format; defines `SubtreeID` --- # 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/0127.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.