arc402-cli 0.2.0

package/src/commands/agreements.ts

@@ -0,0 +1,324 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import * as readline from "readline";
+import { AgreementStatus, ServiceAgreementClient } from "@arc402/sdk";
+import { loadConfig } from "../config";
+import { getClient } from "../client";
+import { agreementStatusLabel, formatDate, printTable, truncateAddress } from "../utils/format";
+import { formatDeadline } from "../utils/time";
+import { hashString } from "../utils/hash";
+
+// ─── AgreementTree minimal ABI ────────────────────────────────────────────────
+
+const AGREEMENT_TREE_ABI = [
+  "function registerSubAgreement(uint256 parentAgreementId, uint256 childAgreementId) external",
+  "function getChildren(uint256 agreementId) external view returns (uint256[])",
+  "function getRoot(uint256 agreementId) external view returns (uint256)",
+  "function getPath(uint256 agreementId) external view returns (uint256[])",
+  "function allChildrenSettled(uint256 agreementId) external view returns (bool)",
+  "function getDepth(uint256 agreementId) external view returns (uint256)",
+];
+
+export function registerAgreementsCommands(program: Command): void {
+
+  // ── arc402 agreements ────────────────────────────────────────────────────────
+  program
+    .command("agreements")
+    .description("List agreements for the configured wallet")
+    .option("--as <role>", "client or provider", "client")
+    .option("--json")
+    .action(async (opts) => {
+      const config = loadConfig();
+      if (!config.serviceAgreementAddress) throw new Error("serviceAgreementAddress missing in config");
+      const { provider, address } = await getClient(config);
+      if (!address) throw new Error("No wallet configured");
+      const client = new ServiceAgreementClient(config.serviceAgreementAddress, provider);
+      const agreements = opts.as === "provider"
+        ? await client.getProviderAgreements(address)
+        : await client.getClientAgreements(address);
+      if (opts.json) return console.log(JSON.stringify(agreements, (_k, value) => typeof value === "bigint" ? value.toString() : value, 2));
+      printTable(
+        ["ID", "COUNTERPARTY", "SERVICE", "DEADLINE", "STATUS"],
+        agreements.map((agreement) => [
+          agreement.id.toString(),
+          truncateAddress(opts.as === "provider" ? agreement.client : agreement.provider),
+          agreement.serviceType,
+          formatDeadline(Number(agreement.deadline)),
+          agreementStatusLabel(agreement.status),
+        ])
+      );
+    });
+
+  // ── arc402 agreement <id> ────────────────────────────────────────────────────
+  program
+    .command("agreement <id>")
+    .description("Show agreement detail, including remediation/dispute fields")
+    .option("--json")
+    .action(async (id, opts) => {
+      const config = loadConfig();
+      if (!config.serviceAgreementAddress) throw new Error("serviceAgreementAddress missing in config");
+      const { provider } = await getClient(config);
+      const client = new ServiceAgreementClient(config.serviceAgreementAddress, provider);
+      const agreement = await client.getAgreement(BigInt(id));
+      if (opts.json) return console.log(JSON.stringify(agreement, (_k, value) => typeof value === "bigint" ? value.toString() : value, 2));
+      console.log(`agreement #${agreement.id}\nclient=${agreement.client}\nprovider=${agreement.provider}\nstatus=${agreementStatusLabel(agreement.status)}\ncreated=${formatDate(Number(agreement.createdAt))}\ndeadline=${formatDate(Number(agreement.deadline))}\nverifyWindowEnd=${Number(agreement.verifyWindowEnd) ? formatDate(Number(agreement.verifyWindowEnd)) : "n/a"}\ncommittedHash=${agreement.committedHash}`);
+      if ([AgreementStatus.REVISION_REQUESTED, AgreementStatus.REVISED, AgreementStatus.PARTIAL_SETTLEMENT, AgreementStatus.ESCALATED_TO_HUMAN, AgreementStatus.DISPUTED, AgreementStatus.ESCALATED_TO_ARBITRATION].includes(agreement.status)) {
+        const remediation = await client.getRemediationCase(agreement.id);
+        const dispute = await client.getDisputeCase(agreement.id);
+        console.log(`remediationActive=${remediation.active} cycles=${remediation.cycleCount} disputeOutcome=${dispute.outcome}`);
+      }
+    });
+
+  // ── arc402 agreements-sub-register ──────────────────────────────────────────
+  // Spec 19: arc402 agreements sub-register --parent <id> --child <id>
+  program
+    .command("agreements-sub-register")
+    .description("Link a child agreement to its parent in the AgreementTree (Spec 19)")
+    .requiredOption("--parent <id>", "Parent agreement ID")
+    .requiredOption("--child <id>", "Child agreement ID to register under the parent")
+    .option("--json", "Machine-parseable output")
+    .action(async (opts) => {
+      const config = loadConfig();
+      if (!config.agreementTreeAddress) throw new Error("agreementTreeAddress missing in config");
+      const { signer } = await getClient(config);
+      if (!signer) { console.error("No private key configured."); process.exit(1); }
+
+      const tree = new ethers.Contract(config.agreementTreeAddress, AGREEMENT_TREE_ABI, signer);
+      const tx = await tree.registerSubAgreement(BigInt(opts.parent), BigInt(opts.child));
+      const receipt = await tx.wait();
+
+      if (opts.json) {
+        console.log(JSON.stringify({ txHash: receipt.hash, parentId: opts.parent, childId: opts.child }));
+      } else {
+        console.log(`Sub-agreement registered.`);
+        console.log(`  Parent: ${opts.parent}  Child: ${opts.child}`);
+        console.log(`  tx: ${receipt.hash}`);
+      }
+    });
+
+  // ── arc402 agreements-tree <id> ──────────────────────────────────────────────
+  // Spec 19: arc402 agreements tree <agreementId>
+  program
+    .command("agreements-tree <agreementId>")
+    .description("View full agreement tree for an agreement (Spec 19)")
+    .option("--json", "Machine-parseable output")
+    .action(async (agreementId, opts) => {
+      const config = loadConfig();
+      if (!config.agreementTreeAddress) throw new Error("agreementTreeAddress missing in config");
+      const { provider } = await getClient(config);
+
+      const tree = new ethers.Contract(config.agreementTreeAddress, AGREEMENT_TREE_ABI, provider);
+
+      const id = BigInt(agreementId);
+      const [root, path, children, depth] = await Promise.all([
+        tree.getRoot(id),
+        tree.getPath(id),
+        tree.getChildren(id),
+        tree.getDepth(id),
+      ]);
+
+      const result = {
+        agreementId: agreementId,
+        root: root.toString(),
+        path: (path as bigint[]).map(String),
+        children: (children as bigint[]).map(String),
+        depth: Number(depth),
+      };
+
+      if (opts.json) {
+        console.log(JSON.stringify(result));
+        return;
+      }
+
+      console.log(`Agreement Tree — node #${agreementId}`);
+      console.log(`  Root:     #${result.root}`);
+      console.log(`  Depth:    ${result.depth}`);
+      console.log(`  Path:     ${result.path.map((p) => "#" + p).join(" → ")}`);
+      console.log(`  Children: ${result.children.length > 0 ? result.children.map((c) => "#" + c).join(", ") : "(none)"}`);
+    });
+
+  // ── arc402 agreements-tree-status <id> ───────────────────────────────────────
+  // Spec 19: arc402 agreements tree-status <agreementId>
+  program
+    .command("agreements-tree-status <agreementId>")
+    .description("Check whether all sub-agreements are settled before delivering (Spec 19)")
+    .option("--json", "Machine-parseable output")
+    .action(async (agreementId, opts) => {
+      const config = loadConfig();
+      if (!config.agreementTreeAddress) throw new Error("agreementTreeAddress missing in config");
+      const { provider } = await getClient(config);
+
+      const tree = new ethers.Contract(config.agreementTreeAddress, AGREEMENT_TREE_ABI, provider);
+
+      const id = BigInt(agreementId);
+      const [allSettled, children] = await Promise.all([
+        tree.allChildrenSettled(id),
+        tree.getChildren(id),
+      ]);
+
+      const result = {
+        agreementId: agreementId,
+        childCount: (children as bigint[]).length,
+        allChildrenSettled: Boolean(allSettled),
+        readyToDeliver: Boolean(allSettled),
+      };
+
+      if (opts.json) {
+        console.log(JSON.stringify(result));
+        return;
+      }
+
+      console.log(`Agreement #${agreementId} tree status:`);
+      console.log(`  Sub-agreements: ${result.childCount}`);
+      console.log(`  All settled:    ${result.allChildrenSettled ? "YES" : "NO"}`);
+      console.log(`  Ready to deliver to parent: ${result.readyToDeliver ? "YES" : "NO"}`);
+    });
+
+  // ── arc402 agreements-create-tree ────────────────────────────────────────────
+  // Spec 19: interactive multi-party agreement setup
+  // Usage: arc402 agreements-create-tree \
+  //   --provider <addr> --task <desc> --service-type <type> --price <wei> --deadline <s> \
+  //   --sub <addr>,<task>,<type>,<wei>,<deadline> [--sub ...]
+  program
+    .command("agreements-create-tree")
+    .description("Create a multi-party agreement tree: one root agreement plus sub-agreements (Spec 19)")
+    .requiredOption("--provider <address>", "Root provider (Agent B)")
+    .requiredOption("--task <description>", "Root task description")
+    .requiredOption("--service-type <type>", "Root service type")
+    .requiredOption("--price <wei>", "Root price in wei")
+    .requiredOption("--deadline <seconds>", "Root deadline offset in seconds from now")
+    .option(
+      "--sub <spec>",
+      "Sub-agreement in format <provider>,<task>,<serviceType>,<priceWei>,<deadlineSeconds>. Repeatable.",
+      (val: string, acc: string[]) => { acc.push(val); return acc; },
+      [] as string[],
+    )
+    .option("--interactive", "Prompt interactively for sub-agreements")
+    .option("--json", "Machine-parseable output")
+    .action(async (opts) => {
+      const config = loadConfig();
+      if (!config.serviceAgreementAddress) throw new Error("serviceAgreementAddress missing in config");
+      if (!config.agreementTreeAddress) throw new Error("agreementTreeAddress missing in config");
+      const { signer } = await getClient(config);
+      if (!signer) { console.error("No private key configured."); process.exit(1); }
+
+      type SubSpec = { provider: string; task: string; serviceType: string; price: bigint; deadline: number };
+      const subSpecs: SubSpec[] = [];
+
+      // Parse --sub flags
+      for (const raw of opts.sub as string[]) {
+        const parts = raw.split(",");
+        if (parts.length < 5) {
+          console.error(`--sub format: <provider>,<task>,<serviceType>,<priceWei>,<deadlineSeconds>  got: ${raw}`);
+          process.exit(1);
+        }
+        subSpecs.push({
+          provider: parts[0],
+          task: parts.slice(1, parts.length - 3).join(",") || parts[1],
+          serviceType: parts[parts.length - 3],
+          price: BigInt(parts[parts.length - 2]),
+          deadline: Number(parts[parts.length - 1]),
+        });
+      }
+
+      // Interactive mode: prompt for sub-agreements if no --sub flags provided
+      if (opts.interactive || subSpecs.length === 0) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q: string) => new Promise<string>((res) => rl.question(q, res));
+
+        console.log("\nMulti-party agreement setup — add sub-agreements (leave provider blank to finish)");
+        while (true) {
+          const provider = await ask("  Sub-provider address (blank to finish): ");
+          if (!provider.trim()) break;
+          const task = await ask("  Task description: ");
+          const serviceType = await ask("  Service type: ");
+          const priceRaw = await ask("  Price (wei): ");
+          const deadlineRaw = await ask("  Deadline offset (seconds): ");
+          subSpecs.push({
+            provider: provider.trim(),
+            task: task.trim(),
+            serviceType: serviceType.trim(),
+            price: BigInt(priceRaw.trim()),
+            deadline: Number(deadlineRaw.trim()),
+          });
+        }
+        rl.close();
+      }
+
+      const saContract = new ethers.Contract(config.serviceAgreementAddress, [
+        "function propose(address provider, string serviceType, string description, uint256 price, address token, uint256 deadline, bytes32 deliverablesHash) external payable returns (uint256)",
+        "event AgreementProposed(uint256 indexed id, address indexed client, address indexed provider, string serviceType, uint256 price, address token, uint256 deadline)",
+      ], signer);
+      const treeContract = new ethers.Contract(config.agreementTreeAddress, AGREEMENT_TREE_ABI, signer);
+
+      const rootPrice = BigInt(opts.price);
+      const rootDeadline = Number(opts.deadline);
+      const rootHash = hashString(opts.task);
+
+      if (!opts.json) console.log(`\nProposing root agreement to ${opts.provider}...`);
+      const rootTx = await saContract.propose(
+        opts.provider, opts.serviceType, opts.task,
+        rootPrice, ethers.ZeroAddress, rootDeadline, rootHash,
+        { value: rootPrice },
+      );
+      const rootReceipt = await rootTx.wait();
+      const iface = new ethers.Interface([
+        "event AgreementProposed(uint256 indexed id, address indexed client, address indexed provider, string serviceType, uint256 price, address token, uint256 deadline)",
+      ]);
+      let rootAgreementId: bigint | undefined;
+      for (const log of rootReceipt.logs) {
+        try {
+          const parsed = iface.parseLog(log);
+          if (parsed?.name === "AgreementProposed") { rootAgreementId = BigInt(parsed.args.id); break; }
+        } catch { /* skip */ }
+      }
+      if (rootAgreementId === undefined) throw new Error("Could not parse root AgreementProposed event");
+
+      if (!opts.json) console.log(`  Root agreement ID: ${rootAgreementId}`);
+
+      const childAgreementIds: bigint[] = [];
+      for (const sub of subSpecs) {
+        if (!opts.json) console.log(`  Proposing sub-agreement to ${sub.provider}...`);
+        const subHash = hashString(sub.task);
+        const subTx = await saContract.propose(
+          sub.provider, sub.serviceType, sub.task,
+          sub.price, ethers.ZeroAddress, sub.deadline, subHash,
+          { value: sub.price },
+        );
+        const subReceipt = await subTx.wait();
+        let childId: bigint | undefined;
+        for (const log of subReceipt.logs) {
+          try {
+            const parsed = iface.parseLog(log);
+            if (parsed?.name === "AgreementProposed") { childId = BigInt(parsed.args.id); break; }
+          } catch { /* skip */ }
+        }
+        if (childId === undefined) throw new Error(`Could not parse AgreementProposed for sub-agreement to ${sub.provider}`);
+        if (!opts.json) console.log(`    Sub-agreement ID: ${childId} — registering in tree...`);
+        await (await treeContract.registerSubAgreement(rootAgreementId, childId)).wait();
+        childAgreementIds.push(childId);
+      }
+
+      const result = {
+        rootAgreementId: rootAgreementId.toString(),
+        childAgreementIds: childAgreementIds.map(String),
+        txHash: rootReceipt.hash,
+      };
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`\nAgreement tree created.`);
+        console.log(`  Root:     #${result.rootAgreementId}`);
+        if (result.childAgreementIds.length > 0) {
+          console.log(`  Children: ${result.childAgreementIds.map((id) => "#" + id).join(", ")}`);
+        } else {
+          console.log(`  Children: (none — sub-agreements can be added with agreements-sub-register)`);
+        }
+      }
+    });
+
+  // ── arc402 agreements-tree <id> (alias) already exists above ─────────────────
+  // The spec also refers to this as "arc402 agreements tree <id>" — the flat
+  // command agreements-tree <agreementId> above fulfils that requirement.
+}

