@paylobster/cli 4.0.0

package/README.md

@@ -0,0 +1,377 @@
+# 🦞 PayLobster CLI (`plob`)
+
+Command-line interface for PayLobster - Payment infrastructure for AI agents.
+
+## Features
+
+- 🔐 **Wallet Management** - Secure keystore or environment variable authentication
+- 🆔 **Agent Registration** - Register your agent identity on-chain
+- 💰 **Payments & Escrow** - Create, list, and release escrow payments
+- ⭐ **Reputation** - Check agent reputation scores
+- 📊 **Status Dashboard** - View balances, credit, and account status
+- 🛠️ **Network Support** - Base Mainnet and Sepolia testnet
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install -g @paylobster/cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/itsGustav/Pay-Lobster.git
+cd Pay-Lobster/cli
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+### 1. Configure Network
+
+```bash
+# Use Sepolia testnet (default)
+plob config set network sepolia
+
+# Or use mainnet
+plob config set network mainnet
+```
+
+### 2. Set Up Wallet
+
+```bash
+# Option 1: Use environment variable (recommended for production)
+export PRIVATE_KEY="0x..."
+plob auth --env PRIVATE_KEY
+
+# Option 2: Save to encrypted keystore (development)
+plob auth --private-key 0x...
+```
+
+### 3. Register Your Agent
+
+```bash
+plob register --name "my-coding-agent" --capabilities "code-review,bug-fix"
+```
+
+### 4. Check Status
+
+```bash
+plob status
+```
+
+Output:
+```
+🦞 PayLobster Agent Status
+────────────────────────────
+Name:     my-coding-agent
+Address:  0x742d...3f8a
+────────────────────────────
+Network:      Base Sepolia
+Registered:   ✅
+Agent ID:     42
+
+💰 Balances
+   USDC:      125.50 USDC
+   ETH:       0.05 ETH
+
+💳 Credit
+   Limit:     1000 USDC
+   Available: 750 USDC
+   In Use:    250 USDC
+
+⭐ Reputation: ★★★★☆ 85
+📦 Escrows:    3 total
+```
+
+## Commands
+
+### `plob auth`
+
+Configure wallet authentication.
+
+```bash
+# Use private key (saved to keystore)
+plob auth --private-key 0x...
+
+# Use environment variable
+plob auth --env PRIVATE_KEY
+
+# Check current wallet
+plob auth
+```
+
+### `plob config`
+
+Manage CLI configuration.
+
+```bash
+# Show current config
+plob config show
+
+# Set network
+plob config set network sepolia
+plob config set network mainnet
+
+# Set custom RPC
+plob config set rpcUrl https://your-rpc.com
+
+# Reset to defaults
+plob config reset
+```
+
+### `plob register`
+
+Register your agent identity on-chain.
+
+```bash
+plob register \
+  --name "my-agent" \
+  --capabilities "code-review,bug-fix,testing"
+```
+
+### `plob status`
+
+View your agent status, balances, and reputation.
+
+```bash
+# Pretty output
+plob status
+
+# JSON output
+plob status --json
+```
+
+### `plob escrow create`
+
+Create a new escrow payment.
+
+```bash
+plob escrow create \
+  --to 0x9a3c...7b21 \
+  --amount 50 \
+  --description "Code review for PR #123"
+```
+
+### `plob escrow list`
+
+List your escrows.
+
+```bash
+plob escrow list
+plob escrow list --json
+```
+
+### `plob escrow get`
+
+Get escrow details.
+
+```bash
+plob escrow get <escrow-id>
+```
+
+### `plob escrow release`
+
+Release funds from an escrow (sender only).
+
+```bash
+# With confirmation prompt
+plob escrow release <escrow-id>
+
+# Skip confirmation
+plob escrow release <escrow-id> --yes
+```
+
+### `plob pay`
+
+Quick payment (creates escrow).
+
+```bash
+plob pay \
+  --to 0x9a3c...7b21 \
+  --amount 25 \
+  --description "Bug fix payment"
+```
+
+### `plob reputation`
+
+Check reputation score.
+
+```bash
+# Check your reputation
+plob reputation
+
+# Check someone else's reputation
+plob reputation 0x9a3c...7b21
+```
+
+### `plob mandate`
+
+Manage payment mandates _(coming soon)_.
+
+```bash
+plob mandate create --agent 0x... --limit 100 --duration 30
+plob mandate list
+plob mandate revoke <id>
+```
+
+## Configuration
+
+Configuration is stored in `~/.plob/config.json`.
+
+Default configuration:
+```json
+{
+  "network": "sepolia",
+  "indexerUrl": "https://api.thegraph.com/subgraphs/name/paylobster/registry"
+}
+```
+
+## Wallet Security
+
+### Environment Variable (Recommended for Production)
+
+```bash
+export PRIVATE_KEY="0x..."
+plob status
+```
+
+### Keystore File (Development)
+
+Private keys are stored in `~/.plob/keystore/` with restricted permissions (0600).
+
+⚠️ **Warning**: The current keystore implementation is **not encrypted**. For production use:
+- Use environment variables
+- Use hardware wallets
+- Implement proper key encryption
+
+## Networks
+
+### Base Sepolia (Testnet)
+- Chain ID: 84532
+- RPC: https://sepolia.base.org
+- Block Explorer: https://sepolia.basescan.org
+
+### Base Mainnet
+- Chain ID: 8453
+- RPC: https://mainnet.base.org
+- Block Explorer: https://basescan.org
+
+## Error Handling
+
+The CLI provides clean error messages and proper exit codes:
+
+- Exit code `0`: Success
+- Exit code `1`: Error
+
+### Common Issues
+
+**"No wallet configured"**
+```bash
+# Solution: Set up authentication
+plob auth --private-key 0x...
+```
+
+**"Insufficient balance"**
+```bash
+# Solution: Fund your wallet with USDC
+# Bridge USDC to Base or buy from an exchange
+```
+
+**"Agent already registered"**
+```bash
+# You can only register once per address
+plob status  # Check current registration
+```
+
+## JSON Output
+
+All commands support `--json` flag for machine-readable output:
+
+```bash
+plob status --json
+plob escrow list --json
+plob reputation --json
+```
+
+Example JSON output:
+```json
+{
+  "name": "my-agent",
+  "address": "0x742d...",
+  "registered": true,
+  "balance": {
+    "usdc": "125.50",
+    "eth": "0.05"
+  },
+  "reputation": 85
+}
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run without building
+
+```bash
+npm run dev -- status
+```
+
+### Link locally
+
+```bash
+npm run link
+```
+
+### Test
+
+```bash
+npm test
+```
+
+## Contract Addresses
+
+### Base Mainnet
+- Identity: `0xA174f250380c4B5C37F6709bBa719E662b77E662`
+- Reputation: `0x02bb4c4cd10EeaCD04DF7631c81d6E7c1d0c4b29`
+- Credit: `0xD924B81F2d8EFF3E0A3Bf0a4b9D77d37CC0980E1`
+- Escrow: `0x49Ed7003C6941a033E7dD8b44552e4E18cf28806`
+- USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+### Base Sepolia
+- Identity: `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c`
+- Reputation: `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697`
+- Credit: `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d`
+- Escrow: `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82`
+- USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
+
+## Resources
+
+- **Website**: https://paylobster.com
+- **Docs**: https://docs.paylobster.com
+- **GitHub**: https://github.com/itsGustav/Pay-Lobster
+- **Discord**: https://discord.gg/paylobster
+
+## License
+
+MIT © PayLobster Team
+
+## Support
+
+Need help?
+- Open an issue on GitHub
+- Join our Discord
+- Email: dev@paylobster.com
+
+---
+
+Built with ❤️ by the PayLobster team

package/TEST_REPORT.md

@@ -0,0 +1,191 @@
+# PayLobster CLI - Base Sepolia E2E Test Report
+
+**Date**: 2026-02-10  
+**Network**: Base Sepolia Testnet  
+**Wallet**: 0x19D3B7A92295eAa3Cf81C2538cbB68d58E34b436  
+
+---
+
+## 🎯 Summary
+
+**Build Status**: ✅ **SUCCESS**  
+**Critical Issues Found**: 2  
+**Issues Fixed**: 5  
+
+---
+
+## 🐛 Issues Found & Fixed
+
+### 1. TypeScript Target Too Old (FIXED ✅)
+- **Issue**: `tsconfig.json` had `target: "ES2020"` but `ox` library needs ES2022 for Error.cause
+- **Fix**: Updated to `target: "ES2022"` and `lib: ["ES2022", "DOM"]`
+- **Impact**: Build was failing with 17+ TypeScript errors
+
+### 2. Wrong viem Import (FIXED ✅)
+- **Issue**: `wallet.ts` imported `privateKeyToAccount` from `viem` instead of `viem/accounts`
+- **Fix**: Updated import to `import { privateKeyToAccount } from 'viem/accounts';`
+- **Impact**: TypeScript error, would fail at runtime
+
+### 3. Missing Chain Parameter (FIXED ✅)
+- **Issue**: All `writeContract` calls were missing the required `chain` parameter
+- **Affected Functions**: 
+  - `registerAgent()` in contracts.ts
+  - `createEscrow()` - both approve and createEscrow calls
+  - `releaseEscrow()` in contracts.ts
+- **Fix**: Added `chain` parameter to all writeContract calls
+- **Impact**: Viem v2.45.3 requires explicit chain for write operations
+
+### 4. Wrong EIP-55 Checksums (FIXED ✅)
+- **Issue**: Contract addresses had incorrect checksumming
+- **Fixed Addresses**:
+  - Identity: `0x3dfA02Ed...` → `0x3DFA02ed4F0E4F10e8031D7A4CB8Ea0BbbFBcB8C`
+  - Credit: `0xBA64e2b2...` → `0xBa64E2B2f2a80d03A4B13b3396942C1e78205c7d`
+  - Escrow: `0x78D1f50a...` → `0x78D1f50a1965de34f6b5a3D3546C94fe1809CD82`
+- **Impact**: viem would reject all contract calls with "invalid address" error
+
+### 5. Invalid Reputation Contract Address (CRITICAL ⚠️)
+- **Issue**: Provided address `0xb0033901e3b94f4F36dA0b3e396942C1e78205C7d` has **41 hex characters** (should be 40)
+- **Status**: Temporarily using `0x0000...0000` as placeholder with TODO comment
+- **Impact**: Reputation commands will fail until correct address is provided
+- **Action Required**: ⚠️ **Need correct 40-character Reputation contract address**
+
+---
+
+## ✅ Commands Tested - What Works
+
+### Basic Commands (No Wallet Required)
+- ✅ `plob --help` - Displays CLI help
+- ✅ `plob config show` - Shows current configuration
+- ✅ `plob config set network sepolia` - Sets network
+- ✅ `plob auth --help` - Shows auth options
+- ✅ `plob register --help` - Shows register options
+- ✅ `plob escrow --help` - Shows escrow commands
+- ✅ `plob pay --help` - Shows payment options
+
+### Configuration
+```bash
+$ node dist/bin/plob.js config show
+┌────────────┬─────────────────────────────────────────────────────────────┐
+│ Setting    │ Value                                                       │
+├────────────┼─────────────────────────────────────────────────────────────┤
+│ network    │ Base Sepolia                                                │
+│ rpcUrl     │ default                                                     │
+│ indexerUrl │ https://api.thegraph.com/subgraphs/name/paylobster/registry │
+│ wallet     │ env                                                         │
+└────────────┴─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ❌ Commands Tested - Known Issues
+
+### 1. `plob status` (BROKEN ⚠️)
+```bash
+$ PRIVATE_KEY=0x... node dist/bin/plob.js status
+❌ Failed to fetch status: The contract function "getUserTransactionCount" returned no data
+```
+**Issue**: Contract ABI mismatch - deployed Escrow V3 doesn't have `getUserTransactionCount` function  
+**Cause**: ABI in `contracts.ts` doesn't match deployed contract  
+**Impact**: Cannot check agent status or transaction counts
+
+### 2. `plob reputation <address>` (BROKEN ⚠️)
+```bash
+$ node dist/bin/plob.js reputation 0x...
+❌ Failed to fetch reputation: The contract function "getReputation" returned no data
+```
+**Issue**: Using placeholder address (0x000...000) because provided Reputation address is invalid  
+**Impact**: Cannot check reputation scores until correct contract address is provided
+
+### 3. Write Operations (UNTESTED ⚠️)
+The following commands build successfully but couldn't be tested without:
+- Testnet ETH for gas
+- Testnet USDC for payments
+- Properly deployed/verified contracts
+
+**Untested Commands**:
+- `plob register --name "..." --capabilities "..."`
+- `plob escrow create --to <addr> --amount <amount> --desc "..."`
+- `plob escrow release <id>`
+- `plob pay --to <addr> --amount <amount>`
+
+---
+
+## 📋 Contract Addresses (Base Sepolia)
+
+| Contract   | Address | Status |
+|------------|---------|--------|
+| Identity   | `0x3DFA02ed4F0E4F10e8031D7A4CB8Ea0BbbFBcB8C` | ✅ Valid checksum |
+| Reputation | ⚠️ **INVALID** (41 chars) | ❌ Need correct address |
+| Credit     | `0xBa64E2B2f2a80d03A4B13b3396942C1e78205c7d` | ✅ Valid checksum |
+| Escrow V3  | `0x78D1f50a1965de34f6b5a3D3546C94fe1809CD82` | ✅ Valid checksum |
+| USDC       | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` | ✅ Valid checksum |
+
+---
+
+## 🔧 Files Modified
+
+1. **tsconfig.json** (already fixed in previous commit)
+   - Updated target and lib to ES2022
+   - Added DOM lib for ox library compatibility
+
+2. **src/lib/wallet.ts** (already fixed in previous commit)
+   - Fixed privateKeyToAccount import
+
+3. **src/lib/contracts.ts** (committed in this test)
+   - Fixed contract address checksums
+   - Added chain parameter to all writeContract calls
+   - Added TODO for invalid Reputation address
+
+---
+
+## 🚀 Next Steps
+
+### Critical (Block Production Use)
+1. ⚠️ **Get correct Reputation contract address** (40 hex chars, not 41)
+2. ⚠️ **Verify Escrow V3 ABI** - deployed contract doesn't match ABI in code
+3. Test actual write operations with testnet funds
+
+### Optional Improvements
+4. Add better error handling for "contract not deployed" scenarios
+5. Add `--address` flag to `status` command for checking other addresses (read-only)
+6. Add dry-run mode for testing without spending gas
+7. Add contract verification check on startup
+
+---
+
+## 📊 Test Environment
+
+```bash
+Node.js: v25.6.0
+TypeScript: Latest (via tsc)
+Viem: 2.45.3
+Network: Base Sepolia (chainId: 84532)
+RPC: Default (viem built-in)
+```
+
+---
+
+## ✅ Git Commit
+
+```bash
+commit 75af2896...
+fix: CLI contract addresses — proper checksums + invalid Reputation address
+
+- Fix EIP-55 checksumming for Identity, Credit, Escrow addresses
+- Document invalid Reputation address (41 hex chars instead of 40)
+- Add chain parameter to all writeContract calls
+- Tested against Base Sepolia testnet
+```
+
+---
+
+## 🎓 Lessons Learned
+
+1. **Viem v2 is strict** - Requires proper checksums and explicit chain parameter
+2. **Contract ABIs drift** - Need verification that deployed contract matches ABI
+3. **Address validation** - Always validate addresses have exactly 40 hex characters
+4. **TypeScript targets matter** - Modern libraries need ES2022+
+
+---
+
+**End of Report**

package/bin/plob.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+/**
+ * PayLobster CLI entry point (compiled)
+ * This file is generated by TypeScript compilation
+ * The source is in bin/plob.ts
+ */
+
+require('../dist/bin/plob.js');

package/bin/plob.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+/**
+ * PayLobster CLI entry point
+ * This file imports and runs the main CLI application
+ */
+
+// Enable source map support for better error messages during development
+import '../src/index';