Ika TypeScript SDK
Build cross-chain signing applications with @ika.xyz/sdk on Sui.
References (detailed patterns and complete API)
references/api-reference.md - Complete API: IkaClient methods, IkaTransaction methods, cryptography functions, UserShareEncryptionKeysreferences/flows.md - End-to-end flows: zero-trust dWallet, shared dWallet, imported key, transfer, future signingreferences/types-and-validation.md - Type system, enums, curve/sig/hash validation, state narrowing
Install
bash
pnpm add @ika.xyz/sdk
# or
npm install @ika.xyz/sdk
Requires: @mysten/sui ^2.5.0, Node >=18
Setup
typescript
import { getNetworkConfig, IkaClient } from '@ika.xyz/sdk';
import { SuiGrpcClient } from '@mysten/sui/grpc';
// Public Sui fullnodes serve gRPC only.
const suiClient = new SuiGrpcClient({
baseUrl: 'https://fullnode.testnet.sui.io:443',
network: 'testnet',
});
const ikaClient = new IkaClient({
suiClient,
config: getNetworkConfig('testnet'), // or 'mainnet'
cache: true,
});
await ikaClient.initialize();
Enums
typescript
import { Curve, SignatureAlgorithm, Hash } from '@ika.xyz/sdk';
// Curves
Curve.SECP256K1 // Bitcoin, Ethereum
Curve.SECP256R1 // WebAuthn, P-256
Curve.ED25519 // Solana, Substrate
Curve.RISTRETTO // Privacy
// Signature Algorithms
SignatureAlgorithm.ECDSASecp256k1 // SECP256K1
SignatureAlgorithm.Taproot // SECP256K1
SignatureAlgorithm.ECDSASecp256r1 // SECP256R1
SignatureAlgorithm.EdDSA // ED25519
SignatureAlgorithm.SchnorrkelSubstrate // RISTRETTO
// Hashes
Hash.KECCAK256 // ECDSASecp256k1
Hash.SHA256 // ECDSASecp256k1, Taproot, ECDSASecp256r1
Hash.DoubleSHA256 // ECDSASecp256k1
Hash.SHA512 // EdDSA
Hash.Merlin // SchnorrkelSubstrate
Valid Combinations Quick Reference
| Chain | Curve | SignatureAlgorithm | Hash | |
|---|
| Ethereum | SECP256K1 | ECDSASecp256k1 | KECCAK256 | |
| Bitcoin Taproot | SECP256K1 | Taproot | SHA256 | |
| Bitcoin Legacy | SECP256K1 | ECDSASecp256k1 | DoubleSHA256 | |
| Solana | ED25519 | EdDSA | SHA512 | |
| WebAuthn | SECP256R1 | ECDSASecp256r1 | SHA256 | |
| Substrate | RISTRETTO | SchnorrkelSubstrate | Merlin | |
dWallet Types
| Kind | Description | Use Case | |
|---|
zero-trust | Encrypted user share, user must participate in signing | Personal wallets, max security | |
shared | Public user share, network signs autonomously | DAOs, contracts, automation | |
imported-key | Existing private key imported (encrypted share) | Migrating existing wallets | |
imported-key-shared | Imported key with public share | Migrated wallets for contracts | |
Core Flow: Shared dWallet (Most Common)
1. Create Encryption Keys
typescript
import { UserShareEncryptionKeys, Curve } from '@ika.xyz/sdk';
const keys = await UserShareEncryptionKeys.fromRootSeedKeyV2(
new TextEncoder().encode('your-seed'),
Curve.SECP256K1,
);
2. Register Encryption Key
typescript
import { IkaTransaction } from '@ika.xyz/sdk';
import { Transaction } from '@mysten/sui/transactions';
const tx = new Transaction();
const ikaTx = new IkaTransaction({ ikaClient, transaction: tx, userShareEncryptionKeys: keys });
await ikaTx.registerEncryptionKey({ curve: Curve.SECP256K1 });
await suiClient.core.signAndExecuteTransaction({ transaction: tx, signer: keypair });
3. DKG (Create dWallet)
typescript
import { prepareDKGAsync, createRandomSessionIdentifier } from '@ika.xyz/sdk';
const sessionIdBytes = createRandomSessionIdentifier();
const dkgData = await prepareDKGAsync(ikaClient, Curve.SECP256K1, keys, sessionIdBytes, senderAddress);
const networkKey = await ikaClient.getLatestNetworkEncryptionKey();
const tx = new Transaction();
const ikaTx = new IkaTransaction({ ikaClient, transaction: tx, userShareEncryptionKeys: keys });
const sessionId = ikaTx.registerSessionIdentifier(sessionIdBytes);
const [dwalletCap, signId] = await ikaTx.requestDWalletDKG({
dkgRequestInput: dkgData,
ikaCoin: tx.splitCoins(tx.object(ikaCoinId), [1_000_000]),
suiCoin: tx.splitCoins(tx.gas, [1_000_000]),
sessionIdentifier: sessionId,
dwalletNetworkEncryptionKeyId: networkKey.id,
curve: Curve.SECP256K1,
});
const result = await suiClient.core.signAndExecuteTransaction({ transaction: tx, signer: keypair });
4. Get dWallet & Public Key
typescript
import { publicKeyFromDWalletOutput } from '@ika.xyz/sdk';
const dWallet = await ikaClient.getDWalletInParticularState(dwalletId, 'Active');
const publicKey = await publicKeyFromDWalletOutput(Curve.SECP256K1, Uint8Array.from(dWallet.state.Active.public_output));
5. Request Presign
typescript
const tx = new Transaction();
const ikaTx = new IkaTransaction({ ikaClient, transaction: tx });
ikaTx.requestGlobalPresign({
dwalletNetworkEncryptionKeyId: networkKey.id,
curve: Curve.SECP256K1,
signatureAlgorithm: SignatureAlgorithm.Taproot,
ikaCoin: tx.splitCoins(tx.object(ikaCoinId), [1_000_000]),
suiCoin: tx.splitCoins(tx.gas, [1_000_000]),
});
6. Sign Message
typescript
import { createUserSignMessageWithPublicOutput } from '@ika.xyz/sdk';
// Wait for presign completion
const presign = await ikaClient.getPresignInParticularState(presignId, 'Completed');
const pp = await ikaClient.getProtocolPublicParameters(dWallet);
// Create user signature
const msgSig = await createUserSignMessageWithPublicOutput(
pp, Uint8Array.from(dWallet.state.Active.public_output),
Uint8Array.from(dWallet.public_user_secret_key_share),
Uint8Array.from(presign.state.Completed.presign),
message, Hash.SHA256, SignatureAlgorithm.Taproot, Curve.SECP256K1,
);
// Build & execute sign transaction
const tx = new Transaction();
const ikaTx = new IkaTransaction({ ikaClient, transaction: tx, userShareEncryptionKeys: keys });
const signRef = await ikaTx.requestSign({
dWallet, messageApproval: ikaTx.approveMessage({
dWalletCap, curve: Curve.SECP256K1,
signatureAlgorithm: SignatureAlgorithm.Taproot,
hashScheme: Hash.SHA256, message,
}),
hashScheme: Hash.SHA256,
verifiedPresignCap: ikaTx.verifyPresignCap({ presign }),
presign, message,
signatureScheme: SignatureAlgorithm.Taproot,
ikaCoin: tx.splitCoins(tx.object(ikaCoinId), [1_000_000]),
suiCoin: tx.splitCoins(tx.gas, [1_000_000]),
});
7. Retrieve Signature
typescript
import { parseSignatureFromSignOutput } from '@ika.xyz/sdk';
const sign = await ikaClient.getSignInParticularState(
signId, Curve.SECP256K1, SignatureAlgorithm.Taproot, 'Completed',
);
// sign.state.Completed.signature is already parsed
IkaClient Key Methods
typescript
// Initialization
await ikaClient.initialize();
// Query dWallets
const dWallet = await ikaClient.getDWallet(id);
const dWallet = await ikaClient.getDWalletInParticularState(id, 'Active', { timeout: 60000 });
const dWallets = await ikaClient.getMultipleDWallets([id1, id2]);
const caps = await ikaClient.getOwnedDWalletCaps(address);
// Query presigns, signs, partial sigs (all support InParticularState polling)
const presign = await ikaClient.getPresign(id);
const presign = await ikaClient.getPresignInParticularState(id, 'Completed');
const sign = await ikaClient.getSign(id, Curve.SECP256K1, SignatureAlgorithm.Taproot);
const sign = await ikaClient.getSignInParticularState(id, curve, sigAlgo, 'Completed');
// Encryption keys
const key = await ikaClient.getLatestNetworkEncryptionKey();
const keys = await ikaClient.getAllNetworkEncryptionKeys();
// Protocol parameters
const pp = await ikaClient.getProtocolPublicParameters(dWallet);
// Cache management
ikaClient.invalidateCache();
ikaClient.invalidateObjectCache();
ikaClient.invalidateEncryptionKeyCache();
Polling Options
All *InParticularState methods accept:
typescript
{
timeout?: number, // default: 30000ms
interval?: number, // default: 1000ms (initial)
maxInterval?: number, // default: 5000ms (with backoff)
backoffMultiplier?: number, // default: 1.5
signal?: AbortSignal, // for cancellation
}
UserShareEncryptionKeys
typescript
import { UserShareEncryptionKeys } from '@ika.xyz/sdk';
// New keys: current curve-byte hash and the new platform-independent sampler
const keys = await UserShareEncryptionKeys.fromRootSeedKeyV2(seed, curve);
// Legacy: for keys registered before the curve-byte fix (non-SECP256K1 only)
const legacyKeys = await UserShareEncryptionKeys.fromRootSeedKeyLegacyHash(seed, curve);
// Serialize/deserialize for storage (preserves legacy/fixed distinction)
const bytes = keys.toShareEncryptionKeysBytes();
const restored = UserShareEncryptionKeys.fromShareEncryptionKeysBytes(bytes);
// Properties
keys.getSuiAddress(); // Sui address for registration
keys.getSigningPublicKeyBytes(); // Ed25519 public key bytes
keys.encryptionKey; // Class-groups public key
keys.decryptionKey; // Class-groups private key
keys.curve; // Curve used
keys.legacyHash; // true if legacy hash derivation
// Operations
await keys.getEncryptionKeySignature(); // Proof of ownership
await keys.getUserOutputSignature(dWallet, userPublicOutput); // Authorize dWallet
await keys.decryptUserShare(dWallet, encShare, pp); // Decrypt secret share
Existing keys: fromRootSeedKey is deprecated and always uses historical WASM32 sampling in browsers and Node.js. Use it only to recover existing keys; use fromRootSeedKeyV2 for all new registrations. Rotate existing keys by deriving new keys from a fresh seed, registering them, and re-encrypting and accepting each user share under the new keys. Restore serialized bundles directly when available.
Legacy Hash: The legacy hash had a bug where the curve byte was always 0 regardless of curve (only affects non-SECP256K1 curves). If you registered encryption keys before the fix with a non-SECP256K1 curve, use fromRootSeedKeyLegacyHash to reproduce the legacy keys.
Network Config
typescript
import { getNetworkConfig } from '@ika.xyz/sdk';
const config = getNetworkConfig('testnet'); // or 'mainnet'
// config.packages.ikaPackage
// config.packages.ikaDwallet2pcMpcPackage
// config.objects.ikaDWalletCoordinator.objectID
// config.objects.ikaSystemObject.objectID
Error Classes
typescript
import {
IkaClientError, // Base error
ObjectNotFoundError, // Object not found on chain
InvalidObjectError, // Object parsing failed
NetworkError, // Network operation failure
CacheError, // Caching operation failure
} from '@ika.xyz/sdk';
Low-Level Transaction Builders
For direct Move call construction (bypassing IkaTransaction):
typescript
import { coordinatorTransactions } from '@ika.xyz/sdk';
// All functions follow: (ikaConfig, coordinatorObjectRef, ...params, tx)
coordinatorTransactions.registerSessionIdentifier(config, coordRef, sessionBytes, tx);
coordinatorTransactions.requestDWalletDKGWithPublicUserSecretKeyShare(config, coordRef, ...params, tx);
coordinatorTransactions.requestGlobalPresign(config, coordRef, ...params, tx);
coordinatorTransactions.requestSignAndReturnId(config, coordRef, ...params, tx);
coordinatorTransactions.approveMessage(config, coordRef, ...params, tx);
// ... etc (50+ functions)
Key Imports Summary
typescript
// Core
import { IkaClient, IkaTransaction, getNetworkConfig } from '@ika.xyz/sdk';
// Keys
import { UserShareEncryptionKeys } from '@ika.xyz/sdk';
// Cryptography
import {
prepareDKGAsync, createRandomSessionIdentifier,
createUserSignMessageWithPublicOutput, publicKeyFromDWalletOutput,
parseSignatureFromSignOutput, prepareImportedKeyDWalletVerification,
} from '@ika.xyz/sdk';