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

The CPI Framework

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

A Solana program controls a dWallet by being its owner. It then calls the ika program through a cross-program invocation (CPI) to issue vouchers and to move the dWallet. Three crates build these calls, one for each common way to write a program:

CrateFrameworkAccount type it takes
ika-dwallet-pinocchioPinocchio&AccountView
ika-dwallet-nativesolana-program&AccountInfo<'info>
ika-dwallet-anchorAnchorAccountInfo<'info>

The three send the same instruction bytes and the same accounts. Only the account types differ. The pages for each framework show the dependencies and a full example: Pinocchio, Native, Anchor.

The CPI authority

The ika program cannot see which program called it. It sees only which accounts signed. So each program has one address that it alone can sign for: its CPI authority. It is the PDA of the seed __ika_cpi_authority under the program’s id.

#![allow(unused)]
fn main() {
use ika_dwallet_pinocchio::CPI_AUTHORITY_SEED; // b"__ika_cpi_authority"

let (cpi_authority, bump) =
    pinocchio::Address::find_program_address(&[CPI_AUTHORITY_SEED], program_id);
}

A dWallet whose owner is this address belongs to the program. When the program calls the ika program, it signs for its CPI authority with invoke_signed. The ika program then checks three things:

  1. The calling program’s account is executable.
  2. The CPI authority is the PDA of __ika_cpi_authority under that program, and it signed.
  3. The CPI authority equals the dWallet’s owner. For a voucher control, it must equal the voucher’s owner instead.

That is all the ika program checks. Your program has one CPI authority for every dWallet it holds. So the ika program cannot tell which of your users, proposals or vaults a call is for. Your program must make that check itself. See Integrator Invariants.

DWalletContext

Each crate provides a DWalletContext. It holds the four values every call needs:

#![allow(unused)]
fn main() {
use ika_dwallet_pinocchio::DWalletContext;

let ctx = DWalletContext {
    dwallet_program,       // the ika program's account
    cpi_authority,         // your program's CPI authority account
    caller_program,        // your program's own account. It must be executable
    cpi_authority_bump,    // the CPI authority's bump
};
}

Pass a bump that is wrong and the signature for the CPI authority fails, so the call fails.

The context calls only the real ika program

Each crate exports ID, the address of the ika program on the network the crate was built for. Every call of DWalletContext first compares dwallet_program with ID. Any other account is refused with ProgramError::IncorrectProgramId, and nothing is called.

The check exists because of how Solana passes signatures on. Every call the context makes is signed by your program’s CPI authority. A program that receives a signed account can pass that signature on in the calls it makes in turn. So suppose a caller passes a program of its own as dwallet_program, and the context called it. That fake program would receive your CPI authority’s signature. It could then call the real ika program with it, and issue a voucher for any dWallet your program holds, or give one away. Refusing every program but ID means your CPI authority’s signature only ever reaches the real ika program.

ID comes from a network feature of the crate: devnet-pre-alpha for the devnet pre-alpha, and none for the test suites, which load the ika program at a fixed development address. Build your program with the feature of the network you deploy it to. A program built for one network calls only that network’s ika program, so it refuses the dWallets of every other. See Pinocchio for the build lines.

The calls

MethodInstructionWhat it does
issue_signature_voucher156Creates a voucher for one signature
issue_future_signature_voucher161Creates a voucher for one future sign
set_voucher_signing_key157Sets the key a sign request must be signed by
revoke_signature_voucher158Revokes a voucher
transfer_signature_voucher159Gives a voucher to a new owner
transfer_dwallet129Gives the dWallet to a new owner

The three voucher controls act on either kind of voucher.

issue_signature_voucher

#![allow(unused)]
fn main() {
ctx.issue_signature_voucher(
    coordinator,              // the DWalletCoordinator, read only
    signature_voucher,        // the new voucher's address: writable, empty, a signer
    dwallet,                  // the dWallet, read only
    payer,                    // writable signer, pays the voucher's rent
    system_program,
    message_digest,           // [u8; 32]: the Keccak-256 of the message
    message_metadata_digest,  // [u8; 32]: zeros for no metadata
    signature_scheme,         // u16: the scheme number
    owner,                    // Option<[u8; 32]>: None makes your CPI authority the owner
    signing_key,              // Option<[u8; 32]>: the key a sign request must be signed by
    voucher_seeds,            // Option<&[Seed]>: the voucher PDA's seeds, bump included
)?;
}

The voucher’s address must sign its own creation. There are two ways:

  • Pass your program’s PDA as the voucher, and its seeds as voucher_seeds. The helper signs for it with invoke_signed.
  • Pass None for voucher_seeds. The outer transaction must then carry the signature of a new keypair at the voucher’s address.

Prefer a PDA derived from your own record. A voucher at a keypair’s address can be put anywhere the transaction’s sender likes, so your program cannot know where it went.

The accounts the CPI sends:

#AccountWritableSigner
0coordinatornono
1signature_voucheryesyes
2dwalletnono
3caller_programnono
4cpi_authoritynoyes
5payeryesyes
6system_programnono

Your instruction must receive all of these accounts, and the ika program’s account too, so it can pass them on.

issue_future_signature_voucher

The same arguments and accounts as issue_signature_voucher. The signing key is the key step 1 must be signed by. See Future Signature Vouchers.

The voucher controls

#![allow(unused)]
fn main() {
ctx.set_voucher_signing_key(signature_voucher, new_signing_key)?;  // [u8; 32]
ctx.revoke_signature_voucher(signature_voucher)?;
ctx.transfer_signature_voucher(signature_voucher, new_owner)?;    // [u8; 32]
}

Each sends three accounts: the voucher (writable), the calling program, and the CPI authority (signer). The voucher’s owner must be your CPI authority.

transfer_dwallet

#![allow(unused)]
fn main() {
ctx.transfer_dwallet(dwallet, new_owner)?;
}

It sends three accounts: the calling program, the CPI authority (signer), and the dWallet (writable). The dWallet must be Active. In ika-dwallet-pinocchio the new owner is a [u8; 32]. In the native and Anchor crates it is a &Pubkey.

When a call fails

A failed CPI fails the whole transaction, with the ika program’s error code. The codes a program meets most:

CodeCause
IncorrectProgramIddwallet_program is not the ika program the crate was built for. Refused before any call
4005The dWallet is not Active
4030The coordinator is paused
MissingRequiredSignatureThe CPI authority is not the dWallet’s or the voucher’s owner
AccountAlreadyInitializedThe voucher address already holds an account
4059The voucher is not pending any more

All codes are in the Error Reference.