@ilalv3/cli 0.2.9 → 0.2.11

package/README.md

@@ -94,7 +94,35 @@ PRIVATE_KEY=0x... ilal credential prove \
   --expires-at 1800000000
 ```
 
-Generates a Groth16 proof locally (~5s), verifies it on-chain, and mints/renews your CNF without revealing identity. If the Merkle root does not match, the issuer/operator must queue the updated root with `ilal oracle propose-root --root <newRoot>` and activate it after the timelock.
+The CLI automatically prepares proving artifacts:
+
+1. Use `--circuit-dir` when a local `circuits/build` directory exists.
+2. Otherwise use the local cache at `~/.ilal/artifacts/ilal-v1`.
+3. If the cache is empty, download hosted artifacts from the ILAL release CDN.
+
+No institution needs to compile Circom in its backend. The flow generates a Groth16 proof locally (~5s), verifies it on-chain, and mints/renews your CNF without revealing identity. If the Merkle root does not match, the issuer/operator must queue the updated root with `ilal oracle propose-root --root <newRoot>` and activate it after the timelock.
+
+Advanced artifact controls:
+
+```bash
+# Use a custom enterprise artifact mirror
+PRIVATE_KEY=0x... ilal credential prove \
+  --wallet 0xYourWallet \
+  --artifact-url https://zk-artifacts.yourdomain.example/ilal-v1
+
+# Pre-seeded/offline mode
+PRIVATE_KEY=0x... ilal credential prove \
+  --wallet 0xYourWallet \
+  --artifact-cache /opt/ilal/artifacts/ilal-v1 \
+  --offline
+```
+
+Equivalent environment variables:
+
+```bash
+ILAL_ARTIFACT_BASE_URL=https://zk-artifacts.yourdomain.example/ilal-v1
+ILAL_ARTIFACT_CACHE=/opt/ilal/artifacts/ilal-v1
+```
 
 ## Command reference
 
@@ -103,7 +131,7 @@ Generates a Groth16 proof locally (~5s), verifies it on-chain, and mints/renews
 | `ilal init` | Create `.ilal.json` with contract addresses |
 | `ilal status` | Dashboard: credential · issuer config · pool policy |
 | `ilal credential zk-root` | Operator helper: compute the ZK Merkle root for a demo wallet/expiry |
-| `ilal credential prove` | Trader flow: local ZK proof → mint or renew CNF |
+| `ilal credential prove` | Trader flow: hosted/cached ZK artifacts → local proof → mint or renew CNF |
 | `ilal credential mint` | Mint CNF via Coinbase EAS attestation |
 | `ilal credential renew` | Renew CNF via EAS attestation |
 | `ilal swap` | Compliant swap via ILALRouter with optional `--min-amount-out` |

package/dist/commands/credential.d.ts

@@ -1,6 +1,6 @@
 export declare function credentialStatus(opts: {
     wallet: string;
-    issuer: string;
+    issuer?: string;
     rpc?: string;
-    chain: string;
+    chain?: string;
 }): Promise<void>;

package/dist/commands/credential.js

@@ -1,6 +1,7 @@
 import { createPublicClient, http, isAddress } from "viem";
 import { base, baseSepolia } from "viem/chains";
 import { fmt, log, die } from "../ui.js";
+import { withConfig } from "../config.js";
 const CNF_ABI = [
     { name: "isValid", type: "function", stateMutability: "view", inputs: [{ name: "wallet", type: "address" }], outputs: [{ type: "bool" }] },
     { name: "credentialOf", type: "function", stateMutability: "view", inputs: [{ name: "wallet", type: "address" }], outputs: [{ name: "tokenId", type: "uint256" }] },
@@ -11,30 +12,39 @@ const CHAINS = {
     "84532": baseSepolia,
 };
 export async function credentialStatus(opts) {
-    if (!isAddress(opts.wallet))
-        die(`Invalid wallet address: ${opts.wallet}`);
-    if (!isAddress(opts.issuer))
-        die(`Invalid issuer address: ${opts.issuer}`);
-    const chain = CHAINS[opts.chain] ?? baseSepolia;
-    const transport = opts.rpc ? http(opts.rpc) : http();
+    const cfg = withConfig(opts);
+    if (!isAddress(cfg.wallet))
+        die(`Invalid wallet address: ${cfg.wallet}`);
+    if (!cfg.issuer)
+        die("CNFIssuer address required. Use --issuer or run `ilal init`.");
+    if (!isAddress(cfg.issuer))
+        die(`Invalid issuer address: ${cfg.issuer}`);
+    const chain = CHAINS[cfg.chain ?? "84532"] ?? baseSepolia;
+    const transport = cfg.rpc ? http(cfg.rpc) : http();
     const client = createPublicClient({ chain, transport });
     console.log();
     console.log(fmt.bold("  ILAL Credential Status"));
     log.line();
-    log.kv("wallet", opts.wallet);
-    log.kv("issuer", opts.issuer);
+    log.kv("wallet", cfg.wallet);
+    log.kv("issuer", cfg.issuer);
     log.kv("chain", chain.name);
     log.line();
     log.step("Querying CNFIssuer on-chain…");
     const [valid, tokenId] = await Promise.all([
-        client.readContract({ address: opts.issuer, abi: CNF_ABI, functionName: "isValid", args: [opts.wallet] }),
-        client.readContract({ address: opts.issuer, abi: CNF_ABI, functionName: "credentialOf", args: [opts.wallet] }),
+        client.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "isValid", args: [cfg.wallet] }),
+        client.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "credentialOf", args: [cfg.wallet] }),
     ]);
     if (tokenId === 0n) {
         log.fail("No credential found for this wallet");
         console.log();
         console.log(fmt.bold("  How to get a CNF credential:"));
         console.log();
+        console.log(fmt.bold("  Demo path — issuer-created MockEAS attestation"));
+        console.log(`  ${fmt.gray("1.")} Ask the issuer/operator to run:`);
+        console.log(`       ${fmt.cyan("PRIVATE_KEY=<issuer-owner> ilal demo attest --wallet " + cfg.wallet)}`);
+        console.log(`  ${fmt.gray("2.")} Then mint with your wallet key:`);
+        console.log(`       ${fmt.cyan("PRIVATE_KEY=<wallet-key> ilal credential mint --attestation <uid>")}`);
+        console.log();
         console.log(fmt.bold("  Path A — Coinbase Verifications (EAS)"));
         console.log(`  ${fmt.gray("1.")} Complete KYC at ${fmt.cyan("https://coinbase.com/onchain-verify")}`);
         console.log(`  ${fmt.gray("2.")} Find your attestation UID on EAS Explorer:`);
@@ -49,12 +59,12 @@ export async function credentialStatus(opts) {
         console.log(`  ${fmt.gray("1.")} Issuer/operator adds wallet to the Merkle tree`);
         console.log(`  ${fmt.gray("2.")} Operator queues root: ${fmt.cyan("ilal oracle propose-root --root <newMerkleRoot>")}`);
         console.log(`  ${fmt.gray("3.")} After timelock, operator activates: ${fmt.cyan("ilal oracle activate-root")}`);
-        console.log(`  ${fmt.gray("4.")} Trader runs: ${fmt.cyan("ilal credential prove --wallet " + opts.wallet)}`);
+        console.log(`  ${fmt.gray("4.")} Trader runs: ${fmt.cyan("ilal credential prove --wallet " + cfg.wallet)}`);
         console.log();
         return;
     }
     const cred = await client.readContract({
-        address: opts.issuer,
+        address: cfg.issuer,
         abi: CNF_ABI,
         functionName: "getCredential",
         args: [tokenId],

package/dist/commands/demo.js

@@ -2,7 +2,7 @@ import { createPublicClient, createWalletClient, decodeEventLog, formatUnits, ht
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
 import { loadConfig } from "../config.js";
-import { die, fmt, header, log, Spinner } from "../ui.js";
+import { die, fmt, header, log, Spinner, requirePrivateKey } from "../ui.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const POOL_MANAGER = {
     "84532": "0x05E73354cFDd6745C338b50BcFDfA3Aa6fA03408",
@@ -442,6 +442,11 @@ export async function demoCheck(opts) {
     }
     if (wallet) {
         log.command(`ilal status --wallet ${wallet}`);
+        if (!credentialReady) {
+            log.info("Credential missing: the issuer must create an attestation before the wallet can mint CNF.");
+            log.command(`PRIVATE_KEY=<issuer-owner> ilal demo attest --wallet ${wallet}`);
+            log.command("PRIVATE_KEY=<wallet-key> ilal credential mint --attestation <uid>");
+        }
         log.command(`ilal session sign --pool ${cfg.poolId ?? "<poolId>"} --action swap --hook ${cfg.hook ?? "<hook>"} --issuer ${cfg.issuer ?? "<issuer>"} --caller ${cfg.router ?? "<router>"}`);
     }
     else {
@@ -454,10 +459,7 @@ export async function demoCheck(opts) {
 export async function demoFaucet(opts) {
     const cfg = loadConfig();
     const chain = CHAINS[cfg.chain ?? "84532"] ?? baseSepolia;
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey || !isHex(rawKey) || rawKey.length !== 66) {
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
-    }
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!cfg.tokenA || !cfg.tokenB || !isAddress(cfg.tokenA) || !isAddress(cfg.tokenB)) {
         die("tokenA/tokenB required. Run `ilal init` with demo token addresses first.");
     }
@@ -492,10 +494,7 @@ export async function demoFaucet(opts) {
 export async function demoAttest(opts) {
     const cfg = loadConfig();
     const chain = CHAINS[cfg.chain ?? "84532"] ?? baseSepolia;
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey || !isHex(rawKey) || rawKey.length !== 66) {
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
-    }
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!cfg.issuer || !isAddress(cfg.issuer))
         die("CNFIssuer required. Run `ilal init` first.");
     if (!isAddress(opts.wallet))

package/dist/commands/deploy.js

@@ -1,7 +1,7 @@
 import { execSync } from "child_process";
 import { existsSync } from "fs";
 import { resolve } from "path";
-import { fmt, log, die } from "../ui.js";
+import { fmt, log, die, requirePrivateKey } from "../ui.js";
 import { EAS_ADDRESSES, COINBASE_ATTESTER, COINBASE_SCHEMA_UID } from "../constants.js";
 const POOL_MANAGERS = {
     "8453": "0x498581ff718922c3f8e6a244956af099b2652b2b", // Base mainnet
@@ -12,9 +12,7 @@ const RPC_URLS = {
     "84532": "https://sepolia.base.org",
 };
 export async function deploy(opts) {
-    const privateKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!privateKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const privateKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     const chainId = opts.chain;
     const poolManager = POOL_MANAGERS[chainId];
     if (!poolManager)

package/dist/commands/init.d.ts

@@ -18,5 +18,7 @@ export declare function init(opts: {
     chain: string;
     rpc?: string;
     circuitDir?: string;
+    artifactUrl?: string;
+    artifactCache?: string;
     force: boolean;
 }): Promise<void>;

package/dist/commands/init.js

@@ -51,6 +51,8 @@ export async function init(opts) {
         tickSpacing: opts.tickSpacing ?? preset["tickSpacing"],
         rpc: opts.rpc ?? preset["rpc"],
         ...(opts.circuitDir ? { circuitDir: opts.circuitDir } : {}),
+        ...(opts.artifactUrl ? { artifactUrl: opts.artifactUrl } : {}),
+        ...(opts.artifactCache ? { artifactCache: opts.artifactCache } : {}),
     };
     // Validate addresses
     for (const [key, val] of Object.entries(config)) {
@@ -86,6 +88,10 @@ export async function init(opts) {
         log.kv("tickSpacing", config.tickSpacing);
     if (config.rpc)
         log.kv("rpc", config.rpc);
+    if (config.artifactUrl)
+        log.kv("artifactUrl", config.artifactUrl);
+    if (config.artifactCache)
+        log.kv("artifactCache", config.artifactCache);
     log.line();
     console.log(`  ${fmt.gray("You can now run commands without --issuer and --chain flags:")}`);
     console.log();

package/dist/commands/liquidity.js

@@ -16,7 +16,7 @@
 import { createPublicClient, createWalletClient, encodeAbiParameters, formatEther, formatUnits, http, isAddress, isHex, parseAbiParameters, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, header, Spinner, die, dieOnContract } from "../ui.js";
+import { fmt, log, header, Spinner, die, dieOnContract, requirePrivateKey } from "../ui.js";
 import { withConfig } from "../config.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 // ─── ABIs ─────────────────────────────────────────────────────────────────────
@@ -128,9 +128,7 @@ function defaultUserSalt(address) {
 // ─── Shared core ──────────────────────────────────────────────────────────────
 async function executeLiquidity(action, opts) {
     const cfg = withConfig(opts);
-    const rawKey = cfg.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const rawKey = requirePrivateKey(cfg.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!cfg.router)
         die("ILALRouter address required. Use --router or set in .ilal.json");
     if (!cfg.hook)
@@ -199,7 +197,7 @@ async function executeLiquidity(action, opts) {
     if (tokenId === 0n) {
         preflightErrors.push("wallet has no CNF credential; mint one before changing liquidity.");
         if (hasEASPath)
-            preflightErrors.push("issuer supports EAS/mock attestation minting: run `ilal credential mint --attestation <uid>`.");
+            preflightErrors.push("issuer supports EAS/mock attestation minting: first ask issuer to run `ilal demo attest --wallet <wallet>`, then run `ilal credential mint --attestation <uid>`.");
         else if (hasZKPath)
             preflightErrors.push(`issuer supports ZK minting: run \`ilal credential prove --wallet ${account.address}\`.`);
         else

