@frontiercompute/zcash-ika 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,39 +1,44 @@
 /**
  * @frontiercompute/zcash-ika
  *
- * Zero-trust custody for Zcash and Bitcoin. Born shielded, stay shielded.
+ * Split-key custody for Zcash transparent, Bitcoin, and EVM chains.
  *
- * Two dWallets, one operator:
- * - Ed25519 dWallet -> Zcash Orchard (shielded ZEC)
- * - secp256k1 dWallet -> Bitcoin (BTC) + Zcash transparent (t-addr)
- *
- * Neither key ever exists whole. Both chains signed through Ika 2PC-MPC.
+ * One secp256k1 dWallet signs for all three chain families.
+ * Neither key half can sign alone. Policy enforced by Sui Move contract.
  * Every operation attested to Zcash via ZAP1.
  *
  * Built on Ika's 2PC-MPC network (Sui).
+ *
+ * NOTE: Zcash shielded (Orchard) uses RedPallas on the Pallas curve,
+ * which Ika does not currently support. Only transparent ZEC (secp256k1)
+ * is viable through this package today.
  */
 export { Curve, Hash, SignatureAlgorithm, IkaClient, IkaTransaction, UserShareEncryptionKeys, getNetworkConfig, createClassGroupsKeypair, createRandomSessionIdentifier, prepareDKG, prepareDKGAsync, prepareDKGSecondRound, prepareDKGSecondRoundAsync, createDKGUserOutput, publicKeyFromDWalletOutput, parseSignatureFromSignOutput, } from "@ika.xyz/sdk";
-export type Chain = "zcash-shielded" | "zcash-transparent" | "bitcoin";
+export { fetchUTXOs, selectUTXOs, buildUnsignedTx, attachSignatures, broadcastTx, estimateFee, BRANCH_ID, } from "./tx-builder.js";
+export type { UTXO } from "./tx-builder.js";
+export type Chain = "zcash-transparent" | "bitcoin" | "ethereum";
 export interface ZcashIkaConfig {
     /** Ika network: mainnet or testnet */
     network: "mainnet" | "testnet";
-    /** Sui RPC URL (defaults to Ika's network config) */
+    /** Sui RPC URL (defaults to PublicNode) */
     suiRpcUrl?: string;
+    /** Sui private key (base64 encoded, suiprivkey1...) */
+    suiPrivateKey: string;
+    /** IKA coin object ID (required for Ika transactions, separate from SUI gas) */
+    ikaCoinId?: string;
     /** Zebra node RPC for broadcasting Zcash txs */
-    zebraRpcUrl: string;
+    zebraRpcUrl?: string;
     /** ZAP1 API for attestation */
-    zap1ApiUrl: string;
+    zap1ApiUrl?: string;
     /** ZAP1 API key for write operations */
     zap1ApiKey?: string;
 }
