nodpay 0.2.30 → 0.2.32

package/README.md

@@ -16,12 +16,14 @@ This npm package (`nodpay`) is the **agent-facing CLI**. It is also published as
 | **ClawHub** (`clawhub install nodpay`) | `SKILL.md` only | OpenClaw agents |
 | **nodpay.ai/skill.md** | `SKILL.md` via CDN proxy | All agent frameworks |
 
-The CLI provides three commands:
+The CLI provides five commands:
 
 ```
 nodpay keygen     # Generate agent keypair (~/.nodpay/.env, chmod 600)
-nodpay propose    # Propose a transaction for human approval
+nodpay nonce      # Query next nonce (on-chain EntryPoint + pending proposals)
+nodpay propose    # Propose a transaction for human approval (--nonce required)
 nodpay txs        # List and verify transactions for a wallet
+nodpay gasprice   # Get current gas price + estimated cost per chain
 ```
 
 ## Quick Start
@@ -30,25 +32,32 @@ nodpay txs        # List and verify transactions for a wallet
 # 1. Generate key (public address only in stdout; key never exposed)
 npx nodpay keygen
 
-# 2. Propose a payment
+# 2. Get next nonce (on-chain + pending)
+npx nodpay nonce --safe 0xWALLET --chain base
+
+# 3. Propose a payment
 npx nodpay propose \
   --chain base \
   --safe 0xWALLET \
   --to 0xRECIPIENT \
   --value-eth 0.01 \
+  --nonce 0 \
   --human-signer-passkey-x 0x... \
   --human-signer-passkey-y 0x... \
   --recovery-signer 0x...
 
-# 3. Check pending transactions (with verification)
+# 4. Check transactions (with verification)
 npx nodpay txs --safe 0xWALLET
+
+# 5. Estimate gas cost for a sweep
+npx nodpay gasprice --chain base
 ```
 
 ## Security
 
 All config lives in `~/.nodpay/` — zero `process.env` references in code.
 
-- **Hardened Key Isolation:** private key written directly to `~/.nodpay/.env` (chmod 600), strictly excluded from stdout and agent context.
+- **Hardened Key Isolation:** private key written to `~/.nodpay/.env` (chmod 600), read via file I/O at runtime. Not passed through CLI args, env vars, or stdout.
 - **Zero Trust:** `txs` independently verifies every server response (decode calldata → recompute hash → recover signer → check owner set).
 - **Threshold Security:** 2-of-3 multisig — agent cannot move funds unilaterally.
 

package/SKILL.md

@@ -9,7 +9,7 @@ metadata:
         "homepage": "https://nodpay.ai",
         "install": [{ "id": "node", "kind": "node", "package": "nodpay", "label": "Install NodPay CLI (npm)", "author": "xhyumiracle", "source": "https://github.com/xhyumiracle/nodpay-cli" }]
       },
-    "credentials": "Agent signing key stored in ~/.nodpay/.env (generated by npx nodpay keygen, never exposed to agent context)",
+    "credentials": "Agent signing key stored in ~/.nodpay/.env (chmod 600, generated by npx nodpay keygen). Read at runtime by CLI process; not passed via CLI args, env vars, or stdout.",
     "persistence": ["~/.nodpay/.env (agent key, chmod 600)", "~/.nodpay/wallets/*.json (wallet info, public key material)"],
     "network": ["nodpay.ai (op-store relay + wallet creation UI)", "Public RPC endpoints via --chain"]
   }
@@ -30,7 +30,7 @@ You propose payments, your human approves with one tap. 2-of-3 multisig — you
 | **Threshold Security** | **Elimination of single point of failure:** authority keys are distributed between the agent, human, and a recovery signer (2-of-3 multisig). Ensures non-custodial control — the agent cannot move funds unilaterally. |
 | **Zero Trust** | **End-to-end verification:** no party is implicitly trusted. Server validates signatures; client and CLI independently verify server responses (decode calldata → recompute hash → recover signer → check owner set). The blockchain serves as the canonical source of truth. |
 | **Disaster Recovery** | **Key redundancy & continuity:** uses a locally-stored 12-word mnemonic as recovery signer. Any two of the three signers can reconstruct authority to unlock the wallet, ensuring the user is never locked out by a single lost credential. |
-| **Hardened Key Isolation** | `keygen` writes to `~/.nodpay/.env` (chmod 600). The CLI reads the key internally at runtime — only the public address appears in stdout. |
+| **Hardened Key Isolation** | `keygen` writes to `~/.nodpay/.env` (chmod 600). The CLI reads the key via file I/O at runtime — not passed through CLI arguments, environment variables, or stdout. Only the public address is returned to the caller. |
 | **Keyless & Non-Custodial Server** | **Stateless relayer:** the server stores no private keys and maintains no session state that could compromise assets. All signing happens locally. 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.
@@ -93,6 +93,7 @@ npx nodpay propose \
   --safe <SAFE> \
   --to <RECIPIENT> \
   --value-eth <AMOUNT> \
+  --nonce <N> \
   --human-signer-passkey-x <X> \
   --human-signer-passkey-y <Y> \
   --recovery-signer <RECOVERY>
@@ -111,7 +112,13 @@ First tx deploys the wallet. Pass all params for first tx; after that `--safe` a
 npx nodpay txs --safe <SAFE>
 ```
 
