Binary Encoding for the Message Relay Interface
If your app sends messages between users and those messages contain binary data, like signatures or encrypted blobs, encoding everything as JSON text makes the payload bigger than it needs to be, and that waste gets worse the more binary content you pack in. This matters once you care about bandwidth or are sending a lot of small messages. It makes it possible to send and receive the exact same messages more compactly.
Reference for an AI
Everything an assistant needs to answer questions about BRC-231 accurately, including what it depends on.
Summary
- Why
- JSON text encoding inflates binary payloads, and the bloat compounds when binary data is itself encoded as text inside the payload.
- What
- BRC-231 defines a CBOR (Concise Binary Object Representation) wire format for the BRC-33 message relay interface, using the same endpoints but with bodies and identity keys as raw bytes instead of text.
- How
- A client sends a request with Content-Type application/cbor to the same BRC-33 endpoints, and the server replies in DAG-CBOR using the same keys as the JSON version, with recipient, sender and body fields as byte strings instead of base64 text.
What this lets you do
- Send and receive BRC-33 messages encoded as binary CBOR instead of JSON
- Submit recipient and sender identity keys as raw 33-byte values instead of hex or base64 strings
- Send message bodies as opaque bytes, delivered unchanged
- Pick JSON or CBOR per request using the Content-Type header
- Reduce payload size for messages carrying binary content
Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.
The specification
Abstract
An alternative wire format for the BRC-33 message relay interface: the same requests and responses as DAG-CBOR instead of JSON, with the message body and identity keys as byte strings.
Motivation
Text encoding makes binary data larger, and the growth compounds when a text-encoded payload itself carries binary encoded as text.
Specification
The endpoints, authentication and semantics are those of BRC-33. A request with Content-Type: application/cbor is answered in CBOR; a JSON request is answered in JSON. Each JSON object becomes a DAG-CBOR map with the same keys.
| Endpoint | Request | Response |
|---|---|---|
POST /sendMessage | { message: { recipient: bstr(33), messageBox: tstr, body: bstr } } | { status: tstr, messageId: tstr } |
POST /listMessages | { messageBox: tstr } | { status: tstr, messages: [ { messageId: tstr, body: bstr, sender: bstr(33) } ] } |
POST /acknowledgeMessage | { messageIds: [ tstr ] } | { status: tstr } |
recipient and sender are 33-byte compressed identity keys. body is opaque bytes, delivered as submitted.