BIP 324: Clarify equivalence between 1 and 13 byte message types

ajtowns commented at 0:36 am on January 16, 2026: contributor

BIP 324 introduced single-byte short identifiers for messages used multiple times in a connection, relating them to existing v1 messages, however it left it ambiguous as to what should happen if a 13-byte message_type was received. Clarify that the single byte message types are simply aliases for the longer equivalents, and that nodes should behave identically whether a message uses a one byte message_type or the equivalent 13-byte message type.

Also lowercases the message types (matching the on-the-wire encoding, rather than the Bitcoin Core constants), explicitly defines the payload’s message_length, and adds a Version header and Changelog section.

BIP324: Add Version header and Changelog section 48c0f201aa

ajtowns commented at 0:51 am on January 16, 2026: contributor

cc @sipa @real-or-random @dhruv @jonasschnelli

I believe Bitcoin Core and btcd match this spec, but that rust-bitcoin does not, and will instead reject messages that don’t use the assigned short id. (Likewise for floresta and the bip324 crate, AIUI)

The rationale is twofold:

keep things simple and avoid creating two distinct namespaces for message types – every message has a 12 byte name that’s suitable for v1/v2, and some of those message have a short, one byte alias
having short ids be an alias for the longer id makes dynamic allocation of short ids more straightforward: you just need to link the new short id with the 12-byte ASCII id; and if a short id is not allocated, you can reliably just use the 12-byte ASCII id.

murchandamus added the label Proposed BIP modification on Jan 16, 2026

murchandamus added the label Pending acceptance on Jan 16, 2026

murchandamus added the label Bug fix on Jan 16, 2026

real-or-random commented at 12:52 pm on January 20, 2026: contributor

Concept ACK

I’d rather see this as a 1.0.1. I believe the current text is already pretty clear when it says “If the first byte of message_type is b’\x00’, the following 12 bytes are interpreted as an ASCII message type (as in the v1 P2P protocol) (…)”

sipa commented at 7:20 pm on January 20, 2026: member

ACK. Agree with @real-or-random on the versioning.

ajtowns force-pushed on Jan 21, 2026

ajtowns commented at 4:48 am on January 21, 2026: contributor

Changed to 1.0.1.

I believe the current text is already pretty clear when it says “If the first byte of message_type is b'\x00', the following 12 bytes are interpreted as an ASCII message type (as in the v1 P2P protocol) (…)”

This was what I originally thought, but given the text specifies the messages in caps, and the actual ascii messages are all lowercase, it felt a bit ambiguous. That rust seems to have implemented it differently also suggests it’s not clear, I think.

in bip-0324.mediawiki:13 in aeb79971af

 9@@ -10,6 +10,7 @@
10   Type: Specification
11   Assigned: 2019-03-08
12   License: BSD-3-Clause
13+  Version: 1.1.0

real-or-random commented at 9:46 am on January 21, 2026:

0  Version: 1.0.1

in bip-0324.mediawiki:575 in aeb79971af outdated

579 || colspan="4" | (undefined)
580 |}
581 
582 
583-Additional message types may be added separately after BIP finalization.
584+Peers that support a message type ID should also support the same message when encoded with the equivalent 12 byte ASCII message type (eg, if the one byte <code>message_type = b'\x0a'</code> is supported, then the 13 byte <code>message_type = b'\x00getblocktxn\x00'</code> should also be supported and behave identically).

real-or-random commented at 9:55 am on January 21, 2026:

If the philosophy is that the type IDs and the ASCII types are “equivalent”, what about the opposite direction? Should a peer that supports a long ASCII type should also support the short type ID? I think it will be okay to require this? If yes, we should also make it explicit.

(It seems to conflict with “Additional message type IDs may be added separately after BIP finalization.”, but that’s not really the case. If a type ID is added because the message type itself is new, then everything will be fine. And if a type ID for an existing message type is added, then strictly speaking, implementations will no longer be compliant and will need to be updated to conform with the new spec. But that’s precisely what we would want to express, I think.)

nit:

0Peers that support a message type ID should also support the same message when encoded with the equivalent 12 byte ASCII message type (e.g., if the one byte <code>message_type = b'\x0a'</code> is supported, then the 13 byte <code>message_type = b'\x00getblocktxn\x00'</code> should also be supported and behave identically).

ajtowns commented at 10:25 am on January 21, 2026:

