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

Quick Start

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

This page takes a TypeScript app from nothing to a signature on the devnet pre-alpha. The app creates an Ed25519 dWallet, approves one message, has the network sign it, and checks the signature. Then it shows where a Solana program takes over the approval.

You need Node.js 22.12 or later, the packages from Installation, and a devnet keypair with about 0.1 SOL. Get the SOL from https://faucet.solana.com.

1. Create the client

The client needs two connections: one to Solana, to send transactions and read accounts, and one to the ika network, to send requests. The values come from the devnet pre-alpha.

import { DWalletGrpcClient } from '@ika.xyz/pre-alpha-core/web';
import { withMockCryptography } from '@ika.xyz/pre-alpha-core/mock';
import {
	Curve,
	Hash,
	IkaClient,
	IkaTransaction,
	SignatureAlgorithm,
	UserShareEncryptionKeys,
} from '@ika.xyz/pre-alpha-solana/web3';
import { Connection, Keypair, PublicKey, Transaction } from '@solana/web3.js';
import { ed25519 } from '@noble/curves/ed25519.js';

const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
const programId = new PublicKey('8siGnE3tCZbu4LTuX8QoBPErvWeGBF4pRSJDnaGdHyQv');
const networkKey = Uint8Array.from(
	Buffer.from('fe8a6482521cc4bae052c55cd5b3c92d05c8749bcc2c584046de3efb077d65ed', 'hex'),
);

const ikaClient = new IkaClient(
	withMockCryptography({
		connection,
		grpc: new DWalletGrpcClient('https://solana-alpha-dev-1.ika-network.net'),
		config: {
			network: { custom: { networkPublicKeys: [networkKey] } },
			programId,
			chainNumber: 1,
			networkValue: 3,
		},
	}),
);

withMockCryptography puts the client in mock mode, which the pre-alpha needs. Drop it, and name the real network, to move the same app to the real network.

2. Make the user’s keys

Every key of a user comes from one root seed of 32 random bytes. Keep the seed as a secret: a user who loses it loses the shares of their dWallets.

const wallet = Keypair.fromSecretKey(/* your devnet keypair */);
const rootSeed = crypto.getRandomValues(new Uint8Array(32));
const keys = await UserShareEncryptionKeys.fromRootSeedKey(rootSeed, Curve.ED25519);

wallet is the user’s Solana wallet. It pays for transactions and owns the new dWallet. keys holds the user’s encryption key, which the user’s share is encrypted to, and the request key, which signs every request to the network.

3. Register the encryption key and open a gas deposit

Both are Solana transactions the wallet signs, once per root seed. The registration goes in a transaction of its own, because it carries the whole encryption key.

async function send(build: (ikaTx: IkaTransaction) => unknown): Promise<void> {
	const transaction = new Transaction();
	const ikaTx = new IkaTransaction({
		ikaClient,
		transaction,
		owner: wallet.publicKey,
		userShareEncryptionKeys: keys,
	});
	await build(ikaTx);
	transaction.feePayer = wallet.publicKey;
	transaction.recentBlockhash = (await connection.getLatestBlockhash('finalized')).blockhash;
	transaction.sign(wallet, ...ikaTx.signers);
	const signature = await connection.sendRawTransaction(transaction.serialize());
	// The network reads Solana at finalized commitment, so wait for it.
	await connection.confirmTransaction(signature, 'finalized');
}

await send((ikaTx) => ikaTx.registerEncryptionKey({ curve: Curve.ED25519 }));
await send((ikaTx) => ikaTx.createGasDeposit());

Every request is charged to the gas deposit of the key that signs it. The mock charges nothing, so an empty deposit is enough. On the real network, fund it with topUpGasDeposit.

4. Create the dWallet

const { dWallet } = await ikaClient.requestDWalletDKG({
	curve: Curve.ED25519,
	userShareEncryptionKeys: keys,
	owner: wallet.publicKey,
});
await send((ikaTx) => ikaTx.acceptEncryptedUserShare({ dWallet }));
const address = await ikaClient.waitForDWallet(dWallet);

requestDWalletDKG asks the network for a new dWallet and checks the network’s answer. The network writes the DWallet account on Solana and leaves the user’s share waiting there. The user accepts the share in a Solana transaction, and only then can the dWallet sign. waitForDWallet returns the dWallet account’s address once Solana shows the acceptance.

5. Approve a message and sign it

const message = new TextEncoder().encode('hello from the pre-alpha');
const scheme = { signatureAlgorithm: SignatureAlgorithm.EdDSA, hashScheme: Hash.SHA512 };

let signatureVoucher!: PublicKey;
await send(async (ikaTx) => {
	signatureVoucher = await ikaTx.approveMessage({ dWallet, message, ...scheme });
});

const signature = await ikaClient.requestSign({
	dWallet,
	signatureVoucherId: signatureVoucher,
	message,
	...scheme,
	userShareEncryptionKeys: keys,
});

console.log('verifies:', ed25519.verify(signature, message, dWallet.publicKey));

approveMessage adds an instruction that creates a signature voucher: an account that allows one signature of this message, with this dWallet. The voucher lives at a fresh address that signs its own creation, which is why send signs with ikaTx.signers too.

requestSign reads the voucher first, and refuses before sending anything if the voucher is for another dWallet, message or scheme. It takes a presign from the network’s pool, sends the sign request, and checks the signature against the dWallet’s public key. The network also writes the signature into the voucher account.

6. Hand the approval to a program

Above, the user’s wallet owns the dWallet, so the wallet approves messages. To let a program decide instead, transfer the dWallet to the program’s CPI authority. That is the address derived from the seed __ika_cpi_authority under your program’s id. Only your program can sign for it.

const [cpiAuthority] = PublicKey.findProgramAddressSync(
	[Buffer.from('__ika_cpi_authority')],
	yourProgramId,
);
await send((ikaTx) => ikaTx.transferDWallet({ dWallet, newOwner: cpiAuthority }));

Set up your program’s own record of who may use the dWallet before this transfer, while the wallet still owns it. After the transfer, only your program can act on the dWallet.

From then on, your program creates the voucher through a CPI when its conditions hold:

#![allow(unused)]
fn main() {
ctx.issue_signature_voucher(
    coordinator,             // the ika program's DWalletCoordinator account
    signature_voucher,       // a fresh writable address that signs its own creation
    dwallet,                 // the dWallet account
    payer,                   // pays the voucher's rent
    system_program,
    message_digest,          // keccak256 of the message
    message_metadata_digest, // keccak256 of the metadata, or all zeros if there is none
    signature_scheme,        // a DWalletSignatureScheme value, for example 5 for EdDSA with SHA-512
    None,                    // the voucher's owner: None makes it your program's CPI authority
    Some(user_pubkey),       // the request key allowed to send the sign request
    Some(&voucher_seeds),    // the voucher's seeds, when it is your program's PDA
)?;
}

The app then calls requestSign with that voucher’s address, as in step 5.

The ika program checks only that your program owns the dWallet. Which dWallet gets a voucher, and who may ask for one, is your program’s decision. Read Integrator Invariants before you ship, and follow the voting tutorial for a whole program.