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 - 类型系统、枚举、曲线/签名/哈希验证、状态收窄

安装

bash
pnpm add @ika.xyz/sdk

或

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

设置

typescript
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();

枚举

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

// 曲线
Curve.SECP256K1 // 比特币、以太坊
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. 创建加密密钥

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

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

2. 注册加密密钥

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（创建 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), [1000000]),
suiCoin: tx.splitCoins(tx.gas, [1000000]),
sessionIdentifier: sessionId,
dwalletNetworkEncryptionKeyId: networkKey.id,
curve: Curve.SECP256K1,
});
const result = await suiClient.core.signAndExecuteTransaction({ transaction: tx, signer: keypair });

4. 获取 dWallet 和公钥

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

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), [1000000]),
suiCoin: tx.splitCoins(tx.gas, [1000000]),
});

6. 签名消息

typescript
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.publicusersecretkeyshare),
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), [1000000]),
suiCoin: tx.splitCoins(tx.gas, [1000000]),
});

7. 检索签名

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

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

IkaClient 关键方法

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

// 查询 dWallet
const dWallet = await ikaClient.getDWallet(id);
const dWallet = await ikaClient.getDWalletInPartic