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

Instruction 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 ika program’s dWallet instructions. The first byte of an instruction’s data is the instruction’s number. The rest is the instruction’s own data, and it must be exactly the length its layout gives. A shorter or longer instruction is refused with InvalidInstructionData.

The SDKs build every instruction a user sends. The CPI crates build the ones a program sends. You need this page to build an instruction yourself, or to read one in a transaction.

Who sends what

Three kinds of signer send dWallet instructions.

  • A user or a program. These are the instructions an integrator sends: vouchers, ownership, deposits, encryption keys and accepts. They are described in full below.
  • The network. The network writes every result to the chain with its own transactions, signed by a network key (NetworkEncryptionKey.noa_public_key). They are listed in Network instructions.
  • The pauser. One key may pause and unpause. See Pauses.
NumberInstructionSent by
129TransferOwnershipthe dWallet’s owner
130CommitNetworkDkgthe network
131CommitNetworkKeyReconfigurationthe network
132CommitDWalletthe network
134CommitEncryptedUserSecretKeySharethe network
135CommitPublicUserSecretKeySharethe network
136CreateDepositanyone, with a proof from the request key
137TopUpanyone
138SettleGasthe network
140CommitSignaturethe network
141RequestWithdrawthe deposit’s owner
143Initializethe program’s upgrade authority, once at deployment
144AdvanceEpochthe network
145SettleGasWithoutDeliverythe network
147Pausethe pauser or the network
148Unpausethe pauser or the network
149SetPauserthe network
150SettleGasChargethe network
151PauseSigningParameterthe pauser or the network
152UnpauseSigningParameterthe pauser or the network
153RegisterEncryptionKeyanyone, with a signature from the holder
156IssueSignatureVoucherthe dWallet’s owner
157SetVoucherSigningKeythe voucher’s owner
158RevokeSignatureVoucherthe voucher’s owner
159TransferSignatureVoucherthe voucher’s owner
161IssueFutureSignatureVoucherthe dWallet’s owner
163CommitPartialUserSignaturethe network
164SetChainIdentifierthe network
165AcceptEncryptedUserShareanyone, with a signature from the holder
166TransferGasDepositthe deposit’s owner
167SettleGasWithdrawalthe network
168SetMinFirstDepositthe network
169SetMinBalancethe network
170SetDepositFeethe network
228EmitEventthe program itself, to emit an event

Numbers 128, 133, 139, 142, 146, 154, 155, 160 and 162 belonged to instructions that were removed. They are refused, and they are never given to another instruction.

Signer mode and program mode

The instructions that an owner sends work in two modes.

  • Signer mode. The owner is a wallet, and it signs the transaction.
  • Program mode. The owner is a program’s CPI authority. The program calls the ika program through a CPI and signs for its CPI authority with invoke_signed.

The ika program tells the two apart by one account: when the account in a fixed slot is an executable program, the instruction is in program mode, and it takes one more account. In program mode the program checks that the CPI authority signed, that it is the address ["__ika_cpi_authority"] derived under the calling program, and that it equals the owner. See The CPI Framework.

Vouchers

IssueSignatureVoucher (156)

Creates a SignatureVoucher: the right to have the network sign one message once, with one dWallet. See Signature Vouchers.

Data, 67 to 131 bytes after the instruction number:

FieldSizeMeaning
message_digest32The Keccak-256 of the message
message_metadata_digest32The Keccak-256 of the message’s metadata, or 32 zeros for none
signature_scheme2The signature scheme number, little-endian
flags1Bit 1: an owner follows. Bit 2: a signing key follows. Any other bit is refused
owner32Only when bit 1 is set. The voucher’s owner. Must not be all zeros
signing_key32Only when bit 2 is set. The key a sign request must be signed by

Without an owner, the voucher’s owner is the issuer. Without a signing key, the voucher has none until its owner sets one.

Accounts in signer mode:

#AccountWritableSignerMeaning
0coordinatornonoThe DWalletCoordinator
1signature_voucheryesyesThe new voucher’s address. It must be empty and owned by the system program
2dwalletnonoThe dWallet
3ownernoyesThe dWallet’s owner
4payeryesyesPays the voucher’s rent
5system_programnonoThe system program

