Payload envelope
The binary payload envelope shared by raw HTTP, QUIC streams and IPC records for transactions and bundles.
Every raw channel carries this payload: /binary, /plaintext, QUIC streams and the agent's IPC records.
A payload whose first byte is not 0x00 is one signed transaction in wire format.
A payload that starts with 0x00 is an envelope:
| Offset | Size | Field |
|---|---|---|
| 0 | 1 | 0x00 |
| 1 | 1 | Flags: 0x01 declared tip present, 0x02 bundle body. No other bits may be set. |
| 2 | 8 | Declared tip in lamports, u64 little endian. Present only when flags include 0x01. |
| 2 or 10 | rest | The body. |
Without the 0x02 flag, the body is one transaction. With it, the body is:
| Size | Field |
|---|---|
| 1 | Transaction count, 1 to 4 |
| 2 | Length of the next transaction, u16 little endian, 1 to 4,096 |
| length | The transaction's wire bytes |
The length and transaction pair repeats once per transaction, and no bytes may follow the last one. The largest payload, a declared-tip bundle of four 4,096-byte transactions, is 16,403 bytes.
| Payload | Bytes |
|---|---|
| One transaction | TX |
| One transaction, declared tip of 1,000,000 lamports | 00 01 40 42 0f 00 00 00 00 00 TX |
| Bundle of two | 00 02 02 L1 L1 TX1 L2 L2 TX2 |
| Bundle of two, declared tip of 1,000,000 lamports | 00 03 40 42 0f 00 00 00 00 00 02 L1 L1 TX1 L2 L2 TX2 |
Here L1 L1 is the little-endian length of TX1. An envelope that breaks these rules is refused as malformed with problem invalid_envelope, or as bundle_size when the count is 0 or above 4.