Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Account Reference

Pre-alpha. The devnet pre-alpha is a mock network with no MPC. Read the warning in the introduction first.

This page lists the byte layout of every account the ika program keeps for dWallets. Use it to read an account from a client or from your own program. The program also keeps accounts for the network’s own operation. An integrator does not read them, so they are not listed here.

How to read an account

Every account starts with a two-byte header. Byte 0 is the account type’s tag, and byte 1 is the layout version. Every layout is version 1. All integers are little-endian. A key is 32 raw bytes.

Before you trust an account’s bytes, check three things:

  1. The account’s owner is the ika program.
  2. Byte 0 is the tag of the type you expect.
  3. The account’s length is the type’s length. A type marked “header” below has a fixed part and then data of varying length, so check that the account is at least that long.

Every account type has the same owner, the ika program. So the owner check alone does not tell you which type an account is. The tag does.

AccountTagLength in bytesAddress
DWalletCoordinator96727["dwallet_coordinator"]
DWallet97185see The dWallet’s address
NetworkEncryptionKey98199["network_encryption_key", noa_public_key]
GasDeposit99205["gas_deposit", user_pubkey]
EncryptedUserSecretKeyShare101header 214["dwallet", "encrypted_user_share", root, holder]
NetworkReconfigurationOutput102182["network_reconfig", noa_public_key, epoch_le]
DWalletAttestation104header 101see Attestation accounts
GasCharge10691["gas_charge", charge_id]
GasWithdrawalCharge11267["gas_withdrawal_charge", user_pubkey, withdrawal_sequence_le]
EncryptionKey107header 120["encryption_key", signer_public_key, curve_le]
SignatureVoucher108304none: a fresh address the issuer picks
FutureSignatureVoucher1091941none: a fresh address the issuer picks

Every address in the table is a program-derived address (PDA) of the ika program, with the seeds listed. epoch_le is the epoch as eight little-endian bytes. curve_le is the curve as two little-endian bytes. The SDK carries a table of every tag, seed and instruction byte an integrator uses, in sdk/solana/src/wire-tables-data.ts.

The dWallet’s address

A dWallet’s address is derived from its curve and its public key. Take the curve as two little-endian bytes and append the public key. Split that buffer into chunks of 32 bytes, the most one Solana seed may hold. Each chunk is one seed. We call this list of chunks the root.

Public keyBufferChunks
32 bytes (Curve25519, Ristretto)34 bytes32, 2
33 bytes (compressed secp256k1, secp256r1)35 bytes32, 3

A dWallet made by key generation lives at ["dwallet", "record", root...].

An imported dWallet lives at ["dwallet", "imported_record", root..., session_identifier]. The session identifier is the one of the import request that created it, and the dWallet stores it at offset 153. The same key can be imported more than once. Each import makes its own dWallet, so the identifier is part of the address.

Every account that belongs to one dWallet starts its seeds with "dwallet", then a word that names the account’s kind, then the root. The kind comes before the root on purpose. A root has no fixed length, so a word after it could be read as part of a longer root, and two kinds of account could get one address.

DWalletCoordinator (tag 96)

One account for the whole program, at ["dwallet_coordinator"]. It holds the epoch, the pause and this deployment’s fixed values.

OffsetFieldSizeMeaning
2epoch8The network’s epoch on this chain. Only the network moves it, with AdvanceEpoch
10total_dwallets_created8How many dWallets CommitDWallet has created
18paused11 while the program is paused. See Pauses
19bump1This account’s bump
20ika_mint32The IKA token’s mint
52treasury_vault32The token account that holds every deposit’s IKA
84pauser32The key that may pause and unpause. All zeros means no pauser
116chain_identifier_len1The length of the next field
117chain_identifier40This chain’s ERC-7930 chain identifier, padded with zeros
157collected_ika8IKA the network has charged and not yet paid to stakers
165paused_signing_parameters395The curves, algorithms and hashes the network refuses. See below
560pauser_protocol_version8The protocol version that last set pauser
568vault_authority_bump1The bump of ["vault_authority"], which owns treasury_vault
569chain_number4This chain’s fixed number. Signed messages name it
573pending_chain_identifier_len1The length of the next field. Zero when nothing waits
574pending_chain_identifier40A new chain identifier that waits for an epoch
614pending_chain_identifier_effective_epoch8The epoch the waiting identifier applies at
622chain_identifier_protocol_version8The protocol version that last set a waiting identifier
630network11 mainnet, 2 testnet, 3 a local or test network
631min_first_deposit_ika8The minimum first deposit in IKA’s smallest unit. CreateDeposit and every TopUp must leave the balance net of debt at or above it. Zero is no minimum
639min_first_deposit_sol8The same minimum in lamports
647min_first_deposit_protocol_version8The protocol version that last set it. SetMinFirstDeposit refuses one not above it
655min_balance_ika8The minimum balance net of debt to start a new action, in IKA’s smallest unit. The network enforces it on requests. The program checks only that a TopUp’s IKA amount is zero or at least it
663min_balance_sol8The same minimum in lamports
671min_balance_protocol_version8The protocol version that last set it. SetMinBalance refuses one not above it

