@kairoguard/sdk 0.0.1

package/dist/suiCustody.js

@@ -0,0 +1,183 @@
+import { SuiClient } from "@mysten/sui/client";
+import { bcs } from "@mysten/sui/bcs";
+import { keccak256, toBytes } from "viem";
+const VecU8 = bcs.vector(bcs.u8());
+// Matches `kairo_policy_engine::custody_ledger::EventV2Canonical`
+const EventV2CanonicalBcs = bcs.struct("EventV2Canonical", {
+    chain_id: bcs.Address,
+    seq: bcs.u64(),
+    kind: bcs.u8(),
+    recorded_at_ms: bcs.u64(),
+    prev_hash: VecU8,
+    src_namespace: bcs.u8(),
+    src_chain_id: bcs.u64(),
+    src_tx_hash: VecU8,
+    to_addr: VecU8,
+    policy_object_id: bcs.Address,
+    policy_version: VecU8,
+    intent_hash: VecU8,
+    receipt_object_id: bcs.Address,
+    payload: VecU8,
+});
+/**
+ * Verify a custody event hash by recomputing the canonical BCS encoding (v2/v3 hashing).
+ *
+ * Note: This does NOT discover events. You must provide a specific `CustodyEvent` object id.
+ */
+export async function fetchAndVerifyCustodyEvent(args) {
+    try {
+        const client = new SuiClient({ url: args.suiRpcUrl });
+        const obj = await client.getObject({
+            id: args.custodyEventObjectId,
+            options: { showType: true, showContent: true },
+        });
+        if (!obj.data)
+            throw new Error("CustodyEvent object not found");
+        const typeStr = String(obj.data.type ?? "");
+        if (!typeStr.endsWith("::custody_ledger::CustodyEvent")) {
+            throw new Error(`Object is not a CustodyEvent (type=${typeStr})`);
+        }
+        const content = obj.data.content;
+        if (!content || content.dataType !== "moveObject") {
+            throw new Error("CustodyEvent object has no Move content");
+        }
+        const f = content.fields ?? {};
+        const chainId = String(f["chain_id"] ?? "").trim();
+        const receiptId = String(f["receipt_object_id"] ?? "").trim();
+        const policyObjectId = String(f["policy_object_id"] ?? "").trim();
+        if (!chainId.startsWith("0x") || !receiptId.startsWith("0x") || !policyObjectId.startsWith("0x")) {
+            throw new Error("CustodyEvent missing required object id fields");
+        }
+        const seq = toBigInt(f["seq"]);
+        const kind = toNumberU8(f["kind"]);
+        const recordedAt = toBigInt(f["recorded_at_ms"]);
+        const prevHash = coerceBytes(f["prev_hash"]);
+        const srcNs = toNumberU8(f["src_namespace"]);
+        const srcChainId = toBigInt(f["src_chain_id"]);
+        const srcTxHash = coerceBytes(f["src_tx_hash"]) ?? new Uint8Array();
+        const toAddr = coerceBytes(f["to_addr"]) ?? new Uint8Array();
+        const policyVersion = coerceBytes(f["policy_version"]) ?? new Uint8Array();
+        const intentHash = coerceBytes(f["intent_hash"]);
+        const payload = coerceBytes(f["payload"]) ?? new Uint8Array();
+        const eventHashOnChain = coerceBytes(f["event_hash"]);
+        if (seq == null ||
+            kind == null ||
+            recordedAt == null ||
+            srcNs == null ||
+            srcChainId == null ||
+            !prevHash ||
+            !intentHash ||
+            !eventHashOnChain) {
+            throw new Error("CustodyEvent missing required scalar/hash fields");
+        }
+        if (prevHash.length !== 32)
+            throw new Error("prev_hash must be 32 bytes");
+        if (intentHash.length !== 32)
+            throw new Error("intent_hash must be 32 bytes");
+        if (eventHashOnChain.length !== 32)
+            throw new Error("event_hash must be 32 bytes");
+        const canonBytes = EventV2CanonicalBcs.serialize({
+            chain_id: chainId,
+            seq,
+            kind,
+            recorded_at_ms: recordedAt,
+            prev_hash: Array.from(prevHash),
+            src_namespace: srcNs,
+            src_chain_id: srcChainId,
+            src_tx_hash: Array.from(srcTxHash),
+            to_addr: Array.from(toAddr),
+            policy_object_id: policyObjectId,
+            policy_version: Array.from(policyVersion),
+            intent_hash: Array.from(intentHash),
+            receipt_object_id: receiptId,
+            payload: Array.from(payload),
+        }).toBytes();
+        const computed = toBytes(keccak256(canonBytes));
+        if (!bytesEq(computed, eventHashOnChain)) {
+            throw new Error(`CustodyEvent hash mismatch (computed=${toHex(computed)}, onchain=${toHex(eventHashOnChain)})`);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function toBigInt(v) {
+    if (v == null)
+        return null;
+    if (typeof v === "bigint")
+        return v;
+    if (typeof v === "number" && Number.isFinite(v))
+        return BigInt(v);
+    if (typeof v === "string") {
+        const s = v.trim();
+        if (!s)
+            return null;
+        if (s.startsWith("0x") || s.startsWith("0X"))
+            return BigInt(s);
+        if (/^\\d+$/.test(s))
+            return BigInt(s);
+    }
+    return null;
+}
+function toNumberU8(v) {
+    if (v == null)
+        return null;
+    const n = typeof v === "number" ? v : Number(String(v));
+    if (!Number.isFinite(n))
+        return null;
+    const i = Math.floor(n);
+    if (i < 0 || i > 255)
+        return null;
+    return i;
+}
+function coerceBytes(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Array.isArray(v) && v.every((x) => Number.isInteger(x) && x >= 0 && x <= 255)) {
+        return Uint8Array.from(v);
+    }
+    if (typeof v === "string") {
+        const s = v.trim();
+        if (!s)
+            return null;
+        if (/^0x[0-9a-fA-F]*$/.test(s)) {
+            try {
+                return toBytes(s);
+            }
+            catch {
+                return null;
+            }
+        }
+        // base64
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (typeof Buffer !== "undefined")
+                return Uint8Array.from(Buffer.from(s, "base64"));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (v && typeof v === "object") {
+        const o = v;
+        if (o.bytes != null)
+            return coerceBytes(o.bytes);
+        if (o.data != null)
+            return coerceBytes(o.data);
+        if (o.value != null)
+            return coerceBytes(o.value);
+    }
+    return null;
+}
+function bytesEq(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function toHex(bytes) {
+    return `0x${Buffer.from(bytes).toString("hex")}`;
+}

package/dist/suiReceipts.d.ts

@@ -0,0 +1,27 @@
+import type { Hex } from "./types.js";
+/**
+ * Minimal "hard gate" receipt verification helper.
+ *
+ * We verify:
+ * - receipt object exists
+ * - receipt.allowed === true
+ * - receipt fields match the expected commitment (policyId, policyVersion, chainId, intent hash, optional destination)
+ *
+ * The exact object type + field names are defined in the Move package under `sui/kairo_policy_engine`.
+ */
+export declare function fetchAndValidatePolicyReceipt(params: {
+    suiRpcUrl: string;
+    receiptObjectId: string;
+    expected: {
+        policyId: string;
+        policyVersion: string;
+        evmChainId: number;
+        intentHash: Hex;
+        toEvm?: Hex;
+        policyStableId?: string;
+        policyRoot?: Hex;
+        policyVersionId?: string;
+        evmSelector?: Hex;
+        erc20Amount?: Hex;
+    };
+}): Promise<void>;

package/dist/suiReceipts.js

@@ -0,0 +1,203 @@
+import { SuiClient } from "@mysten/sui/client";
+/**
+ * Minimal "hard gate" receipt verification helper.
+ *
+ * We verify:
+ * - receipt object exists
+ * - receipt.allowed === true
+ * - receipt fields match the expected commitment (policyId, policyVersion, chainId, intent hash, optional destination)
+ *
+ * The exact object type + field names are defined in the Move package under `sui/kairo_policy_engine`.
+ */
+export async function fetchAndValidatePolicyReceipt(params) {
+    const suiClient = new SuiClient({ url: params.suiRpcUrl });
+    const obj = await suiClient.getObject({
+        id: params.receiptObjectId,
+        options: { showContent: true, showType: true },
+    });
+    if (!obj.data)
+        throw new Error("Receipt object not found");
+    const content = obj.data.content;
+    const typeStr = String(obj.data.type ?? "");
+    if (!content || content.dataType !== "moveObject") {
+        throw new Error("Receipt object has no Move content");
+    }
+    const fields = content.fields ?? {};
+    // PolicyReceiptV2
+    if (typeStr.endsWith("::policy_registry::PolicyReceiptV2")) {
+        const allowed = Boolean(fields["allowed"]);
+        if (!allowed) {
+            const denial = fields["denial_reason"];
+            const denialReason = typeof denial === "bigint" ? denial.toString() : String(denial ?? "");
+            throw new Error(`Receipt is denied (denial_reason=${denialReason})`);
+        }
+        const policyObjectId = String(fields["policy_object_id"] ?? "");
+        const policyVersion = bytesFieldToUtf8(fields["policy_version"]);
+        const stableId = bytesFieldToUtf8(fields["policy_stable_id"]);
+        const policyRoot = normalizeBytesFieldToHex(fields["policy_root"]);
+        const policyVersionId = String(fields["policy_version_id"] ?? "");
+        const evmChainId = Number(String(fields["evm_chain_id"] ?? ""));
+        const intentHash = normalizeBytesFieldToHex(fields["intent_hash"]);
+        const toEvm = normalizeBytesFieldToHex(fields["to_evm"]);
+        const selector = normalizeBytesFieldToHex(fields["evm_selector"]);
+        const amount = normalizeBytesFieldToHex(fields["erc20_amount"]);
+        if (!policyObjectId || !policyVersion || !Number.isFinite(evmChainId) || !intentHash || !toEvm) {
+            throw new Error("ReceiptV2 missing required fields");
+        }
+        if (!policyRoot || coerceBytes(fields["policy_root"])?.length !== 32) {
+            throw new Error("ReceiptV2 policy_root missing/invalid (expected 32 bytes)");
+        }
+        if (!policyVersionId.startsWith("0x")) {
+            throw new Error("ReceiptV2 policy_version_id missing/invalid");
+        }
+        if (selector && coerceBytes(fields["evm_selector"])?.length !== 4) {
+            throw new Error("ReceiptV2 evm_selector invalid (expected 4 bytes or empty)");
+        }
+        if (amount && coerceBytes(fields["erc20_amount"])?.length !== 32) {
+            throw new Error("ReceiptV2 erc20_amount invalid (expected 32 bytes or empty)");
+        }
+        if (policyObjectId.toLowerCase() !== params.expected.policyId.toLowerCase()) {
+            throw new Error("ReceiptV2 policy_object_id mismatch");
+        }
+        if (policyVersion !== params.expected.policyVersion) {
+            throw new Error("ReceiptV2 policy_version mismatch");
+        }
+        if (evmChainId !== params.expected.evmChainId) {
+            throw new Error("ReceiptV2 evm_chain_id mismatch");
+        }
+        if (intentHash.toLowerCase() !== params.expected.intentHash.toLowerCase()) {
+            throw new Error("ReceiptV2 intent_hash mismatch");
+        }
+        if (params.expected.toEvm && toEvm.toLowerCase() !== params.expected.toEvm.toLowerCase()) {
+            throw new Error("ReceiptV2 destination mismatch");
+        }
+        // Optional stronger checks (if caller provides expectations)
+        if (params.expected.policyStableId && stableId && stableId !== params.expected.policyStableId) {
+            throw new Error("ReceiptV2 policy_stable_id mismatch");
+        }
+        if (params.expected.policyRoot && policyRoot.toLowerCase() !== params.expected.policyRoot.toLowerCase()) {
+            throw new Error("ReceiptV2 policy_root mismatch");
+        }
+        if (params.expected.policyVersionId &&
+            policyVersionId.toLowerCase() !== params.expected.policyVersionId.toLowerCase()) {
+            throw new Error("ReceiptV2 policy_version_id mismatch");
+        }
+        if (params.expected.evmSelector && (!selector || selector.toLowerCase() !== params.expected.evmSelector.toLowerCase())) {
+            throw new Error("ReceiptV2 evm_selector mismatch");
+        }
+        if (params.expected.erc20Amount && (!amount || amount.toLowerCase() !== params.expected.erc20Amount.toLowerCase())) {
+            throw new Error("ReceiptV2 erc20_amount mismatch");
+        }
+        return;
+    }
+    // Legacy PolicyReceipt (MVP)
+    const policyId = String(fields["policy_id"] ?? "");
+    const policyVersion = bytesFieldToUtf8(fields["policy_version"]);
+    const evmChainId = Number(String(fields["evm_chain_id"] ?? ""));
+    const allowed = Boolean(fields["allowed"]);
+    if (!allowed) {
+        const denial = fields["denial_reason"];
+        const denialReason = typeof denial === "bigint" ? denial.toString() : String(denial ?? "");
+        throw new Error(`Receipt is denied (denial_reason=${denialReason})`);
+    }
+    const intentHash = normalizeBytesFieldToHex(fields["intent_hash"]);
+    if (!intentHash)
+        throw new Error("Receipt intent_hash missing/invalid");
+    if (!policyId || !policyVersion || !Number.isFinite(evmChainId)) {
+        throw new Error("Receipt missing required fields");
+    }
+    if (policyId.toLowerCase() !== params.expected.policyId.toLowerCase()) {
+        throw new Error("Receipt policy_id mismatch");
+    }
+    if (policyVersion !== params.expected.policyVersion) {
+        throw new Error("Receipt policy_version mismatch");
+    }
+    if (evmChainId !== params.expected.evmChainId) {
+        throw new Error("Receipt evm_chain_id mismatch");
+    }
+    if (intentHash.toLowerCase() !== params.expected.intentHash.toLowerCase()) {
+        throw new Error("Receipt intent_hash mismatch");
+    }
+    const expectedTo = params.expected.toEvm;
+    if (expectedTo) {
+        const receiptTo = normalizeBytesFieldToHex(fields["to_evm"]);
+        if (!receiptTo)
+            throw new Error("Receipt to_evm missing/invalid");
+        if (receiptTo.toLowerCase() !== expectedTo.toLowerCase()) {
+            throw new Error("Receipt destination mismatch");
+        }
+    }
+}
+function normalizeBytesFieldToHex(v) {
+    const bytes = coerceBytes(v);
+    if (!bytes)
+        return null;
+    return `0x${bytesToHex(bytes)}`;
+}
+function bytesFieldToUtf8(v) {
+    const bytes = coerceBytes(v);
+    if (!bytes)
+        return "";
+    return new TextDecoder().decode(bytes);
+}
+function bytesToHex(bytes) {
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function coerceBytes(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Array.isArray(v) && v.every((x) => Number.isInteger(x) && x >= 0 && x <= 255)) {
+        return Uint8Array.from(v);
+    }
+    if (typeof v === "string") {
+        if (/^0x[0-9a-fA-F]*$/.test(v)) {
+            const raw = v.slice(2);
+            if (raw.length % 2 !== 0)
+                return null;
+            const out = new Uint8Array(raw.length / 2);
+            for (let i = 0; i < out.length; i++)
+                out[i] = parseInt(raw.slice(i * 2, i * 2 + 2), 16);
+            return out;
+        }
+        return base64ToBytes(v);
+    }
+    if (v && typeof v === "object") {
+        const o = v;
+        if (typeof o.bytes === "string")
+            return coerceBytes(o.bytes);
+        if (typeof o.data === "string")
+            return coerceBytes(o.data);
+        if (typeof o.value === "string")
+            return coerceBytes(o.value);
+    }
+    return null;
+}
+function base64ToBytes(s) {
+    // Node
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (typeof Buffer !== "undefined") {
+            const buf = Buffer.from(s, "base64");
+            if (buf.length === 0 && s.length > 0)
+                return null;
+            return Uint8Array.from(buf);
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Browser
+    try {
+        const atobFn = globalThis.atob;
+        if (typeof atobFn !== "function")
+            return null;
+        const bin = atobFn(s);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/suiResult.d.ts

@@ -0,0 +1,8 @@
+import type { SuiTransactionBlockResponse } from "@mysten/sui/client";
+/**
+ * Extract created object IDs from a Sui transaction response.
+ *
+ * Wallet adapters differ in what they return; for hard-gating we want to reliably
+ * recover the newly created `PolicyReceipt` object id.
+ */
+export declare function getCreatedObjectIds(result: SuiTransactionBlockResponse): string[];

package/dist/suiResult.js

@@ -0,0 +1,12 @@
+/**
+ * Extract created object IDs from a Sui transaction response.
+ *
+ * Wallet adapters differ in what they return; for hard-gating we want to reliably
+ * recover the newly created `PolicyReceipt` object id.
+ */
+export function getCreatedObjectIds(result) {
+    const created = result.effects?.created ?? [];
+    return created
+        .map((c) => c.reference?.objectId)
+        .filter((x) => typeof x === "string" && x.length > 0);
+}

package/dist/suiTxBuilders.d.ts

@@ -0,0 +1,15 @@
+import { Transaction } from "@mysten/sui/transactions";
+import type { Hex, KairoPolicyId } from "./types.js";
+/**
+ * Build a Sui Transaction that calls the Move policy engine to mint a hard-gating receipt.
+ *
+ * You can have the user sign this tx with their Sui wallet, then pass the resulting receipt object id
+ * into the EVM signing flow.
+ */
+export declare function buildMintEvmReceiptTx(params: {
+    packageId: string;
+    policyObjectId: KairoPolicyId;
+    evmChainId: number;
+    intentHash: Hex;
+    toEvm: Hex;
+}): Transaction;

package/dist/suiTxBuilders.js

@@ -0,0 +1,38 @@
+import { Transaction } from "@mysten/sui/transactions";
+/**
+ * Build a Sui Transaction that calls the Move policy engine to mint a hard-gating receipt.
+ *
+ * You can have the user sign this tx with their Sui wallet, then pass the resulting receipt object id
+ * into the EVM signing flow.
+ */
+export function buildMintEvmReceiptTx(params) {
+    const tx = new Transaction();
+    const intentBytes = hexToBytes(params.intentHash, 32);
+    const toBytes = hexToBytes(params.toEvm, 20);
+    tx.moveCall({
+        // Use *_to_sender to avoid UnusedValueWithoutDrop in Sui PTB semantics.
+        // This function transfers the created PolicyReceipt to the tx sender and returns its id (droppable).
+        target: `${params.packageId}::policy_registry::mint_receipt_evm_to_sender`,
+        arguments: [
+            tx.object(params.policyObjectId),
+            tx.object("0x6"), // Clock object (standard)
+            tx.pure.u64(BigInt(params.evmChainId)),
+            tx.pure.vector("u8", [...intentBytes]),
+            tx.pure.vector("u8", [...toBytes]),
+        ],
+    });
+    // The receipt is returned as a newly created object; callers should inspect execution effects
+    // and extract the created object id of type `PolicyReceipt`.
+    return tx;
+}
+function hexToBytes(hex, expectedLen) {
+    const raw = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (raw.length !== expectedLen * 2) {
+        throw new Error(`Expected ${expectedLen} bytes, got ${raw.length / 2}`);
+    }
+    const out = new Uint8Array(expectedLen);
+    for (let i = 0; i < expectedLen; i++) {
+        out[i] = parseInt(raw.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+export type Hex = `0x${string}`;
+export type EvmChainId = number;
+export type KairoPolicyId = string;
+export type KairoPolicyReceiptId = string;
+export interface EvmIntent {
+    chainId: EvmChainId;
+    /**
+     * Keccak256 hash of the unsigned tx bytes (EIP-1559 serialized unsigned tx).
+     * 32 bytes, hex with 0x prefix.
+     */
+    intentHash: Hex;
+}
+export interface PolicyReceiptCommitment {
+    policyId: KairoPolicyId;
+    policyVersion: string;
+    evmChainId: EvmChainId;
+    intentHash: Hex;
+    /**
+     * Optional EVM destination address if the policy checks destination gating.
+     * 20 bytes, hex with 0x prefix.
+     */
+    to?: Hex;
+}
+/**
+ * Expected commitment for PolicyReceiptV2.
+ *
+ * Note:
+ * - `policyId` remains the on-chain *policy object id* (receipt field: `policy_object_id`).
+ * - `policyStableId` is the human-readable stable id (receipt field: `policy_stable_id`).
+ * - Selector/amount are optional and depend on the policy + intent.
+ */
+export interface PolicyReceiptV2Commitment extends PolicyReceiptCommitment {
+    policyStableId?: string;
+    policyRoot?: Hex;
+    policyVersionId?: string;
+    evmSelector?: Hex;
+    erc20Amount?: Hex;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@kairoguard/sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "kairo": "dist/cli.js",
+    "kairo-audit": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@ika.xyz/sdk": "^0.2.7",
+    "@mysten/sui": "^1.44.0",
+    "@noble/hashes": "^1.7.2",
+    "viem": "^2.23.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  }
+}
+