Request Headers

Developer reference for the live RAIDA request envelope and the newer 48-byte authenticated preamble used by modern flows.

Overview 32-byte legacy header 48-byte modern preamble Field reference Encryption types Live command map

Overview

Every RAIDA request begins with the classic 32-byte transport header. Many newer command families then begin the request body with a 48-byte authenticated prefix: a 16-byte challenge followed by a 32-byte identity preamble. Older docs often mixed these two layers together; this page separates them.

What is stable

  • The transport header is still 32 bytes.
  • Multi-byte numeric fields are big-endian.
  • The request header itself is not encrypted.
  • The body may be plaintext or encrypted depending on byte 16.

32-byte legacy request header

This is the fixed outer header sent before every request body.

VR SP RI SH CG CM ID ID PR RS RS RS RS RS RS RS EN DN SN SN SN SN BL BL NO NO NO NO NO NO EC EC
Offset Bytes Name Purpose
0 1 VR Protocol/version bitfield.
1 1 SP Split identifier. Normally zero.
2 1 RI Target RAIDA index (0-24).
3 1 SH Shard identifier. Zero for non-sharded traffic.
4-5 2 CG / CM Command group and command code.
6-7 2 ID Coin type / token family identifier.
8-15 8 PR / RS Presentation and reserved bytes. Keep zero unless a service defines otherwise.
16 1 EN Encryption type selector.
17-21 5 DN + SN Key selector for the encryption context when the chosen mode needs one.
22-23 2 BL Body length. Legacy 16-bit field.
24-29 6 NO Nonce bytes for encrypted modes, or zeros in plaintext flows.
30-31 2 EC Client echo bytes returned in the response header.

48-byte modern authenticated preamble

Newer V2-style services frequently start the body with a 48-byte prefix: a 16-byte challenge plus a 32-byte authenticated identity block. This does not replace the outer 32-byte request header; it is the first structure inside the request body.

CH CH CH CH CH CH CH CH CH CH CH CH CH CH CH CH SI SI SI SI SI SI SI SI CT CT DN SN SN SN SN DV AN AN AN AN AN AN AN AN AN AN AN AN AN AN AN AN
Segment Bytes Meaning
Challenge 16 Random challenge material used for request validation.
Session ID 8 Reserved/session bytes. Often zero-filled.
Coin type 2 Token family identifier.
Identity 6 Denomination, serial number, and device/client discriminator.
AN 16 Authenticity number for the identity being asserted in the body preamble.

Developer field notes

Field Notes for implementers
RAIDA ID Always target a single RAIDA per packet. Clients fan out one packet per server.
Command group / code Treat these as independent bytes, not one packed decimal value.
Denomination / SN These reference the key source for encryption, which may differ from the coin or object named in the body.
Body length The length describes the request body, not the full packet.
Echo bytes Useful for matching request/response pairs without parsing the body.

Encryption types

The active protocol number space includes the following request-header encryption codes.

Code Name Reference use
0 None Plaintext body. Header key-selector bytes are ignored except for general parsing conventions.
1 Shared secret AES-128 using a coin-derived shared secret.
2 Locker key AES-128 using locker-derived key material.
3 Reserved Reserved / unused in the current live public reference set.
4 Assigned Extended modern mode identifier.
5 Assigned Extended modern mode identifier.
7 Assigned Extended modern mode identifier.

Practical guidance

Classic command families documented on this site primarily depend on codes 0, 1, and 2. Code 3 is intentionally left unused in the active reference. Codes 4, 5, and 7 remain part of the live number space and should not be treated as documentation-only typos.

Live command map

Group Live commands
0 Status00 echo, 01 version, 02 show_stats, 03 audit
1 Authentication10 detect, 11 detect_sum, 20 pown, 21 pown_sum
2 Healing40 get_ticket, 50 validate_ticket, 60 find, 61 fix2, 80 fix
6 QMail70 upload2, 71 tell2, 72 ping2, 73 peek2, 74 download2
8 Locker8 download, 80 store, 81 peek_trade_locker, 82 store_sum, 83 peek, 84 remove, 85 put_for_sale, 86 list_lockers_for_sale, 87 buy, 88 store_multiple_sum, 89 remove_trade_locker
9 Change90 make_change, 91 get_available_change_sns, 92 break, 93 join
10 Shard170 switch_shard_sum, 171 pickup_coins, 172 get_sns, 174 switch_shard_sum_with_sns, 175 switch_shard_no_sum_with_sns
11 Crossover110 reserve_locker, 111 check_depository, 112 withdraw_from_depository, 114 get_exchange_rate
12 RPC120 nslookup
13 File134 put_object, 135 get_object, 136 rm_object
14 Integrity10 get_sync_file
15 RKE1 preload_master_key, 2 get_key_share