-**Always run `txs` before proposing.** Do not assume a previous transaction is still pending — the human may have approved or rejected it without telling you. Check actual on-chain state first.
+**Always check nonce before proposing.** Do not assume a previous transaction is still pending — the human may have approved or rejected it without telling you.
+
+```bash
+npx nodpay nonce --safe <SAFE> --chain <CHAIN>
+```
+
+Returns `nextNonce` (from on-chain EntryPoint + pending proposals), `onChainNonce`, and `pendingCount`. Pass `nextNonce` as `--nonce` to propose.
 
 ```bash
 npx nodpay gasprice --chain <CHAIN>
@@ -156,7 +163,7 @@ EOA wallets: replace passkey fields with `"humanSignerEoa": "0x..."`.
 | `--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) |
+| `--nonce` | **required** | Nonce for this proposal. Run `txs` first to determine. |
 
 Wallet address is the same across all chains. **Ask which chain if not specified.**
 

package/bin/nodpay.mjs

@@ -15,6 +15,10 @@ if (command === 'propose') {
   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 === 'nonce') {
+  const scriptPath = new URL('../scripts/nonce.mjs', import.meta.url).pathname;
+  process.argv = [process.argv[0], scriptPath, ...process.argv.slice(3)];
+  await import(scriptPath);
 } else if (command === 'gasprice') {
   const scriptPath = new URL('../scripts/gasprice.mjs', import.meta.url).pathname;
   process.argv = [process.argv[0], scriptPath, ...process.argv.slice(3)];
@@ -30,12 +34,14 @@ Commands:
   keygen    Generate (or reuse) agent keypair
   propose   Propose a transaction for human approval
   txs       List pending and completed transactions
+  nonce     Query next nonce from on-chain EntryPoint
   gasprice  Get current gas price and estimated gas cost per chain
 
 Examples:
   nodpay keygen
   nodpay propose --safe 0x... --to 0x... --value-eth 0.01 --chain base
   nodpay txs --safe 0x...
+  nodpay nonce --safe 0x... --chain base
   nodpay gasprice --chain base
 
 Docs: https://nodpay.ai/skill.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodpay",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "NodPay CLI — propose on-chain payments from agent-human shared wallets",
   "type": "module",
   "bin": {

package/scripts/nonce.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Query the next available nonce for a Safe wallet from on-chain EntryPoint.
+ *
+ * This is the ERC-4337 standard: EntryPoint.getNonce(sender, key).
+ * Pure on-chain query — no server dependency.
+ *
+ * Usage:
+ *   npx nodpay nonce --safe <SAFE_ADDRESS> --chain <CHAIN>
+ *
+ * Output:
+ *   { "nonce": 0, "safe": "0x...", "chain": "base", "chainId": "8453" }
+ */
+
+import { ethers } from 'ethers';
+import { ENTRYPOINT } from '@nodpay/core';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const NETWORKS = require('@nodpay/core/networks');
+
+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 chainArg = getArg('--chain');
+
+if (!safe) {
+  console.error(JSON.stringify({ error: '--safe <address> is required' }));
+  process.exit(1);
+}
+if (!chainArg) {
+  const allChains = { ...NETWORKS.mainnet, ...NETWORKS.testnet };
+  console.error(JSON.stringify({ error: '--chain is required. Supported: ' + Object.keys(allChains).join(', ') }));
+  process.exit(1);
+}
+
+const allChains = { ...NETWORKS.mainnet, ...NETWORKS.testnet };
+const net = allChains[chainArg];
+if (!net) {
+  console.error(JSON.stringify({ error: `Unknown chain "${chainArg}". Supported: ${Object.keys(allChains).join(', ')}` }));
+  process.exit(1);
+}
+
+try {
+  // 1. On-chain nonce from EntryPoint (source of truth for executed txs)
+  const provider = new ethers.JsonRpcProvider(net.rpcUrl);
+  const ep = new ethers.Contract(
+    ENTRYPOINT,
+    ['function getNonce(address,uint192) view returns (uint256)'],
+    provider
+  );
+  const onChainNonce = await ep.getNonce(safe, 0);
+
+  // 2. Check pending ops to find the highest queued nonce
+  //    (same logic as the battle-tested propose.mjs nonce resolution)
+  let nextNonce = onChainNonce;
+  let pendingCount = 0;
+  try {
+    const baseUrl = 'https://nodpay.ai/api';
+    const listRes = await fetch(`${baseUrl}/txs?safe=${safe}&chain=${net.chainId}`);
+    if (listRes.ok) {
+      const listData = await listRes.json();
+      for (const op of (listData.txs || listData.ops || [])) {
+        const opNonce = BigInt(op.nonce ?? -1);
+        if (opNonce >= onChainNonce && opNonce >= nextNonce) {
+          pendingCount++;
+          nextNonce = opNonce + 1n;
+        }
+      }
+    }
+  } catch (e) {
+    // Non-fatal: op-store may be unavailable, fall back to on-chain only
+  }
+
+  console.log(JSON.stringify({
+    nextNonce: Number(nextNonce),
+    onChainNonce: Number(onChainNonce),
+    pendingCount,
+    safe,
+    chain: chainArg,
+    chainId: String(net.chainId),
+  }, null, 2));
+} catch (err) {
+  console.error(JSON.stringify({ error: err.message }));
+  process.exit(1);
+}

package/scripts/propose.mjs

@@ -19,7 +19,7 @@
  *   --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
+ *   --nonce <n>              - Required. Use `txs` to find current nonce.
  *
  * Output: JSON with userOpHash, safeTxHash, safeOperationJson, etc.
  */
@@ -336,38 +336,14 @@ try {
   const opStoreUrl = opStoreBase;
   const safeAddr = await safe4337Pack.protocolKit.getAddress();
 
-  // Determine nonce: on-chain nonce is the source of truth.
-  // For queued ops, find the highest pending nonce and increment.
-  if (customNonceArg !== undefined) {
-    txOptions.customNonce = BigInt(customNonceArg);
-  } else {
-    try {
-      const provider = new ethers.JsonRpcProvider(RPC_URL);
-      const ep = new ethers.Contract('0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
-        ['function getNonce(address,uint192) view returns (uint256)'], provider);
-      const onChainNonce = await ep.getNonce(safeAddr, 0);
-
-      // Check pending ops to find the highest queued nonce
-      const listRes = await fetch(`${opStoreUrl}/txs?safe=${safeAddr}&chain=${CHAIN_ID}`);
-      let nextNonce = onChainNonce;
-      if (listRes.ok) {
-        const listData = await listRes.json();
-        for (const op of (listData.txs || listData.ops || [])) {
-          const opNonce = BigInt(op.nonce ?? -1);
-          if (opNonce >= onChainNonce && opNonce >= nextNonce) {
-            nextNonce = opNonce + 1n;
-          }
-        }
-      }
-      // Only set custom nonce if we need to skip ahead for queuing
-      if (nextNonce > onChainNonce) {
-        txOptions.customNonce = nextNonce;
-      }
-      // else: let SDK use on-chain nonce naturally
-    } catch (e) {
-      // Non-fatal: SDK will use its own nonce detection
-    }
+  // --nonce is required. Agent must run `txs` first to determine the correct nonce.
+  // This prevents accidental double-proposals: if agent proposes twice with the same nonce,
+  // the second is just a replacement (same slot), not a new transaction.
+  if (customNonceArg === undefined) {
+    console.error(JSON.stringify({ error: '--nonce is required. Run `npx nodpay txs --safe <SAFE>` first to check current nonce.' }));
+    process.exit(1);
   }
+  txOptions.customNonce = BigInt(customNonceArg);
 
   // Resolve gas values: use hardcoded defaults (from RPC gas price) always.
   // If --reuse-gas-from is provided and fetch succeeds, use those values instead