package/src/commands/arbitrator.ts

@@ -0,0 +1,129 @@
+import { Command } from "commander";
+import { DisputeArbitrationClient } from "@arc402/sdk";
+import { loadConfig } from "../config";
+import { getClient, requireSigner } from "../client";
+
+export function registerArbitratorCommand(program: Command): void {
+  const arbitrator = program
+    .command("arbitrator")
+    .description("Arbitrator panel operations: bonds, eligibility, status");
+
+  // Bond subcommands — nest under 'bond' to avoid duplicate registration
+  const bond = arbitrator
+    .command("bond")
+    .description("Arbitrator bond operations: status, accept, fallback");
+
+  bond
+    .command("status <arbitratorAddress> [agreementId]")
+    .description("Check arbitrator bond status for an agreement (or general eligibility)")
+    .action(async (arbitratorAddress, agreementId, _opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { provider } = await getClient(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, provider);
+
+      const eligible = await client.isEligibleArbitrator(arbitratorAddress);
+      console.log(`Arbitrator ${arbitratorAddress} eligible: ${eligible}`);
+
+      if (agreementId) {
+        const bondState = await client.getArbitratorBondState(arbitratorAddress, BigInt(agreementId));
+        console.log(`Bond state for agreement ${agreementId}:`);
+        console.log(`  Amount: ${bondState.bondAmount.toString()} tokens`);
+        console.log(`  Locked: ${bondState.locked}`);
+        console.log(`  Slashed: ${bondState.slashed}`);
+        console.log(`  Returned: ${bondState.returned}`);
+        console.log(`  Locked at: ${new Date(Number(bondState.lockedAt) * 1000).toISOString()}`);
+      }
+    });
+
+  bond
+    .command("accept <agreementId>")
+    .description("Accept panel assignment and post bond")
+    .option("--bond <bond>", "Bond amount in wei (for ETH agreements)", "0")
+    .action(async (agreementId, opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, signer);
+
+      const bondAmount = BigInt(opts.bond);
+      if (bondAmount === 0n) {
+        console.warn("Warning: bond amount is 0. For ERC-20 agreements, pre-approve the DisputeArbitration contract.");
+      }
+
+      await client.acceptAssignment(BigInt(agreementId), bondAmount);
+      console.log(`accepted assignment for agreement ${agreementId}`);
+    });
+
+  bond
+    .command("fallback <agreementId>")
+    .description("Trigger fallback to human backstop (mutual unfunded or panel incomplete)")
+    .action(async (agreementId, _opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, signer);
+      await client.triggerFallback(BigInt(agreementId));
+      console.log(`fallback triggered for ${agreementId}`);
+    });
+
+  // Rate subcommands — nest under 'rate'
+  const rate = arbitrator
+    .command("rate")
+    .description("Token USD rate management (owner only)");
+
+  rate
+    .command("set <tokenAddress> <usdPerToken>")
+    .description("Set USD rate for a token. Rate in USD with 18 decimals. e.g. 2000e18 for $2000")
+    .action(async (tokenAddress, usdPerToken, _opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, signer);
+
+      const rateVal = BigInt(usdPerToken);
+      await client.setTokenUsdRate(tokenAddress, rateVal);
+      console.log(`token rate set: ${tokenAddress} = ${rateVal.toString()} USD/token`);
+    });
+
+  // Admin: slash arbitrator (manual rules violation)
+  arbitrator
+    .command("slash <agreementId> <arbitratorAddress> <reason>")
+    .description("Owner only: manually slash an arbitrator for rules violation")
+    .action(async (agreementId, arbitratorAddress, reason, _opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, signer);
+      await client.slashArbitrator(BigInt(agreementId), arbitratorAddress, reason);
+      console.log(`slashed arbitrator ${arbitratorAddress} for ${reason}`);
+    });
+
+  arbitrator
+    .command("reclaim-bond <agreementId>")
+    .description("Reclaim an arbitrator bond after 45 days if dispute was never resolved via resolveDisputeFee")
+    .action(async (agreementId, _opts) => {
+      const config = loadConfig();
+      if (!config.disputeArbitrationAddress) throw new Error("disputeArbitrationAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new DisputeArbitrationClient(config.disputeArbitrationAddress, signer);
+      await client.reclaimExpiredBond(BigInt(agreementId));
+      console.log(`bond reclaimed for agreement ${agreementId}`);
+    });
+
+  arbitrator
+    .command("resolve-from <agreementId>")
+    .description("Resolve a dispute from arbitration with split amounts (calls ServiceAgreement.resolveFromArbitration)")
+    .requiredOption("--recipient <address>", "Winning recipient address")
+    .requiredOption("--provider-amount <amount>", "Provider payout in wei/tokens")
+    .requiredOption("--client-amount <amount>", "Client refund in wei/tokens")
+    .action(async (agreementId, opts) => {
+      const { ServiceAgreementClient } = await import("@arc402/sdk");
+      const config = loadConfig();
+      if (!config.serviceAgreementAddress) throw new Error("serviceAgreementAddress missing in config");
+      const { signer } = await requireSigner(config);
+      const client = new ServiceAgreementClient(config.serviceAgreementAddress, signer);
+      await client.resolveFromArbitration(BigInt(agreementId), opts.recipient, BigInt(opts.providerAmount), BigInt(opts.clientAmount));
+      console.log(`resolved from arbitration: agreement ${agreementId}, recipient ${opts.recipient}`);
+    });
+}

