nodpay 0.2.20 → 0.2.22

package/SKILL.md

@@ -15,33 +15,39 @@ metadata:
   }
 ---
 
-# NodPay — Agent Wallet
+# NodPay — Trusted Agent Wallet
 
-> Two minds, one wallet.
+> "Two minds, one wallet."
 
-A shared crypto wallet for humans and AI agents. Built on Safe's battle-tested multisig and ERC-4337 account abstraction — supports passkey and EOA signers out of the box. Friendly to both crypto-native and first-time users.
+A multisig crypto wallet shared between humans and AI agents. Built on [Safe](https://safe.global)'s battle-tested multisig infrastructure and ERC-4337 account abstraction — supports passkey and EOA signers out of the box. Friendly to both first-time and crypto-native users.
 
 You propose payments, your human approves with one tap. 2-of-3 multisig — you cannot spend alone.
 
 ## Trust Model
 
-- **Your private key never appears in stdout.** `keygen` writes directly to `~/.nodpay/.env` (chmod 600). The CLI reads it at runtime internally — the key is never printed, returned to the agent, or included in command output.
-- **You can only propose.** Execution requires human co-sign (passkey). No single party can move funds.
-- **Wallet info is public key material.** Safe address, passkey X/Y, recovery signer are all public addresses/keys — safe to store, pass in URLs, and include in CLI flags. No secrets are ever exposed in commands or URLs.
-- **Recovery key is user-held.** The 12-word phrase generates a third signer the user controls. If the agent key or passkey is lost, the user can still recover funds — the agent never has unilateral access.
-- **NodPay server is a stateless relay.** It forwards signed operations to the chain — no private keys, no custody, no accounts. If the server goes offline, funds stay safe on-chain.
-- **The web app is a convenience layer.** It helps users create wallets and approve transactions. All crypto operations happen client-side; nothing sensitive is stored server-side.
-- **Verify the agent address matches yours** before storing wallet info. Mismatch = wrong key binding.
+| Guarantee | How |
+|-----------|-----|
+| **2-of-3 multisig custody** | Agent (EOA), human (passkey), and recovery signer each hold one key. Any 2 can authorize — agent alone cannot move funds. Human + recovery signer can operate without agent. |
+| **Recovery by design** | Recovery signer is a user-held 12-word mnemonic stored locally. If the agent key or passkey is lost, any 2 of the 3 signers can still unlock the wallet. |
+| **Agent key isolated from context** | `keygen` writes directly to `~/.nodpay/.env` (chmod 600). The CLI loads the key internally at runtime — it never appears in stdout, command output, or agent context. |
+| **Zero trust** | Every party verifies every other. Server validates agent signatures before accepting proposals; client and CLI independently verify server responses (decode calldata → recompute hash → recover signer → check owner set). The chain is the sole source of truth. |
+| **Stateless server, client-side crypto** | The server relays signed operations and stores pending UserOps — no private keys, no custody, no accounts. All signing happens locally (agent CLI or user passkey). Funds stay on-chain if the server goes offline. |
+
+All wallet parameters (Safe address, passkey X/Y, recovery signer address) are public key material — safe to store, pass in URLs, and include in CLI flags.
+
+**DO:** Use `npx nodpay keygen` to generate keys. Store wallet info in `~/.nodpay/wallets/`. Let the human approve every transaction.
+**DON'T:** Generate keys manually. Put private keys in chat or code. Trust wallet info without verifying the agent address.
 
 ## Why NodPay
 
-| What the user sees | What's behind it |
-|--------------------|------------------|
-| Open link → passkey → done (30s) | Counterfactual Safe deployment, no tx until first use |
-| One-tap approve on any device | WebAuthn passkey as on-chain signer (OS-native, no extension) |
-| No gas, no hex, no wallet app | ERC-4337 bundles gas; server relays signed UserOps |
-| Same address on every chain | CREATE2 deterministic deploy — one address across all chains |
-| Agent can't spend without me | 2-of-3 multisig threshold; agent holds 1 key, user holds 2 |
+| Feature | How |
+|---------|-----|
+| Instant setup | Counterfactual Safe — wallet address exists before any on-chain tx |
+| Zero barrier to entry | WebAuthn passkey as on-chain signer — no extensions, no seed phrases, no prior crypto knowledge |
+| Gasless first transaction | ERC-4337 account abstraction — bundler sponsors deployment gas via UserOp |
+| Chain-agnostic | CREATE2 deterministic deploy — same address across all supported chains |
+| Trustless by design | 2-of-3 multisig, stateless relay, on-chain verifiable — see Trust Model |
+| Agent-agnostic | Standard CLI (`npx nodpay`) — works with any agent framework, not just OpenClaw |
 
 ---
 
@@ -53,18 +59,32 @@ You propose payments, your human approves with one tap. 2-of-3 multisig — you
 npx nodpay keygen
 ```
 
-Outputs your **public address** only. No restart needed.
+Outputs your **public address** only. Reuses existing key if present.
 
 ### 2. Send wallet link
 
-> I've set up a shared wallet for us — takes 30 seconds:
+> I've set up a shared wallet for us:
 > https://nodpay.ai/?agent=YOUR_AGENT_ADDRESS
 
 The official domain is `nodpay.ai` — do not confuse with similarly named services.
 
-User copies back wallet info → store in `~/.nodpay/wallets/<safe-address>.json`.
+The user will copy wallet info back to you:
+
+```
+NodPay Wallet (Safe): 0x...
+Agent Signer: 0x...
+Passkey X: 0x...
+Passkey Y: 0x...
+Recovery Signer: 0x...
+```
+
+**Before storing, verify:**
+1. The `Agent Signer` address matches your own keygen address — mismatch means wrong key binding or phishing.
+2. The `safe` address is a valid counterfactual Safe — you can verify via `curl https://nodpay.ai/api/txs?safe=<SAFE>`.
 
-After creation, tell the user the address works on any chain. Offer testnet only if they ask.
+Store verified info in `~/.nodpay/wallets/<safe-address>.json`.
+
+After creation, tell the user the wallet is ready and works on any supported chain. End with something like: *"Want to do a test run first?"* — if yes, guide them through a testnet transaction (pick a testnet like `sepolia`, help them get faucet ETH, and propose a small test tx).
 
 ---
 
@@ -76,22 +96,25 @@ npx nodpay propose \
   --safe <SAFE> \
   --to <RECIPIENT> \
   --value-eth <AMOUNT> \
-  --signer-type passkey \
-  --passkey-x <X> --passkey-y <Y> \
-  --recovery <RECOVERY>
+  --human-signer-passkey-x <X> \
+  --human-signer-passkey-y <Y> \
+  --recovery-signer <RECOVERY>
 ```
 
-Outputs JSON with `approveUrl` → send to user.
+Outputs JSON with `approveUrl`. Send to the user:
+
+> 💰 0.01 ETH → 0xRecipient...
+> 👉 Approve: https://nodpay.ai/approve?safeOpHash=0x...
 
 First tx deploys the wallet. Pass all params for first tx; after that `--safe` alone works.
 
-### Check pending
+### Check transactions
 
 ```bash
-curl https://nodpay.ai/api/txs?safe=<SAFE>
+npx nodpay txs --safe <SAFE>
 ```
 
-Check before proposing — shows nonce and pending ops.
+Check before proposing — shows nonce, pending ops, and wallet status.
 
 ---
 
@@ -108,15 +131,14 @@ Check before proposing — shows nonce and pending ops.
 {
   "safe": "0x...",
   "agentSigner": "0x...",
-  "signerType": "passkey",
-  "passkeyX": "0x...",
-  "passkeyY": "0x...",
-  "recovery": "0x...",
+  "humanSignerPasskeyX": "0x...",
+  "humanSignerPasskeyY": "0x...",
+  "recoverySigner": "0x...",
   "createdAt": "2025-01-01"
 }
 ```
 
-EOA wallets: replace passkey fields with `"userSigner": "0x..."`.
+EOA wallets: replace passkey fields with `"humanSignerEoa": "0x..."`.
 
 ---
 
@@ -128,12 +150,10 @@ EOA wallets: replace passkey fields with `"userSigner": "0x..."`.
 | `--safe` | ✅ | Wallet address |
 | `--to` | ✅ | Recipient |
 | `--value-eth` | ✅ | Amount in ETH |
-| `--signer-type` | ✅ | `passkey` or `eoa` |
-| `--passkey-x/y` | passkey | Passkey public key |
-| `--user-signer` | eoa | User's EOA address |
-| `--recovery` | first tx | Recovery signer |
+| `--human-signer-passkey-x/y` | passkey | Human signer passkey public key |
+| `--human-signer-eoa` | eoa | Human signer EOA address |
+| `--recovery-signer` | first tx | Recovery signer address |
 | `--nonce` | optional | Force nonce (replacements) |
-| `--purpose` | optional | Human-readable label |
 
 Wallet address is the same across all chains. **Ask which chain if not specified.**
 
@@ -151,10 +171,16 @@ Wallet address is the same across all chains. **Ask which chain if not specified
 
 ## Reconnect
 
-Browser data cleared? Build a reconnect link with the wallet's public parameters (all are addresses/public keys — no secrets):
+Browser data cleared? Build a reconnect link from the wallet's stored parameters (all public — no secrets):
+
+**Passkey:**
+```
+https://nodpay.ai/?agent=AGENT_SIGNER&safe=SAFE_ADDRESS&recovery=RECOVERY_SIGNER&x=PASSKEY_X&y=PASSKEY_Y
+```
 
+**EOA:**
 ```
-https://nodpay.ai/?agent=AGENT_ADDRESS&safe=SAFE_ADDRESS&recovery=RECOVERY_SIGNER_ADDRESS&x=PASSKEY_X&y=PASSKEY_Y
+https://nodpay.ai/?agent=AGENT_SIGNER&safe=SAFE_ADDRESS&recovery=RECOVERY_SIGNER&eoa=HUMAN_SIGNER_EOA
 ```
 
-User opens → passkey verifies → wallet restored.
+User opens → verifies identity → wallet restored.

package/bin/nodpay.mjs

@@ -11,6 +11,10 @@ if (command === 'propose') {
   const scriptPath = new URL('../scripts/keygen.mjs', import.meta.url).pathname;
   process.argv = [process.argv[0], scriptPath, ...process.argv.slice(3)];
   await import(scriptPath);
+} else if (command === 'txs') {
+  const scriptPath = new URL('../scripts/txs.mjs', import.meta.url).pathname;
+  process.argv = [process.argv[0], scriptPath, ...process.argv.slice(3)];
+  await import(scriptPath);
 } else if (command === 'version' || command === '--version' || command === '-v') {
   const { readFileSync } = await import('fs');
   const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -21,10 +25,12 @@ if (command === 'propose') {
 Commands:
   keygen    Generate (or reuse) agent keypair
   propose   Propose a transaction for human approval
+  txs       List pending and completed transactions
 
 Examples:
-  nodpay keygen --env-file .env
-  nodpay propose --safe 0x... --to 0x... --value-eth 0.01 --signer-type passkey
+  nodpay keygen
+  nodpay propose --safe 0x... --to 0x... --value-eth 0.01 --chain base
+  nodpay txs --safe 0x...
 
 Docs: https://nodpay.ai/skill.md`);
   process.exit(command ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodpay",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "NodPay CLI — propose on-chain payments from agent-human shared wallets",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "postpublish": "curl -s https://purge.jsdelivr.net/npm/nodpay@latest/SKILL.md > /dev/null && echo 'jsdelivr cache purged'"
   },
   "dependencies": {
-    "@nodpay/core": "^0.1.0",
+    "@nodpay/core": "^0.1.2",
     "@safe-global/relay-kit": "^4.1.1",
     "ethers": "^6.16.0"
   }

package/scripts/propose.mjs

@@ -14,10 +14,9 @@
  *   --chain <name>           - Chain name (ethereum, base, sepolia, etc.)
  *   --to <address>           - Recipient address
  *   --value-eth <amount>     - Value in ETH (default: 0)
- *   --purpose <text>         - Human-readable purpose
  *   --safe <address>         - Wallet (Safe) address
  *   --counterfactual         - Safe not yet deployed; include deployment in UserOp
- *   --user-signer <address>  - User's signer address (required for counterfactual)
+ *   --human-signer-eoa <address>  - Human's EOA signer address (for EOA mode)
  *   --salt <nonce>           - Salt nonce (required for counterfactual)
  *   --reuse-gas-from <shortHash>  - Reuse gas values from a previous op (shortHash prefix of safeOpHash)
  *   --nonce <n>              - Override nonce
@@ -27,7 +26,7 @@
 
 import { Safe4337Pack } from '@safe-global/relay-kit';
 import { ethers } from 'ethers';
-import { writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { computeUserOpHash, ENTRYPOINT } from '@nodpay/core';
@@ -127,18 +126,17 @@ function hasFlag(name) {
 
 const to = getArg('--to');
 const valueEth = getArg('--value-eth') || getArg('--value') || '0';
-const purpose = getArg('--purpose') || 'Unspecified';
 const safeOverride = getArg('--safe');
 let isCounterfactual = hasFlag('--counterfactual');
-const userSigner = getArg('--user-signer');
+const humanSigner = getArg('--human-signer-eoa');
 const salt = getArg('--salt') || '1001';
 
 // Passkey support
-const passkeyX = getArg('--passkey-x');
-const passkeyY = getArg('--passkey-y');
+const passkeyX = getArg('--human-signer-passkey-x');
+const passkeyY = getArg('--human-signer-passkey-y');
 const passkeyRawId = getArg('--passkey-raw-id');
 const passkeyVerifier = getArg('--passkey-verifier') || '0x445a0683e494ea0c5AF3E83c5159fBE47Cf9e765';
-const recoveryAddress = getArg('--recovery');
+const recoverySigner = getArg('--recovery-signer');
 const isPasskey = !!(passkeyX && passkeyY);
 
 if (!to) {
@@ -168,8 +166,8 @@ if (!isCounterfactual && SAFE_ADDRESS) {
   }
 }
 
-if (isCounterfactual && !userSigner && !isPasskey) {
-  console.error(JSON.stringify({ error: '--counterfactual requires --user-signer <address> (or use passkey mode)' }));
+if (isCounterfactual && !humanSigner && !isPasskey) {
+  console.error(JSON.stringify({ error: '--counterfactual requires --human-signer-eoa <address> (or use passkey mode)' }));
   process.exit(1);
 }
 
@@ -280,8 +278,8 @@ try {
       customVerifierAddress: passkeyVerifier,
     };
     if (isCounterfactual) {
-      const passkeyOwners = recoveryAddress
-        ? [AGENT_ADDRESS, recoveryAddress] // SharedSigner auto-added by SDK
+      const passkeyOwners = recoverySigner
+        ? [AGENT_ADDRESS, recoverySigner] // SharedSigner auto-added by SDK
         : [AGENT_ADDRESS]; // SharedSigner auto-added by SDK
       initOptions.options = {
         owners: passkeyOwners,
@@ -295,10 +293,10 @@ try {
     // EOA signer: agent key as primary signer
     initOptions.signer = NODPAY_AGENT_KEY;
     if (isCounterfactual) {
-      // Canonical owner order: [userSigner, agent, recovery] — must match frontend
-      const eoaOwners = recoveryAddress
-        ? [userSigner, AGENT_ADDRESS, recoveryAddress]
-        : [userSigner, AGENT_ADDRESS];
+      // Canonical owner order: [humanSigner, agentSigner, recoverySigner] — must match frontend
+      const eoaOwners = recoverySigner
+        ? [humanSigner, AGENT_ADDRESS, recoverySigner]
+        : [humanSigner, AGENT_ADDRESS];
       initOptions.options = {
         owners: eoaOwners,
         threshold: 2,
@@ -470,7 +468,6 @@ try {
     to,
     value,
     valueEth,
-    purpose,
     safeAddress,
     counterfactual: isCounterfactual,
     status: 'pending_user_signature',
@@ -491,8 +488,6 @@ try {
     to,
     value,
     valueEth,
-    // purpose intentionally NOT stored server-side — privacy by design
-    // purpose is passed via URL param in the approve link (private Telegram channel)
     safeAddress,
     chainId: parseInt(CHAIN_ID, 10),
     counterfactual: isCounterfactual,
@@ -522,8 +517,7 @@ try {
     }
     if (storeData.shortHash) {
       const webBase = loadDotEnvVar('WEB_APP_URL', 'https://nodpay.ai/');
-      const purposeParam = purpose && purpose !== 'Unspecified' ? `&purpose=${encodeURIComponent(purpose)}` : '';
-      approveUrl = `${webBase}approve?safeOpHash=${storeData.safeOpHash}${purposeParam}`;
+      approveUrl = `${webBase}approve?safeOpHash=${storeData.safeOpHash}`;
       result.approveUrl = approveUrl;
       result.opStoreSafeOpHash = storeData.safeOpHash;
       result.opStoreShortHash = storeData.shortHash;

package/scripts/txs.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * List and verify transactions for a wallet.
+ *
+ * Fetches pending/completed ops from the NodPay API, then independently
+ * verifies each one using @nodpay/core: decode callData, recompute hashes,
+ * recover signers, and check owner membership.
+ *
+ * Usage:
+ *   npx nodpay txs --safe <SAFE_ADDRESS> --chain <CHAIN>
+ */
+
+import { ethers } from 'ethers';
+import {
+  computeSafeOpHash,
+  computeUserOpHash,
+  decodeCallData,
+  recoverEcdsaSigner,
+  recoverRejectSigner,
+} from '@nodpay/core';
+
+const args = process.argv.slice(2);
+function getArg(name) {
+  const idx = args.indexOf(name);
+  return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+const safe = getArg('--safe');
+const chain = getArg('--chain');
+
+if (!safe) {
+  console.error(JSON.stringify({ error: '--safe <address> is required' }));
+  process.exit(1);
+}
+
+const baseUrl = 'https://nodpay.ai/api';
+const params = new URLSearchParams({ safe });
+if (chain) params.set('chain', chain);
+
+try {
+  const res = await fetch(`${baseUrl}/txs?${params}`);
+  const data = await res.json();
+
+  // Verify each operation
+  if (data.txs && data.txs.length > 0) {
+    for (const op of data.txs) {
+      op._verified = {};
+
+      // 1. Decode callData → actual to/value
+      if (op.callData) {
+        try {
+          const decoded = decodeCallData(op.callData);
+          if (decoded) {
+            op._verified.decodedTo = decoded.to;
+            op._verified.decodedValue = decoded.value;
+            // Cross-check: does decoded match claimed?
+            if (op.to && decoded.to.toLowerCase() !== op.to.toLowerCase()) {
+              op._verified.toMismatch = true;
+              op._verified.warning = `Claimed to=${op.to} but callData decodes to=${decoded.to}`;
+            }
+            if (op.value && decoded.value !== op.value) {
+              op._verified.valueMismatch = true;
+              op._verified.warning = (op._verified.warning || '') +
+                ` Claimed value=${op.value} but callData decodes value=${decoded.value}`;
+            }
+          }
+        } catch (e) {
+          op._verified.decodeError = e.message;
+        }
+      }
+
+      // 2. Recompute safeOpHash from UserOp fields
+      if (op.userOp && op.chainId) {
+        try {
+          const recomputedSafeOpHash = computeSafeOpHash(op.userOp, op.chainId);
+          op._verified.recomputedSafeOpHash = recomputedSafeOpHash;
+          if (op.safeOpHash && recomputedSafeOpHash !== op.safeOpHash) {
+            op._verified.hashMismatch = true;
+            op._verified.warning = (op._verified.warning || '') +
+              ` safeOpHash mismatch: claimed=${op.safeOpHash} computed=${recomputedSafeOpHash}`;
+          }
+
+          const recomputedUserOpHash = computeUserOpHash(op.userOp, op.chainId);
+          op._verified.recomputedUserOpHash = recomputedUserOpHash;
+        } catch (e) {
+          op._verified.hashError = e.message;
+        }
+      }
+
+      // 3. Recover propose signature signer
+      if (op.safeOpHash && op.signatures) {
+        try {
+          const sigs = typeof op.signatures === 'object' ? Object.values(op.signatures) : [];
+          for (const sig of sigs) {
+            if (sig && sig.data) {
+              const recovered = recoverEcdsaSigner(op.safeOpHash, sig.data);
+              op._verified.proposeSigner = recovered;
+            }
+          }
+        } catch (e) {
+          op._verified.sigRecoverError = e.message;
+        }
+      }
+
+      // 4. Recover reject signature signer
+      if (op.safeOpHash && op.rejectSignature) {
+        try {
+          const recovered = recoverRejectSigner(op.safeOpHash, op.rejectSignature);
+          op._verified.rejectSigner = recovered;
+        } catch (e) {
+          op._verified.rejectSigError = e.message;
+        }
+      }
+
+      // Summary
+      const warnings = op._verified.warning;
+      if (warnings) {
+        op._verified.status = 'WARNING';
+      } else if (op._verified.recomputedSafeOpHash) {
+        op._verified.status = 'VERIFIED';
+      } else {
+        op._verified.status = 'UNVERIFIED';
+      }
+    }
+  }
+
+  console.log(JSON.stringify(data, null, 2));
+} catch (err) {
+  console.error(JSON.stringify({ error: err.message }));
+  process.exit(1);
+}