BIP: 333
Layer: Peer Services
Title: BIP324 One-Byte Message Type ID Alias Assignment
Authors: Anthony Towns <aj@erisian.com.au>
Status: Draft
Type: Specification
Assigned: 2026-10-28
License: BSD-2-Clause
Discussion: 2026-09-20: https://gnusha.org/pi/bitcoindev/aq9ADn7GscMHWc19@erisian.com.au/T/#u
Requires: 324, 434
Abstract
Provides a new set324alias message that permits peers using
BIP-324 encrypted transport to assign one-byte IDs as aliases
for 12-byte ASCII message types to improve bandwidth usage for their
outbound messages.
Motivation
BIP-324 assigns one-byte IDs (aka 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 IDs at runtime for their own outgoing messages gives the same benefit while avoiding 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.
If a node violates a REQUIRED, MUST or MUST NOT directive, its peer MAY close the connection; beyond that, this BIP does not specify the peer's ongoing behaviour. If a node violates a RECOMMENDED, SHOULD or SHOULD NOT directive, its peer SHOULD continue operation normally, but MAY close the connection (eg if the violation creates resource usage concerns).
Feature advertisement
Support for this feature is advertised via the BIP-434 feature
message.
Nodes that support receiving set324alias messages MUST advertise
support for the feature by sending a feature message with featureid
BIP333 and an empty featuredata after sending the version message
and before sending the verack message.
Nodes that support sending set324alias messages MUST treat the peer
as having advertised support for this BIP after receiving a feature
message with featureid BIP333 (with any BIP-434 compliant featuredata
value1) between version and verack.
Nodes MAY selectively advertise support for this feature on only some connections2. Nodes SHOULD NOT advertise support for this feature on connections that do not support one-byte IDs.
set324alias message
The set324alias message allows extending or modifying the set of
aliases defined by BIP-324.
The payload of the set324alias message is serialized as a vector of
aliases, that is 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 serialized as the one-byte ID (with value 1 to 255), followed by the 12-byte ASCII message type it corresponds to.
| Type | Name | Description |
|---|---|---|
uint8_t | id | The one-byte ID (1-255) |
uint8_t[12] | msg_type | The corresponding 12-byte ASCII message type as per BIP-324 |
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,
and MUST NOT define an alias with id=03.
Nodes SHOULD NOT send set324alias on a connection that does not
support one-byte IDs (such as p2pv1 connections). 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. 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).
Once an alias is defined, a node SHOULD use that alias's one-byte ID
for all future messages of that type4.
Nodes MAY hardcode a bundle of aliases they prefer and send that bundle to all peers that support this feature5.
Nodes MAY override any existing one-byte ID, including one-byte IDs defined in BIP-324 or elsewhere.
Nodes receiving a set324alias message MUST maintain a per-peer mapping
of one-byte IDs to 12-byte ASCII message types, and future messages
using the one-byte ID MUST be interpreted as if the 12-byte msg_type
had been used instead6.
A node receiving a set324alias message MUST update the mapping with
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
order7.
If a peer specifies an unknown msg_type in an alias, the node
receiving the alias SHOULD record the id as corresponding to a generic
unknown message type rather than tracking each unknown msg_type
distinctly. Nodes MUST NOT treat a set324alias message defining an
alias for an unknown 12-byte ASCII message type as an error. Nodes
MAY treat a later message using that one-byte ID as an error if they
would also have treated a message using the msg_type it aliases as
an error8.
A node receiving a set324alias message MUST continue to accept
and process messages that use the 12-byte msg_type rather than the
one-byte ID.
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 12-byte ASCII message type stays valid for every message, so messages whose one-byte ID has been reassigned to a different message type can still be sent.
Copyright
This BIP is licensed under the 2-clause BSD license.
Rationale
Supporting receiving any featuredata rather than
requiring it be empty allows for backwards-compatible updates to this
BIP in future.
Only advertising the feature on some connections may be useful for privacy reasons, in cases where leaking additional information about what node software you are running may be undesirable.
Due to the way BIP-324 encodes 12-byte ASCII message types, the zero value alias is not usable.
Defining an additional alias costs 13 bytes, and using a one-byte ID saves 12 bytes, so defining an alias results in a saving for messages that are sent more than once, but no saving for messages sent only once. Aliasing multiple one-byte IDs to the same message type is not harmful, but also provides no benefit. Once an alias is defined, using the 12-byte ASCII message type instead of the one-byte ID simply wastes an additional 12 bytes per message.
Having a single set of aliases that is used for all peers may make implementation simpler as it results in only needing to check a single flag per-peer: "should the aliases be used, or the BIP-324 defaults?" rather than full per-peer mappings.
Note that aliases only affect messages being sent by
the node that sent the set324alias message; they do not affect messages
received by that node. If the peer were to attempt to use those aliases
for its messages, then because messaging is asynchronous, it would not be
clear to the node receiving those messages at which point the peer would
have received the set324alias message and applied the new mapping. The
only way to resolve that would be for the peer to also send some form of
"ack" message indicating "your message was received and my future messages
will use those aliases", but if a message has to be sent anyway, then
it is simpler for the peer to just send its own set324alias mapping.
Updating the mapping in order removes the ambiguity
if a single one-byte ID is assigned to multiple 12-byte ASCII message
types. For example, if set324alias [1:foo, 2:bar, 3:baz, 1:baz] is
received, subsequent messages with either of the one-byte IDs 1 or
3 will be interpreted as baz messages (rather than foo) by nodes
implementing this BIP.
One way to efficiently implement the receive-side per-peer map is to use a small array with the index corresponding to the one-byte ID, and the value being an internal identifier for each supported message, which should only need one or, at most, two bytes. With this approach, unknown messages will get represented by a placeholder identifier, and all unsupported messages will need to be treated the same way.