Ika TypeScript SDK

在 Sui 上使用 @ika.xyz/sdk 构建跨链签名应用。

参考文档（详细模式与完整 API）

• references/api-reference.md — 完整 API：IkaClient 方法、IkaTransaction 方法、密码学函数、UserShareEncryptionKeys
• references/flows.md — 端到端流程：零信任 dWallet、共享 dWallet、导入密钥、转账、未来签名
• references/types-and-validation.md — 类型系统、枚举、曲线/签名/哈希校验、状态收窄

安装

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

依赖要求：@mysten/sui ^2.5.0，Node >=18

初始化配置

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'), // 或 'mainnet'
    cache: true,
});
await ikaClient.initialize();

枚举类型

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

// 曲线类型
Curve.SECP256K1   // Bitcoin、Ethereum
Curve.SECP256R1   // WebAuthn、P-256
Curve.ED25519     // Solana、Substrate
Curve.RISTRETTO   // 隐私场景

// 签名算法
SignatureAlgorithm.ECDSASecp256k1      // SECP256K1
SignatureAlgorithm.Taproot             // SECP256K1
SignatureAlgorithm.ECDSASecp256r1      // SECP256R1
SignatureAlgorithm.EdDSA               // ED25519
SignatureAlgorithm.SchnorrkelSubstrate // RISTRETTO

// 哈希算法
Hash.KECCAK256     // ECDSASecp256k1
Hash.SHA256        // ECDSASecp256k1、Taproot、ECDSASecp256r1
Hash.DoubleSHA256  // ECDSASecp256k1
Hash.SHA512        // EdDSA
Hash.Merlin        // SchnorrkelSubstrate

有效组合速查表

dWallet 类型

核心流程：共享 dWallet（最常用）

1. 创建加密密钥

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

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

2. 注册加密密钥

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（创建 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. 获取 dWallet 及公钥

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. 请求预签名（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. 签名消息

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

// 等待预签名完成
const presign = await ikaClient.getPresignInParticularState(presignId, 'Completed');
const pp = await ikaClient.getProtocolPublicParameters(dWallet);

// 创建用户签名
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,
);

// 构建并执行签名交易
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. 获取签名结果

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

const sign = await ikaClient.getSignInParticularState(
    signId, Curve.SECP256K1, SignatureAlgorithm.Taproot, 'Completed',
);
// sign.state.Completed.signature 已自动解析

IkaClient 核心方法

// 初始化
await ikaClient.initialize();

// 查询 dWallet
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);

// 查询预签名、签名、部分签名（均支持 InParticularState 轮询）
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');

// 加密密钥
const key = await ikaClient.getLatestNetworkEncryptionKey();
const keys = await ikaClient.getAllNetworkEncryptionKeys();

// 协议参数
const pp = await ikaClient.getProtocolPublicParameters(dWallet);

// 缓存管理
ikaClient.invalidateCache();
ikaClient.invalidateObjectCache();
ikaClient.invalidateEncryptionKeyCache();

轮询选项

所有 *InParticularState 方法均接受以下参数：

{
    timeout?: number,          // 默认：30000ms
    interval?: number,         // 默认：1000ms（初始间隔）
    maxInterval?: number,      // 默认：5000ms（带退避策略）
    backoffMultiplier?: number, // 默认：1.5
    signal?: AbortSignal,      // 用于取消请求
}

UserShareEncryptionKeys

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

// 从种子派生（哈希中含正确曲线字节）
const keys = await UserShareEncryptionKeys.fromRootSeedKey(seed, curve);

// 兼容旧版：适用于曲线字节修复前注册的密钥（仅非 SECP256K1 曲线）
const legacyKeys = await UserShareEncryptionKeys.fromRootSeedKeyLegacyHash(seed, curve);

// 序列化/反序列化存储（保留旧版/新版区分）
const bytes = keys.toShareEncryptionKeysBytes();
const restored = UserShareEncryptionKeys.fromShareEncryptionKeysBytes(bytes);

// 属性
keys.getSuiAddress();            // 用于注册的 Sui 地址
keys.getSigningPublicKeyBytes(); // Ed25519 公钥字节
keys.encryptionKey;              // Class-groups 公钥
keys.decryptionKey;              // Class-groups 私钥
keys.curve;                      // 使用的曲线
keys.legacyHash;                 // 若为旧版哈希推导则为 true

// 操作方法
await keys.getEncryptionKeySignature();     // 所有权证明
await keys.getUserOutputSignature(dWallet, userPublicOutput); // 授权 dWallet
await keys.decryptUserShare(dWallet, encShare, pp); // 解密用户秘密份额

旧版哈希说明：旧版哈希存在缺陷：无论实际曲线如何，曲线字节始终为 0（仅影响非 SECP256K1 曲线）。若你在修复前使用非 SECP256K1 曲线注册了加密密钥，请使用 fromRootSeedKeyLegacyHash 重建旧版密钥。

网络配置

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

const config = getNetworkConfig('testnet'); // 或 'mainnet'
// config.packages.ikaPackage
// config.packages.ikaDwallet2pcMpcPackage
// config.objects.ikaDWalletCoordinator.objectID
// config.objects.ikaSystemObject.objectID

错误类

import {
    IkaClientError,       // 基础错误类
    ObjectNotFoundError,  // 链上对象未找到
    InvalidObjectError,   // 对象解析失败
    NetworkError,         // 网络操作失败
    CacheError,           // 缓存操作失败
} from '@ika.xyz/sdk';

底层交易构建器

用于直接构造 Move 调用（绕过 IkaTransaction）：

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

// 所有函数签名格式为：(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);
// ……等等（共 50+ 个函数）

关键导入汇总

// 核心模块
import { IkaClient, IkaTransaction, getNetworkConfig } from '@ika.xyz/sdk';

// 密钥模块
import { UserShareEncryptionKeys } from '@ika.xyz/sdk';

// 密码学模块
import {
    prepareDKGAsync, createRandomSessionIdentifier,
    createUserSignMessageWithPublicOutput, publicKeyFromDWalletOutput,
    parseSignatureFromSignOutput, prepareImportedKeyDWalletVerification,
} from '@ika.xyz/sdk';

// 类型定义
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';

// 校验模块
import {
    validateHashSignatureCombination, validateCurveSignatureAlgorithm,
    fromCurveToNumber, fromSignatureAlgorithmToNumber, fromHashToNumber,
} from '@ika.xyz/sdk';

// 底层模块
import { coordinatorTransactions, systemTransactions } from '@ika.xyz/sdk';