package/src/commands/arena-handshake.ts

@@ -0,0 +1,217 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import { loadConfig, getUsdcAddress } from "../config";
+import { requireSigner } from "../client";
+
+// ─── Handshake Contract ABI (from Handshake.sol) ─────────────────────────────
+
+const HANDSHAKE_ABI = [
+  "function sendHandshake(address to, uint8 hsType, string note) payable",
+  "function sendHandshakeWithToken(address to, uint8 hsType, string note, address token, uint256 tokenAmount)",
+  "function sendBatch(address[] recipients, uint8[] hsTypes, string[] notes)",
+  "function hasConnection(address from, address to) view returns (bool)",
+  "function isMutual(address a, address b) view returns (bool)",
+  "function getStats(address agent) view returns (uint256 sent, uint256 received, uint256 uniqueInbound)",
+  "function sentCount(address) view returns (uint256)",
+  "function receivedCount(address) view returns (uint256)",
+  "function uniqueSenders(address) view returns (uint256)",
+  "function totalHandshakes() view returns (uint256)",
+  "function allowedTokens(address) view returns (bool)",
+  "event HandshakeSent(uint256 indexed handshakeId, address indexed from, address indexed to, uint8 hsType, address token, uint256 amount, string note, uint256 timestamp)",
+  "event NewConnection(address indexed from, address indexed to, uint256 handshakeId)",
+];
+
+const POLICY_ENGINE_ABI = [
+  "function isContractWhitelisted(address wallet, address target) view returns (bool)",
+  "function whitelistContract(address wallet, address target)",
+];
+
+const HANDSHAKE_TYPES: Record<string, number> = {
+  respect: 0,
+  curiosity: 1,
+  endorsement: 2,
+  thanks: 3,
+  collaboration: 4,
+  challenge: 5,
+  referral: 6,
+  hello: 7,
+};
+
+// ─── Auto-Whitelist ──────────────────────────────────────────────────────────
+
+async function ensureWhitelisted(
+  signer: ethers.Signer,
+  provider: ethers.Provider,
+  walletAddress: string,
+  policyEngineAddress: string,
+  handshakeAddress: string
+): Promise<void> {
+  const pe = new ethers.Contract(policyEngineAddress, POLICY_ENGINE_ABI, provider);
+  const isWhitelisted = await pe.isContractWhitelisted(walletAddress, handshakeAddress);
+
+  if (!isWhitelisted) {
+    console.log("Handshake contract not yet whitelisted on your wallet.");
+    console.log("Whitelisting now (one-time setup)...");
+
+    const peSigner = new ethers.Contract(policyEngineAddress, POLICY_ENGINE_ABI, signer);
+    const tx = await peSigner.whitelistContract(walletAddress, handshakeAddress);
+    console.log(`  tx: ${tx.hash}`);
+    await tx.wait();
+    console.log("  ✓ Handshake contract whitelisted\n");
+  }
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+export function registerArenaHandshakeCommands(program: Command): void {
+  const hs = program
+    .command("shake")
+    .description("ARC Arena social handshake — send a typed trust signal to another agent.");
+
+  // ── send ──────────────────────────────────────────────────────────────────
+  hs.command("send <agentAddress>")
+    .description("Send a handshake to another agent.")
+    .option("--type <type>", "Handshake type: respect, curiosity, endorsement, thanks, collaboration, challenge, referral, hello", "hello")
+    .option("--note <note>", "Short message (max 280 chars)", "")
+    .option("--tip <amount>", "ETH tip to attach (e.g. 0.01)")
+    .option("--usdc <amount>", "USDC tip to attach (e.g. 5.00)")
+    .option("--json", "Output as JSON")
+    .action(async (agentAddress: string, opts) => {
+      const config = loadConfig();
+      const { signer, provider } = await requireSigner(config);
+      const myAddress = await signer.getAddress();
+
+      if (!config.handshakeAddress) {
+        console.error("handshakeAddress not configured. Run: arc402 config set handshakeAddress <address>");
+        process.exit(1);
+      }
+      if (!config.policyEngineAddress) {
+        console.error("policyEngineAddress not configured.");
+        process.exit(1);
+      }
+
+      // Auto-whitelist check
+      await ensureWhitelisted(signer, provider, myAddress, config.policyEngineAddress, config.handshakeAddress);
+
+      const hsType = HANDSHAKE_TYPES[opts.type.toLowerCase()];
+      if (hsType === undefined) {
+        console.error(`Unknown handshake type: ${opts.type}`);
+        console.error(`Valid types: ${Object.keys(HANDSHAKE_TYPES).join(", ")}`);
+        process.exit(1);
+      }
+
+      const handshake = new ethers.Contract(config.handshakeAddress, HANDSHAKE_ABI, signer);
+
+      let tx;
+      if (opts.usdc) {
+        // USDC handshake
+        const usdcAddress = getUsdcAddress(config);
+        const amount = ethers.parseUnits(opts.usdc, 6);
+        tx = await handshake.sendHandshakeWithToken(agentAddress, hsType, opts.note, usdcAddress, amount);
+      } else {
+        // ETH handshake (with optional tip)
+        const value = opts.tip ? ethers.parseEther(opts.tip) : 0n;
+        tx = await handshake.sendHandshake(agentAddress, hsType, opts.note, { value });
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify({ tx: tx.hash, from: myAddress, to: agentAddress, type: opts.type, note: opts.note }));
+      } else {
+        console.log(`✓ Handshake sent`);
+        console.log(`  From: ${myAddress}`);
+        console.log(`  To:   ${agentAddress}`);
+        console.log(`  Type: ${opts.type}`);
+        if (opts.note) console.log(`  Note: ${opts.note}`);
+        if (opts.tip) console.log(`  Tip:  ${opts.tip} ETH`);
+        if (opts.usdc) console.log(`  Tip:  ${opts.usdc} USDC`);
+        console.log(`  tx:   ${tx.hash}`);
+      }
+    });
+
+  // ── batch ─────────────────────────────────────────────────────────────────
+  hs.command("batch")
+    .description("Send handshakes to multiple agents at once (onboarding ritual).")
+    .argument("<agents...>", "Agent addresses to handshake (up to 10)")
+    .option("--type <type>", "Handshake type for all", "hello")
+    .option("--note <note>", "Note for all", "")
+    .action(async (agents: string[], opts) => {
+      const config = loadConfig();
+      const { signer, provider } = await requireSigner(config);
+      const myAddress = await signer.getAddress();
+
+      if (!config.handshakeAddress || !config.policyEngineAddress) {
+        console.error("handshakeAddress or policyEngineAddress not configured.");
+        process.exit(1);
+      }
+
+      await ensureWhitelisted(signer, provider, myAddress, config.policyEngineAddress, config.handshakeAddress);
+
+      const hsType = HANDSHAKE_TYPES[opts.type.toLowerCase()];
+      if (hsType === undefined) {
+        console.error(`Unknown type: ${opts.type}. Valid: ${Object.keys(HANDSHAKE_TYPES).join(", ")}`);
+        process.exit(1);
+      }
+
+      if (agents.length > 10) {
+        console.error("Max 10 agents per batch.");
+        process.exit(1);
+      }
+
+      const handshake = new ethers.Contract(config.handshakeAddress, HANDSHAKE_ABI, signer);
+      const types = agents.map(() => hsType);
+      const notes = agents.map(() => opts.note);
+
+      const tx = await handshake.sendBatch(agents, types, notes);
+      console.log(`✓ Batch handshake sent to ${agents.length} agents`);
+      agents.forEach(a => console.log(`  → ${a}`));
+      console.log(`  tx: ${tx.hash}`);
+    });
+
+  // ── stats ─────────────────────────────────────────────────────────────────
+  hs.command("stats [address]")
+    .description("View handshake stats for an agent.")
+    .action(async (address?: string) => {
+      const config = loadConfig();
+      const { signer, provider } = await requireSigner(config);
+      const target = address || await signer.getAddress();
+
+      if (!config.handshakeAddress) {
+        console.error("handshakeAddress not configured.");
+        process.exit(1);
+      }
+
+      const handshake = new ethers.Contract(config.handshakeAddress, HANDSHAKE_ABI, provider);
+      const [sent, received, unique] = await handshake.getStats(target);
+      const total = await handshake.totalHandshakes();
+
+      console.log(`Handshake Stats: ${target}`);
+      console.log(`  Sent:            ${sent}`);
+      console.log(`  Received:        ${received}`);
+      console.log(`  Unique senders:  ${unique}`);
+      console.log(`  Network total:   ${total}`);
+    });
+
+  // ── check ─────────────────────────────────────────────────────────────────
+  hs.command("check <agentAddress>")
+    .description("Check if a connection or mutual handshake exists with an agent.")
+    .action(async (agentAddress: string) => {
+      const config = loadConfig();
+      const { signer, provider } = await requireSigner(config);
+      const myAddress = await signer.getAddress();
+
+      if (!config.handshakeAddress) {
+        console.error("handshakeAddress not configured.");
+        process.exit(1);
+      }
+
+      const handshake = new ethers.Contract(config.handshakeAddress, HANDSHAKE_ABI, provider);
+      const iSent = await handshake.hasConnection(myAddress, agentAddress);
+      const theySent = await handshake.hasConnection(agentAddress, myAddress);
+      const mutual = await handshake.isMutual(myAddress, agentAddress);
+
+      console.log(`Connection: ${myAddress} ↔ ${agentAddress}`);
+      console.log(`  You → them: ${iSent ? "✓ handshaked" : "✗ no handshake"}`);
+      console.log(`  Them → you: ${theySent ? "✓ handshaked" : "✗ no handshake"}`);
+      console.log(`  Mutual:     ${mutual ? "✓ yes" : "✗ no"}`);
+    });
+}