The paused signing parameters, from offset 165:

OffsetFieldSizeMeaning
165revision8Counts every change to the three lists
173curves_len1How many entries of the next list are in use
174curves128Up to 32 curve numbers, four bytes each
302signature_algorithms_len1As above
303signature_algorithms128Up to 32 signature algorithm numbers
431hash_schemes_len1As above
432hash_schemes128Up to 32 hash scheme numbers

On the devnet pre-alpha the coordinator holds chain number 1 and network 3.

DWallet (tag 97)

OffsetFieldSizeMeaning
2owner32Who controls the dWallet: a wallet, or a program’s CPI authority
34curve20 secp256k1, 1 secp256r1, 2 Curve25519, 3 Ristretto
36state1See the states below
37public_key_len1The length of the public key
38public_key65The dWallet’s public key, padded with zeros
103created_epoch8The epoch the dWallet was created in
111noa_public_key32The network key that holds the network’s share of this dWallet
143is_imported11 for an imported key, 0 for a generated one
144bump1This account’s bump
145_reserved8Zero
153session_identifier32An imported dWallet’s import session. Zero for a generated one

The states:

ValueStateMeaning
0DKGInProgressNot written by the current program
1ActiveUsable: vouchers can be issued and the owner can be changed
2FrozenNot written by the current program
3AwaitingKeyHolderSignatureCreated with an encrypted share that its holder has not accepted yet

A dWallet only moves from 3 to 1. See Encrypted Shares.

NetworkEncryptionKey (tag 98)

The record of one network key. The network’s address on Solana for that key is noa_public_key: every transaction the network sends for the key is signed by it.

OffsetFieldSizeMeaning
2noa_public_key32The key’s Ed25519 public key, and the network’s signing address
34state10 waiting for its key generation, 1 active, 2 waiting for a reconfiguration, 3 active after a reconfiguration
35created_epoch8The epoch the record was created in
43last_reconfig_epoch8The highest epoch with a reconfiguration record. 0 if none
51dkg_output_digest32The Blake2b-256 digest of the key’s network key-generation output
83bump1This account’s bump
84_reserved16Zero
100dkg_output_proof_len1The length of the next field. 0 while the record is unsigned
101dkg_output_proof98The network’s signature over this record

NetworkReconfigurationOutput (tag 102)

One per network key and epoch in which the key was reconfigured.

OffsetFieldSizeMeaning
2noa_public_key32The network key
34epoch8The epoch of the reconfiguration
42reconfig_output_digest32The Blake2b-256 digest of the reconfiguration’s output
74reconfiguration_output_proof_len1The length of the next field. 0 while unsigned
75reconfiguration_output_proof98The network’s signature over this record
173bump1This account’s bump
174_reserved8Zero

GasDeposit (tag 99)

One per request key: the Ed25519 key that signs the user’s gRPC requests. The wallet that creates it owns it (owner). Only the owner requests a withdrawal, which the network then pays; the request key only pays for requests. See Gas Deposits.

OffsetFieldSizeMeaning
2user_pubkey32The request key this deposit pays for
34ika_balance8IKA available for request fees, in IKA’s smallest unit
42sol_balance8Lamports available for the network’s own transactions
50total_ika_deposited8All IKA ever added
58total_ika_consumed8All IKA ever charged
66total_sol_deposited8All lamports ever added
74total_sol_consumed8All lamports ever charged
82withdrawal_sequence8Counts withdrawal requests. Nothing else advances it
90last_settlement_epoch8The epoch of the last charge
98created_epoch8The epoch the deposit was created in
106bump1This account’s bump
107ika_debt8IKA charged beyond the balance. The next charge takes it first
115sol_debt8Lamports charged beyond the balance
123sequence8Counts every change to the account. 1 at creation
131owner32The deposit’s owner: the wallet that signed CreateDeposit, or the owner a TransferGasDeposit named since
163withdrawal_pending11 while a withdrawal request waits for the network’s payout
164ika_destination32The token account the pending request’s IKA is paid to. Zeros when none is pending

A request advances withdrawal_sequence and sequence. The payout, top-ups and charges advance only sequence.

GasCharge (tag 106)

A record the network writes when it charges for work it delivered nothing for. Its address is derived from the charge’s id, so the same charge is written only once.

OffsetFieldSizeMeaning
2charge_id32The charge’s id
34user_pubkey32The deposit charged
66ika_amount8The IKA asked for
74sol_amount8The lamports asked for, this record’s rent included
82epoch8The epoch of the charge
90bump1This account’s bump

