@ilalv3/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { credentialStatus } from "./commands/credential.js";
+import { credentialProve } from "./commands/prove.js";
+import { mintCredential, renewCredential } from "./commands/mint.js";
+import { proofMint, proofRenew } from "./commands/proof.js";
+import { sessionSign } from "./commands/session.js";
+import { poolPolicySet, poolPolicyGet } from "./commands/pool.js";
+import { deploy } from "./commands/deploy.js";
+import { demo, demoCheck } from "./commands/demo.js";
+import { init } from "./commands/init.js";
+import { status } from "./commands/status.js";
+import { swap } from "./commands/swap.js";
+import { addLiquidity, removeLiquidity } from "./commands/liquidity.js";
+import { fmt } from "./ui.js";
+import { COINBASE_SCHEMA_UID } from "./constants.js";
+const program = new Command();
+program
+    .name("ilal")
+    .description("ILAL Protocol CLI — Uniswap v4 compliance hook toolkit")
+    .version("0.1.0")
+    .addHelpText("before", `\n  ${fmt.bold(fmt.cyan("◆"))} ${fmt.bold("ILAL Protocol")}  ${fmt.gray("Uniswap v4 Compliance Hook")}\n`);
+// ─── init ─────────────────────────────────────────────────────────────────────
+program
+    .command("init")
+    .description("Create .ilal.json config — save issuer, chain, hook addresses")
+    .option("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-H, --hook <address>", "ComplianceHook contract address")
+    .option("-R, --registry <address>", "PolicyRegistry contract address")
+    .option("--router <address>", "ILALRouter contract address")
+    .option("--treasury <address>", "ILAL protocol fee treasury address")
+    .option("--token-a <address>", "Demo token A / currency0 address")
+    .option("--token-b <address>", "Demo token B / currency1 address")
+    .option("--pool-id <bytes32>", "Default Uniswap v4 pool ID")
+    .option("--fee <uint24>", "Pool fee tier; 8388608 means dynamic fee")
+    .option("--tick-spacing <int24>", "Pool tick spacing")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("--circuit-dir <path>", "Path to circuits/build directory")
+    .option("-f, --force", "Overwrite existing .ilal.json", false)
+    .action(async (opts) => {
+    await init(opts).catch(err);
+});
+// ─── status ───────────────────────────────────────────────────────────────────
+program
+    .command("status")
+    .description("Dashboard: credential validity, issuer config, pool policy")
+    .option("-w, --wallet <address>", "Wallet address to check")
+    .option("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-H, --hook <address>", "ComplianceHook contract address")
+    .option("-R, --registry <address>", "PolicyRegistry contract address")
+    .option("-p, --pool <bytes32>", "Pool ID to check policy for")
+    .option("-c, --chain <chainId>", "Chain ID", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .action(async (opts) => {
+    await status(opts).catch(err);
+});
+// ─── demo ─────────────────────────────────────────────────────────────────────
+const demoCommand = program
+    .command("demo")
+    .description("Preview and preflight the ILAL institutional DeFi demo")
+    .option("--commands", "Show the live command sequence after the preview", false)
+    .action(async (opts) => {
+    await demo(opts).catch(err);
+});
+demoCommand
+    .command("check")
+    .description("Check whether the configured live demo can run on-chain")
+    .option("-w, --wallet <address>", "Wallet address to check (defaults to PRIVATE_KEY address)")
+    .option("-k, --private-key <hex>", "Private key used only to derive the wallet address")
+    .action(async (opts) => {
+    await demoCheck(opts).catch(err);
+});
+const err = (e) => {
+    console.error(fmt.red(`\nError: ${e instanceof Error ? e.message : String(e)}\n`));
+    process.exit(1);
+};
+// ─── credential ───────────────────────────────────────────────────────────────
+const credential = program.command("credential").description("Manage compliance credentials (CNF)");
+credential
+    .command("status <wallet>")
+    .description("Check CNF credential status for a wallet")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .action(async (wallet, opts) => {
+    await credentialStatus({ wallet, ...opts }).catch(err);
+});
+credential
+    .command("prove")
+    .description("Generate ZK proof and mint/renew CNF in one step (no shell scripts needed)")
+    .option("-w, --wallet <address>", "Wallet address to prove eligibility for")
+    .option("-i, --issuer <address>", "CNFIssuer contract address (or set in .ilal.json)")
+    .option("-a, --action <action>", "mint or renew (default: auto-detect)")
+    .option("--update-root", "Call setMerkleRoot on-chain before minting (requires owner key)", false)
+    .option("--circuit-dir <path>", "Path to circuits/build directory (auto-detected by default)")
+    .option("--out-dir <path>", "Directory to write proof/witness files")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .action(async (opts) => {
+    await credentialProve(opts).catch(err);
+});
+credential
+    .command("mint")
+    .description("Mint a CNF credential using a Coinbase EAS attestation")
+    .requiredOption("-a, --attestation <uid>", "EAS attestation UID (0x + 64 hex chars)")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--simulate", "Verify attestation without sending tx", false)
+    .action(async (opts) => {
+    await mintCredential(opts).catch(err);
+});
+credential
+    .command("renew")
+    .description("Renew an existing CNF credential with a fresh EAS attestation")
+    .requiredOption("-a, --attestation <uid>", "EAS attestation UID (0x + 64 hex chars)")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--simulate", "Verify attestation without sending tx", false)
+    .action(async (opts) => {
+    await renewCredential(opts).catch(err);
+});
+// ─── proof ────────────────────────────────────────────────────────────────────
+const proof = program.command("proof").description("ZK proof credential operations (Phase 4)");
+proof
+    .command("mint")
+    .description("Mint a CNF using a Groth16 ZK proof (snarkjs format)")
+    .requiredOption("-p, --proof <path>", "Path to snarkjs proof.json")
+    .requiredOption("-P, --public <path>", "Path to snarkjs public.json")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .action(async (opts) => {
+    await proofMint(opts).catch(err);
+});
+proof
+    .command("renew")
+    .description("Renew a CNF using a Groth16 ZK proof (snarkjs format)")
+    .requiredOption("-p, --proof <path>", "Path to snarkjs proof.json")
+    .requiredOption("-P, --public <path>", "Path to snarkjs public.json")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .action(async (opts) => {
+    await proofRenew(opts).catch(err);
+});
+// ─── session ──────────────────────────────────────────────────────────────────
+const session = program.command("session").description("Session token operations");
+session
+    .command("sign")
+    .description("Sign an EIP-712 session token locally — no ILAL API call")
+    .requiredOption("-p, --pool <bytes32>", "Pool ID (bytes32 hex)")
+    .requiredOption("-a, --action <action>", "Action: swap | addLiquidity | removeLiquidity")
+    .requiredOption("-H, --hook <address>", "ComplianceHook contract address")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .option("-u, --user <address>", "Trader address (defaults to key's address)")
+    .option("--caller <address>", "Authorized v4 caller (defaults to user; use ILALRouter address for router flows)")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-t, --ttl <seconds>", "Session lifetime in seconds", "600")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .action(async (opts) => {
+    await sessionSign({ ...opts, ttl: parseInt(opts.ttl, 10) }).catch(err);
+});
+// ─── pool ─────────────────────────────────────────────────────────────────────
+const pool = program.command("pool").description("Pool operator commands");
+const policy = pool.command("policy").description("Pool compliance policy commands");
+policy
+    .command("set")
+    .description("Register a compliance policy for a pool (pool operator only)")
+    .requiredOption("-p, --pool <bytes32>", "Pool ID (bytes32 hex)")
+    .requiredOption("-i, --issuer <address>", "CNFIssuer contract address")
+    .requiredOption("-R, --registry <address>", "PolicyRegistry contract address")
+    .option("-T, --cred-type <bytes32>", "Required credential type", COINBASE_SCHEMA_UID)
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .action(async (opts) => {
+    await poolPolicySet(opts).catch(err);
+});
+policy
+    .command("get")
+    .description("Read the compliance policy for a pool")
+    .requiredOption("-p, --pool <bytes32>", "Pool ID (bytes32 hex)")
+    .requiredOption("-R, --registry <address>", "PolicyRegistry contract address")
+    .option("-c, --chain <chainId>", "Chain ID", "8453")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .action(async (opts) => {
+    await poolPolicyGet(opts).catch(err);
+});
+pool
+    .command("add-liquidity")
+    .description("Add liquidity to a compliant Uniswap v4 pool through the ILAL channel")
+    .requiredOption("--tick-lower <int24>", "Lower tick of position")
+    .requiredOption("--tick-upper <int24>", "Upper tick of position")
+    .requiredOption("--liquidity <uint128>", "Liquidity amount to add (in raw units)")
+    .option("--salt <bytes32>", "Position salt for multiple positions at the same range", "0x0000000000000000000000000000000000000000000000000000000000000000")
+    .option("--pool-id <bytes32>", "Pool ID (or set in .ilal.json)")
+    .option("--router <address>", "ILALRouter address (or set in .ilal.json)")
+    .option("-H, --hook <address>", "ComplianceHook address (or set in .ilal.json)")
+    .option("-i, --issuer <address>", "CNFIssuer address (or set in .ilal.json)")
+    .option("--token-a <address>", "currency0 token address (or set in .ilal.json)")
+    .option("--token-b <address>", "currency1 token address (or set in .ilal.json)")
+    .option("--fee <uint24>", "Pool fee tier (default: config or 3000; 8388608=dynamic)")
+    .option("--tick-spacing <int24>", "Tick spacing (default: config or 60)")
+    .option("-c, --chain <chainId>", "Chain ID", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--ttl <seconds>", "Session token lifetime in seconds", "600")
+    .action(async (opts) => {
+    await addLiquidity(opts).catch(err);
+});
+pool
+    .command("remove-liquidity")
+    .description("Remove liquidity from a compliant Uniswap v4 pool through the ILAL channel")
+    .requiredOption("--tick-lower <int24>", "Lower tick of position")
+    .requiredOption("--tick-upper <int24>", "Upper tick of position")
+    .requiredOption("--liquidity <uint128>", "Liquidity amount to remove (in raw units)")
+    .option("--salt <bytes32>", "Position salt", "0x0000000000000000000000000000000000000000000000000000000000000000")
+    .option("--pool-id <bytes32>", "Pool ID (or set in .ilal.json)")
+    .option("--router <address>", "ILALRouter address (or set in .ilal.json)")
+    .option("-H, --hook <address>", "ComplianceHook address (or set in .ilal.json)")
+    .option("-i, --issuer <address>", "CNFIssuer address (or set in .ilal.json)")
+    .option("--token-a <address>", "currency0 token address (or set in .ilal.json)")
+    .option("--token-b <address>", "currency1 token address (or set in .ilal.json)")
+    .option("--fee <uint24>", "Pool fee tier (default: config or 3000; 8388608=dynamic)")
+    .option("--tick-spacing <int24>", "Tick spacing (default: config or 60)")
+    .option("-c, --chain <chainId>", "Chain ID", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--ttl <seconds>", "Session token lifetime in seconds", "600")
+    .action(async (opts) => {
+    await removeLiquidity(opts).catch(err);
+});
+// ─── swap ─────────────────────────────────────────────────────────────────────
+program
+    .command("swap")
+    .description("Execute a compliant token swap through the ILAL channel")
+    .requiredOption("--amount-in <amount>", "Input amount in human-readable units (e.g. 100)")
+    .option("--token-in <address>", "Token to sell (defaults to tokenA from config)")
+    .option("--token-a <address>", "currency0 token address (or set in .ilal.json)")
+    .option("--token-b <address>", "currency1 token address (or set in .ilal.json)")
+    .option("--pool-id <bytes32>", "Pool ID (or set in .ilal.json)")
+    .option("--router <address>", "ILALRouter address (or set in .ilal.json)")
+    .option("-H, --hook <address>", "ComplianceHook address (or set in .ilal.json)")
+    .option("-i, --issuer <address>", "CNFIssuer address (or set in .ilal.json)")
+    .option("--fee <uint24>", "Pool fee tier (default: config or 3000; 8388608=dynamic)")
+    .option("--tick-spacing <int24>", "Tick spacing (default: config or 60)")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--ttl <seconds>", "Session token lifetime in seconds", "600")
+    .option("--simulate", "Sign session without sending tx", false)
+    .action(async (opts) => {
+    await swap(opts).catch(err);
+});
+// ─── deploy ───────────────────────────────────────────────────────────────────
+program
+    .command("deploy")
+    .description("Deploy ILAL contracts (PolicyRegistry + CNFIssuer + ComplianceHook)")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "84532")
+    .option("-r, --rpc <url>", "Custom RPC URL")
+    .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
+    .option("--broadcast", "Send transactions (omit for dry run)", false)
+    .option("--verify", "Verify contracts on Etherscan/Basescan", false)
+    .option("--mock", "Use MockEAS for testnet (Base Sepolia only)", false)
+    .option("--wallet-to-seed <address>", "Wallet that receives a seeded test attestation (--mock only)")
+    .option("--contracts-dir <path>", "Path to contracts/ directory")
+    .action(async (opts) => {
+    await deploy(opts).catch(err);
+});
+program.parse();

package/dist/ui.d.ts

@@ -0,0 +1,59 @@
+export declare const fmt: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    addr: (s: string) => string;
+    hash: (s: string) => string;
+    mono: (s: string) => string;
+    percent: (n: number) => string;
+    badge: (s: string, tone?: "green" | "yellow" | "red" | "cyan" | "gray") => string;
+};
+export declare class Spinner {
+    private timer;
+    private frame;
+    private text;
+    constructor(text: string);
+    start(): this;
+    update(text: string): this;
+    private render;
+    succeed(msg?: string): void;
+    fail(msg?: string): void;
+    stop(): void;
+}
+export declare const log: {
+    step: (msg: string) => void;
+    ok: (msg: string) => void;
+    fail: (msg: string) => void;
+    warn: (msg: string) => void;
+    info: (msg: string) => void;
+    line: () => void;
+    gap: () => void;
+    section: (title: string, meta?: string) => void;
+    end: () => void;
+    kv: (key: string, val: string) => void;
+    kvdim: (key: string, val: string) => void;
+    result: (label: string, value: string, tone?: "green" | "yellow" | "red" | "cyan") => void;
+    command: (cmd: string) => void;
+    progress: (label: string, percent: number, tone?: "green" | "yellow" | "red" | "cyan") => void;
+    callout: (title: string, body: string, tone?: "green" | "yellow" | "red" | "cyan") => void;
+    metrics: (items: Array<{
+        label: string;
+        value: string;
+        tone?: "green" | "yellow" | "red" | "cyan" | "gray";
+    }>) => void;
+    deal: (items: Array<{
+        label: string;
+        value: string;
+        note?: string;
+        tone?: "green" | "yellow" | "red" | "cyan" | "gray";
+    }>) => void;
+};
+export declare function header(title: string, subtitle?: string): void;
+export declare function die(msg: string): never;
+export declare function dieOnContract(e: unknown): never;

