@frontiercompute/zcash-ika 0.1.0 → 0.3.0

package/README.md

@@ -1,46 +1,31 @@
 # zcash-ika
 
-Split-key custody for Zcash and Bitcoin. The private key never exists whole.
+Split-key custody for Zcash, Bitcoin, and EVM chains. The private key never exists whole. Spend policy enforced on-chain. Every action attested to Zcash.
 
 [![npm](https://img.shields.io/npm/v/@frontiercompute/zcash-ika)](https://www.npmjs.com/package/@frontiercompute/zcash-ika)
 
-## What this is
+## What this does
 
-Your agent/DAO/treasury holds ZEC and BTC through [Ika's 2PC-MPC network](https://ika.xyz). One key share on your device, one distributed across Ika's nodes on Sui. Both must cooperate to sign. Spending policy enforced by smart contract. Every action attested on-chain via [ZAP1](https://pay.frontiercompute.io).
+One secp256k1 dWallet on [Ika's 2PC-MPC network](https://ika.xyz) signs for three chain families. Your device holds half the key. Ika's nodes hold the other half. Neither can spend alone.
 
-**Ed25519 dWallet live on Ika testnet.** First Zcash-capable dWallet ever created on the network.
+- **Spend policy** enforced by Sui Move contract (per-tx limits, daily caps, recipient whitelist, emergency freeze)
+- **Transparent TX builder** for Zcash v5 transactions (ZIP 244 sighash, P2PKH, UTXO selection)
+- **Attestation** of every operation to Zcash mainnet via [ZAP1](https://pay.frontiercompute.io)
+- **5-chain verification** of attestation proofs (Arbitrum, Base, Hyperliquid, Solana, NEAR)
 
-## Use cases
-
-### AI Agent Custody
-Your agent needs to spend money. Give it a split-key wallet instead of full access. The agent requests transactions, but can't override spending limits, daily caps, or approved recipient lists. If the agent gets compromised, the attacker gets half a key. Worthless.
-
-```
-npx @frontiercompute/zcash-mcp  # 17 tools, any MCP client
-```
-
-### DAO Treasury
-Multi-sig is 2003 technology. Split-key custody means the treasury key literally doesn't exist in one place. Policy lives in a Sui Move contract that no single party controls. Every spend attested to Zcash for the full audit trail, but balances stay shielded.
-
-### Privacy Payroll
-Pay contributors without publishing amounts on a block explorer. Shielded ZEC from an Orchard address, every payment attested via ZAP1 for compliance. The auditor sees proof of payment. Nobody else sees anything.
-
-### Cross-Border Commerce
-Hold shielded ZEC + stablecoins (USDC/USDT via secp256k1 on EVM chains) in one wallet. Same operator, same policy. Swap between them via NEAR Intents. Settlement is private. Compliance is provable.
-
-### Compliance Without Exposure
-ZAP1 attestations prove what happened without revealing what you hold. Bond deposits prove skin in the game. Policy verification proves you followed the rules. All on Zcash mainnet, all verifiable, nothing visible beyond what you choose to share.
-
-## Signing parameters
+## Chain support
 
 | Chain | Curve | Algorithm | Hash | Status |
 |-------|-------|-----------|------|--------|
-| Zcash Orchard | ED25519 | EdDSA | SHA512 | dWallet live on testnet |
-| Bitcoin | SECP256K1 | ECDSASecp256k1 | DoubleSHA256 | SDK ready |
-| Zcash transparent | SECP256K1 | ECDSASecp256k1 | DoubleSHA256 | SDK ready |
-| Ethereum/Base | SECP256K1 | ECDSASecp256k1 | KECCAK256 | SDK ready |
+| Zcash transparent | secp256k1 | ECDSA | DoubleSHA256 | TX builder + signing live |
+| Bitcoin | secp256k1 | ECDSA | DoubleSHA256 | Same dWallet, signing live |
+| Ethereum/EVM | secp256k1 | ECDSA | KECCAK256 | Same dWallet, signing live |
+
+One dWallet. Three chain families. Split custody on all of them.
 
-One secp256k1 dWallet signs for Bitcoin, Zcash transparent, and every EVM chain.
+## What does NOT work
+
+**Zcash shielded (Orchard)** requires RedPallas on the Pallas curve. Ika supports secp256k1 and Ed25519, not Pallas. No path from Ika to Orchard signing today. For shielded, use the [embedded wallet](https://github.com/Frontier-Compute/zap1) which holds Orchard keys directly.
 
 ## Install
 
@@ -52,102 +37,151 @@ npm install @frontiercompute/zcash-ika
 
 ```typescript
 import {
-  createDualCustody,
-  spendShielded,
-  spendBitcoin,
+  createWallet,
+  sign,
   setPolicy,
-  getHistory,
-  checkCompliance,
-  CHAIN_PARAMS,
+  spendTransparent,
+  checkPolicy,
+  deriveZcashAddress,
 } from "@frontiercompute/zcash-ika";
 
 const config = {
-  network: "mainnet",
-  zebraRpcUrl: "http://127.0.0.1:8232",
+  network: "testnet",
+  suiPrivateKey: "suiprivkey1...",
   zap1ApiUrl: "https://pay.frontiercompute.io",
-  zap1ApiKey: "your-key",
 };
 
-// Create dual custody - shielded ZEC + BTC/stablecoins
-const custody = await createDualCustody(config, operatorSeed);
-
-// Set spending policy (enforced by Sui contract, not by trust)
-await setPolicy(config, custody.shielded.id, {
-  maxPerTx: 100_000,       // 0.001 ZEC per tx
-  maxDaily: 1_000_000,     // 0.01 ZEC daily cap
-  allowedRecipients: [],   // any recipient (or lock to specific addresses)
-  approvalThreshold: 500_000, // operator approval above 0.005 ZEC
+// 1. Create split-key wallet
+const wallet = await createWallet(config);
+console.log("dWallet:", wallet.id);
+console.log("t-addr:", wallet.address);
+console.log("Save this seed:", wallet.encryptionSeed);
+
+// 2. Set spend policy (Sui Move contract)
+const policy = await setPolicy(config, wallet.id, {
+  maxPerTx: 100_000_000,       // 1 ZEC max per transaction
+  maxDaily: 500_000_000,       // 5 ZEC daily cap
+  allowedRecipients: [],       // empty = any recipient
+  approvalThreshold: 50_000_000, // flag above 0.5 ZEC
 });
+console.log("Policy:", policy.policyId);
 
-// Shielded spend - agent requests, both key shares cooperate
-const result = await spendShielded(config, custody.shielded.id, operatorSeed, {
-  to: "u1abc...",
-  amount: 50_000,
-  memo: "payment for API access",
+// 3. Check if a spend is allowed
+const check = await checkPolicy(config, policy.policyId, {
+  amount: 10_000_000,
+  recipient: "t1SomeAddress...",
 });
-
-// Compliance check (works now against live ZAP1 API)
-const compliance = await checkCompliance(config, custody.shielded.id);
-// { compliant: true, violations: 0, bondDeposits: 1 }
+console.log("Allowed:", check.allowed);
+
+// 4. Spend from the transparent address
+const spend = await spendTransparent(config, {
+  walletId: wallet.id,
+  encryptionSeed: wallet.encryptionSeed,
+  recipient: "t1RecipientAddr...",
+  amount: 10_000_000,   // 0.1 ZEC
+  zebraRpcUrl: "http://localhost:8232",
+});
+console.log("Txid:", spend.txid);
 ```
 
-## How it works
+## Architecture
 
 ```
-Operator (phone / hardware wallet / DAO multisig)
+Operator (device / HSM)
   |
-  | user key share
+  | user key share (encryption seed from DKG)
   |
-Ika MPC Network (2PC-MPC on Sui, mainnet live)
+Ika MPC Network (2PC-MPC on Sui)
   |
   | network key share (distributed across nodes)
   |
-  +-- Spending Policy (Sui Move contract)
-  |     max per tx, daily cap, approved recipients
-  |     the agent CANNOT modify its own limits
+  +-- Spend Policy (Sui Move contract)
+  |     max per tx, daily cap, recipient whitelist, freeze
   |
-  +-- Sign Zcash tx (Ed25519/EdDSA)  -> shielded spend
-  +-- Sign Bitcoin tx (secp256k1/ECDSA) -> BTC spend
-  +-- Sign EVM tx (secp256k1/ECDSA)  -> USDC/USDT spend
+  +-- Sign ZEC transparent  (secp256k1 / ECDSA / DoubleSHA256)
+  +-- Sign BTC              (secp256k1 / ECDSA / DoubleSHA256)
+  +-- Sign ETH/EVM          (secp256k1 / ECDSA / KECCAK256)
+  |
+TX Builder (Zcash v5, ZIP 244)
+  +-- UTXO fetch from Zebra
+  +-- Sighash computation
+  +-- Signature attachment
+  +-- Broadcast + attestation
   |
 ZAP1 Attestation (Zcash mainnet)
-  +-- every spend recorded as AGENT_ACTION
-  +-- policy violations on-chain as POLICY_VIOLATION
-  +-- bond deposits prove skin in the game
-  +-- full audit trail, verifiable by anyone
+  +-- every spend recorded in Merkle tree
+  +-- anchored to Zcash blockchain
+  +-- verified on 5 EVM/L1 chains
 ```
 
-## What's live
+## Sign flow
+
+1. **Presign** - pre-compute MPC ephemeral key share (Sui TX 1, poll for completion)
+2. **Sign** - approve message + request signature (Sui TX 2, poll for completion)
 
-- Ed25519 dWallet on Ika testnet (TX: `FYcuaxBCAfuZqfBW7JEtEJME3KLBSBKLvhjLpZGSyaXb`)
-- `getHistory()` and `checkCompliance()` against live ZAP1 API
-- All Ika SDK primitives re-exported and typed
-- Chain parameter configs for all signing modes
-- DKG test script proving the full round-trip
+Both transactions on Sui. The user partial is computed locally via WASM. Neither party sees the full private key.
 
-## What's next
+## Spend flow (transparent)
 
-- secp256k1 dWallet for BTC/stablecoins (same flow, different curve)
-- Sign a real Zcash sighash through the MPC
-- Ed25519 -> Orchard spending key derivation bridge
-- Move policy template for spending limits
-- Mainnet deployment
+1. Fetch UTXOs from Zebra RPC (`getaddressutxos`)
+2. Build unsigned v5 TX with ZIP 244 sighash per input
+3. Sign each sighash through Ika MPC (presign + sign)
+4. Attach DER signatures to scriptSig fields
+5. Broadcast via `sendrawtransaction`
+6. Attest spend to ZAP1
 
-## The competition
+## Policy enforcement
 
-| Project | Custody | Privacy | Attestation |
-|---------|---------|---------|-------------|
-| Coinbase AgentKit | Full key in agent | None | None |
-| GOAT SDK | Full key in agent | None | None |
-| Solana Agent Kit | Full key in agent | None | None |
-| **zcash-ika** | **Split-key MPC** | **Zcash Orchard** | **ZAP1 on-chain** |
+The Sui Move contract (`zap1_policy::policy`) stores:
+- Per-transaction limit (zatoshis)
+- 24-hour rolling daily cap
+- Allowed recipient whitelist (empty = any)
+- Emergency freeze toggle
+
+Policy is checked before every MPC sign request. The contract owns the approval gate - you can't bypass it from the client.
+
+Deploy: `sui client publish --path move/` then set `POLICY_PACKAGE_ID`.
+
+## On-chain proof
+
+secp256k1 dWallet on Ika testnet:
+
+- dWalletId: `0xd9055400c88aeae675413b78143aa54e25eca7061ab659f54a42167cbfdd7aec`
+- TX: [`CYrS5X1S3itHUtux4qS35AJz5AAyUaJYeWZuqm1CcX2L`](https://testnet.suivision.xyz/txblock/CYrS5X1S3itHUtux4qS35AJz5AAyUaJYeWZuqm1CcX2L)
+- Compressed pubkey: `03ba9e85a85674df494520c2e80b804656fac54fe68668266f33fee9b03ad4b069`
+- Derived ZEC t-addr: `t1Rqh1TKqXsSiaV4wrSDandEPccucpHEudn`
+
+Attestation anchors verified on Arbitrum, Base, Hyperliquid, Solana, NEAR testnet.
+
+## Environment variables
+
+```
+SUI_PRIVATE_KEY         - Sui keypair for signing transactions
+POLICY_PACKAGE_ID       - Published Move package address (after sui client publish)
+ZAP1_API_URL            - ZAP1 attestation API (default: https://pay.frontiercompute.io)
+ZAP1_API_KEY            - API key for attestation
+ZEBRA_RPC_URL           - Zebra JSON-RPC endpoint for UTXO queries and broadcast
+```
+
+## Test scripts
+
+```bash
+# Create a new dWallet
+SUI_PRIVATE_KEY=suiprivkey1... node dist/test-dkg.js
+
+# Sign a test message through MPC
+SUI_PRIVATE_KEY=... DWALLET_ID=0x... ENC_SEED=... node dist/test-sign.js
+
+# End-to-end: DKG + presign + sign
+SUI_PRIVATE_KEY=... node dist/test-e2e.js
+```
 
 ## Stack
 
 - [Ika](https://ika.xyz) - 2PC-MPC threshold signing on Sui
 - [ZAP1](https://pay.frontiercompute.io) - on-chain attestation protocol
 - [Zebra](https://github.com/ZcashFoundation/zebra) - Zcash node
-- [zcash-mcp](https://www.npmjs.com/package/@frontiercompute/zcash-mcp) - 17-tool MCP server
+- [Sui Move](https://docs.sui.io/concepts/sui-move-concepts) - policy enforcement
 
 ## License
 

package/dist/hybrid.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Hybrid custody model for Zcash agents.
+ *
+ * Two custody paths, one interface:
+ *
+ * TRANSPARENT (secp256k1 via Ika MPC):
+ *   - t-addr transactions signed through 2PC-MPC
+ *   - Neither party holds the full key
+ *   - Policy enforced by Sui Move contract
+ *   - Same key signs BTC and ETH
+ *
+ * SHIELDED (RedPallas via local Orchard wallet):
+ *   - Orchard transactions signed locally (direct key)
+ *   - Ika cannot sign RedPallas (Pallas curve not supported)
+ *   - Privacy from Zcash protocol, not from MPC
+ *   - Every shielded spend attested to ZAP1
+ *
+ * The gap:
+ *   Orchard uses RedPallas on the Pallas curve. Ika supports secp256k1,
+ *   Ed25519, secp256r1, and Ristretto. None of these are Pallas.
+ *   Until an MPC network adds Pallas curve support, shielded custody
+ *   requires holding keys directly.
+ *
+ * The bridge:
+ *   shield()  - move ZEC from t-addr (MPC) to shielded pool (local wallet)
+ *   unshield() - move ZEC from shielded back to t-addr (for MPC custody)
+ *   Both operations attested on-chain via ZAP1.
+ */
+import type { ZcashIkaConfig, DWalletHandle, SignResult } from "./index.js";
+export type CustodyMode = "mpc" | "local";
+export interface HybridWallet {
+    /** MPC-custody transparent wallet (secp256k1 dWallet on Ika) */
+    transparent: {
+        mode: "mpc";
+        walletId: string;
+        publicKey: Uint8Array;
+        tAddress: string;
+        encryptionSeed: string;
+    };
+    /** Local-custody shielded wallet (Orchard keys held directly) */
+    shielded: {
+        mode: "local";
+        /** Unified address (starts with u1) */
+        uAddress: string;
+        /** Whether the local wallet is initialized */
+        initialized: boolean;
+    };
+    /** ZAP1 attestation endpoint */
+    zap1ApiUrl: string;
+}
+export interface ShieldRequest {
+    /** Amount in zatoshis to move from t-addr to shielded pool */
+    amount: number;
+    /** Optional memo for the shielding transaction */
+    memo?: string;
+}
+export interface UnshieldRequest {
+    /** Amount in zatoshis to move from shielded back to t-addr */
+    amount: number;
+    /** Optional memo */
+    memo?: string;
+}
+export interface ShieldResult {
+    /** Zcash transaction ID */
+    txid: string;
+    /** Direction */
+    direction: "shield" | "unshield";
+    /** Amount moved */
+    amount: number;
+    /** ZAP1 attestation leaf hash */
+    leafHash?: string;
+}
+/**
+ * Create a hybrid wallet - MPC for transparent, local for shielded.
+ *
+ * The transparent side is an Ika dWallet (already created via createWallet).
+ * The shielded side connects to the local Zebra/Zashi wallet.
+ */
+export declare function createHybridWallet(transparentWallet: DWalletHandle, shieldedAddress: string, zap1ApiUrl: string): HybridWallet;
+/**
+ * Sign a transparent transaction through MPC.
+ * Delegates to the Ika sign() function.
+ */
+export declare function signTransparent(config: ZcashIkaConfig, wallet: HybridWallet, sighash: Uint8Array): Promise<SignResult>;
+/**
+ * Shield ZEC - move from MPC-custody t-addr to local shielded pool.
+ *
+ * Flow:
+ * 1. Build transparent tx: t-addr -> shielded address
+ * 2. Compute sighash (DoubleSHA256)
+ * 3. Sign via Ika MPC (secp256k1)
+ * 4. Broadcast via Zebra
+ * 5. Attest via ZAP1 as AGENT_ACTION
+ *
+ * After shielding, the ZEC is in the local Orchard wallet.
+ * Private from that point forward.
+ */
+export declare function shield(config: ZcashIkaConfig, wallet: HybridWallet, request: ShieldRequest): Promise<ShieldResult>;
+/**
+ * Unshield ZEC - move from local shielded pool back to MPC-custody t-addr.
+ *
+ * Flow:
+ * 1. Build Orchard tx: shielded -> t-addr (signed locally, RedPallas)
+ * 2. Broadcast via Zebra
+ * 3. Attest via ZAP1 as AGENT_ACTION
+ *
+ * After unshielding, the ZEC is back under MPC custody.
+ * The MPC can then send it to BTC, ETH, or another t-addr.
+ */
+export declare function unshield(config: ZcashIkaConfig, wallet: HybridWallet, request: UnshieldRequest): Promise<ShieldResult>;
+/**
+ * Attest a custody operation to ZAP1.
+ */
+export declare function attestCustodyOp(zap1ApiUrl: string, zap1ApiKey: string, op: {
+    direction: "shield" | "unshield";
+    txid: string;
+    amount: number;
+    walletId: string;
+}): Promise<string | null>;

package/dist/hybrid.js

@@ -0,0 +1,148 @@
+/**
+ * Hybrid custody model for Zcash agents.
+ *
+ * Two custody paths, one interface:
+ *
+ * TRANSPARENT (secp256k1 via Ika MPC):
+ *   - t-addr transactions signed through 2PC-MPC
+ *   - Neither party holds the full key
+ *   - Policy enforced by Sui Move contract
+ *   - Same key signs BTC and ETH
+ *
+ * SHIELDED (RedPallas via local Orchard wallet):
+ *   - Orchard transactions signed locally (direct key)
+ *   - Ika cannot sign RedPallas (Pallas curve not supported)
+ *   - Privacy from Zcash protocol, not from MPC
+ *   - Every shielded spend attested to ZAP1
+ *
+ * The gap:
+ *   Orchard uses RedPallas on the Pallas curve. Ika supports secp256k1,
+ *   Ed25519, secp256r1, and Ristretto. None of these are Pallas.
+ *   Until an MPC network adds Pallas curve support, shielded custody
+ *   requires holding keys directly.
+ *
+ * The bridge:
+ *   shield()  - move ZEC from t-addr (MPC) to shielded pool (local wallet)
+ *   unshield() - move ZEC from shielded back to t-addr (for MPC custody)
+ *   Both operations attested on-chain via ZAP1.
+ */
+import { sign } from "./index.js";
+/**
+ * Create a hybrid wallet - MPC for transparent, local for shielded.
+ *
+ * The transparent side is an Ika dWallet (already created via createWallet).
+ * The shielded side connects to the local Zebra/Zashi wallet.
+ */
+export function createHybridWallet(transparentWallet, shieldedAddress, zap1ApiUrl) {
+    return {
+        transparent: {
+            mode: "mpc",
+            walletId: transparentWallet.id,
+            publicKey: transparentWallet.publicKey,
+            tAddress: transparentWallet.address,
+            encryptionSeed: transparentWallet.encryptionSeed,
+        },
+        shielded: {
+            mode: "local",
+            uAddress: shieldedAddress,
+            initialized: shieldedAddress.startsWith("u1"),
+        },
+        zap1ApiUrl,
+    };
+}
+/**
+ * Sign a transparent transaction through MPC.
+ * Delegates to the Ika sign() function.
+ */
+export async function signTransparent(config, wallet, sighash) {
+    return sign(config, {
+        messageHash: sighash,
+        walletId: wallet.transparent.walletId,
+        chain: "zcash-transparent",
+        encryptionSeed: wallet.transparent.encryptionSeed,
+    });
+}
+/**
+ * Shield ZEC - move from MPC-custody t-addr to local shielded pool.
+ *
+ * Flow:
+ * 1. Build transparent tx: t-addr -> shielded address
+ * 2. Compute sighash (DoubleSHA256)
+ * 3. Sign via Ika MPC (secp256k1)
+ * 4. Broadcast via Zebra
+ * 5. Attest via ZAP1 as AGENT_ACTION
+ *
+ * After shielding, the ZEC is in the local Orchard wallet.
+ * Private from that point forward.
+ */
+export async function shield(config, wallet, request) {
+    if (!wallet.shielded.initialized) {
+        throw new Error("Shielded wallet not initialized. Provide a valid u1 address.");
+    }
+    if (!config.zebraRpcUrl) {
+        throw new Error("shield() requires zebraRpcUrl for building and broadcasting the tx.");
+    }
+    // The full pipeline:
+    // 1. z_listunspent on the t-addr to find UTXOs
+    // 2. Build raw tx spending to the shielded address
+    // 3. Extract sighash
+    // 4. sign() via Ika MPC
+    // 5. Attach signature
+    // 6. sendrawtransaction
+    // 7. Attest to ZAP1
+    throw new Error("shield() requires Zcash transparent tx builder (zcash-primitives or librustzcash). " +
+        "Use sign() with a pre-built sighash for now. " +
+        "The shielding tx is a standard t-addr -> Orchard spend.");
+}
+/**
+ * Unshield ZEC - move from local shielded pool back to MPC-custody t-addr.
+ *
+ * Flow:
+ * 1. Build Orchard tx: shielded -> t-addr (signed locally, RedPallas)
+ * 2. Broadcast via Zebra
+ * 3. Attest via ZAP1 as AGENT_ACTION
+ *
+ * After unshielding, the ZEC is back under MPC custody.
+ * The MPC can then send it to BTC, ETH, or another t-addr.
+ */
+export async function unshield(config, wallet, request) {
+    if (!config.zebraRpcUrl) {
+        throw new Error("unshield() requires zebraRpcUrl.");
+    }
+    // Unshielding is done entirely locally - no MPC involved.
+    // The Orchard wallet holds keys directly and signs with RedPallas.
+    // z_sendmany from the shielded address to the t-addr.
+    throw new Error("unshield() requires connection to local Zebra wallet with Orchard spending keys. " +
+        "Use z_sendmany via Zebra RPC directly for now.");
+}
+/**
+ * Attest a custody operation to ZAP1.
+ */
+export async function attestCustodyOp(zap1ApiUrl, zap1ApiKey, op) {
+    try {
+        const resp = await fetch(`${zap1ApiUrl}/attest`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${zap1ApiKey}`,
+            },
+            body: JSON.stringify({
+                event_type: "AGENT_ACTION",
+                wallet_hash: op.walletId,
+                input_hash: op.txid,
+                memo: JSON.stringify({
+                    action: op.direction,
+                    amount: op.amount,
+                    custody: op.direction === "shield" ? "mpc->local" : "local->mpc",
+                }),
+            }),
+        });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        return data.leaf_hash || null;
+    }
+    catch {
+        return null;
+    }
+}