Accounts in program mode:

#AccountWritableSignerMeaning
0coordinatornonoThe DWalletCoordinator
1signature_voucheryesyesThe new voucher’s address
2dwalletnonoThe dWallet
3caller_programnonoThe calling program. Executable
4cpi_authoritynoyesThe calling program’s CPI authority
5payeryesyesPays the voucher’s rent
6system_programnonoThe system program

It is refused when the dWallet is not Active (InvalidDWalletState, 4005), when the coordinator is paused (Paused, 4030), or when the signer is not the dWallet’s owner (MissingRequiredSignature).

IssueFutureSignatureVoucher (161)

Creates a FutureSignatureVoucher. Its data, its accounts and its checks are those of IssueSignatureVoucher. Its signing key is the key step 1 must be signed by. See Future Signature Vouchers.

SetVoucherSigningKey (157), RevokeSignatureVoucher (158), TransferSignatureVoucher (159)

The voucher’s owner changes the voucher. Each acts on a SignatureVoucher or a FutureSignatureVoucher, chosen by the account’s tag. None checks the pause, so an owner can always narrow what a voucher allows.

InstructionDataEffect
SetVoucherSigningKeythe new signing key, 32 bytesSets or replaces the key a request must be signed by
RevokeSignatureVouchernoneRevokes the voucher for good
TransferSignatureVoucherthe new owner, 32 bytes, not all zerosGives the voucher to a new owner, in any state

Accounts in signer mode: signature_voucher (writable), then owner (signer).

Accounts in program mode: signature_voucher (writable), caller_program (executable), then cpi_authority (signer).

A signature voucher takes a new key, or a revoke, only while pending. A future voucher takes them while open or partially signed. Otherwise the instruction fails with VoucherNotPending (4059). A signer that is not the voucher’s owner fails with NotVoucherOwner (4060).

Ownership

TransferOwnership (129)

Gives a dWallet to a new owner. The dWallet must be Active. The pause does not apply.

Data: the new owner, 32 bytes, not all zeros (InvalidAuthority, 4031).

Accounts in signer mode:

#AccountWritableSigner
0ownernoyes
1dwalletyesno

Accounts in program mode:

#AccountWritableSigner
0caller_programnono
1cpi_authoritynoyes
2dwalletyesno

Gas deposits

See Gas Deposits for what a deposit is and what the network charges.

CreateDeposit (136)

Creates the GasDeposit of one request key. The request key proves it agrees with an Ed25519 signature, checked by the Ed25519 precompile in an earlier instruction of the same transaction. The signed message is:

version (u16, 2) || "ika_protocol::gas::proof_of_possession" || chain_number (u32) ||
network (u8) || 32 || the signer's address (32) || incarnation (u64)

The incarnation is the life the instruction opens: 1 for a new deposit, and the closed deposit’s incarnation plus one for a reopen. So the proof of a life that ended does not reopen the deposit.

All integers are little-endian. The chain number and the network are the coordinator’s. The signer is account 0, the wallet that creates the deposit. It becomes the deposit’s owner, the only key that can withdraw. A paused coordinator refuses the instruction (Paused, 4030).

The same instruction reopens a closed deposit, with the same data and accounts. A payout that paid everything closes the deposit and keeps its account. A create on it opens the deposit’s next life: the signer becomes the owner, incarnation goes up by one, and no rent is paid. A deposit that is open, or whose withdrawal is pending, is refused with AccountAlreadyInitialized.

Data, 97 bytes:

FieldSizeMeaning
user_pubkey32The request key
pop_signature64The request key’s signature over the message above
bump1The deposit’s canonical bump

Accounts:

#AccountWritableSigner
0signernoyes
1gas_deposit, ["gas_deposit", user_pubkey]yesno
2coordinatornono
3payeryesyes
4system_programnono
5instructions sysvarnono

After those come the payer’s IKA token account and the treasury vault (both writable), the token program, the event authority, the program, and last the deposit fee recipient (writable). While a fee is set, the recipient must be the coordinator’s (InvalidDepositFeeRecipient, 4083). The fee comes out of sol_amount, and the rest is credited. A sol_amount below the fee is refused (BelowDepositFee, 4082).

