QMail Subscribe — Group 6, Code 85
A vendor adds prepaid storage credit to one or many target mailboxes in a single request, so those mailboxes can upload QMail attachments without attaching a payment locker. The vendor proves ownership of an allow-listed billing coin by presenting its Authenticity Number, exactly like an upload; each entry’s credit is added to that mailbox’s balance on this RAIDA.
Quick reference
| Command Group | 6 (QMail) |
| Command Code | 85 (0x55) |
| Server function | cmd_qmail_subscribe in cmd_qmail.c |
| Request body | Variable: QMail preamble(48) + N×9-byte entries + terminator(2), N = 1–150. The count is derived from the length. Max 1400 bytes (150 entries). |
| Authentication | Vendor AN in the preamble, verified against the coin database like upload. The vendor (den,sn) must be on the server’s hard-coded allowlist. |
| Success response | Status 250, no payload |
| Semantics | Adds each entry’s credit bytes to that mailbox’s balance (accumulates; saturates at 232−1). All-or-nothing: a bad denomination in any entry rejects the whole batch. |
| Distribution | Client sends the same request to every QMail server |
Purpose
Subscribe is how a billing vendor pre-funds a mailbox’s storage. Once a mailbox has credit, its owner can upload attachments with an all-zero locker code and the RAIDA draws down the prepaid balance instead of requiring a funded locker. Each RAIDA keeps its own balance table, so the vendor sends the same Subscribe to every QMail server; the per-server results tell the vendor which servers were funded.
The vendor is the preamble coin. The preamble carries the vendor coin’s denomination, serial number, and this-RAIDA Authenticity Number in the same layout every QMail command uses. The server first checks that (denomination, serial number) is on its compiled-in vendor allowlist, then verifies the AN against the coin database. Only the target mailbox and the credit amount travel in the payload after the preamble.
The credit is a raw byte count — an unsigned 32-bit big-endian integer. Repeated Subscribes to the same mailbox accumulate; the running total saturates at 4 294 967 295 (232−1) rather than overflowing.
Request body
Variable length: the 48-byte QMail preamble (challenge + identity + AN, identical to every other QMail command) followed by an array of 1–150 nine-byte entries and the 2-byte terminator. The server derives the entry count from the body length — it must be a whole number of 9-byte entries. The diagram below shows the preamble and the first entry; entries 2…N repeat the same MDN(1) MSN(4) credit(4) layout back-to-back. “VDN/VSN” = vendor denomination/serial; “MDN/MSN” = target mailbox denomination/serial; T = terminator.
Request body layout (variable length)
+-------------------+---------------------------------+----------------------------------+------------+
| challenge / CRC | vendor identity + auth (preamble)| entries (1..150 x 9 bytes) | terminator |
| 16 bytes | session(8) type(2) VDN(1) VSN(4) | [ MDN(1) MSN(4) credit(4) ] ... | 2 bytes |
| | rsv(1) AN(16) | one 9-byte entry per mailbox | 3E 3E |
+-------------------+---------------------------------+----------------------------------+------------+
| body[0..15] | body[16..47] | body[48 .. 48 + N*9 - 1] | last 2 |
+-------------------+---------------------------------+----------------------------------+------------+
total = 48 + N*9 + 2 bytes (N = 1..150; N = 150 -> 1400 bytes)
| Body offset | Size | Field | Description |
|---|---|---|---|
| 0–11 | 12 | Challenge random | Random bytes generated by the client. |
| 12–15 | 4 | Challenge CRC32 | Big-endian CRC32 of bytes 0–11. |
| 16–23 | 8 | Session ID | Preamble session field; zeros. |
| 24–25 | 2 | Coin Type | Big-endian 0x0006 (CloudCoin). |
| 26 | 1 | Vendor denomination | Vendor coin denomination (signed, −8 to +6). Must be on the allowlist. |
| 27–30 | 4 | Vendor serial number | Vendor coin serial number, big-endian. Must be on the allowlist. |
| 31 | 1 | Reserved | Preamble reserved byte (was device ID); ignored. |
| 32–47 | 16 | Vendor Authenticity Number | Vendor coin AN for this RAIDA. Compared to the stored AN; mismatch → ERROR_INVALID_AN, nothing written. |
| 48 | 1 | Mailbox denomination (entry 1) | Target mailbox denomination (signed, −8 to +6). |
| 49–52 | 4 | Mailbox serial number (entry 1) | Target mailbox serial number, big-endian. The balance is keyed by (mailbox den, mailbox sn). |
| 53–56 | 4 | Credit (entry 1) | Bytes of storage credit to add. Unsigned 32-bit big-endian. |
| 57… | 9 each | Entries 2…N | Zero or more further 9-byte entries, same den(1) sn(4) credit(4) layout, back-to-back. Up to 150 entries total. |
| last 2 | 2 | Terminator | Fixed 3E 3E. |
Response
Success is a status-only response: standard RAIDA response header with status 250 (STATUS_SUCCESS) and no payload. The credit has been added to the target mailbox’s balance on this RAIDA and recorded in the server’s durable purchase log.
Status codes
| Decimal | Hex | Symbol | Meaning |
|---|---|---|---|
| 250 | 0xFA | STATUS_SUCCESS | Credit added to the mailbox balance. |
| 16 | 0x10 | ERROR_INVALID_PACKET_LENGTH | Payload is not a whole number of 9-byte entries, is empty, or exceeds 150 entries. |
| 40 | 0x28 | ERROR_INVALID_SN_OR_DENOMINATION | Vendor or mailbox denomination is out of the −8…+6 range. |
| 172 | 0xAC | ERROR_VENDOR_NOT_AUTHORIZED | Vendor (den,sn) is not on the server’s allowlist. |
| 8 | 0x08 | ERROR_COIN_NOT_FOUND | The vendor coin is not held by this RAIDA. |
| 200 | 0xC8 | ERROR_INVALID_AN | Vendor AN does not match the stored AN. Nothing is written. |
| 194 | 0xC2 | ERROR_FILESYSTEM | Balance database write failed. |
Common mistakes
Confusing the address spelling with the serial number
A QMail address like 20.100@giga is dotted base-256: the serial number is hi×256 + lo (here 20×256+100 = 5220), and the domain names the denomination (giga = 4). The allowlist and the wire fields use the real serial number, not the decimal spelling of the address.
Putting the vendor identity in the payload
The vendor is the preamble coin, just like an upload. The 9-byte payload carries only the target mailbox and the credit — there are no vendor fields after the preamble.
Subscribing to fewer than all QMail servers
Each RAIDA keeps its own balance table. A mailbox funded on only some servers will hit “no credit” on the others when it uploads; send the Subscribe to every QMail server.
Overrunning the batch or the packet budget
At most 150 entries fit in one request (150 × 9 + 48 + 2 = 1400 bytes). The payload must be an exact multiple of 9 bytes; a partial entry is rejected with ERROR_INVALID_PACKET_LENGTH. Split larger vendor runs across multiple requests.