convert_pickup — Group 10, Code 177

Mint CCv3 coins by spending the credit built up with convert_authenticate (176). This is the only command in the conversion flow that mints. The client chooses each new coin's serial number (usually found with convert_get_sns (178)) and supplies each new coin's Authenticity Number directly. Mixed denominations are allowed in one request.

Request Body

The body is encrypted per the standard encryption types. Total body size is 34 + 21×M bytes (M = number of coins to mint, M ≥ 1). There is no count field — the server derives M from the body length. Offsets below are from the start of the body.

CH CH CH CH CH CH CH CH CH CH CH CH CH CH CH CH  // Challenge generated by the client
TX TX TX TX TX TX TX TX TX TX TX TX TX TX TX TX  // Transaction ID: the pickup password — the same secret this
                                                 //   client opened with 176 ON THIS RAIDA (different per RAIDA)

Repeated M times (21 bytes per coin):
DN                                               // CCv3 denomination code (0x00 = 1 CC ... 0x06 = 1,000,000 CC)
SN SN SN SN                                      // Serial Number to mint, big-endian
AN AN AN AN AN AN AN AN AN AN AN AN AN AN AN AN  // Authenticity Number, generated by the CLIENT for this coin on this RAIDA

3E 3E                                            // Terminating bytes, not encrypted

Packet Diagram — fixed header (bytes 0–31)

Packet Diagram — coin record (21 bytes, repeats M times, first record starts at byte 32)

Client-supplied Authenticity Numbers

The client generates a random 16-byte AN for each coin on each RAIDA (25 different ANs per coin) and sends them in this request. The client must store these ANs before sending — they are the ownership proof of the new coins. The call is authorized by the transaction ID itself: it is the pickup password opened by 176 on this RAIDA, and the server checks it by hashing it (SHA-256) and looking up the ledger row — the raw transaction ID is never stored on the server. An unknown or expired transaction ID is status 93 and nothing is minted.

Credit check — all or nothing

Before minting anything, the server totals the face value of the requested coins. If that total exceeds the credit available to this transaction ID, the whole command fails with status 92: nothing is minted, the credits remain untouched, and the client can make another (smaller) request.

Coins that will cost nothing this call are excluded from that total: a target that already exists with exactly the AN this client supplied, and a target this transaction ID already paid for according to the ledger. This is what makes retries idempotent — re-sending a list whose first (lost-response) attempt already spent the credits returns bit=1 for every coin instead of a false 92.

Response Body

MN MN                    // MINTED_NOTES: a COUNT of notes, not a value. How many of the requested
                         //   notes now exist with the ANs this client supplied (big-endian)
VM VM VM VM VM VM VM VM  // VALUE_MINTED: microunits of credit debited and minted by this call (big-endian)
RB RB RB RB RB RB RB RB  // RAIDA_BALANCE: credit in microunits that this transaction ID still
                         //   holds on this RAIDA after this call (big-endian)
NB ...                   // NOTE_BITMAP: ceil(M/8) bytes, one bit per requested note;
                         //   bit i = 1 means note i was minted (or already ours)
3E 3E                    // Terminating bytes

Field	Bytes	Notes
MINTED_NOTES	2 BE	A count, not a value — values are in VALUE_MINTED and RAIDA_BALANCE. Always equals the number of 1-bits in NOTE_BITMAP (newly minted + already-ours retries).
VALUE_MINTED	8 BE	Microunits of credit debited and minted by this call (1 CC = 100,000,000 microunits). 0 on a pure retry.
RAIDA_BALANCE	8 BE	The credit balance, in microunits, that this transaction ID still holds on this RAIDA after this call.
NOTE_BITMAP	ceil(M/8)	One bit per requested note, in request order: bit i = 1 means note i now exists with the AN this client supplied. Within each byte the least-significant bit is the lowest-numbered note.

A target SN that is already occupied by someone else's coin gets bit 0 and costs nothing; use 178 to find replacement SNs and retry those coins. A target that already holds a coin with exactly the AN this client supplied (a retry of an earlier 177) gets bit 1 and is not debited again.

Header Status Codes

Code	Name	When
250	SUCCESS	Every requested coin was minted or was already ours.
243	MIXED	Some target SNs were occupied. Get replacements from 178 for the zero bits.
242	ALL_FAIL	No coins minted.
92	INSUFFICIENT_DUE	Requested total exceeds available credit. Nothing minted, credits unchanged — retry with a smaller request.
93	UNKNOWN_OR_EXPIRED_TXN	No ledger row for this transaction ID, expired row, or all-zero transaction ID.
198	INVALID_PARAMETER	Bad denomination or body length.
252	INTERNAL	Mint or ledger fault.

Every successful 176/177/178 call refreshes the ledger row's expiry to now + 30 days.