package/dist/ui.js

@@ -0,0 +1,218 @@
+// ─── ANSI codes ───────────────────────────────────────────────────────────────
+const C = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    blue: "\x1b[34m",
+    white: "\x1b[37m",
+    magenta: "\x1b[35m",
+    clearLine: "\x1b[2K\r",
+};
+const isTTY = process.stdout.isTTY ?? false;
+// ─── Formatters ───────────────────────────────────────────────────────────────
+export const fmt = {
+    bold: (s) => `${C.bold}${s}${C.reset}`,
+    dim: (s) => `${C.dim}${s}${C.reset}`,
+    green: (s) => `${C.green}${s}${C.reset}`,
+    red: (s) => `${C.red}${s}${C.reset}`,
+    yellow: (s) => `${C.yellow}${s}${C.reset}`,
+    cyan: (s) => `${C.cyan}${s}${C.reset}`,
+    gray: (s) => `${C.gray}${s}${C.reset}`,
+    blue: (s) => `${C.blue}${s}${C.reset}`,
+    magenta: (s) => `${C.magenta}${s}${C.reset}`,
+    addr: (s) => fmt.cyan(shortHex(s, 6, 4)),
+    hash: (s) => fmt.gray(shortHex(s, 10, 6)),
+    mono: (s) => fmt.gray(s),
+    percent: (n) => `${Math.max(0, Math.min(100, Math.round(n)))}%`,
+    badge: (s, tone = "cyan") => {
+        const color = tone === "green" ? fmt.green : tone === "yellow" ? fmt.yellow : tone === "red" ? fmt.red : tone === "gray" ? fmt.gray : fmt.cyan;
+        return color(`[${s}]`);
+    },
+};
+function visibleLength(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function shortHex(s, head, tail) {
+    if (!s || s.length <= head + tail + 1)
+        return s;
+    return `${s.slice(0, head)}…${s.slice(-tail)}`;
+}
+function padVisible(s, width) {
+    return s + " ".repeat(Math.max(0, width - visibleLength(s)));
+}
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export class Spinner {
+    timer = null;
+    frame = 0;
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    start() {
+        if (!isTTY) {
+            process.stdout.write(`  ${fmt.gray("›")} ${this.text}\n`);
+            return this;
+        }
+        process.stdout.write("\x1b[?25l"); // hide cursor
+        this.render();
+        this.timer = setInterval(() => this.render(), 80);
+        return this;
+    }
+    update(text) {
+        this.text = text;
+        return this;
+    }
+    render() {
+        const frame = fmt.cyan(FRAMES[this.frame % FRAMES.length]);
+        process.stdout.write(`${C.clearLine}  ${frame} ${this.text}`);
+        this.frame++;
+    }
+    succeed(msg) {
+        this.stop();
+        console.log(`  ${fmt.green("✓")} ${msg ?? this.text}`);
+    }
+    fail(msg) {
+        this.stop();
+        console.log(`  ${fmt.red("✗")} ${msg ?? this.text}`);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (isTTY) {
+            process.stdout.write(`${C.clearLine}\x1b[?25h`); // show cursor
+        }
+    }
+}
+// ─── Logger ───────────────────────────────────────────────────────────────────
+export const log = {
+    step: (msg) => console.log(`  ${fmt.gray("›")} ${msg}`),
+    ok: (msg) => console.log(`  ${fmt.green("✓")} ${msg}`),
+    fail: (msg) => console.log(`  ${fmt.red("✗")} ${msg}`),
+    warn: (msg) => console.log(`  ${fmt.yellow("!")} ${msg}`),
+    info: (msg) => console.log(`  ${fmt.gray("·")} ${msg}`),
+    line: () => console.log(fmt.gray("  " + "─".repeat(64))),
+    gap: () => console.log(),
+    section: (title, meta) => console.log(`  ${fmt.cyan("┌")} ${fmt.bold(title)}${meta ? ` ${fmt.gray(meta)}` : ""}`),
+    end: () => console.log(`  ${fmt.cyan("└")} ${fmt.gray("done")}`),
+    kv: (key, val) => console.log(`  ${fmt.gray("│")} ${fmt.gray(padVisible(key, 18))} ${val}`),
+    kvdim: (key, val) => console.log(`  ${fmt.gray("│")} ${fmt.gray(padVisible(key, 18))} ${fmt.dim(val)}`),
+    result: (label, value, tone = "green") => {
+        const color = tone === "green" ? fmt.green : tone === "yellow" ? fmt.yellow : tone === "red" ? fmt.red : fmt.cyan;
+        console.log(`  ${color("●")} ${fmt.bold(label)} ${value}`);
+    },
+    command: (cmd) => console.log(`  ${fmt.gray("$")} ${fmt.cyan(cmd)}`),
+    progress: (label, percent, tone = "cyan") => {
+        const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+        const width = 28;
+        const filled = Math.round((clamped / 100) * width);
+        const color = tone === "green" ? fmt.green : tone === "yellow" ? fmt.yellow : tone === "red" ? fmt.red : fmt.cyan;
+        const bar = color("█".repeat(filled)) + fmt.gray("░".repeat(width - filled));
+        console.log(`  ${fmt.gray("│")} ${fmt.gray(padVisible(label, 18))} ${bar} ${color(`${clamped}%`)}`);
+    },
+    callout: (title, body, tone = "cyan") => {
+        const color = tone === "green" ? fmt.green : tone === "yellow" ? fmt.yellow : tone === "red" ? fmt.red : fmt.cyan;
+        console.log(`  ${color("◆")} ${fmt.bold(title)} ${body}`);
+    },
+    metrics: (items) => {
+        const width = 20;
+        const cells = items.map((item) => {
+            const color = item.tone === "green" ? fmt.green
+                : item.tone === "yellow" ? fmt.yellow
+                    : item.tone === "red" ? fmt.red
+                        : item.tone === "gray" ? fmt.gray
+                            : fmt.cyan;
+            return `${fmt.gray(item.label)} ${color(fmt.bold(item.value))}`;
+        });
+        console.log(`  ${cells.map((cell) => padVisible(cell, width)).join(fmt.gray("│ "))}`);
+    },
+    deal: (items) => {
+        const width = 22;
+        console.log(`  ${fmt.cyan("╭")}${fmt.cyan("─".repeat(70))}${fmt.cyan("╮")}`);
+        for (const item of items) {
+            const color = item.tone === "green" ? fmt.green
+                : item.tone === "yellow" ? fmt.yellow
+                    : item.tone === "red" ? fmt.red
+                        : item.tone === "gray" ? fmt.gray
+                            : fmt.cyan;
+            const left = fmt.gray(padVisible(item.label, width));
+            const right = `${color(fmt.bold(item.value))}${item.note ? ` ${fmt.gray(item.note)}` : ""}`;
+            console.log(`  ${fmt.cyan("│")} ${left} ${padVisible(right, 46)}${fmt.cyan("│")}`);
+        }
+        console.log(`  ${fmt.cyan("╰")}${fmt.cyan("─".repeat(70))}${fmt.cyan("╯")}`);
+    },
+};
+// ─── Header ───────────────────────────────────────────────────────────────────
+export function header(title, subtitle) {
+    console.log();
+    const brand = `${fmt.bold(fmt.cyan("ILAL"))} ${fmt.gray("Institutional Liquidity Access Layer")}`;
+    const slogan = `${fmt.green("Compliance is the hook.")} ${fmt.gray("Just prove it and swap.")}`;
+    const heading = `${fmt.bold(title)}${subtitle ? ` ${fmt.badge(subtitle, "gray")}` : ""}`;
+    const width = Math.max(70, visibleLength(brand), visibleLength(slogan), visibleLength(heading)) + 2;
+    console.log(fmt.cyan(`  ╭${"─".repeat(width)}╮`));
+    console.log(`${fmt.cyan("  │")} ${padVisible(brand, width - 1)}${fmt.cyan("│")}`);
+    console.log(`${fmt.cyan("  │")} ${padVisible(slogan, width - 1)}${fmt.cyan("│")}`);
+    console.log(`${fmt.cyan("  ├")}${fmt.cyan("─".repeat(width))}${fmt.cyan("┤")}`);
+    console.log(`${fmt.cyan("  │")} ${padVisible(heading, width - 1)}${fmt.cyan("│")}`);
+    console.log(fmt.cyan(`  ╰${"─".repeat(width)}╯`));
+}
+// ─── Error handling ───────────────────────────────────────────────────────────
+// Known contract error selectors → human-readable messages
+const CONTRACT_ERRORS = {
+    "0x724efe91": "Credential already exists — use `ilal credential prove` to renew",
+    "0xe6567cc4": "ZK verifier not set on CNFIssuer — contact the issuer admin",
+    "0xd611c318": "ZK proof verification failed — regenerate your proof",
+    "0x9dd854d3": "Invalid Merkle root — re-run with --update-root",
+    "0x0432f01c": "Merkle root mismatch — re-run with --update-root",
+    "0xddefae28": "Credential already minted for this wallet",
+    "0x30cd7471": "Not the contract owner",
+    "0xf6f992e7": "Credential has expired — renew it",
+    "0x6773afec": "Invalid public inputs length",
+    "0xfa9f081c": "Schema hash mismatch",
+    "0xb7e9429b": "Issuer hash mismatch",
+    "0x0e917e64": "Wallet hash mismatch — wrong wallet key",
+};
+function parseViemError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (process.env["ILAL_DEBUG"]) {
+        console.error(e);
+    }
+    // Extract 4-byte selector from viem error
+    const selMatch = msg.match(/0x[0-9a-f]{8}/i);
+    if (selMatch) {
+        const readable = CONTRACT_ERRORS[selMatch[0].toLowerCase()];
+        if (readable)
+            return readable;
+    }
+    // Simplify common viem errors
+    if (msg.includes("reverted")) {
+        const inner = msg.match(/reverted.*?["']([^"']+)["']/)?.[1];
+        if (inner)
+            return `Transaction reverted: ${inner}`;
+        return "Transaction reverted — check contract state";
+    }
+    if (msg.includes("insufficient funds"))
+        return "Insufficient gas funds in wallet";
+    if (msg.includes("nonce"))
+        return "Nonce error — try again";
+    if (msg.includes("timeout") || msg.includes("ETIMEDOUT"))
+        return "RPC timeout — try again or use --rpc with a faster endpoint";
+    // Trim the verbose viem stack
+    return msg.split("\n")[0].slice(0, 120);
+}
+export function die(msg) {
+    console.error();
+    console.error(`  ${fmt.red("✗")} ${fmt.bold("Error:")} ${msg}`);
+    console.error();
+    process.exit(1);
+}
+export function dieOnContract(e) {
+    die(parseViemError(e));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ilalv3/cli",
+  "version": "0.1.0",
+  "description": "ILAL Protocol CLI — compliant swaps and credential management for Uniswap v4",
+  "type": "module",
+  "bin": {
+    "ilal": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "uniswap",
+    "uniswap-v4",
+    "compliance",
+    "kyc",
+    "zk-proof",
+    "defi",
+    "rwa",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ilal-protocol/ilal"
+  },
+  "homepage": "https://github.com/ilal-protocol/ilal#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@zk-kit/incremental-merkle-tree": "^1.1.0",
+    "commander": "^12.0.0",
+    "poseidon-lite": "^0.3.0",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  }
+}