@ika.xyz/sdk — TypeScript SDK for Ika Network

v0.3.0

Overview

TypeScript SDK for interacting with the Ika Network on Sui. Provides everything needed to create and manage dWallets, zero-trust multi-chain signing powered by 2PC-MPC.

• Create and manage dWallets (zero-trust, imported-key, shared variants)
• Sign messages across multiple curves and signature algorithms
• Handle user share encryption, decryption, and re-encryption
• Query on-chain state (dWallets, presigns, encryption keys, protocol parameters)
• Build transaction blocks for all dWallet flows (DKG, presign, sign, future sign)

Install

bun add @ika.xyz/sdk

Peer/runtime requirements:

• Node >= 18

Build (in this repo)

From the repo root:

pnpm install
pnpm sdk build

Or from sdk/typescript:

pnpm install
pnpm run build

Network configuration

Use getNetworkConfig(network) to obtain package/object IDs for testnet or mainnet.

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

const config = getNetworkConfig('testnet');

Creating a client

IkaClient wraps a Sui JSON-RPC client and provides caching, encryption key management, and helpers for fetching network objects and protocol parameters.

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'),
	cache: true,
	encryptionKeyOptions: { autoDetect: true },
});

await ikaClient.initialize();

Client options

| Option | Description | | -------------------------- | ------------------------------------------------------------------- | | config | Network configuration from getNetworkConfig() | | suiClient | A SuiJsonRpcClient (or any ClientWithCoreApi) instance | | cache | Enable caching for network objects (default: false) | | timeout | Polling timeout in ms for state-waiting queries | | encryptionKeyOptions | Encryption key selection: { autoDetect } or { encryptionKeyID } | | protocolPublicParameters | Pre-loaded protocol public parameters to skip fetching |

Querying dWallets

const dWallet = await ikaClient.getDWallet('0x...');
const dWallets = await ikaClient.getMultipleDWallets(['0x...', '0x...']);
const caps = await ikaClient.getOwnedDWalletCaps('0xaddress...');

// Poll until a dWallet reaches a specific state
const ready = await ikaClient.getDWalletInParticularState('0x...', 'Completed');

Querying presigns, signatures, and shares

const presign = await ikaClient.getPresign('0x...');
const sign = await ikaClient.getSign('0x...', Curve.SECP256K1, SignatureAlgorithm.ECDSASecp256k1);
const share = await ikaClient.getEncryptedUserSecretKeyShare('0x...');
const partial = await ikaClient.getPartialUserSignature('0x...');

// All support polling for a specific state
const completedSign = await ikaClient.getSignInParticularState(
	'0x...',
	Curve.SECP256K1,
	SignatureAlgorithm.ECDSASecp256k1,
	'Completed',
);

Encryption keys and protocol parameters

const allKeys = await ikaClient.getAllNetworkEncryptionKeys();
const latestKey = await ikaClient.getLatestNetworkEncryptionKey();
const encKey = await ikaClient.getActiveEncryptionKey('0xaddress...');
const pp = await ikaClient.getProtocolPublicParameters();
const epoch = await ikaClient.getEpoch();

Transactions helper

IkaTransaction wraps a Sui Transaction and adds typed methods for every dWallet flow.

import { IkaClient, IkaTransaction } from '@ika.xyz/sdk';
import { Transaction } from '@mysten/sui/transactions';

const tx = new Transaction();
const ikaTx = new IkaTransaction({ ikaClient, transaction: tx });

DKG (distributed key generation)

// Create a dWallet in a single transaction
const result = await ikaTx.requestDWalletDKG({
	dkgRequestInput,
	sessionIdentifier,
	dwalletNetworkEncryptionKeyId,
	curve: Curve.SECP256K1,
	ikaCoin,
	suiCoin,
});

// Or with a public user share
await ikaTx.requestDWalletDKGWithPublicUserShare({ ... });

Presigning

// Standard presign for a specific dWallet
const presignRef = ikaTx.requestPresign({
	dWallet,
	signatureAlgorithm: SignatureAlgorithm.ECDSASecp256k1,
	ikaCoin,
	suiCoin,
});

// Global presign (not tied to a specific dWallet)
const globalPresignRef = ikaTx.requestGlobalPresign({
	dwalletNetworkEncryptionKeyId,
	curve: Curve.SECP256K1,
	signatureAlgorithm: SignatureAlgorithm.ECDSASecp256k1,
	ikaCoin,
	suiCoin,
});

Signing

// Sign with a zero-trust dWallet
const signRef = await ikaTx.requestSign({
	dWallet,
	messageApproval,
	hashScheme: Hash.KECCAK256,
	verifiedPresignCap,
	presign,
	encryptedUserSecretKeyShare,
	message,
	signatureScheme: SignatureAlgorithm.ECDSASecp256k1,
	ikaCoin,
	suiCoin,
});

// Sign with an imported key dWallet
await ikaTx.requestSignWithImportedKey({ ... });

Future signing

Future signing pre-computes a partial user signature that can be used to sign multiple messages.

const futureSignRef = await ikaTx.requestFutureSign({ ... });
await ikaTx.requestFutureSignWithImportedKey({ ... });

Share management

// Accept an encrypted user share
await ikaTx.acceptEncryptedUserShare({ ... });

// Re-encrypt a share for another user
await ikaTx.requestReEncryptUserShareFor({ ... });

// Register an encryption key
await ikaTx.registerEncryptionKey({ curve: Curve.SECP256K1 });

// Make user secret key shares public
await ikaTx.requestMakeDwalletUserSecretKeySharesPublic({ dWallet, secretShare, ikaCoin, suiCoin });

Imported key verification

await ikaTx.requestImportedKeyDWalletVerification({ ... });

Session identifiers

const sessionId = ikaTx.createSessionIdentifier();