-/** Parameters for dWallet creation per chain */
+/** Parameters for dWallet creation per chain.
+ *
+ * All chains use secp256k1 - one dWallet signs for all of them.
+ * Zcash shielded (Orchard) requires RedPallas on the Pallas curve,
+ * which is not available in Ika's current MPC. Transparent ZEC works. */
 export declare const CHAIN_PARAMS: {
-    readonly "zcash-shielded": {
-        readonly curve: "ED25519";
-        readonly algorithm: "EdDSA";
-        readonly hash: "SHA512";
-        readonly description: "Zcash Orchard shielded pool (Ed25519/EdDSA)";
-    };
     readonly "zcash-transparent": {
         readonly curve: "SECP256K1";
         readonly algorithm: "ECDSASecp256k1";
@@ -46,11 +51,30 @@ export declare const CHAIN_PARAMS: {
         readonly hash: "DoubleSHA256";
         readonly description: "Bitcoin (secp256k1/ECDSA, DoubleSHA256)";
     };
+    readonly ethereum: {
+        readonly curve: "SECP256K1";
+        readonly algorithm: "ECDSASecp256k1";
+        readonly hash: "KECCAK256";
+        readonly description: "Ethereum/EVM (secp256k1/ECDSA, KECCAK256)";
+    };
 };
+/**
+ * Derive a Zcash transparent address from a compressed secp256k1 public key.
+ *
+ * Same as Bitcoin P2PKH but with Zcash 2-byte version prefix:
+ *   mainnet 0x1cb8 (t1...), testnet 0x1d25 (tm...)
+ *
+ * Steps:
+ *   1. SHA256(pubkey) then RIPEMD160 = 20-byte hash
+ *   2. Prepend 2-byte version
+ *   3. Double-SHA256 checksum (first 4 bytes)
+ *   4. Base58 encode (version + hash + checksum)
+ */
+export declare function deriveZcashAddress(publicKey: Uint8Array, network?: "mainnet" | "testnet"): string;
 export interface DWalletHandle {
     /** dWallet object ID on Sui */
     id: string;
-    /** Raw public key bytes */
+    /** Raw public key bytes (compressed secp256k1) */
     publicKey: Uint8Array;
     /** Which chain this wallet targets */
     chain: Chain;
@@ -58,14 +82,14 @@ export interface DWalletHandle {
     address: string;
     /** Ika network (mainnet/testnet) */
     network: string;
+    /** Encryption seed (hex) - save this for signing */
+    encryptionSeed: string;
 }
 export interface DualCustody {
-    /** Shielded ZEC wallet (Ed25519 dWallet -> Orchard address) */
-    shielded: DWalletHandle;
-    /** Bitcoin wallet (secp256k1 dWallet -> BTC address) */
-    bitcoin: DWalletHandle;
-    /** Operator ID (shared across both wallets) */
-    operatorId: string;
+    /** Zcash transparent + Bitcoin wallet (secp256k1 dWallet) */
+    primary: DWalletHandle;
+    /** Operator Sui address */
+    operatorAddress: string;
 }
 export interface SpendPolicy {
     /** Max zatoshis (or satoshis) per single transaction */
@@ -78,7 +102,7 @@ export interface SpendPolicy {
     approvalThreshold: number;
 }
 export interface SpendRequest {
-    /** Recipient address (Orchard UA, t-addr, or BTC address) */
+    /** Recipient address (t-addr, BTC address, or ETH address) */
     to: string;
     /** Amount in smallest unit (zatoshis or satoshis) */
     amount: number;
@@ -100,72 +124,100 @@ export interface SignRequest {
     messageHash: Uint8Array;
     /** Which dWallet to sign with */
     walletId: string;
-    /** Chain determines signing params */
+    /** Chain determines signing params (hash algo) */
     chain: Chain;
+    /** Encryption seed (hex) from wallet creation */
+    encryptionSeed: string;
+    /** dWalletCap ID (ownership proof on Sui) */
+    dWalletCapId?: string;
 }
 export interface SignResult {
-    /** DER-encoded signature (ECDSA) or raw Ed25519 signature */
+    /** DER-encoded ECDSA signature */
     signature: Uint8Array;
     /** Public key used */
     publicKey: Uint8Array;
+    /** Sui transaction digest for the sign request */
+    signTxDigest: string;
 }
 /**
- * Create a dual-custody setup: one shielded ZEC wallet + one BTC wallet.
- * Same operator controls both via Ika split-key.
+ * Create a split-key custody wallet.
+ * One secp256k1 dWallet signs for Zcash transparent, Bitcoin, and EVM.
  *
- * Flow per wallet:
- * 1. Generate UserShareEncryptionKeys from operator seed
- * 2. Run DKG on Ika (2PC-MPC key generation)
- * 3. Extract public key, derive chain-specific address
- * 4. Attest wallet creation via ZAP1
+ * Returns the dWallet handle with ID, public key, and encryption seed.
+ * Save the encryption seed - you need it for signing.
  */
-export declare function createDualCustody(config: ZcashIkaConfig, operatorSeed: Uint8Array): Promise<DualCustody>;
+export declare function createDualCustody(config: ZcashIkaConfig, _operatorSeed?: Uint8Array): Promise<DualCustody>;
 /**
- * Create a single dWallet for a specific chain.
+ * Create a single secp256k1 dWallet on Ika.
+ *
+ * Flow:
+ * 1. Generate encryption keys from random seed
+ * 2. Prepare DKG locally (WASM crypto)
+ * 3. Submit DKG request to Ika network
+ * 4. Poll until dWallet reaches Active state
+ * 5. Extract compressed public key
  */
-export declare function createWallet(config: ZcashIkaConfig, chain: Chain, operatorSeed: Uint8Array): Promise<DWalletHandle>;
+export declare function createWallet(config: ZcashIkaConfig, chain: Chain, _operatorSeed?: Uint8Array): Promise<DWalletHandle>;
 /**
  * Sign a message hash through Ika 2PC-MPC.
  *
- * The operator provides their seed, Ika provides the network share.
- * Neither party ever sees the full private key.
+ * Two on-chain transactions:
+ * 1. Request presign (pre-compute MPC ephemeral key share)
+ * 2. Approve message + request signature
  *
- * Flow:
- * 1. Create presign session on Ika
- * 2. Compute partial user signature locally
- * 3. Submit to Ika coordinator
- * 4. Poll for completion
- * 5. Extract full signature from sign output
+ * The operator provides their encryption seed, Ika provides the network share.
+ * Neither party ever sees the full private key.
+ */
+export declare function sign(config: ZcashIkaConfig, request: SignRequest): Promise<SignResult>;
+export interface PolicyResult {
+    /** SpendPolicy shared object ID on Sui */
+    policyId: string;
+    /** PolicyCap object ID (owner holds this to manage policy) */
+    capId: string;
+    /** Sui transaction digest */
+    txDigest: string;
+}
+export interface PolicyState {
+    policyId: string;
+    dwalletId: string;
+    owner: string;
+    maxPerTx: number;
+    maxDaily: number;
+    dailySpent: number;
+    windowStart: number;
+    allowedRecipients: string[];
+    frozen: boolean;
+}
+/**
+ * Set spending policy on a dWallet.
+ * Creates a SpendPolicy shared object and PolicyCap on Sui.
+ * The PolicyCap is transferred to the caller.
  */
-export declare function sign(config: ZcashIkaConfig, operatorSeed: Uint8Array, request: SignRequest): Promise<SignResult>;
+export declare function setPolicy(config: ZcashIkaConfig, walletId: string, policy: SpendPolicy): Promise<PolicyResult>;
 /**
- * Set spending policy on the dWallet.
- * Policy enforced at Sui Move contract level.
- * The agent cannot bypass it - the contract holds the DWalletCap.
+ * Query a SpendPolicy object and check if a spend would be allowed.
+ * Returns the full policy state plus a boolean for the specific check.
  */
-export declare function setPolicy(config: ZcashIkaConfig, walletId: string, policy: SpendPolicy): Promise<string>;
+export declare function checkPolicy(config: ZcashIkaConfig, policyId: string, amount?: number, recipient?: string): Promise<PolicyState & {
+    allowed: boolean;
+}>;
 /**
- * Spend from a shielded ZEC wallet.
+ * Spend from a Zcash transparent wallet.
  *
- * 1. Build Zcash Orchard transaction (zcash_primitives)
- * 2. Extract sighash
- * 3. Sign via Ika 2PC-MPC (Ed25519/EdDSA)
- * 4. Attach signature to transaction
+ * Full pipeline:
+ * 1. Fetch UTXOs from Zebra
+ * 2. Build unsigned TX, compute ZIP 244 sighashes
+ * 3. Sign each sighash via Ika 2PC-MPC
+ * 4. Attach signatures, serialize signed TX
  * 5. Broadcast via Zebra sendrawtransaction
- * 6. Attest via ZAP1 as AGENT_ACTION
+ * 6. Attest to ZAP1 as AGENT_ACTION
  */
-export declare function spendShielded(config: ZcashIkaConfig, walletId: string, operatorSeed: Uint8Array, request: SpendRequest): Promise<SpendResult>;
+export declare function spendTransparent(config: ZcashIkaConfig, walletId: string, encryptionSeed: string, request: SpendRequest): Promise<SpendResult>;
 /**
  * Spend from a Bitcoin wallet.
- *
- * 1. Build Bitcoin transaction
- * 2. Compute sighash (DoubleSHA256)
- * 3. Sign via Ika 2PC-MPC (secp256k1/ECDSA)
- * 4. Attach signature
- * 5. Broadcast to Bitcoin network
- * 6. Attest via ZAP1 as AGENT_ACTION
+ * Same MPC flow as Zcash transparent - DoubleSHA256 sighash, ECDSA signature.
  */
-export declare function spendBitcoin(config: ZcashIkaConfig, walletId: string, operatorSeed: Uint8Array, request: SpendRequest): Promise<SpendResult>;
+export declare function spendBitcoin(config: ZcashIkaConfig, walletId: string, encryptionSeed: string, request: SpendRequest): Promise<SpendResult>;
 /**
  * Verify the wallet's attestation history via ZAP1.
  * Works today against the live API.