createDepositInstructions in @ika.xyz/pre-alpha-solana/instructions builds the precompile instruction and this one, in order.

TopUp (137)

Adds IKA, SOL, or both to a deposit. Anyone may top up any deposit that is not closed (DepositClosed, 4080); a deposit whose withdrawal is pending accepts it. A top-up that moves nothing is refused (EmptyTopUp, 4038). Each coin’s amount must be zero or at least the coordinator’s minimum balance in that coin (BelowMinimumTopUp, 4078).

Data, 16 bytes: ika_amount (u64), then sol_amount (u64).

Accounts:

#AccountWritableSignerMeaning
0gas_deposityesnoThe deposit
1coordinatornonoNames the treasury vault and the IKA mint
2user_token_accountyesnoThe IKA source. payer must be its owner
3treasury_vaultyesnoThe coordinator’s treasury vault
4token_programnonoThe SPL Token program
5payeryesyesPays the SOL and owns the token account
6system_programnonoThe system program
7event_authoritynonoEmits GasDeposited
8programnonoThis program
9fee_recipientyesnoThe coordinator’s deposit fee recipient, paid the deposit fee out of sol_amount, which credits the rest. Any writable account when no fee is set; another while a fee is set is refused (InvalidDepositFeeRecipient, 4083). A sol_amount below the fee is refused (BelowDepositFee, 4082), and one that is only the fee is an empty top-up (EmptyTopUp)

RequestWithdraw (141)

A deposit’s owner asks for the whole deposit back. The request carries no amount. It names the token account the IKA is paid to. The network then pays the withdrawal with its own transaction, SettleGasWithdrawal (167), and the owner sends nothing more. See Gas Deposits for the payout.

The program refuses any signer but the owner, the request key included, with AuthorityMismatch (4004). The owner may be a program’s address that signs through invoke_signed. The IKA destination must be an initialized, unfrozen SPL token account of the IKA mint, or the request is refused with InvalidIkaDestination (4077).

A request is final. There is no cancel, and a second request while one is pending is refused with WithdrawalAlreadyPending (4076). A closed deposit is refused with DepositClosed (4080), and a request for another incarnation than the deposit’s with GasDepositIncarnationMismatch (4081). The payout that pays everything closes the deposit, and the owner reopens it with CreateDeposit. Nothing cancels a pending request: only the network’s payout ends it, and a TransferGasDeposit is refused while it is pending. A pause does not stop a request.

The request sets the deposit’s pending flag and records the IKA destination. It advances the deposit’s withdrawal_sequence and its sequence, and emits GasWithdrawalRequested (128).

Data, 8 bytes: incarnation (u64, little-endian), the deposit’s life the request is for. Any other length is refused with InvalidInstructionData.

Accounts:

#AccountWritableSignerMeaning
0ownernoyesThe deposit’s owner. The payout sends the SOL to it
1gas_deposityesnoThe deposit
2coordinatornonoNames the IKA mint and the epoch
3ika_destinationnonoThe token account the IKA is paid to
4event authority, ["__event_authority"]nonoSigns the event’s self-invocation
5the ika programnonoThe target of that self-invocation

The mock network pays no withdrawal. On the devnet pre-alpha, a request stays pending, and the deposit’s funds stay where they are.

TransferGasDeposit (166)

The deposit’s owner names a new owner. A zero owner is refused with InvalidAuthority, and any other signer with AuthorityMismatch (4004). A pause does not stop it.

A transfer is refused while a withdrawal request is pending, with TransferWhileWithdrawalPending (4079). A request is final: the payout sends the SOL to the owner and the IKA to the token account the request recorded, and only that payout ends the request. The owner can transfer the deposit again once the payout has landed. A transfer leaves the pending flag and withdrawal_sequence unchanged.

A closed deposit is refused with DepositClosed (4080), and a transfer for another incarnation than the deposit’s with GasDepositIncarnationMismatch (4081).

Every transfer advances the deposit’s sequence and emits GasDepositTransferred (126).

Data, 40 bytes: new_owner (32), incarnation (8, little-endian). Accounts, in order: the owner (signer), the deposit (writable), the event authority, the program.

Encryption keys and shares

See Encrypted Shares for the whole flow.

RegisterEncryptionKey (153)

