@kairoguard/sdk 0.0.3 → 0.0.5

package/dist/auditBundle.d.ts

@@ -1,4 +1,4 @@
-import type { Hex } from "./types";
+import type { Hex } from "./types.js";
 export type AuditBundle = {
     v: 1;
     network: "testnet" | "mainnet";

package/dist/auditBundle.js

@@ -1,4 +1,4 @@
-import { fetchAndValidatePolicyReceipt } from "./suiReceipts";
+import { fetchAndValidatePolicyReceipt } from "./suiReceipts.js";
 /**
  * Minimal verifier for an audit bundle (v1).
  * This intentionally verifies only receipt commitments using on-chain receipt contents.

package/dist/backend.d.ts

@@ -253,6 +253,7 @@ export declare class BackendClient {
     private apiKey;
     constructor(opts: BackendClientOpts);
     setApiKey(key: string): void;
+    getBaseUrl(): string;
     private request;
     getHealth(): Promise<HealthResponse>;
     register(label: string, email?: string): Promise<RegisterKeyResponse>;

package/dist/backend.js

@@ -15,6 +15,9 @@ export class BackendClient {
     setApiKey(key) {
         this.apiKey = key;
     }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
     async request(method, path, body) {
         const headers = { "Content-Type": "application/json" };
         if (this.apiKey) {

package/dist/cli.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { verifyAuditBundle } from "./auditBundle.js";
 import { BackendClient } from "./backend.js";
+import { KairoClient } from "./client.js";
 import { SKILL_MD, API_REFERENCE_MD, SDK_REFERENCE_MD } from "./skill-templates.js";
 const CONFIG_DIR = join(homedir(), ".kairo");
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
@@ -80,6 +81,26 @@ async function cmdHealth() {
     const res = await client.getHealth();
     console.log(JSON.stringify(res, null, 2));
 }
+async function cmdWalletCreate(args) {
+    const curveRaw = flag(args, "--curve") ?? "secp256k1";
+    if (curveRaw !== "secp256k1" && curveRaw !== "ed25519") {
+        console.error('Invalid --curve value. Use "secp256k1" or "ed25519".');
+        process.exit(1);
+    }
+    const policyId = flag(args, "--policy-id");
+    const stableId = flag(args, "--stable-id");
+    const cfg = requireConfig();
+    const kairo = new KairoClient({
+        apiKey: cfg.apiKey,
+        backendUrl: cfg.backendUrl,
+    });
+    const wallet = await kairo.createWallet({
+        curve: curveRaw,
+        policyObjectId: policyId,
+        stableId,
+    });
+    console.log(JSON.stringify(wallet, null, 2));
+}
 async function cmdRegister(args) {
     const label = requireFlag(args, "--label", "name");
     const client = getClient();
@@ -184,6 +205,8 @@ Setup:
 
 Wallet & Policy:
   health                            Server health check
+  wallet-create [--curve secp256k1|ed25519] [--policy-id <id>] [--stable-id <id>]
+                                    Create a new dWallet via SDK DKG flow
   register --label <name>           Register new API key
   policy-create --stable-id <id> --allow <addrs>  Create policy
   policy-register --policy-id <id>  Register policy version
@@ -206,6 +229,8 @@ async function main() {
             return cmdInit(rest);
         case "health":
             return cmdHealth();
+        case "wallet-create":
+            return cmdWalletCreate(rest);
         case "register":
             return cmdRegister(rest);
         case "policy-create":

package/dist/client.d.ts

@@ -17,7 +17,7 @@ export interface KairoClientOpts {
     backendUrl?: string;
     /** Local directory for secret share storage. Defaults to ~/.kairo/keys */
     storePath?: string;
-    /** Sui RPC URL for fetching Ika protocol params. Defaults to public testnet. */
+    /** Sui RPC URL for fetching Ika protocol params. Defaults to backend's proxy, then SUI_RPC_URL env, then public testnet. */
     suiRpcUrl?: string;
     /** Sui network. Defaults to "testnet". */
     network?: "testnet" | "mainnet";
@@ -138,6 +138,10 @@ export declare class KairoClient {
     private network;
     private evmRpcUrls;
     constructor(opts: KairoClientOpts);
+    /**
+     * Resolve Sui RPC URL, testing backend proxy first and falling back to public RPC.
+     */
+    private resolveSuiRpcUrl;
     /**
      * Create a new dWallet. Runs DKG on the agent's machine, submits to backend,
      * and optionally provisions the wallet in the vault.

package/dist/client.js

@@ -14,7 +14,43 @@ import { Curve, fetchProtocolParams, deriveEncryptionKeys, generateSeed, generat
 import { Hash, SignatureAlgorithm, createUserSignMessageWithPublicOutput } from "@ika.xyz/sdk";
 import { computeEvmIntentFromUnsignedTxBytes } from "./evmIntent.js";
 import { keccak256, recoverTransactionAddress, serializeTransaction, } from "viem";
-const DEFAULT_SUI_RPC = "https://fullnode.testnet.sui.io:443";
+const FALLBACK_SUI_RPC = "https://fullnode.testnet.sui.io:443";
+async function testRpcEndpoint(url) {
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "suix_getLatestSuiSystemState", params: [] }),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function isRateLimitError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes("429") || message.includes("Too Many Requests");
+}
+async function withRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? 3;
+    const baseDelayMs = opts?.baseDelayMs ?? 2000;
+    const label = opts?.label ?? "operation";
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const lastAttempt = attempt >= maxRetries;
+            if (lastAttempt || !isRateLimitError(err)) {
+                throw err;
+            }
+            const delayMs = baseDelayMs * 2 ** attempt;
+            console.warn(`[KairoSDK] ${label} rate-limited (attempt ${attempt + 1}/${maxRetries + 1}); retrying in ${delayMs / 1000}s...`);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
 const DEFAULT_EVM_RPC_URLS = {
     1: "https://rpc.ankr.com/eth",
     11155111: "https://rpc.ankr.com/eth_sepolia",
@@ -37,9 +73,30 @@ export class KairoClient {
     constructor(opts) {
         this.backend = new BackendClient({ backendUrl: opts.backendUrl, apiKey: opts.apiKey });
         this.store = new KeyStore(opts.storePath);
-        this.suiRpcUrl = opts.suiRpcUrl ?? DEFAULT_SUI_RPC;
         this.network = opts.network ?? "testnet";
         this.evmRpcUrls = { ...DEFAULT_EVM_RPC_URLS, ...(opts.evmRpcUrls ?? {}) };
+        // Sui RPC priority: explicit option > env var > will resolve lazily (proxy or fallback)
+        this.suiRpcUrl =
+            opts.suiRpcUrl ??
+                process.env.SUI_RPC_URL?.trim() ??
+                ""; // Empty means we'll resolve lazily
+    }
+    /**
+     * Resolve Sui RPC URL, testing backend proxy first and falling back to public RPC.
+     */
+    async resolveSuiRpcUrl() {
+        if (this.suiRpcUrl)
+            return this.suiRpcUrl;
+        // Try backend proxy first (uses Shinami)
+        const backendProxy = `${this.backend.getBaseUrl()}/api/sui-rpc`;
+        if (await testRpcEndpoint(backendProxy)) {
+            this.suiRpcUrl = backendProxy;
+            return this.suiRpcUrl;
+        }
+        // Fall back to public RPC
+        console.warn("[KairoSDK] Backend RPC proxy not available, falling back to public Sui RPC");
+        this.suiRpcUrl = FALLBACK_SUI_RPC;
+        return this.suiRpcUrl;
     }
     /**
      * Create a new dWallet. Runs DKG on the agent's machine, submits to backend,
@@ -53,7 +110,8 @@ export class KairoClient {
         const seed = generateSeed();
         const encryptionKeys = await deriveEncryptionKeys(seed, curve);
         // 2. Fetch protocol params from Ika network (runs locally, avoids backend memory limit)
-        const protocolParams = await fetchProtocolParams(curve, this.suiRpcUrl, this.network);
+        const rpcUrl = await this.resolveSuiRpcUrl();
+        const protocolParams = await withRetry(() => fetchProtocolParams(curve, rpcUrl, this.network), { label: "fetchProtocolParams" });
         // 3. Generate session identifier
         const sessionIdentifier = generateSessionIdentifier();
         // 4. Get backend admin address (DKG must target the admin signer)
@@ -323,7 +381,8 @@ export class KairoClient {
             presignId = presign.presignId;
             presignBytes = presign.presignBytes;
         }
-        const protocolParams = await fetchProtocolParams("secp256k1", this.suiRpcUrl, this.network);
+        const rpcUrlForSign = await this.resolveSuiRpcUrl();
+        const protocolParams = await withRetry(() => fetchProtocolParams("secp256k1", rpcUrlForSign, this.network), { label: "fetchProtocolParams(sign)" });
         const messageBytes = new Uint8Array(Buffer.from(messageHexNoPrefix, "hex"));
         const userSignMessage = await this.computeUserSignMessageWithExtensionFallback(wallet, protocolParams, presignBytes, messageBytes);
         const policyContext = opts?.policyContext ?? {
@@ -474,7 +533,33 @@ export class KairoClient {
     async activateWallet(walletId, encryptedShareId, encryptionKeys, userPublicOutput) {
         // Wait a moment for the dWallet state to propagate
         await new Promise((r) => setTimeout(r, 2000));
-        const dWallet = await fetchDWallet(this.suiRpcUrl, this.network, walletId);
+        const rpcUrlForActivation = await this.resolveSuiRpcUrl();
+        const dWallet = await withRetry(() => fetchDWallet(rpcUrlForActivation, this.network, walletId), { label: "fetchDWallet(activate)" });
+        // Check dWallet state - skip activation if already active
+        const state = dWallet?.state;
+        const isActive = Boolean(state?.Active) || state?.$kind === "Active";
+        if (isActive) {
+            // Already activated, nothing to do
+            return;
+        }
+        const isAwaitingSignature = Boolean(state?.AwaitingKeyHolderSignature) ||
+            state?.$kind === "AwaitingKeyHolderSignature";
+        if (!isAwaitingSignature) {
+            // Unknown state - wait and retry once
+            await new Promise((r) => setTimeout(r, 3000));
+            const dWallet2 = await withRetry(() => fetchDWallet(rpcUrlForActivation, this.network, walletId), { label: "fetchDWallet(activate-recheck)" });
+            const state2 = dWallet2?.state;
+            const isActive2 = Boolean(state2?.Active) || state2?.$kind === "Active";
+            if (isActive2)
+                return;
+            const isAwaiting2 = Boolean(state2?.AwaitingKeyHolderSignature) ||
+                state2?.$kind === "AwaitingKeyHolderSignature";
+            if (!isAwaiting2) {
+                const stateKind = state2?.$kind ?? Object.keys(state2 ?? {})[0] ?? "Unknown";
+                throw new Error(`dWallet is not ready for activation (state=${stateKind}). ` +
+                    `This can happen if the DKG is still processing. Wait a few seconds and retry.`);
+            }
+        }
         const signature = await computeUserOutputSignature({
             encryptionKeys,
             dWallet,

package/dist/ika-protocol.js

@@ -12,22 +12,43 @@ function resolveCurve(curve) {
 }
 // Protocol params are large (~MB). Cache per curve to avoid refetching.
 const paramsCache = new Map();
+// Reuse a single initialized Ika client per (network + RPC URL) to avoid
+// repeated initialize() bursts that can trigger upstream rate limits.
+const clientCache = new Map();
+function getClientCacheKey(network, suiRpcUrl) {
+    return `${network}:${suiRpcUrl}`;
+}
+function getOrCreateIkaClient(network, suiRpcUrl) {
+    const key = getClientCacheKey(network, suiRpcUrl);
+    const cached = clientCache.get(key);
+    if (cached)
+        return cached;
+    const suiClient = new SuiClient({ url: suiRpcUrl });
+    const ikaConfig = getNetworkConfig(network);
+    const ikaClient = new IkaClient({ suiClient, config: ikaConfig });
+    const ready = ikaClient.initialize().catch((err) => {
+        clientCache.delete(key);
+        throw err;
+    });
+    const created = { ikaClient, ready };
+    clientCache.set(key, created);
+    return created;
+}
 /**
  * Fetch Ika protocol public parameters for a given curve.
  * Uses the IkaClient which reads from the Ika coordinator on Sui.
  */
 export async function fetchProtocolParams(curve, suiRpcUrl, network = "testnet") {
     const ikaCurve = resolveCurve(curve);
-    const cached = paramsCache.get(ikaCurve);
+    const paramsCacheKey = `${getClientCacheKey(network, suiRpcUrl)}:${ikaCurve}`;
+    const cached = paramsCache.get(paramsCacheKey);
     if (cached)
         return cached;
-    const suiClient = new SuiClient({ url: suiRpcUrl });
-    const ikaConfig = getNetworkConfig(network);
-    const ikaClient = new IkaClient({ suiClient, config: ikaConfig });
-    await ikaClient.initialize();
+    const { ikaClient, ready } = getOrCreateIkaClient(network, suiRpcUrl);
+    await ready;
     // First arg is dWallet (undefined for new wallets), second is curve
     const params = await ikaClient.getProtocolPublicParameters(undefined, ikaCurve);
-    paramsCache.set(ikaCurve, params);
+    paramsCache.set(paramsCacheKey, params);
     return params;
 }
 /**
@@ -73,10 +94,8 @@ export async function computeUserOutputSignature(params) {
  * Fetch the dWallet object from Ika network for activation.
  */
 export async function fetchDWallet(suiRpcUrl, network, dwalletId) {
-    const suiClient = new SuiClient({ url: suiRpcUrl });
-    const ikaConfig = getNetworkConfig(network);
-    const ikaClient = new IkaClient({ suiClient, config: ikaConfig });
-    await ikaClient.initialize();
+    const { ikaClient, ready } = getOrCreateIkaClient(network, suiRpcUrl);
+    await ready;
     return ikaClient.getDWallet(dwalletId);
 }
 /**

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-export * from "./types";
-export * from "./evmIntent";
-export * from "./evm";
-export * from "./bitcoinIntent";
-export { type SolanaCluster, LAMPORTS_PER_SOL, type ParsedInstruction, type ParsedSolanaTransaction, type SolanaIntent, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent";
-export * from "./suiReceipts";
-export * from "./suiResult";
-export * from "./suiTxBuilders";
-export * from "./auditBundle";
-export * from "./suiCustody";
-export { KairoClient, type KairoClientOpts, type CreateWalletOpts, type WalletInfo, type ProposePolicyUpdateParams, type PolicyUpdateProposalResult, type ApprovePolicyUpdateParams, type ExecutePolicyUpdateParams, type PolicyUpdateStatus, } from "./client";
-export { KeyStore, type WalletRecord } from "./keystore";
-export { BackendClient, DEFAULT_BACKEND_URL, type BackendClientOpts } from "./backend";
+export * from "./types.js";
+export * from "./evmIntent.js";
+export * from "./evm.js";
+export * from "./bitcoinIntent.js";
+export { type SolanaCluster, LAMPORTS_PER_SOL, type ParsedInstruction, type ParsedSolanaTransaction, type SolanaIntent, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent.js";
+export * from "./suiReceipts.js";
+export * from "./suiResult.js";
+export * from "./suiTxBuilders.js";
+export * from "./auditBundle.js";
+export * from "./suiCustody.js";
+export { KairoClient, type KairoClientOpts, type CreateWalletOpts, type WalletInfo, type ProposePolicyUpdateParams, type PolicyUpdateProposalResult, type ApprovePolicyUpdateParams, type ExecutePolicyUpdateParams, type PolicyUpdateStatus, } from "./client.js";
+export { KeyStore, type WalletRecord } from "./keystore.js";
+export { BackendClient, DEFAULT_BACKEND_URL, type BackendClientOpts } from "./backend.js";

package/dist/index.js

@@ -1,13 +1,13 @@
-export * from "./types";
-export * from "./evmIntent";
-export * from "./evm";
-export * from "./bitcoinIntent";
-export { LAMPORTS_PER_SOL, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent";
-export * from "./suiReceipts";
-export * from "./suiResult";
-export * from "./suiTxBuilders";
-export * from "./auditBundle";
-export * from "./suiCustody";
-export { KairoClient, } from "./client";
-export { KeyStore } from "./keystore";
-export { BackendClient, DEFAULT_BACKEND_URL } from "./backend";
+export * from "./types.js";
+export * from "./evmIntent.js";
+export * from "./evm.js";
+export * from "./bitcoinIntent.js";
+export { LAMPORTS_PER_SOL, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent.js";
+export * from "./suiReceipts.js";
+export * from "./suiResult.js";
+export * from "./suiTxBuilders.js";
+export * from "./auditBundle.js";
+export * from "./suiCustody.js";
+export { KairoClient, } from "./client.js";
+export { KeyStore } from "./keystore.js";
+export { BackendClient, DEFAULT_BACKEND_URL } from "./backend.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairoguard/sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",