User share encryption keys

UserShareEncryptionKeys manages class-groups encryption/decryption keys and an Ed25519 signing keypair derived from a root seed.

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

// Create from a root seed
const keys = await UserShareEncryptionKeys.fromRootSeedKey(rootSeed, Curve.SECP256K1);

// Serialize / deserialize
const bytes = keys.toShareEncryptionKeysBytes();
const restored = UserShareEncryptionKeys.fromShareEncryptionKeysBytes(bytes);

// Decrypt a user share
const { verifiedPublicOutput, secretShare } = await keys.decryptUserShare(
	dWallet,
	encryptedShare,
	protocolPublicParameters,
);

// Proof-of-ownership signatures
const encKeySig = await keys.getEncryptionKeySignature();
const outputSig = await keys.getUserOutputSignature(dWallet, userPublicOutput);

// Address and public key
const address = keys.getSuiAddress();
const pubkey = keys.getSigningPublicKeyBytes();

Cryptography helpers

Key generation

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

const { encryptionKey, decryptionKey } = await createClassGroupsKeypair(seed, Curve.SECP256K1);

DKG preparation

// Synchronous — supply protocol parameters directly
const dkgInput = await prepareDKG(
	protocolPublicParameters,
	curve,
	encryptionKey,
	bytesToHash,
	senderAddress,
);

// Async — fetches parameters from the client
const dkgInput = await prepareDKGAsync(
	ikaClient,
	curve,
	userShareEncryptionKeys,
	bytesToHash,
	senderAddress,
);

// Lower-level DKG output creation
const { userDKGMessage, userPublicOutput, userSecretKeyShare } = await createDKGUserOutput(
	protocolPublicParameters,
	networkFirstRoundOutput,
);

Signature creation and verification

// Create user sign message
const signMsg = await createUserSignMessageWithPublicOutput(...);
const signMsg = await createUserSignMessageWithCentralizedOutput(...);

// Parse and verify signatures
const signature = await parseSignatureFromSignOutput(curve, signatureAlgorithm, signOutput);
const valid = await verifySecpSignature(...);

Public key derivation

const pubkey = await publicKeyFromDWalletOutput(curve, dWalletOutput);
const pubkey = await publicKeyFromCentralizedDKGOutput(curve, centralizedDkgOutput);

Share encryption

const encrypted = await encryptSecretShare(
	curve,
	secretShare,
	encryptionKey,
	protocolPublicParameters,
);
const valid = await verifyUserShare(curve, secretShare, userDKGOutput, networkDkgPublicOutput);

Session identifiers

import { createRandomSessionIdentifier, sessionIdentifierDigest } from '@ika.xyz/sdk';

const sessionId = createRandomSessionIdentifier();
const digest = sessionIdentifierDigest(bytesToHash, senderAddressBytes);

Supported curves, signature algorithms, and hashes

| Curve | Signature Algorithm | Valid Hashes | | --------- | ------------------- | ------------------------------- | | SECP256K1 | ECDSASecp256k1 | KECCAK256, SHA256, DoubleSHA256 | | SECP256K1 | Taproot | SHA256 | | SECP256R1 | ECDSASecp256r1 | SHA256, DoubleSHA256 | | ED25519 | EdDSA | SHA512 | | RISTRETTO | SchnorrkelSubstrate | Merlin |

The SDK provides compile-time type safety and runtime validation for curve/signature/hash combinations via hash-signature-validation.

import { validateCurveSignatureAlgorithm, validateHashSignatureCombination } from '@ika.xyz/sdk';

DWallet kinds

| Kind | Description | | --------------------- | --------------------------------------------------- | | zero-trust | User holds encrypted secret share; highest security | | imported-key | User imports an existing private key | | imported-key-shared | Imported key with public shares on-chain | | shared | Public secret shares stored on-chain |

Types

Import enums and types from the SDK:

import {
	Curve,
	DWalletKind,
	Hash,
	SignatureAlgorithm,
	type DWallet,
	type EncryptedUserSecretKeyShare,
	type EncryptionKey,
	type EncryptionKeyOptions,
	type IkaClientOptions,
	type IkaConfig,
	type ImportedKeyDWallet,
	type Network,
	type NetworkEncryptionKey,
	type PartialUserSignature,
	type Presign,
	type SharedDWallet,
	type Sign,
	type ZeroTrustDWallet,
} from '@ika.xyz/sdk';

State-narrowing generics are available for polling workflows:

import type { DWalletWithState, PresignWithState, SignWithState } from '@ika.xyz/sdk';

Error classes

import {
	CacheError,
	IkaClientError,
	InvalidObjectError,
	NetworkError,
	ObjectNotFoundError,
} from '@ika.xyz/sdk';

Low-level transaction builders

coordinatorTransactions and systemTransactions expose the raw Move-call builders used internally by IkaTransaction. Import them directly if you need fine-grained control:

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

Generated BCS modules are also exported:

import {
	CoordinatorInnerModule,
	CoordinatorModule,
	SessionsManagerModule,
	SystemModule,
} from '@ika.xyz/sdk';

Testing

Unit and integration tests live under test/. Integration tests require an Ika localnet.

Start a localnet following the Setup Ika Localnet docs:

# Terminal 1 — Sui localnet
RUST_LOG="off,sui_node=info" sui start --with-faucet --force-regenesis --epoch-duration-ms 1000000000000000

# Terminal 2 — Ika localnet
cargo run --bin ika --release --no-default-features -- start

Run SDK tests:

pnpm --filter @ika.xyz/sdk test:unit
pnpm --filter @ika.xyz/sdk test:integration

System tests live under test/system-tests/ and have their own setup; they are not run by the commands above.

License

BSD-3-Clause-Clear © dWallet Labs, Ltd.