Creates a holder’s EncryptionKey for one curve. Anyone may send it and pay for it. The authority is the holder’s Ed25519 signature over the registration message, in an Ed25519 precompile instruction right before this one. That precompile instruction must hold exactly one signature. The program reads the encryption key from the signed message, never from this instruction’s data. A paused coordinator refuses it (Paused, 4030).

The registration message is the BCS encoding of: the version 1 as a u16, the domain ika_encryption_key as a byte vector, the chain number (u32), the network (u8), the curve (u16), and the encryption key as a byte vector. The chain number and the network are the coordinator’s.

Data, 36 bytes: signer_public_key (32), signature_scheme (1, always 0), curve (u16), bump (1).

Accounts:

#AccountWritableSigner
0holder: the signer key as an addressnono
1encryption_key, ["encryption_key", holder, curve_le]yesno
2coordinatornono
3payeryesyes
4system_programnono
5instructions sysvarnono
6event authority, ["__event_authority"]nono
7the ika programnono

One key exists per holder and curve. A second registration fails with AccountAlreadyInitialized.

AcceptEncryptedUserShare (165)

A holder accepts its encrypted share. Anyone may send it and pay for it. The authority is the holder’s Ed25519 signature over the share’s acceptance_digest, in an Ed25519 precompile instruction right before this one, holding exactly one signature. A paused coordinator refuses it (Paused, 4030). It has no data.

Accounts:

#AccountWritableSigner
0coordinatornono
1dwalletyesno
2encrypted_shareyesno
3instructions sysvarnono
4event authoritynono
5the ika programnono

The checks, in order:

CheckError
The coordinator is not pausedPaused (4030)
The share belongs to the dWalletShareOfAnotherDWallet (4072)
The share is not accepted yetShareAlreadyAccepted (4073)
An Ed25519 precompile instruction comes right beforeInvalidAttestation (4009)
It holds one signature, by the holder, over acceptance_digestInvalidAcceptanceSignature (4074)
A first share: the dWallet waits for its holder or is Active. A re-encrypted share: the dWallet is ActiveInvalidDWalletState (4005)

Network instructions

The network sends these with its own transactions. An integrator never sends them, but sees their effects on chain.

NumberInstructionWhat it writes
130CommitNetworkDkgA new NetworkEncryptionKey, or the network’s signature into an unsigned one
131CommitNetworkKeyReconfigurationA NetworkReconfigurationOutput for one key and epoch
132CommitDWalletA new DWallet and its creation attestation. The owner is the request’s intended_chain_sender
134CommitEncryptedUserSecretKeyShareA holder’s EncryptedUserSecretKeyShare and its attestation
135CommitPublicUserSecretKeyShareA dWallet’s public share attestation. It makes a waiting dWallet Active
138SettleGasCharges a deposit for served requests
140CommitSignatureA signature into a voucher. A pending or revoked SignatureVoucher, or a FutureSignatureVoucher that holds step 1’s result
144AdvanceEpochThe coordinator’s epoch
145SettleGasWithoutDeliveryCharges for a signature the network gave up delivering, and closes its voucher with status 2
149SetPauserThe coordinator’s pauser
150SettleGasChargeA GasCharge record, and the charge
163CommitPartialUserSignatureStep 1’s result into a FutureSignatureVoucher
164SetChainIdentifierA new chain identifier that applies at the next epoch
167SettleGasWithdrawalA deposit’s pending withdrawal: takes the withdrawal’s charge first, then pays what is left, the SOL to the owner and the IKA to the recorded destination. Writes a GasWithdrawalCharge record
168SetMinFirstDepositThe coordinator’s minimum first deposit, in IKA and in SOL. CreateDeposit and every TopUp must leave the deposit’s balance net of debt at or above it
169SetMinBalanceThe coordinator’s minimum balance to start a new action. The network refuses a new request against a deposit below it. Each coin a TopUp adds must be zero or at least it
170SetDepositFeeThe coordinator’s deposit fee in lamports, which every CreateDeposit and TopUp pays out of its sol_amount, and its recipient, the network-owned address that sent it

A network instruction is valid only when it is signed by an active network key’s noa_public_key. On the devnet pre-alpha, the mock holds the one network key and sends these transactions itself.