@ilalv3/cli 0.2.7 → 0.2.8

package/dist/commands/liquidity.js

@@ -13,7 +13,7 @@
  *     --router 0xROUTER --hook 0xHOOK --issuer 0xISSUER \
  *     --pool-id 0xPOOLID --token-a 0xTOKA --token-b 0xTOKB
  */
-import { createPublicClient, createWalletClient, encodeAbiParameters, http, isAddress, isHex, parseAbiParameters, } from "viem";
+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";
@@ -103,6 +103,25 @@ function txUrl(chain, hash) {
     return baseUrl ? `${baseUrl}/tx/${hash}` : undefined;
 }
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const MAX_UINT256 = 2n ** 256n - 1n;
+function trimDecimals(value, places = 8) {
+    const [whole, frac] = value.split(".");
+    if (!frac)
+        return whole ?? value;
+    const trimmed = frac.slice(0, places).replace(/0+$/, "");
+    return trimmed ? `${whole}.${trimmed}` : whole ?? value;
+}
+function tokenAmount(raw, decimals, symbol, places = 8) {
+    return `${trimDecimals(formatUnits(raw, decimals), places)} ${symbol}`;
+}
+function allowanceLabel(raw, decimals, symbol) {
+    if (raw >= MAX_UINT256 / 2n)
+        return "unlimited (MAX)";
+    return `${tokenAmount(raw, decimals, symbol)} (${raw.toString()} wei)`;
+}
+function secondsSince(startMs) {
+    return `${((Date.now() - startMs) / 1000).toFixed(1)}s`;
+}
 // ─── Shared core ──────────────────────────────────────────────────────────────
 async function executeLiquidity(action, opts) {
     const cfg = withConfig(opts);
@@ -156,7 +175,7 @@ async function executeLiquidity(action, opts) {
         die("liquidity must be greater than 0. No approval or liquidity transaction was sent.");
     }
     const preflightSpin = new Spinner("Running preflight checks…").start();
-    const [root, verifier, eas, valid, tokenId, sym0, sym1, bal0, bal1] = await Promise.all([
+    const [root, verifier, eas, valid, tokenId, sym0, sym1, dec0, dec1, bal0, bal1] = await Promise.all([
         pubClient.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "merkleRoot" }),
         pubClient.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "zkVerifier" }),
         pubClient.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "eas" }),
@@ -164,6 +183,8 @@ async function executeLiquidity(action, opts) {
         pubClient.readContract({ address: cfg.issuer, abi: CNF_ABI, functionName: "credentialOf", args: [account.address] }),
         pubClient.readContract({ address: c0, abi: ERC20_ABI, functionName: "symbol" }),
         pubClient.readContract({ address: c1, abi: ERC20_ABI, functionName: "symbol" }),
+        pubClient.readContract({ address: c0, abi: ERC20_ABI, functionName: "decimals" }),
+        pubClient.readContract({ address: c1, abi: ERC20_ABI, functionName: "decimals" }),
         pubClient.readContract({ address: c0, abi: ERC20_ABI, functionName: "balanceOf", args: [account.address] }),
         pubClient.readContract({ address: c1, abi: ERC20_ABI, functionName: "balanceOf", args: [account.address] }),
     ]);
