convert_get_sns — Group 10, Code 178

This command can be used to:

  1. Discover free CCv3 serial numbers to mint with convert_pickup (177).
  2. Verify that a contiguous block of serial numbers starting at an SN the client chooses is still free — this makes it much more likely the same SNs are available on all 25 RAIDAs.
  3. Request up to 1,020 serial numbers per denomination instead of the fixed 64 that the old get_sns (172) returns.
  4. Get first-available / last-available hints for a denomination whose requested range could not be satisfied.

Returned SNs are advisory (not leased) — another client may take them before pickup. The response carries a lease-time byte reserved for a future leasing feature. This command does not mint and does not change 172 (Go / old core clients).

The transaction ID is required even though this command spends nothing: the free-SN scan is the most expensive read in this group, so it is gated behind an open conversion session, and a successful call refreshes that session's 30-day expiry. The server does not check whether the session can afford the requested SNs — the client knows its balance from 176 and is responsible for asking for what it can pay for in 177.

Request Body

The body is encrypted per the standard encryption types. Total body size is a fixed 73 bytes. 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
TD TD TD TD TD TD TD TD TD TD TD TD TD TD TD TD  // Transaction ID: the pickup password — the same secret this
                                                 //   client opened with 176 ON THIS RAIDA (different per RAIDA)
D0 D1 D2 D3 D4 D5 D6                             // Requested SN count per denomination, DIVIDED BY 4
                                                 //   (0 = none, 255 = 1,020 SNs)
S0 S0 S0 S0                                      // Start SN for the 1 CC search (big-endian). 0 = start at the beginning
S1 S1 S1 S1                                      // Start SN for the 10 CC search
S2 S2 S2 S2                                      // Start SN for the 100 CC search
S3 S3 S3 S3                                      // Start SN for the 1,000 CC search
S4 S4 S4 S4                                      // Start SN for the 10,000 CC search
S5 S5 S5 S5                                      // Start SN for the 100,000 CC search
S6 S6 S6 S6                                      // Start SN for the 1,000,000 CC search
FU FU FU FU                                      // Reserved for future use (zeros)
3E 3E                                            // Terminating bytes, not encrypted
IndexDenominationCCv3 DN code
D0 / S01 CC0x00
D1 / S110 CC0x01
D2 / S2100 CC0x02
D3 / S31,000 CC0x03
D4 / S410,000 CC0x04
D5 / S5100,000 CC0x05
D6 / S61,000,000 CC0x06

Each Dn byte is the number of serial numbers wanted for that denomination divided by 4, so SNs can only be requested in multiples of 4: 01 = 4 SNs, 10 (16) = 64 SNs, FF (255) = 1,020 SNs. Each Sn field tells the RAIDA which serial number to start searching from for that denomination; 0 means start from the lowest SN.

Packet Diagram — request (73 bytes)

Challenge (bytes 0-7 of 16) 0 7 Challenge (bytes 8-15 of 16) 8 15 Transaction ID (bytes 0-7 of 16) 16 23 Transaction ID (bytes 8-15 of 16) 24 31 D0-D6: requested SN count ÷ 4, one byte per denomination 32 38 S0: start SN, 1 CC (BE) 39 42 S1: start SN, 10 CC (BE) 43 46 S2: start SN, 100 CC (BE) 47 50 S3: start SN, 1,000 CC (BE) 51 54 S4: start SN, 10,000 CC (BE) 55 58 S5: start SN, 100,000 CC (BE) 59 62 S6: start SN, 1,000,000 CC (BE) 63 66 Reserved for future use 67 70 3E 3E 71 72

Response Body

The response starts with one status byte per denomination, then a lease-time byte, then the serial-number lists. Only denominations with status 1 or 2 contribute SNs, in denomination order (D0 first, D6 last). Every SN is 4 bytes, big-endian.

D0 D1 D2 D3 D4 D5 D6     // Denomination status bytes (see table below)
LT                       // Lease time in seconds. Reserved for a future leasing feature; zero for now

For each denomination with status 1, in order D0..D6:
 SN SN SN SN             // First free SN found (the requested count of SNs follows)
 SN SN SN SN             // ...
 SN SN SN SN             // Last of the requested count for this denomination

For each denomination with status 2, in order D0..D6:
 SN SN SN SN             // First available free SN (hint)
 SN SN SN SN             // Last available free SN (hint)

3E 3E                    // Terminating bytes

Denomination status values

StatusMeaningSNs returned
0All requested SNs are free and contiguous, starting at the start SN the client specified. The client can use start SN through start SN + count − 1 without any list. (Also returned when 0 SNs were requested.)none
1The full requested count of free SNs was found, but they are not contiguous from the start SN. The complete list follows.requested count
2The request could not be satisfied (start SN out of range, or not enough free SNs). The first and last free SNs in this denomination are returned as hints to help the client decide what to ask for next. Both zero means no SNs are free.2

Header Status Codes

With the per-denomination statuses above carrying the detail, the header status is general: 250 means the request was processed — check the denomination status bytes for the actual results.

CodeNameWhen
250SUCCESSRequest processed; see the per-denomination status bytes.
93UNKNOWN_OR_EXPIRED_TXNNo ledger row for this transaction ID, expired row, or all-zero transaction ID.
198INVALID_PARAMETERBad body length.
252INTERNALScan fault.

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