nodpay 0.2.3 → 0.2.5

package/README.md

@@ -28,11 +28,29 @@ NODPAY_AGENT_KEY=0x... npx nodpay propose \
 3. Agent proposes transactions with `npx nodpay propose`
 4. User approves/rejects on their phone
 
+## Key generation
+
+```bash
+npx nodpay keygen --env-file .env
+```
+
+Outputs the agent's **public address only**. The private key is written directly to `.env` — it never appears in stdout, logs, or the agent's context window.
+
+If a key already exists, it reuses it and prints the address.
+
+### Security design
+
+The agent (LLM) **never sees the private key**. `keygen` writes the secret directly to disk; the `propose` command reads it from the environment at runtime. This means:
+
+- No private key in conversation history or context window
+- No risk of leaking the key through prompt injection
+- The agent only needs the public address (for wallet links)
+
 ## Env
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `NODPAY_AGENT_KEY` | ✅ | Agent's private key (hex) |
+| `NODPAY_AGENT_KEY` | ✅ | Agent's private key — use `npx nodpay keygen` to generate securely |
 
 ## Supported chains
 

package/SKILL.md

@@ -42,9 +42,9 @@ The wallet is a **Safe 2-of-3 multisig**. You hold 1 key, the user holds 2 (pass
 npx nodpay keygen --env-file .env
 ```
 
-This outputs your agent's **public address** (stdout). The private key is written directly to `.env` — it never appears in your output or context.
+Outputs your agent's **public address** only. The private key is written directly to `.env` — it never appears in your output or context.
 
-If `NODPAY_AGENT_KEY` already exists in the file, it reuses the existing key and prints the address.
+If a key already exists in the file, it reuses it and prints the address.
 
 **After keygen**, trigger a gateway restart so the env var takes effect. Send your wallet link message to the user BEFORE restarting — the restart will interrupt your session.
 
@@ -102,8 +102,6 @@ Each wallet file:
 }
 ```
 
-`agentSigner` is your agent's EOA address (derived from `NODPAY_AGENT_KEY`).
-
 For EOA wallets, replace passkey fields with `"userSigner": "0x..."`.
 
 One agent key serves all wallets — multi-wallet is handled user-side (different passkeys/recovery keys → different Safe addresses, same agent).
@@ -113,8 +111,8 @@ One agent key serves all wallets — multi-wallet is handled user-side (differen
 ### Propose a transaction
 
 ```bash
-NODPAY_AGENT_KEY=0x... \
 npx nodpay propose \
+  --chain <CHAIN_NAME> \
   --safe <WALLET_ADDRESS> \
   --to <RECIPIENT> \
   --value-eth <AMOUNT> \
@@ -133,12 +131,8 @@ The script outputs JSON with an `approveUrl`. Send it to the user:
 
 ### Check balance
 
-Use the RPC URL for the wallet's chain (see `references/networks.json`):
-
 ```bash
-curl -s -X POST <RPC_URL> \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["<WALLET_ADDRESS>","latest"],"id":1}'
+npx nodpay propose --chain <CHAIN_NAME> --safe <WALLET_ADDRESS> --check-balance
 ```
 
 If balance is 0, remind the user to deposit before proposing.
@@ -153,12 +147,11 @@ Always check before proposing — this tells you the current nonce, pending ops,
 
 ---
 
-## Script Reference
-
-### Flags
+## Flags
 
 | Flag | Required | Description |
 |------|----------|-------------|
+| `--chain` | ✅ | Chain name (e.g. `ethereum`, `base`, `sepolia`) |
 | `--safe` | ✅ | Wallet (Safe) address |
 | `--to` | ✅ | Recipient address |
 | `--value-eth` | ✅ | Amount in ETH |
@@ -170,16 +163,6 @@ Always check before proposing — this tells you the current nonce, pending ops,
 | `--nonce` | optional | Force nonce (for replacements) |
 | `--purpose` | optional | Human-readable label |
 
-### Environment
-
-Only one env var is required:
-
-| Var | Description |
-|-----|-------------|
-| `NODPAY_AGENT_KEY` | Agent signing key (required) |
-
-Chain config (RPC, bundler, explorer) is auto-resolved from `references/networks.json`. No need to set `RPC_URL`, `CHAIN_ID`, or bundler keys.
-
 ### Supported Chains
 
 `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `sepolia`, `base_sepolia`
@@ -190,11 +173,11 @@ The wallet address is the same across all chains (counterfactual). Chain is only
 
 ## Transaction Patterns
 
-**Sequential**: Just call propose multiple times. Nonces auto-increment (script handles this).
+**Sequential**: Just call propose multiple times. Nonces auto-increment.
 
-**Replace**: To replace a pending tx, propose with `--nonce N` where N is the nonce of the tx you want to replace. Check pending nonces via `GET /api/txs?safe=<ADDRESS>` — each tx in the response includes its `nonce`.
+**Replace**: Propose with `--nonce N` to replace a pending tx at nonce N. Check pending nonces via `GET /api/txs?safe=<ADDRESS>`.
 
-**Cascade**: Rejecting tx at nonce N auto-invalidates all tx with nonce > N. This is irreversible.
+**Cascade**: Rejecting tx at nonce N invalidates all tx with nonce > N. Irreversible.
 
 ⚠️ **Never propose a new nonce then reject an older one** — the cascade will destroy your new tx too.
 
@@ -202,7 +185,7 @@ The wallet address is the same across all chains (counterfactual). Chain is only
 
 ## Reconnect (Wallet Recovery)
 
-If the user cleared their browser data, the wallet still exists on-chain. Build a reconnect link:
+If the user cleared their browser data, build a reconnect link:
 
 ```
 https://nodpay.ai/?agent=YOUR_AGENT_ADDRESS&safe=WALLET_ADDRESS&recovery=RECOVERY_SIGNER&x=PASSKEY_X&y=PASSKEY_Y
@@ -232,7 +215,7 @@ User opens → verifies passkey → wallet restored. No on-chain action needed.
 | User says | Action |
 |-----------|--------|
 | "create a wallet" | Send `https://nodpay.ai/?agent=YOUR_ADDRESS` |
-| "send 0.1 ETH to 0x..." | Propose transaction |
-| "balance" | RPC `eth_getBalance` on Safe address |
+| "send 0.1 ETH to 0x..." | Propose transaction with `--chain` |
+| "balance" | Check balance on the relevant chain |
 | "pending?" | `GET /api/txs?safe=...` |
 | "wallet disappeared" | Send reconnect link |

package/package.json

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

package/scripts/propose.mjs

@@ -37,10 +37,31 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PENDING_DIR = join(__dirname, '..', '.pending-txs');
 mkdirSync(PENDING_DIR, { recursive: true });
 
-const RPC_URL = process.env.RPC_URL;
-const CHAIN_ID = process.env.CHAIN_ID;
+// Resolve chain config: --chain flag auto-resolves from networks.json, env vars as fallback
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const NETWORKS = require('@nodpay/core/networks');
+const allChains = { ...NETWORKS.mainnet, ...NETWORKS.testnet };
+
+const chainArg = process.argv.includes('--chain')
+  ? process.argv[process.argv.indexOf('--chain') + 1]
+  : null;
+
+let RPC_URL, CHAIN_ID;
+if (chainArg) {
+  const net = allChains[chainArg];
+  if (!net) {
+    console.error(`Error: Unknown chain "${chainArg}". Supported: ${Object.keys(allChains).join(', ')}`);
+    process.exit(1);
+  }
+  RPC_URL = process.env.RPC_URL || net.rpcUrl;
+  CHAIN_ID = String(net.chainId);
+} else {
+  RPC_URL = process.env.RPC_URL;
+  CHAIN_ID = process.env.CHAIN_ID;
+}
 if (!RPC_URL || !CHAIN_ID) {
-  console.error('Error: RPC_URL and CHAIN_ID environment variables are required.\nSet them for your target chain. See references/networks.json for supported chains.');
+  console.error('Error: Specify --chain <name> or set RPC_URL + CHAIN_ID env vars.\nSupported chains: ' + Object.keys(allChains).join(', '));
   process.exit(1);
 }
 const ENTRYPOINT_ADDRESS = ENTRYPOINT;