LOCKER_RECEIPT — Group 8, Code 90
A locker transfer normally leaves no trace, so a receiver can download the coins and claim the code “did not work”. A receipted locker is an ordinary locker whose key ends FF FF FF FE instead of FF FF FF FF; each RAIDA then records every store, peek, download, remove and receipt lookup on that key, and this command reads the record back.
LIVE FLEET-WIDE since 5 November 2026
The RAIDA side shipped in the fleet build of 5 November 2026. The client side (deriving the FE tail and the core’s receipt endpoint) is pending. Verified against the server source and a live probe of the fleet on 6 November 2026. Note that the design-stage move-locker pages also use Group 8 code 90 for create_move_locker; that number is now taken by this command, and the move-locker proposal must be renumbered before it is built.
Quick reference
| Command Group | 8 (Locker) |
| Command Code | 90 (0x5A) |
| Server function | cmd_locker_receipt in locker_receipt.c |
| Body layout | Challenge (16) + locker key (16) + terminator (2) = 34 bytes, the same shape as 83 peek |
| Transport | UDP or TCP; a receipt that does not fit one datagram answers 218 |
| Encryption | Any type, including Type 2 keyed by the locker code itself |
| Authentication | None: knowing the key is the credential |
| Success response | Status 241 with the receipt body below |
Opting in: the key tail
A locker key is 16 bytes. The client derives it per RAIDA exactly as it does today and overwrites the last four bytes with the tail:
| Locker kind | Bytes 12–15 |
|---|---|
| plain locker (unchanged) | FF FF FF FF |
| receipted locker | FF FF FF FE |
| trade locker (unchanged) | byte 13 = coin type, bytes 14–15 = EE EE |
Nothing else changes. Store (80), Store Sum (82), Store Multiple Sum (88), Peek (83), Remove (84) and Download (8) take a receipted key exactly like a plain one, in any encryption type. The sender and receiver stay as anonymous as they choose to be; the only difference is that the RAIDA writes down what happens to the key.
Not a QMail fee locker
The QMail Tell fee gate derives its locker code with the plain tail, so a receipted locker cannot be used to pay an inbox fee. The fee key is never handed to a counterparty, so it needs no receipt.
What is recorded
Each RAIDA keeps one receipt per key, created by the first Store, with an event log. Each event carries the actor exactly as the request header described it.
| Event | Type | Recorded when | Coins carried |
|---|---|---|---|
| store | 1 | Each Store, Store Sum or Store Multiple Sum that put coins under the key | the coins stored |
| peek | 2 | Each Peek (answered 241 found or 242 not found) | the coins listed |
| download | 3 | Download (241), or a failed attempt on an already-emptied locker (179) | the coins moved |
| remove | 4 | Remove (241, 243 or 242) | the coins removed |
| lookup | 5 | Each call of this command | none |
Rules: a failed attempt is appended only to an existing receipt and never creates one, and a lookup never creates one, so nobody can fill the table with keys that never held coins. A successful download, remove or peek on a key with no receipt (the store predates the feature, or the receipt had expired) re-creates the row flagged UPLOADER_UNKNOWN, so the withdrawal is still captured. At most 100 events are kept per key, the first 100, so a flood of later peeks cannot push the download out; the row is then flagged TRUNCATED. A receipt is kept 30 days after its last stored event and purged lazily once a day.
Request body
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–15 | 16 | Challenge | 12 random bytes followed by their big-endian CRC32, as for every locker command. |
| 16–31 | 16 | locker_key | The receipted key. Must end FF FF FF FE. |
| 32–33 | 2 | Terminator | 3E 3E. |
Type 2 after the locker is empty
Under Type 2 the header’s key locator (bytes 17–21, the first five bytes of the locker key) is looked up first in the live locker index and then, for Group 8 only, in the receipts table. The code therefore still works as the encryption key after the coins are gone, so either party can read the receipt of an emptied locker.
Response body
All integers big-endian; times are Unix seconds. A 72-byte header, then the coins ever stored under the key, then the events oldest first.
| Offset | Size | Field | Description |
|---|---|---|---|
| 0 | 1 | version | 1. |
| 1 | 1 | flags | 0x01 LIVE: the key still holds coins in this node’s index. 0x02 UPLOADER_UNKNOWN: row created by a later event. 0x04 TRUNCATED: event cap reached. |
| 2–9 | 8 | created_at | When the receipt was created. |
| 10–17 | 8 | last_event_at | Time of the newest stored event. |
| 18–25 | 8 | expires_at | last_event_at + 30 days. |
| 26–54 | 29 | uploader | Actor of the first Store (layout below); all zero under UPLOADER_UNKNOWN. |
| 55–56 | 2 | coin_count | Every coin ever stored under this key. |
| 57–64 | 8 | value_units | Their total value in units of 10−8 CC. |
| 65–66 | 2 | event_count | Events that follow. |
| 67–71 | 5 | reserved | Zero. |
| 72+ | 5 × coin_count | coins | Signed denomination (1) + serial number (4) each. |
| then | 56 + 5 × coins each | events | See below. |
Event entry:
| Offset | Size | Field | Description |
|---|---|---|---|
| +0 | 1 | type | 1 store, 2 peek, 3 download, 4 remove, 5 lookup. |
| +1 | 1 | status | The status the caller was answered with (241, 242, 243, 179 …). |
| +2 | 8 | at | When. |
| +10 | 29 | actor | Who, layout below. |
| +39 | 2 | coin_count | Coins this event carried. |
| +41 | 8 | value_units | Their value, 10−8 CC. |
| +49 | 7 | reserved | Zero. |
| +56 | 5 × coin_count | coins | Denomination (1) + serial number (4) each. |
Actor (29 bytes):
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–15 | 16 | ip | Calling IP as an ASCII dotted quad, NUL padded. Always present. |
| 16 | 1 | encryption_type | Encryption type of the request that caused the event. |
| 17 | 1 | coin_a_den | Signed denomination of encryption coin A, or 0 under Type 0 and Type 2 (anonymous). |
| 18–21 | 4 | coin_a_sn | Serial number of coin A, big-endian, or 0. |
| 22 | 1 | coin_b_den | Coin B denomination (Types 5 and 8 only), else 0. |
| 23–26 | 4 | coin_b_sn | Coin B serial number, big-endian, else 0. |
| 27 | 1 | transport | 0 = UDP, 1 = TCP. |
| 28 | 1 | header_version | 1 or 2. |
Status codes
| Code | Symbol | Meaning |
|---|---|---|
| 241 | STATUS_ALL_PASS | Receipt returned. |
| 179 | ERROR_LOCKER_EMPTY_OR_NOT_EXISTS | No receipt for this key on this RAIDA: never stored here, or expired. |
| 199 | ERROR_INVALID_PAN | The key does not end FF FF FF FE. |
| 218 | ERROR_TCP_REQUIRED | The receipt does not fit one UDP datagram. Retry over TCP. |
| 16 | ERROR_INVALID_PACKET_LENGTH | Body is not 34 bytes. |
How a client should use it
Ask all 25 RAIDAs and show the matrix. Each node sees only its own traffic under its own derived key. A download that reached 13 or more nodes gave the receiver the coins even if some nodes show nothing; that partial case is the one legitimate “it didn’t work” story, and the matrix makes it visible. The lookup is itself recorded (type 5), so the sender can also see when the receiver checked. If the sender wants the withdrawal tied to an identity, download with a coin-keyed encryption type (1, 4, 5 or 8); under Type 2 the receipt shows the IP only. The RAIDA does not enforce this.