Ika Sdk

Guide for building with the Ika TypeScript SDK (@ika.xyz/sdk) on Mysten Sui v2. Use when creating dWallets, signing cross-chain transactions, managing encryp...

Security Scan

The skill is an instruction-only guide for using the Ika TypeScript SDK and its declared requirements and instructions are coherent with that purpose.

Purpose & Capability

Name/description, required binary (node), and the SKILL.md all align: this is a developer guide for @ika.xyz/sdk on Sui. Nothing in the files requests unrelated services, binaries, or credentials.

Instruction Scope

SKILL.md provides code examples and end-to-end flows for dWallets, DKG, presign/sign flows and explicitly references Sui RPC usage and local key material in examples. It does not instruct the agent to read arbitrary files, environment variables, or to send data to unexpected endpoints. The instructions deal with private key material (expected for an SDK guide) but do not themselves attempt to exfiltrate or aggregate data.

Install Mechanism

No install spec (instruction-only). The guide instructs users to install @ika.xyz/sdk via pnpm/npm — this is the expected, low-risk approach for an SDK guide. Nothing is downloaded by the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths. The examples show handling secret seeds/keys locally (in-code examples) which is appropriate for an SDK guide. There are no extraneous credential requests.

Persistence & Privilege

always:false and default invocation settings are used. The skill is instruction-only and does not request persistent system presence or global configuration changes.

Assessment

This skill is a documentation-style guide (no code files executed by the skill), and its requirements line up with its stated purpose. However: (1) the examples show handling private keys and seed material — do not paste real private keys or secrets into chat or the skill's prompts; run the code locally in a controlled environment. (2) Because the skill is instruction-only, the scanner had no package source to inspect — before installing @ika.xyz/sdk in your project, verify the package on the official registry/homepage (https://ika.xyz and the npm package), review the actual package source/release, and ensure you install the intended version. (3) Ensure Node >=18 and @mysten/sui dependency versions match your environment. If you need the agent to perform operations that involve real keys, prefer ephemeral/test keys or ensure secrets are stored and handled securely (e.g., environment variables in a controlled CI) rather than pasted into the agent.

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, UserShareEncryptionKeys
• references/flows.md - End-to-end flows: zero-trust dWallet, shared dWallet, imported key, transfer, future signing
• references/types-and-validation.md - Type system, enums, curve/sig/hash validation, state narrowing

Install

pnpm add @ika.xyz/sdk
# or
npm install @ika.xyz/sdk

Requires: @mysten/sui ^2.5.0, Node >=18

Setup

import { getNetworkConfig, IkaClient } from '@ika.xyz/sdk';
import { getJsonRpcFullnodeUrl, SuiJsonRpcClient } from '@mysten/sui/jsonRpc';

const suiClient = new SuiJsonRpcClient({
    url: getJsonRpcFullnodeUrl('testnet'),
    network: 'testnet',
});

const ikaClient = new IkaClient({
    suiClient,
    config: getNetworkConfig('testnet'), // or 'mainnet'
    cache: true,
});
await ikaClient.initialize();

Enums

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

import { UserShareEncryptionKeys, Curve } from '@ika.xyz/sdk';

const keys = await UserShareEncryptionKeys.fromRootSeedKey(
    new TextEncoder().encode('your-seed'),
    Curve.SECP256K1,
);

2. Register Encryption Key

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)

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

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

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

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

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

// 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:

{
    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

import { UserShareEncryptionKeys } from '@ika.xyz/sdk';

// Create from seed (correct curve byte in hash)
const keys = await UserShareEncryptionKeys.fromRootSeedKey(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

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

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

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):

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

// 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';

// Types
import { Curve, SignatureAlgorithm, Hash } from '@ika.xyz/sdk';
import type { DWallet, SharedDWallet, ZeroTrustDWallet, ImportedKeyDWallet } from '@ika.xyz/sdk';
import type { Presign, Sign, EncryptedUserSecretKeyShare } from '@ika.xyz/sdk';
import type { DWalletWithState, PresignWithState, SignWithState } from '@ika.xyz/sdk';

// Validation
import {
    validateHashSignatureCombination, validateCurveSignatureAlgorithm,
    fromCurveToNumber, fromSignatureAlgorithmToNumber, fromHashToNumber,
} from '@ika.xyz/sdk';

// Low-level
import { coordinatorTransactions, systemTransactions } from '@ika.xyz/sdk';