GasWithdrawalCharge (tag 112)

The record of one withdrawal’s charge. Its address is derived from the deposit’s request key and the withdrawal counter the request was made at. SettleGasWithdrawal writes it when it takes the withdrawal’s charge and pays the deposit out, or when it charges a request that is no longer pending. Nothing closes it, so a second payout of the same request is refused. A payout short of its charge writes none.

OffsetFieldSizeMeaning
2user_pubkey32The deposit charged
34withdrawal_sequence8The withdrawal counter the request was made at
42ika_amount8The IKA charged
50sol_amount8The lamports charged, this record’s rent included
58epoch8The epoch the payout landed in
66bump1This account’s bump

SignatureVoucher (tag 108)

The right to one signature. See Signature Vouchers.

OffsetFieldSizeMeaning
2dwallet32The dWallet’s address
34message_digest32The Keccak-256 of the message
66message_metadata_digest32The Keccak-256 of the message’s metadata, or zeros for none
98owner32Who controls the voucher
130signature_scheme2The signature scheme number
132has_signing_key11 when signing_key is set
133signing_key32The Ed25519 key a sign request must be signed by
165issued_epoch8The epoch the voucher was issued in
173status10 pending, 1 signed, 2 closed by a charge, 3 revoked
174signature_len2The signature’s length. 0 while none is stored
176signature128The signature, padded with zeros

FutureSignatureVoucher (tag 109)

The right to one signature made in two steps. See Future Signature Vouchers.

OffsetFieldSizeMeaning
2 to 172The same fields as SignatureVoucher, at the same offsets
173status10 open, 1 partially signed, 2 signed, 3 closed by a charge, 4 revoked
174attestation_proof98The network’s signature over step 1’s result
272has_partial_signature11 once step 1 wrote its result
273attestation_len2The length of the next field’s content
275attestation1536Step 1’s result, padded with zeros
1811signature_len2The signature’s length. 0 while none is stored
1813signature128The signature, padded with zeros

EncryptedUserSecretKeyShare (tag 101)

One holder’s encrypted copy of the user’s share of a dWallet. The fixed part is 214 bytes. The encrypted share follows it, encrypted_share_len bytes long. See Encrypted Shares.

OffsetFieldSizeMeaning
2dwallet32The dWallet the share belongs to
34encryption_key_owner32The holder: the Ed25519 key whose registered encryption key encrypts the share
66source_share32The share this one was re-encrypted from. Zero for the first share
98is_re_encrypted11 for a re-encrypted share
99created_epoch8The epoch the share was stored in
107bump1This account’s bump
108accepted11 once the holder accepted the share
109_reserved7Zero
116encrypted_share_len2The length of the encrypted share after offset 214
118acceptance_signature64The holder’s acceptance signature. Zero until accepted
182acceptance_digest32The digest the holder signs to accept
214encrypted sharevariesThe encrypted share and its proof

An imported dWallet’s share lives at ["dwallet", "imported_encrypted_user_share", root..., session_identifier, holder].

EncryptionKey (tag 107)

A holder’s registered encryption key for one curve. The fixed part is 120 bytes. The encryption key follows it, encryption_key_len bytes long.

OffsetFieldSizeMeaning
2signer_public_key32The holder’s Ed25519 key
34signature_scheme10, Ed25519, the only scheme accepted
35curve2The curve the encryption key is for
37encryption_key_len2The length of the key after offset 120
39signature64The holder’s signature over the registration message
103created_epoch8The epoch the key was registered in
111bump1This account’s bump
112_reserved8Zero
120encryption keyvariesThe encryption key

DWalletAttestation (tag 104)

A record of something the network signed about a dWallet. Each has a 101-byte header, then the attested fields.

OffsetFieldSizeMeaning
2bump1This account’s bump
3attestation_proof98The network’s proof: a variant byte (0), the attestation’s version (0), the signing network key (32) and the signature (64)
101fieldsvariesThe attested fields, in order. The session identifier comes first

One account per kind:

KindAddress
The dWallet’s creation["dwallet", "attestation", root...]
An imported dWallet’s creation["dwallet", "imported_attestation", root..., session_identifier]
An encrypted share["dwallet", "encrypted_share_attestation", root..., holder]
The public share["dwallet", "public_user_share", root...]

The imported dWallet’s encrypted share and public share have the same pattern with the words imported_enc_share_attestation and imported_public_user_share, and the session identifier after the root.

The program stores these accounts and never reads them. A client reads them to check what the network signed. To check one, rebuild the attestation’s bytes from the fields, rebuild the message the network signed, and verify the signature under a network key you trust. Response Types describes the attestations and the signed message. The SDKs do this check for you.