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 Group8 (Locker)
Command Code90 (0x5A)
Server functioncmd_locker_receipt in locker_receipt.c
Body layoutChallenge (16) + locker key (16) + terminator (2) = 34 bytes, the same shape as 83 peek
TransportUDP or TCP; a receipt that does not fit one datagram answers 218
EncryptionAny type, including Type 2 keyed by the locker code itself
AuthenticationNone: knowing the key is the credential
Success responseStatus 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 kindBytes 12–15
plain locker (unchanged)FF FF FF FF
receipted lockerFF 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.

EventTypeRecorded whenCoins carried
store1Each Store, Store Sum or Store Multiple Sum that put coins under the keythe coins stored
peek2Each Peek (answered 241 found or 242 not found)the coins listed
download3Download (241), or a failed attempt on an already-emptied locker (179)the coins moved
remove4Remove (241, 243 or 242)the coins removed
lookup5Each call of this commandnone

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

OffsetSizeFieldDescription
0–1516Challenge12 random bytes followed by their big-endian CRC32, as for every locker command.
16–3116locker_keyThe receipted key. Must end FF FF FF FE.
32–332Terminator3E 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.

OffsetSizeFieldDescription
01version1.
11flags0x01 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–98created_atWhen the receipt was created.
10–178last_event_atTime of the newest stored event.
18–258expires_atlast_event_at + 30 days.
26–5429uploaderActor of the first Store (layout below); all zero under UPLOADER_UNKNOWN.
55–562coin_countEvery coin ever stored under this key.
57–648value_unitsTheir total value in units of 10−8 CC.
65–662event_countEvents that follow.
67–715reservedZero.
72+5 × coin_countcoinsSigned denomination (1) + serial number (4) each.
then56 + 5 × coins eacheventsSee below.

Event entry:

OffsetSizeFieldDescription
+01type1 store, 2 peek, 3 download, 4 remove, 5 lookup.
+11statusThe status the caller was answered with (241, 242, 243, 179 …).
+28atWhen.
+1029actorWho, layout below.
+392coin_countCoins this event carried.
+418value_unitsTheir value, 10−8 CC.
+497reservedZero.
+565 × coin_countcoinsDenomination (1) + serial number (4) each.

Actor (29 bytes):

OffsetSizeFieldDescription
0–1516ipCalling IP as an ASCII dotted quad, NUL padded. Always present.
161encryption_typeEncryption type of the request that caused the event.
171coin_a_denSigned denomination of encryption coin A, or 0 under Type 0 and Type 2 (anonymous).
18–214coin_a_snSerial number of coin A, big-endian, or 0.
221coin_b_denCoin B denomination (Types 5 and 8 only), else 0.
23–264coin_b_snCoin B serial number, big-endian, else 0.
271transport0 = UDP, 1 = TCP.
281header_version1 or 2.

Status codes

CodeSymbolMeaning
241STATUS_ALL_PASSReceipt returned.
179ERROR_LOCKER_EMPTY_OR_NOT_EXISTSNo receipt for this key on this RAIDA: never stored here, or expired.
199ERROR_INVALID_PANThe key does not end FF FF FF FE.
218ERROR_TCP_REQUIREDThe receipt does not fit one UDP datagram. Retry over TCP.
16ERROR_INVALID_PACKET_LENGTHBody 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.