BIP324 One-Byte Message Type ID Alias Assignment

3 messages, 20 to 24 Sep 2026. Started by Anthony Towns.

Anthony Towns (2), Peter Todd

Anthony Towns 20 Sep 2026, 02:08 UTC permalink original

Hello world,

I'd like to propose adding a `set324alias` p2p message for dynamic assignment of BIP324 one-byte message type IDs for P2P messages.

You can see the current (non-dynamic) assignments at:

 - https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki#user-content-v2_Bitcoin_P2P_message_structure
 - https://github.com/bitcoin/bips/blob/master/bip-0324/message_type_ids.md

The TLDR summary is that nodes that implement this proposal would send a `set324alias [98:messagea, 99:messageb]` message, then afterwards can save 12 bytes every time they send `messagea` or `messageb` by using the corresponding one-byte message type id (98 or 99) instead. Which messages get aliases and what those number those aliases have are chosen by whoever sends the messages (probably by the node developer at compile-time), so nodes on the same connection may give different aliases to the same messages.

Draft BIP text follows, including a link to a bitcoin core patchset implementing it.

I've previously mentioned this concept at:

 - https://github.com/bitcoin/bips/pull/2241#discussion_r3754167576
 - https://github.com/bitcoin/bips/pull/1937#discussion_r2323645154
 - https://gnusha.org/pi/bitcoindev/aUUXLgEUCgGb122o@erisian.com.au/
 - https://github.com/bitcoin/bips/pull/1378#discussion_r990569523

 - https://github.com/bitcoin/bips/pull/2092
 - https://github.com/bitcoin/bips/pull/2086

Cheers, aj

```
  BIP: TBD
  Layer: Peer Services
  Title: BIP324 One-Byte Message Type ID Alias Assignment
  Authors: Anthony Towns <aj@erisian•com•au>
  Status: Draft
  Type: Standards Track
  Created: TBD
  License: BSD-2-Clause
  Requires: 324, 434
```

## Abstract

Provides a new `set324alias` message that permits peers using [BIP-324][BIP324] encrypted transport to assign one-byte message type ID aliases to improve bandwidth usage for their outbound messages.

## Motivation

[BIP-324][BIP324] assigns one-byte message type IDs via a fixed table, and adding additional entries to the table requires global coordination with the potential for conflicts. Allowing peers to choose their own one-byte message type IDs for their own outgoing messages avoids the need for centralized coordination, and increases flexibility for experimentation at the peer-to-peer layer.

## Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

### Feature advertisement

Support for this feature is indicated via the [BIP-434][BIP434] `feature` message, with `featureid` **TBD** and an empty `featuredata`.

Support for this feature SHOULD NOT be advertised on connections that do not support one-byte message type IDs.

### `set324alias` message

The `set324alias` allows extending or modifying the set of aliases defined by [BIP-324][BIP324].

The payload of the `set324alias` message contains a vector of aliases, represented as a CompactSize encoded number of aliases being defined, followed by that number of aliases.

| Type         | Name          | Description |
| ------------ | ------------- | ----------- |
| alias-vector | `aliases`     | The new aliases |

Each alias is represented by a single byte identifying the alias (with value 1 to 255), followed by a CompactSize-prefixed string of up to 12 bytes giving the message type the alias corresponds to.

| Type         | Name          | Description |
| ------------ | ------------- | ----------- |
| `uint8_t`    | `id`          | The alias (1-255) |
| `var_string` | `msg_type`    | A 1-12 byte message type |

Nodes MUST NOT send `set324alias` before sending `verack`. Nodes MUST NOT send `set324alias` to a peer that has not advertised support for the feature. Nodes MUST NOT send more than 255 elements in `aliases`, MUST NOT define an alias with `id=0`, and MUST NOT send a `msg_type` longer than 12 bytes.

Nodes SHOULD NOT send `set324alias` on a connection that does not support one-byte message types. Nodes SHOULD NOT send `set324alias` with an empty `aliases` vector.

Nodes SHOULD define an alias for all messages that they expect to send multiple times over a connection. Nodes SHOULD NOT define an alias for any message that will only be sent at most once over the connection. Nodes SHOULD NOT define aliases for messages that already have an alias defined in [BIP-324][BIP324].

