BIP 333: BIP324 One-Byte Message Type ID Alias Assignment
2026-10-28
View on GitHub
  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.

TypeNameDescription
alias-vectoraliasesThe 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.

TypeNameDescription
uint8_tidThe one-byte ID (1-255)
uint8_t[12]msg_typeThe 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.

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

Rationale

1

Supporting receiving any featuredata rather than requiring it be empty allows for backwards-compatible updates to this BIP in future.

2

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.

3

Due to the way BIP-324 encodes 12-byte ASCII message types, the zero value alias is not usable.

4

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.

5

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.

6

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.

7

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.

8

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.


Updated

2026-11-20

See an issue with rendering or formatting? Submit an issue on GitHub

Do you find this site useful? Please consider donating some sats to support ongoing development.

bips.dev is presented by nickmonad

All content is owned and licensed by the respective author(s). This website makes no claim of ownership.