package/dist/commands/mint.d.ts

@@ -1,7 +1,7 @@
 declare function sendMintTx(mode: "mint" | "renew", opts: {
     attestation: string;
-    issuer: string;
-    chain: string;
+    issuer?: string;
+    chain?: string;
     rpc?: string;
     privateKey?: string;
     simulate: boolean;

package/dist/commands/mint.js

@@ -1,7 +1,8 @@
 import { createPublicClient, createWalletClient, http, isAddress, isHex, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, die } from "../ui.js";
+import { fmt, log, die, Spinner, requirePrivateKey } from "../ui.js";
+import { withConfig } from "../config.js";
 import { EAS_ADDRESSES, COINBASE_SCHEMA_UID, COINBASE_ATTESTER } from "../constants.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const CNF_ISSUER_ABI = [
@@ -32,25 +33,24 @@ const CNF_ISSUER_ABI = [
 ];
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 async function sendMintTx(mode, opts) {
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
-    if (!isHex(rawKey) || rawKey.length !== 66)
-        die("Invalid private key (expected 0x + 32 bytes).");
-    if (!isAddress(opts.issuer))
-        die(`Invalid issuer address: ${opts.issuer}`);
+    const cfg = withConfig(opts);
+    const rawKey = requirePrivateKey(cfg.privateKey ?? process.env["PRIVATE_KEY"]);
+    if (!cfg.issuer)
+        die("CNFIssuer address required. Use --issuer or run `ilal init`.");
+    if (!isAddress(cfg.issuer))
+        die(`Invalid issuer address: ${cfg.issuer}`);
     if (!isHex(opts.attestation) || opts.attestation.length !== 66)
         die("Attestation UID must be 0x + 32 bytes (64 hex chars).");
-    const chain = CHAINS[opts.chain] ?? baseSepolia;
+    const chain = CHAINS[cfg.chain ?? "84532"] ?? baseSepolia;
     const account = privateKeyToAccount(rawKey);
-    const transport = opts.rpc ? http(opts.rpc) : http();
+    const transport = cfg.rpc ? http(cfg.rpc) : http();
     const publicClient = createPublicClient({ chain, transport });
     const walletClient = createWalletClient({ account, chain, transport });
     console.log();
     console.log(fmt.bold(`  ILAL Credential ${mode === "mint" ? "Mint" : "Renew"}`));
     log.line();
     log.kv("wallet", account.address);
-    log.kv("issuer", opts.issuer);
+    log.kv("issuer", cfg.issuer);
     log.kv("attestation", opts.attestation);
     log.kv("chain", chain.name);
     if (opts.simulate)
@@ -59,9 +59,9 @@ async function sendMintTx(mode, opts) {
     // Verify EAS attestation exists on-chain before sending tx
     log.step("Verifying attestation on EAS…");
     const [issuerEAS, issuerSchema, issuerAttester] = await Promise.all([
-        publicClient.readContract({ address: opts.issuer, abi: CNF_ISSUER_ABI, functionName: "eas" }),
-        publicClient.readContract({ address: opts.issuer, abi: CNF_ISSUER_ABI, functionName: "schemaUID" }),
-        publicClient.readContract({ address: opts.issuer, abi: CNF_ISSUER_ABI, functionName: "trustedAttester" }),
+        publicClient.readContract({ address: cfg.issuer, abi: CNF_ISSUER_ABI, functionName: "eas" }),
+        publicClient.readContract({ address: cfg.issuer, abi: CNF_ISSUER_ABI, functionName: "schemaUID" }),
+        publicClient.readContract({ address: cfg.issuer, abi: CNF_ISSUER_ABI, functionName: "trustedAttester" }),
     ]);
     const easAddress = issuerEAS !== ZERO_ADDRESS ? issuerEAS : EAS_ADDRESSES[chain.id];
     if (!easAddress)
@@ -132,7 +132,7 @@ async function sendMintTx(mode, opts) {
     }
     log.step(`Sending ${mode === "mint" ? "mintWithEAS" : "renewWithEAS"} transaction…`);
     const hash = await walletClient.writeContract({
-        address: opts.issuer,
+        address: cfg.issuer,
         abi: CNF_ISSUER_ABI,
         functionName: mode === "mint" ? "mintWithEAS" : "renewWithEAS",
         args: [opts.attestation],
@@ -144,13 +144,26 @@ async function sendMintTx(mode, opts) {
         log.ok(fmt.bold(fmt.green(`CNF ${mode === "mint" ? "minted" : "renewed"} successfully`)));
         log.kv("tx hash", hash);
         log.kv("block", receipt.blockNumber.toString());
-        const valid = await publicClient.readContract({
-            address: opts.issuer,
-            abi: CNF_ISSUER_ABI,
-            functionName: "isValid",
-            args: [account.address],
-        });
-        log.kv("isValid()", valid ? fmt.green("true ✓") : fmt.red("false"));
+        const validSpin = new Spinner("Waiting for credential validity…").start();
+        let valid = false;
+        for (let attempt = 0; attempt < 6; attempt++) {
+            valid = await publicClient.readContract({
+                address: cfg.issuer,
+                abi: CNF_ISSUER_ABI,
+                functionName: "isValid",
+                args: [account.address],
+            });
+            if (valid)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+        if (valid)
+            validSpin.succeed("Credential active");
+        else {
+            validSpin.succeed("Mint confirmed; credential validity may take a few seconds to appear on this RPC");
+            log.info("Run `ilal credential status <wallet>` if this RPC still shows stale state.");
+        }
+        log.kv("isValid()", valid ? fmt.green("true ✓") : fmt.yellow("pending RPC refresh"));
     }
     else {
         die(`Transaction reverted. Hash: ${hash}`);

package/dist/commands/oracle.js

@@ -25,7 +25,7 @@
 import { createPublicClient, createWalletClient, http, isAddress, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, header, Spinner, die, dieOnContract } from "../ui.js";
+import { fmt, log, header, Spinner, die, dieOnContract, requirePrivateKey } from "../ui.js";
 import { withConfig } from "../config.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const ORACLE_ABI = [
@@ -79,9 +79,7 @@ function txUrl(chain, hash) {
     return baseUrl ? `${baseUrl}/tx/${hash}` : undefined;
 }
 function makeClients(cfg, opts) {
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     const chain = CHAINS[opts.chain ?? "84532"] ?? baseSepolia;
     const transport = opts.rpc ? http(opts.rpc) : http();
     const account = privateKeyToAccount(rawKey);

package/dist/commands/pool.js

@@ -1,7 +1,7 @@
 import { createPublicClient, createWalletClient, http, isAddress, isHex, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, header, Spinner, die } from "../ui.js";
+import { fmt, log, header, Spinner, die, requirePrivateKey } from "../ui.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const REGISTRY_ABI = [
     {
@@ -38,11 +38,7 @@ const REGISTRY_ABI = [
     },
 ];
 export async function poolPolicySet(opts) {
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
-    if (!isHex(rawKey) || rawKey.length !== 66)
-        die("Invalid private key.");
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!isAddress(opts.issuer))
         die(`Invalid issuer address: ${opts.issuer}`);
     if (!isAddress(opts.registry))

package/dist/commands/proof.js

@@ -2,7 +2,7 @@ import { readFileSync } from "fs";
 import { createPublicClient, createWalletClient, encodeAbiParameters, http, isAddress, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, die } from "../ui.js";
+import { fmt, log, die, requirePrivateKey } from "../ui.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const CNF_ISSUER_ABI = [
     {
@@ -73,9 +73,7 @@ export async function proofRenew(opts) {
     await sendProofTx("renew", opts);
 }
 async function sendProofTx(mode, opts) {
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!isAddress(opts.issuer))
         die(`Invalid issuer address: ${opts.issuer}`);
     const chain = CHAINS[opts.chain] ?? baseSepolia;

package/dist/commands/prove.d.ts

@@ -21,6 +21,9 @@ export declare function credentialProve(opts: {
     chain?: string;
     action?: string;
     circuitDir?: string;
+    artifactUrl?: string;
+    artifactCache?: string;
+    offline?: boolean;
     outDir?: string;
     rpc?: string;
     privateKey?: string;

package/dist/commands/prove.js

@@ -16,8 +16,11 @@
  * `ilal oracle activate-root`.
  */
 import { execSync } from "child_process";
-import { mkdirSync, writeFileSync, readFileSync } from "fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { homedir } from "os";
 import { resolve, dirname } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 import { fileURLToPath } from "url";
 import { createPublicClient, createWalletClient, encodeAbiParameters, http, isAddress, keccak256, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
@@ -26,12 +29,21 @@ import { base, baseSepolia } from "viem/chains";
 // @ts-ignore — no bundled types for this package
 import { IncrementalMerkleTree } from "@zk-kit/incremental-merkle-tree";
 import { poseidon2, poseidon4 } from "poseidon-lite";
-import { fmt, log, header, Spinner, die, dieOnContract } from "../ui.js";
+import { fmt, log, header, Spinner, die, dieOnContract, requirePrivateKey } from "../ui.js";
 import { withConfig } from "../config.js";
 import { COINBASE_SCHEMA_UID } from "../constants.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CHAINS = { "8453": base, "84532": baseSepolia };
 const DEPTH = 20;
+const DEFAULT_ARTIFACT_URL = "https://unpkg.com/@ilalv3/proving-artifacts@0.1.0";
+const DEFAULT_ARTIFACT_CACHE = resolve(homedir(), ".ilal/artifacts/ilal-v1");
+const PROVING_ARTIFACTS = [
+    { asset: "ilal.zkey", rel: "ilal.zkey", minBytes: 50_000_000 },
+    { asset: "ilal_vkey.json", rel: "ilal_vkey.json", minBytes: 1_000 },
+    { asset: "ilal_js/ilal.wasm", rel: "ilal_js/ilal.wasm", minBytes: 1_000_000 },
+    { asset: "ilal_js/generate_witness.js", rel: "ilal_js/generate_witness.js", minBytes: 100 },
+    { asset: "ilal_js/witness_calculator.js", rel: "ilal_js/witness_calculator.js", minBytes: 1_000 },
+];
 // ─── ABI ──────────────────────────────────────────────────────────────────────
 const CNF_ABI = [
     {
@@ -82,26 +94,81 @@ function schemaHash(schemaUID) {
     const schemaHi = BigInt("0x" + schemaHex.slice(0, 32));
     return poseidon2([schemaLo, schemaHi]);
 }
-function findCircuitDir(override) {
-    if (override)
-        return resolve(override);
+function hasCircuitArtifacts(dir) {
+    return PROVING_ARTIFACTS.every((artifact) => {
+        const file = resolve(dir, artifact.rel);
+        try {
+            return existsSync(file) && statSync(file).size >= artifact.minBytes;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function requireCircuitArtifacts(dir) {
+    const resolved = resolve(dir);
+    const missing = PROVING_ARTIFACTS.filter((artifact) => {
+        const file = resolve(resolved, artifact.rel);
+        try {
+            return !existsSync(file) || statSync(file).size < artifact.minBytes;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (missing.length > 0) {
+        die(`Proving artifacts are incomplete in ${resolved}.\n` +
+            `  Missing: ${missing.map((x) => x.rel).join(", ")}\n` +
+            "  Pass --artifact-url <base-url> to download them, or use --circuit-dir <path>.");
+    }
+    return resolved;
+}
+async function downloadFile(url, target) {
+    const res = await fetch(url);
+    if (!res.ok || !res.body) {
+        throw new Error(`download failed ${res.status} ${res.statusText}: ${url}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(target));
+}
+async function ensureHostedArtifacts(opts) {
+    const cacheDir = resolve(opts.artifactCache ?? DEFAULT_ARTIFACT_CACHE);
+    if (hasCircuitArtifacts(cacheDir))
+        return cacheDir;
+    if (opts.offline) {
+        die("Hosted proving artifacts are not cached locally.\n" +
+            `  Cache: ${cacheDir}\n` +
+            "  Re-run without --offline, or pass --circuit-dir <path>.");
+    }
+    const baseUrl = (opts.artifactUrl ?? DEFAULT_ARTIFACT_URL).replace(/\/+$/, "");
+    for (const artifact of PROVING_ARTIFACTS) {
+        const target = resolve(cacheDir, artifact.rel);
+        if (existsSync(target) && statSync(target).size >= artifact.minBytes)
+            continue;
+        await downloadFile(`${baseUrl}/${artifact.asset}`, target);
+    }
+    return requireCircuitArtifacts(cacheDir);
+}
+async function findCircuitDir(opts) {
+    if (opts.override) {
+        return { dir: requireCircuitArtifacts(opts.override), source: "local" };
+    }
     // Look relative to the CLI package root (cli/ → circuits/build)
     const candidates = [
         resolve(__dirname, "../../../../circuits/build"), // dev: cli/src/commands → circuits/build
         resolve(__dirname, "../../../circuits/build"),
         resolve(process.cwd(), "circuits/build"),
         resolve(process.cwd(), "build"),
+        resolve(opts.artifactCache ?? DEFAULT_ARTIFACT_CACHE),
     ];
     for (const p of candidates) {
-        try {
-            readFileSync(resolve(p, "ilal.zkey"));
-            return p;
+        if (hasCircuitArtifacts(p)) {
+            const source = resolve(p) === resolve(opts.artifactCache ?? DEFAULT_ARTIFACT_CACHE) ? "cache" : "local";
+            return { dir: p, source };
         }
-        catch { /* not found */ }
     }
-    die("Circuit build directory not found.\n" +
-        "  Run: bash circuits/scripts/compile.sh\n" +
-        "  Or pass: --circuit-dir <path/to/circuits/build>");
+    const dir = await ensureHostedArtifacts(opts);
+    return { dir, source: "download" };
 }
 function resolveExpiresAt(expiresAt) {
     if (!expiresAt)
@@ -193,9 +260,7 @@ function encodeProof(proofJson, publicJson) {
 // ─── Main export ──────────────────────────────────────────────────────────────
 export async function credentialProve(opts) {
     const cfg = withConfig(opts);
-    const rawKey = cfg.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const rawKey = requirePrivateKey(cfg.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!cfg.wallet)
         die("Wallet address required. Use --wallet or set issuer in .ilal.json");
     if (!cfg.issuer)
@@ -226,11 +291,29 @@ export async function credentialProve(opts) {
         action = tokenId === 0n ? "mint" : "renew";
         spin.succeed(`Action: ${fmt.cyan(action)}${tokenId > 0n ? fmt.gray(` (token #${tokenId})`) : ""}`);
     }
-    // ── Find circuit build dir ─────────────────────────────────────────────────
-    const circuitDir = findCircuitDir(cfg.circuitDir);
-    const outDir = cfg.outDir
-        ? resolve(cfg.outDir)
-        : resolve(circuitDir, "../../outputs");
+    // ── Prepare hosted/local proving artifacts ────────────────────────────────
+    const artifactSpin = new Spinner("Preparing proving artifacts…").start();
+    let circuitDir;
+    try {
+        const artifacts = await findCircuitDir({
+            override: cfg.circuitDir,
+            artifactUrl: cfg.artifactUrl,
+            artifactCache: cfg.artifactCache,
+            offline: cfg.offline,
+        });
+        circuitDir = artifacts.dir;
+        const sourceLabel = artifacts.source === "download" ? "downloaded to cache" :
+            artifacts.source === "cache" ? "cache" :
+                "local";
+        artifactSpin.succeed(`Proving artifacts ready (${sourceLabel})`);
+    }
+    catch (e) {
+        artifactSpin.fail("Proving artifacts unavailable");
+        die(e instanceof Error ? e.message : String(e));
+    }
+    const outDir = cfg.outDir ? resolve(cfg.outDir) : resolve(process.cwd(), "outputs");
+    log.kv("artifacts", fmt.gray(circuitDir));
+    log.kv("proofOut", fmt.gray(outDir));
     log.line();
     // ── Generate proof ─────────────────────────────────────────────────────────
     const spin = new Spinner("Building Merkle tree & generating ZK proof…").start();

package/dist/commands/session.js

@@ -1,7 +1,7 @@
 import { createWalletClient, encodeAbiParameters, http, isAddress, isHex, parseAbiParameters, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, header, die } from "../ui.js";
+import { fmt, log, header, die, requirePrivateKey } from "../ui.js";
 import { withConfig } from "../config.js";
 const CHAINS = {
     "8453": base,
@@ -30,11 +30,7 @@ const HOOK_DATA_ABI = parseAbiParameters([
 export async function sessionSign(opts) {
     const cfg = withConfig({ chain: opts.chain, hook: opts.hook, issuer: opts.issuer });
     // Resolve private key
-    const rawKey = opts.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
-    if (!isHex(rawKey) || rawKey.length !== 66)
-        die("Invalid private key format (expected 0x + 32 bytes).");
+    const rawKey = requirePrivateKey(opts.privateKey ?? process.env["PRIVATE_KEY"]);
     const account = privateKeyToAccount(rawKey);
     const user = (opts.user ?? account.address);
     const pool = opts.pool ?? cfg.poolId;

package/dist/commands/swap.js

@@ -21,7 +21,7 @@
 import { createPublicClient, createWalletClient, decodeAbiParameters, encodeAbiParameters, formatEther, formatUnits, http, isAddress, isHex, parseAbiParameters, parseUnits, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base, baseSepolia } from "viem/chains";
-import { fmt, log, header, Spinner, die, dieOnContract } from "../ui.js";
+import { fmt, log, header, Spinner, die, dieOnContract, requirePrivateKey } from "../ui.js";
 import { withConfig } from "../config.js";
 const CHAINS = { "8453": base, "84532": baseSepolia };
 // ─── ABIs ─────────────────────────────────────────────────────────────────────
@@ -127,9 +127,7 @@ function secondsSince(startMs) {
 // ─── Main export ──────────────────────────────────────────────────────────────
 export async function swap(opts) {
     const cfg = withConfig(opts);
-    const rawKey = cfg.privateKey ?? process.env["PRIVATE_KEY"];
-    if (!rawKey)
-        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    const rawKey = requirePrivateKey(cfg.privateKey ?? process.env["PRIVATE_KEY"]);
     if (!cfg.router)
         die("ILALRouter address required. Use --router or set in .ilal.json");
     if (!cfg.hook)
@@ -211,7 +209,7 @@ export async function swap(opts) {
     if (tokenId === 0n) {
         preflightErrors.push(`wallet has no CNF credential; mint one before trading.`);
         if (hasEASPath)
-            preflightErrors.push("issuer supports EAS/mock attestation minting: run `ilal credential mint --attestation <uid>`.");
+            preflightErrors.push("issuer supports EAS/mock attestation minting: first ask issuer to run `ilal demo attest --wallet <wallet>`, then run `ilal credential mint --attestation <uid>`.");
         else if (hasZKPath)
             preflightErrors.push(`issuer supports ZK minting: run \`ilal credential prove --wallet ${account.address}\`.`);
         else

package/dist/config.d.ts

@@ -20,6 +20,8 @@ export interface ILALConfig {
     chain?: string;
     rpc?: string;
     circuitDir?: string;
+    artifactUrl?: string;
+    artifactCache?: string;
     outDir?: string;
 }
 export declare function loadConfig(): ILALConfig;

package/dist/config.js

@@ -52,6 +52,10 @@ export function loadConfig() {
         chain: process.env["ILAL_CHAIN"] ?? fileConfig.chain,
         rpc: process.env["ILAL_RPC"] ?? fileConfig.rpc,
         circuitDir: process.env["ILAL_CIRCUIT_DIR"] ?? fileConfig.circuitDir,
+        artifactUrl: process.env["ILAL_ARTIFACT_BASE_URL"]
+            ?? process.env["ILAL_ARTIFACT_URL"]
+            ?? fileConfig.artifactUrl,
+        artifactCache: process.env["ILAL_ARTIFACT_CACHE"] ?? fileConfig.artifactCache,
         outDir: process.env["ILAL_OUT_DIR"] ?? fileConfig.outDir,
     };
     return _config;

package/dist/index.js

@@ -19,7 +19,7 @@ const program = new Command();
 program
     .name("ilal")
     .description("ILAL Protocol CLI — Uniswap v4 compliance hook toolkit")
-    .version("0.2.9")
+    .version("0.2.11")
     .addHelpText("before", `\n  ${fmt.bold(fmt.cyan("◆"))} ${fmt.bold("ILAL Protocol")}  ${fmt.gray("Uniswap v4 Compliance Hook")}\n`);
 // ─── init ─────────────────────────────────────────────────────────────────────
 program
@@ -38,6 +38,8 @@ program
     .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("--artifact-url <url>", "Hosted proving artifact base URL")
+    .option("--artifact-cache <path>", "Local proving artifact cache directory")
     .option("-f, --force", "Overwrite existing .ilal.json", false)
     .action(async (opts) => {
     await init(opts).catch(err);
@@ -99,8 +101,8 @@ const credential = program.command("credential").description("Manage compliance
 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("-i, --issuer <address>", "CNFIssuer contract address (or set in .ilal.json)")
+    .option("-c, --chain <chainId>", "Chain ID (8453=Base, 84532=Base Sepolia)", "84532")
     .option("-r, --rpc <url>", "Custom RPC URL")
     .action(async (wallet, opts) => {
     await credentialStatus({ wallet, ...opts }).catch(err);
@@ -111,7 +113,10 @@ credential
     .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("--circuit-dir <path>", "Path to circuits/build directory (auto-detected by default)")
+    .option("--circuit-dir <path>", "Path to circuits/build directory (dev/offline override)")
+    .option("--artifact-url <url>", "Hosted proving artifact base URL (defaults to ILAL release artifacts)")
+    .option("--artifact-cache <path>", "Local proving artifact cache directory (default: ~/.ilal/artifacts/ilal-v1)")
+    .option("--offline", "Do not download proving artifacts; require cache or --circuit-dir", false)
     .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")
@@ -133,8 +138,8 @@ 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("-i, --issuer <address>", "CNFIssuer contract address (or set in .ilal.json)")
+    .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("--simulate", "Verify attestation without sending tx", false)
@@ -145,8 +150,8 @@ 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("-i, --issuer <address>", "CNFIssuer contract address (or set in .ilal.json)")
+    .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("--simulate", "Verify attestation without sending tx", false)

package/dist/ui.d.ts

@@ -56,4 +56,5 @@ export declare const log: {
 };
 export declare function header(title: string, subtitle?: string): void;
 export declare function die(msg: string): never;
+export declare function requirePrivateKey(rawKey?: string): `0x${string}`;
 export declare function dieOnContract(e: unknown): never;

package/dist/ui.js

@@ -213,6 +213,19 @@ export function die(msg) {
     console.error();
     process.exit(1);
 }
+export function requirePrivateKey(rawKey) {
+    const key = rawKey?.trim();
+    if (!key) {
+        die("Private key required. Use --private-key or set PRIVATE_KEY env var.");
+    }
+    if (/^[0-9a-fA-F]{64}$/.test(key)) {
+        die("Private key must include the 0x prefix. Example: PRIVATE_KEY=0x...");
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+        die("Private key must be 32-byte hex and include the 0x prefix. Example: PRIVATE_KEY=0x...");
+    }
+    return key;
+}
 export function dieOnContract(e) {
     die(parseViemError(e));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilalv3/cli",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "ILAL Protocol CLI — compliant swaps and credential management for Uniswap v4",
   "type": "module",
   "bin": {