@@ -183,8 +204,24 @@ async function executeLiquidity(action, opts) {
     else if (!valid)
         preflightErrors.push("wallet CNF credential exists but is not valid.");
     if (action === "add" && (bal0 === 0n || bal1 === 0n)) {
-        preflightErrors.push(`token balances are not ready for adding liquidity: ${sym0}=${bal0.toString()} wei, ${sym1}=${bal1.toString()} wei.`);
+        preflightErrors.push(`token balances are not ready for adding liquidity: ${sym0}=${tokenAmount(bal0, dec0, sym0)}, ${sym1}=${tokenAmount(bal1, dec1, sym1)}.`);
     }
+    log.section("Preflight Checks");
+    if (tokenId !== 0n && valid)
+        log.ok(`CNF credential token #${tokenId.toString()}`);
+    else
+        log.fail("CNF credential missing or invalid");
+    log.ok(`Issuer config (${hasEASPath ? "EAS" : "no EAS"}${hasZKPath ? " + ZK" : ""})`);
+    if (action !== "add" || bal0 > 0n)
+        log.ok(`${sym0} balance ${tokenAmount(bal0, dec0, sym0)}`);
+    else
+        log.fail(`${sym0} balance ${tokenAmount(bal0, dec0, sym0)}`);
+    if (action !== "add" || bal1 > 0n)
+        log.ok(`${sym1} balance ${tokenAmount(bal1, dec1, sym1)}`);
+    else
+        log.fail(`${sym1} balance ${tokenAmount(bal1, dec1, sym1)}`);
+    log.ok(`Route bound to router ${fmt.addr(cfg.router)} and hook ${fmt.addr(cfg.hook)}`);
+    log.line();
     if (preflightErrors.length > 0) {
         log.section("Preflight Failed");
         for (const error of preflightErrors)
@@ -194,9 +231,10 @@ async function executeLiquidity(action, opts) {
     }
     // Approve both tokens if adding liquidity
     if (action === "add") {
-        const MAX = 2n ** 256n - 1n;
+        const MAX = MAX_UINT256;
         for (const token of [c0, c1]) {
             const sym = token.toLowerCase() === c0.toLowerCase() ? sym0 : sym1;
+            const decimals = token.toLowerCase() === c0.toLowerCase() ? dec0 : dec1;
             const allowed = await pubClient.readContract({
                 address: token, abi: ERC20_ABI, functionName: "allowance",
                 args: [account.address, cfg.router],
@@ -210,6 +248,9 @@ async function executeLiquidity(action, opts) {
                 await pubClient.waitForTransactionReceipt({ hash: h });
                 appSpin.succeed(`Approved ${sym} ${fmt.gray(fmt.hash(h))}`);
             }
+            else {
+                log.ok(`${sym} allowance: ${allowanceLabel(allowed, decimals, sym)}`);
+            }
         }
     }
     // Sign session token
@@ -243,7 +284,7 @@ async function executeLiquidity(action, opts) {
         message: token,
     });
     const hookData = encodeAbiParameters(HOOK_DATA_ABI, [token, signature]);
-    signSpin.succeed(`Session signed (expires in ${ttl}s)`);
+    signSpin.succeed(`Session authorization signed (expires in ${ttl}s, one-time nonce)`);
     log.section("Gate Checks");
     log.kv("credential", `${fmt.badge("required", "cyan")} issuer ${fmt.addr(cfg.issuer)}`);
     log.kv("caller", `${fmt.badge("bound", "green")} ${fmt.addr(cfg.router)}`);
@@ -261,20 +302,30 @@ async function executeLiquidity(action, opts) {
     const liquidityParams = { tickLower, tickUpper, liquidityDelta, salt };
     const fnName = action === "add" ? "addLiquidity" : "removeLiquidity";
     // Execute
-    const txSpin = new Spinner(`Sending ${fnName}…`).start();
+    const txSpin = new Spinner(`Submitting ${fnName} tx…`).start();
     let txHash;
+    let receipt;
     try {
+        const startMs = Date.now();
         const baseArgs = [poolKey, liquidityParams, hookData];
         txHash = await (action === "add"
             ? walClient.writeContract({ address: cfg.router, abi: ROUTER_LIQUIDITY_ABI, functionName: "addLiquidity", args: baseArgs, value: 0n })
             : walClient.writeContract({ address: cfg.router, abi: ROUTER_LIQUIDITY_ABI, functionName: "removeLiquidity", args: baseArgs }));
-        txSpin.update(`Confirming ${fmt.gray(fmt.hash(txHash))}…`);
-        const receipt = await pubClient.waitForTransactionReceipt({ hash: txHash });
+        txSpin.succeed(`Submitted to mempool ${fmt.gray(fmt.hash(txHash))}`);
+        const confirmSpin = new Spinner(`Confirming ${fmt.gray(fmt.hash(txHash))}…`).start();
+        receipt = await pubClient.waitForTransactionReceipt({ hash: txHash });
         if (receipt.status !== "success") {
-            txSpin.fail("Transaction reverted");
+            confirmSpin.fail("Transaction reverted");
             die(`Tx failed: ${txHash}`);
         }
-        txSpin.succeed(fmt.bold(fmt.green(`Liquidity ${action === "add" ? "added" : "removed"} via ILAL channel ✓`)));
+        confirmSpin.succeed(`Confirmed in block ${receipt.blockNumber.toString()}`);
+        const effectiveGasPrice = receipt.effectiveGasPrice;
+        log.metrics([
+            { label: "finality", value: secondsSince(startMs), tone: "green" },
+            { label: "gas used", value: receipt.gasUsed.toString(), tone: "cyan" },
+            ...(effectiveGasPrice ? [{ label: "gas cost", value: `${trimDecimals(formatEther(receipt.gasUsed * effectiveGasPrice), 8)} ETH`, tone: "cyan" }] : []),
+        ]);
+        log.ok(fmt.bold(fmt.green(`Liquidity ${action === "add" ? "added" : "removed"} via ILAL channel`)));
     }
     catch (e) {
         txSpin.fail(`${fnName} failed`);
@@ -283,7 +334,7 @@ async function executeLiquidity(action, opts) {
     log.line();
     log.callout(action === "add" ? "Hook-enforced liquidity add" : "Hook-enforced liquidity removal", "pool policy, credential type, session binding, and nonce all passed on-chain", "green");
     log.kv("tx", fmt.gray(txHash));
-    log.kv("block", fmt.gray((await pubClient.getTransactionReceipt({ hash: txHash })).blockNumber.toString()));
+    log.kv("block", fmt.gray((receipt ?? await pubClient.getTransactionReceipt({ hash: txHash })).blockNumber.toString()));
     const explorer = txUrl(chain, txHash);
     if (explorer)
         log.kv("explorer", fmt.cyan(explorer));

package/dist/commands/swap.d.ts

@@ -37,4 +37,5 @@ export declare function swap(opts: {
     ttl?: string;
     hookData?: string;
     simulate?: boolean;
+    explain?: boolean;
 }): Promise<void>;

package/dist/commands/swap.js

@@ -18,7 +18,7 @@
  *     --pool-id   0xPOOLID \
  *     --chain     84532
  */
-import { createPublicClient, createWalletClient, decodeAbiParameters, encodeAbiParameters, http, isAddress, isHex, parseAbiParameters, parseUnits, } from "viem";
+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";
@@ -85,13 +85,14 @@ const MAX_SQRT_PRICE = 1461446703485210103287273052203988822378723970341n; // MA
 const DYNAMIC_FEE_FLAG = 8388608;
 const PIPS_DENOMINATOR = 1000000n;
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const MAX_UINT256 = 2n ** 256n - 1n;
 function txUrl(chain, hash) {
     const baseUrl = chain.blockExplorers?.default?.url;
     return baseUrl ? `${baseUrl}/tx/${hash}` : undefined;
 }
 function feeLabel(fee) {
     if (fee === DYNAMIC_FEE_FLAG)
-        return `${fmt.badge("fair flow", "green")} verified swap fee 0.05%`;
+        return `${fmt.badge("verified", "green")} 0.05% (vs 0.30% standard pool)`;
     return `${fmt.badge("static", "gray")} ${(fee / 10_000).toFixed(4).replace(/0+$/, "").replace(/\.$/, "")}%`;
 }
 function pipsToPercent(pips) {
@@ -102,6 +103,27 @@ function poolFeePercent(fee) {
         ? "0.05%"
         : `${(fee / 10_000).toFixed(4).replace(/0+$/, "").replace(/\.$/, "")}%`;
 }
+function trimDecimals(value, places = 8) {
+    const [whole, frac] = value.split(".");
+    if (!frac)
+        return whole ?? value;
+    const trimmed = frac.slice(0, places).replace(/0+$/, "");
+    return trimmed ? `${whole}.${trimmed}` : whole ?? value;
+}
+function tokenAmount(raw, decimals, symbol, places = 8) {
+    return `${trimDecimals(formatUnits(raw, decimals), places)} ${symbol}`;
+}
+function tokenAmountWithWei(raw, decimals, symbol, places = 8) {
+    return `${tokenAmount(raw, decimals, symbol, places)} (${raw.toString()} wei)`;
+}
+function allowanceLabel(raw, decimals, symbol) {
+    if (raw >= MAX_UINT256 / 2n)
+        return "unlimited (MAX)";
+    return tokenAmountWithWei(raw, decimals, symbol);
+}
+function secondsSince(startMs) {
+    return `${((Date.now() - startMs) / 1000).toFixed(1)}s`;
+}
 // ─── Main export ──────────────────────────────────────────────────────────────
 export async function swap(opts) {
     const cfg = withConfig(opts);
@@ -159,7 +181,7 @@ export async function swap(opts) {
     if (amountIn <= 0n) {
         die("amount-in must be greater than 0. Use `ilal swap --simulate` for a dry run.");
     }
-    log.kv("amount", `${opts.amountIn} ${fmt.cyan(symbol)} (${amountIn.toString()} wei)`);
+    log.kv("amount", `${fmt.cyan(tokenAmountWithWei(amountIn, decimals, symbol))}`);
     let protocolFeePips = 0;
     let treasury;
     try {
@@ -198,7 +220,23 @@ export async function swap(opts) {
     else if (!valid)
         preflightErrors.push("wallet CNF credential exists but is not valid.");
     if (balance < totalDebit)
-        preflightErrors.push(`insufficient ${symbol} balance: need ${totalDebit.toString()} wei including ILAL fee, have ${balance.toString()} wei.`);
+        preflightErrors.push(`insufficient ${symbol} balance: need ${tokenAmountWithWei(totalDebit, decimals, symbol)} including ILAL fee, have ${tokenAmountWithWei(balance, decimals, symbol)}.`);
+    log.section("Preflight Checks");
+    if (tokenId !== 0n && valid)
+        log.ok(`CNF credential token #${tokenId.toString()}`);
+    else
+        log.fail("CNF credential missing or invalid");
+    log.ok(`Issuer config (${hasEASPath ? "EAS" : "no EAS"}${hasZKPath ? " + ZK" : ""})`);
+    if (balance >= totalDebit)
+        log.ok(`Wallet balance ${tokenAmount(balance, decimals, symbol)}`);
+    else
+        log.fail(`Wallet balance ${tokenAmount(balance, decimals, symbol)}`);
+    log.ok(`Route bound to router ${fmt.addr(cfg.router)} and hook ${fmt.addr(cfg.hook)}`);
+    if (opts.explain) {
+        log.info("CNF proves this wallet is allowed to access the pool without revealing identity data.");
+        log.info("Caller binding means the signed authorization can only be used through the ILALRouter.");
+    }
+    log.line();
     if (preflightErrors.length > 0) {
         log.section("Preflight Failed");
         for (const error of preflightErrors)
@@ -210,7 +248,7 @@ export async function swap(opts) {
     }
     log.deal([
         { label: "verified input", value: `${opts.amountIn} ${symbol}`, note: "exact-in swap", tone: "cyan" },
-        { label: "LP fee", value: poolFeePercent(parseInt(cfg.fee ?? "3000")), note: "hook-priced flow", tone: "green" },
+        { label: "LP fee", value: poolFeePercent(parseInt(cfg.fee ?? "3000")), note: parseInt(cfg.fee ?? "3000") === DYNAMIC_FEE_FLAG ? "6× cheaper than 0.30% standard" : "pool fee", tone: "green" },
         { label: "ILAL fee", value: protocolFeePips > 0 ? pipsToPercent(protocolFeePips) : "off", note: protocolFeePips > 0 ? "protocol revenue" : "legacy router", tone: protocolFeePips > 0 ? "cyan" : "gray" },
     ]);
     log.line();
@@ -286,10 +324,12 @@ export async function swap(opts) {
     log.kv("credential", `${fmt.badge("required", "cyan")} issuer ${fmt.addr(cfg.issuer)}`);
     log.kv("caller", `${fmt.badge("bound", "green")} ${fmt.addr(cfg.router)}`);
     log.kv("nonce", `${opts.hookData ? fmt.badge("external", "cyan") : fmt.badge("fresh", "green")} ${fmt.hash(sessionNonce)}`);
+    if (opts.explain)
+        log.kvdim("", "↳ unique one-time session ID; prevents replay attacks");
     log.kv("fee", feeLabel(fee));
     if (protocolFeePips > 0) {
         log.kv("protocol fee", `${fmt.badge("ILAL", "cyan")} ${pipsToPercent(protocolFeePips)} to ${treasury ? fmt.addr(treasury) : "treasury"}`);
-        log.kv("total debit", `${totalDebit.toString()} wei (${symbol} input + ILAL fee)`);
+        log.kv("total debit", `${tokenAmountWithWei(totalDebit, decimals, symbol)} input + ILAL fee`);
     }
     log.line();
     if (opts.simulate) {
@@ -315,10 +355,10 @@ export async function swap(opts) {
             args: [cfg.router, totalDebit * 10n], // approve 10× for future swaps
         });
         await pubClient.waitForTransactionReceipt({ hash: approveHash });
-        approveSpin.succeed(`Approved ${symbol} ${fmt.gray(fmt.hash(approveHash))}`);
+        approveSpin.succeed(`Approved ${tokenAmount(totalDebit * 10n, decimals, symbol)} ${fmt.gray(fmt.hash(approveHash))}`);
     }
     else {
-        approveSpin.succeed(`Allowance ok (${fmt.gray(allowed.toString())} wei)`);
+        approveSpin.succeed(`Allowance: ${allowanceLabel(allowed, decimals, symbol)}`);
     }
     // Build PoolKey
     const poolKey = {
@@ -341,9 +381,11 @@ export async function swap(opts) {
         log.kv("min-amount-out", `${fmt.cyan(minAmountOut.toString())} wei (slippage protection on)`);
     }
     // Execute swap
-    const txSpin = new Spinner("Sending swap tx…").start();
+    const txSpin = new Spinner("Submitting swap tx…").start();
     let txHash;
+    let receipt;
     try {
+        const startMs = Date.now();
         txHash = await walClient.writeContract({
             address: cfg.router,
             abi: ROUTER_ABI,
@@ -351,13 +393,21 @@ export async function swap(opts) {
             args: [poolKey, swapParams, minAmountOut, hookData],
             value: 0n,
         });
-        txSpin.update(`Confirming ${fmt.gray(fmt.hash(txHash))}…`);
-        const receipt = await pubClient.waitForTransactionReceipt({ hash: txHash });
+        txSpin.succeed(`Submitted to mempool ${fmt.gray(fmt.hash(txHash))}`);
+        const confirmSpin = new Spinner(`Confirming ${fmt.gray(fmt.hash(txHash))}…`).start();
+        receipt = await pubClient.waitForTransactionReceipt({ hash: txHash });
         if (receipt.status !== "success") {
-            txSpin.fail("Transaction reverted");
+            confirmSpin.fail("Transaction reverted");
             die(`Tx failed: ${txHash}`);
         }
-        txSpin.succeed(fmt.bold(fmt.green(`Swap executed via ILAL channel ✓`)));
+        confirmSpin.succeed(`Confirmed in block ${receipt.blockNumber.toString()}`);
+        const effectiveGasPrice = receipt.effectiveGasPrice;
+        log.metrics([
+            { label: "finality", value: secondsSince(startMs), tone: "green" },
+            { label: "gas used", value: receipt.gasUsed.toString(), tone: "cyan" },
+            ...(effectiveGasPrice ? [{ label: "gas cost", value: `${trimDecimals(formatEther(receipt.gasUsed * effectiveGasPrice), 8)} ETH`, tone: "cyan" }] : []),
+        ]);
+        log.ok(fmt.bold(fmt.green("Swap executed via ILAL channel")));
     }
     catch (e) {
         txSpin.fail("Swap failed");
@@ -366,7 +416,7 @@ export async function swap(opts) {
     log.line();
     log.callout("Hook-enforced swap", "credential, session, caller binding, and nonce all passed on-chain", "green");
     log.kv("tx", fmt.gray(txHash));
-    log.kv("block", fmt.gray((await pubClient.getTransactionReceipt({ hash: txHash })).blockNumber.toString()));
+    log.kv("block", fmt.gray((receipt ?? await pubClient.getTransactionReceipt({ hash: txHash })).blockNumber.toString()));
     const explorer = txUrl(chain, txHash);
     if (explorer)
         log.kv("explorer", fmt.cyan(explorer));

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.7")
+    .version("0.2.8")
     .addHelpText("before", `\n  ${fmt.bold(fmt.cyan("◆"))} ${fmt.bold("ILAL Protocol")}  ${fmt.gray("Uniswap v4 Compliance Hook")}\n`);
 // ─── init ─────────────────────────────────────────────────────────────────────
 program
@@ -286,6 +286,7 @@ program
     .option("-k, --private-key <hex>", "Private key (or set PRIVATE_KEY env var)")
     .option("--ttl <seconds>", "Session token lifetime in seconds", "600")
     .option("--hook-data <hex>", "Use externally signed one-time hookData instead of signing inside swap")
+    .option("--explain", "Show inline explanations for gate checks and session fields", false)
     .option("--simulate", "Sign session without sending tx", false)
     .action(async (opts) => {
     await swap(opts).catch(err);

package/package.json

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