Nodes SHOULD send `set324alias` only once per connection, and SHOULD send it as soon as possible (eg, immediately after receiving the `feature` message indicating support).

Nodes MAY hardcode a bundle of aliases they prefer and send that bundle to all peers that support this feature.

Nodes receiving a `set324alias` message MUST maintain a per-peer alias id to message mapping, so that future messages using the one-byte alias are correctly interpreted as if the 1-12 byte `msg_type` had been used instead.

A node receiving a `set324alias` message MUST apply the new aliases immediately, as the very next message may make use of aliases declared in that message.

Nodes receiving a `set324alias` message MUST update the aliases in order (eg if `[1:foo, 2:bar, 1:baz]` is received, the one-byte message type `1` will be interpreted as `baz` thereafter).

If a peer specifies an unknown `msg_type` in an alias, the node receiving the alias SHOULD record the alias as being a generic unknown message type rather than tracking each unknown `msg_type` distinctly. Nodes MUST NOT treat a `set324alias` message defining an alias for unknown messages as an error. Nodes MAY treat a later message using that alias as an error if they would also have treated a message using `msg_type` it aliases as an error.

A node receiving a `set324alias` message MUST continue to accept messages that use the 1-12 byte `msg_type` rather than the alias.

## Reference implementation

**TODO** See https://github.com/ajtowns/bitcoin/commits/202605-bip324-id/ in the meantime.

## Backward compatibility

Non-implementing peers never receive a `set324alias` (gated on their advertisement), so they keep the default mapping and are unaffected.

The long form message type stays valid for every message, so messages whose one byte type ID alias has been reassigned to a different message type can still be sent.

## Copyright

This BIP is licensed under the 2-clause BSD license.

[BIP324]: https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki [BIP434]: https://github.com/bitcoin/bips/blob/master/bip-0434.md

Peter Todd 20 Sep 2026, 08:29 UTC in reply to Anthony Towns permalink original

On Sun, Sep 20, 2026 at 12:08:14PM +1000, Anthony Towns wrote:

Quoted text (21 lines)

> Hello world,
>
> I'd like to propose adding a `set324alias` p2p message for dynamic
> assignment of BIP324 one-byte message type IDs for P2P messages.
>
> You can see the current (non-dynamic) assignments at:
>
>  - https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki#user-content-v2_Bitcoin_P2P_message_structure
>  - https://github.com/bitcoin/bips/blob/master/bip-0324/message_type_ids.md
>
> The TLDR summary is that nodes that implement this proposal would send a
> `set324alias [98:messagea, 99:messageb]` message, then afterwards can
> save 12 bytes every time they send `messagea` or `messageb` by using
> the corresponding one-byte message type id (98 or 99) instead. Which
> messages get aliases and what those number those aliases have are
> chosen by whoever sends the messages (probably by the node developer
> at compile-time), so nodes on the same connection may give different
> aliases to the same messages.
>
> Draft BIP text follows, including a link to a bitcoin core patchset
> implementing it.

I think the BIP needs to include within it an estimate of what % of total bandwidth this might actually save.

Anthony Towns 24 Sep 2026, 00:36 UTC in reply to Peter Todd permalink original

On Sun, Sep 20, 2026 at 08:29:31AM +0000, Peter Todd wrote:

Quoted text (7 lines)

> On Sun, Sep 20, 2026 at 12:08:14PM +1000, Anthony Towns wrote:
> > The TLDR summary is that nodes that implement this proposal would send a
> > `set324alias [98:messagea, 99:messageb]` message, then afterwards can
> > save 12 bytes every time they send `messagea` or `messageb` by using
> > the corresponding one-byte message type id (98 or 99) instead.
> I think the BIP needs to include within it an estimate of what % of
> total bandwidth this might actually save.

The bandwidth saving is 12 bytes per message; what percentage of total bandwidth that is depends on the messages sent over the link.

If the connection is only used for extremely small messages like PING/PONG, that could be a saving of up to 66%; if it's a more normal connection that's dominated by INV/GETDATA/TX messages, expect a saving of closer to 5%; and if it's in -blocksonly mode and traffic is mostly full 2MB BLOCK messages, then it's something like 0.0006% savings. And in any event, all those messages already have 1-byte identifiers, so until you're using new messages that don't already have a 1-byte identifier assigned, the saving is 0%.

Cheers, aj