I’ve been thinking about this in the context of supporting dynamic one-byte aliases, ie a protocol sequence something like:

A -> B: VERSION ...
B -> A: VERSION ...
B -> A: FEATURE bip324-shortid-negotiation
B -> A: VERACK
A -> B: FEATURE bip324-shortid-negotiation
A -> B: VERACK
A -> B: BIP324ALIAS 67=hax0r 121=elevenses
B -> A: BIP324ALIAS 3=gdaymate

At which point if B receives a message with shortid 67 or 121 form A they should treat it as if it were the message hax0r or elevenses, and if A received message with shortid 3 from B, they should treat it as gdaymate rather than blocktxn.

In that context, if A still wanted to send blocktxn to B, they would need to encode it as a 12 byte ascii message, and should be able to. (If we ever have enough messages to actually allocate all 127 shortids, that would matter; until then nodes should just not override messages)

I’ve got rough code for that at https://github.com/ajtowns/bitcoin/commits/202511-bip324-id/ but haven’t even started writing up text for it.

My rough thinking was that the table in 324 defines the default mapping for when you don’t support “bip324-shortid-negotiation” or don’t receive a “BIP324ALIAS” message, and that otherwise the mapping for send is whatever you choose, and the mapping for receive is whatever your peer chooses. And at that point, you don’t really need to specify a table, you can just negotiate it, whether the messages are new/old.

real-or-random commented at 10:49 am on January 21, 2026:

Okay, I see, but I don’t see the connection to my question:

Should a peer that supports a long ASCII type also support the short type ID?

Are you saying the answer should be a yes because, after negotiation, negotiated IDs must be supported?

ajtowns commented at 12:57 pm on January 21, 2026:

Well, in that example, after negotiation, you might not support the short id 3 for blocktxn (or any other short id for that message type), despite still supporting the message type, which might be interpreted as a violation of a requirement that “a peer that supports a long ASCII type should also support the short type ID”.

“Unless otherwise negotiated, nodes implementing this BIP must treat the following short and long message types as equivalent” or something, maybe?

real-or-random commented at 4:58 pm on January 21, 2026:

“Unless otherwise negotiated, nodes implementing this BIP must treat the following short and long message types as equivalent” or something, maybe?

I’m a bit reluctant to take into account possible future extensions that don’t exist yet. This just adds complexity to the language now, and without the background knowledge, it may be confusing to readers because negotation isn’t mentioned at all in the BIP. (“Negotiated? How? Over a beer?”) If you write this BIP and it gets merged, I’ll be happy to amend BIP324 and add a note.

Here’s a suggestion that expresses both directions: “If a message type ID for a certain message type exists, peers that support receiving messages of that type should accept both the 1-byte encoding and the 13-byte encoding (e.g., the 1-byte message_type = b’\x0a’ should be accepted if and only if the 13-byte message_type = b’\x00getblocktxn\x00’ is accepted, and behavior should not depend on which of the two encodings is received).”

ajtowns commented at 6:40 am on January 24, 2026:

Reworded that a little and pushed, so it now says:

When a message type has both a 1-byte encoding and a 13-byte encoding defined, peers that support receiving that message type should accept messages using either encoding (e.g., if the “getblocktxn” message type is supported, then both the 1-byte b'\x0a' encoding and the 13-byte b'\x00getblocktxn\x00' should be supported, and behavior should not depend on which of the two encodings is received).

Thoughts?

real-or-random commented at 12:49 pm on January 29, 2026:

ACK

ajtowns force-pushed on Jan 21, 2026

BIP324: supporting 1 byte message type ids means supporting the equivalent 12 byte ASCII message types 4c80568652

BIP324: define message_length 40e6634a2e

ajtowns force-pushed on Jan 24, 2026

murchandamus commented at 5:58 pm on January 29, 2026: contributor

@sipa, @real-or-random: It looks like Tim is d’accord on the latest phrasing, could you please let me know if that means that this PR is ready to be merged?

sipa commented at 6:03 pm on January 29, 2026: member

ACK 40e6634a2e8bfe3089e4565ecd361ffddb78e544

murchandamus commented at 6:17 pm on January 29, 2026: contributor

Confirmed with @real-or-random out of band as well.

murchandamus merged this on Jan 29, 2026

murchandamus closed this on Jan 29, 2026

murchandamus removed the label Pending acceptance on Jan 29, 2026

BIP 324: Clarify equivalence between 1 and 13 byte message types #2086