agentwallet-sdk 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# 🤖 Agent Wallet SDK
+
+**Let your AI agent spend crypto. Stay in control.**
+
+Agent Wallet gives AI agents autonomous spending power with hard on-chain limits. No more choosing between "agent can drain everything" and "every transaction needs manual approval."
+
+```
+Agent wants to spend $15 → ✅ Auto-approved (under $25 limit)
+Agent wants to spend $500 → ⏳ Queued for your approval
+Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
+```
+
+## Why Agent Wallet?
+
+| Approach | Problem |
+|----------|---------|
+| Raw EOA wallet | Agent can drain everything. One prompt injection = rugged. |
+| Multisig (Safe) | Every tx needs human sigs. Kills agent autonomy. |
+| Custodial API (Stripe) | Centralized, KYC friction, not crypto-native. |
+| **Agent Wallet** | **Agents spend freely within limits. Everything else queues for approval.** |
+
+Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an NFT — portable, auditable, fully on-chain.
+
+## Quick Start
+
+```bash
+npm install @agentwallet/sdk viem
+```
+
+```typescript
+import {
+  createWallet,
+  setSpendPolicy,
+  agentExecute,
+  checkBudget,
+  getPendingApprovals,
+  approveTransaction,
+  NATIVE_TOKEN,
+} from '@agentwallet/sdk';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+// 1. Connect to your agent's wallet
+const walletClient = createWalletClient({
+  account: privateKeyToAccount('0xAGENT_PRIVATE_KEY'),
+  transport: http('https://mainnet.base.org'),
+});
+
+const wallet = createWallet({
+  accountAddress: '0xYOUR_AGENT_ACCOUNT',
+  chain: 'base',
+  walletClient,
+});
+
+// 2. Owner sets spending limits (one-time setup)
+await setSpendPolicy(wallet, {
+  token: NATIVE_TOKEN,  // ETH
+  perTxLimit: 25_000000000000000n,   // 0.025 ETH per tx
+  periodLimit: 500_000000000000000n, // 0.5 ETH per day
+  periodLength: 86400,               // 24 hours
+});
+
+// 3. Agent spends autonomously
+await agentExecute(wallet, {
+  to: '0xSOME_SERVICE',
+  value: 10_000000000000000n, // 0.01 ETH — under limit, executes immediately
+});
+
+// 4. Check remaining budget
+const budget = await checkBudget(wallet, NATIVE_TOKEN);
+console.log(`Remaining today: ${budget.remainingInPeriod}`);
+
+// 5. Owner reviews queued transactions
+const pending = await getPendingApprovals(wallet);
+for (const tx of pending) {
+  console.log(`Pending #${tx.txId}: ${tx.amount} to ${tx.to}`);
+  await approveTransaction(wallet, tx.txId);
+}
+```
+
+## API Reference
+
+### `createWallet(config)`
+Connect to an existing AgentAccountV2 contract.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `accountAddress` | `Address` | Deployed AgentAccountV2 address |
+| `chain` | `string` | `'base'` \| `'base-sepolia'` \| `'ethereum'` \| `'arbitrum'` \| `'polygon'` |
+| `walletClient` | `WalletClient` | viem wallet client (agent or owner key) |
+| `rpcUrl?` | `string` | Custom RPC URL |
+
+### `setSpendPolicy(wallet, policy)` — Owner only
+Set per-token spending limits.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `Address` | Token address (`NATIVE_TOKEN` for ETH) |
+| `perTxLimit` | `bigint` | Max single tx (0 = all txs need approval) |
+| `periodLimit` | `bigint` | Max per rolling window (0 = no autonomous spending) |
+| `periodLength` | `number` | Window in seconds (default: 86400 = 24h) |
+
+### `agentExecute(wallet, { to, value?, data? })`
+Execute a native ETH transaction. Auto-approves if within limits, queues if over.
+
+**Returns:** `{ executed: boolean, txHash: Hash, pendingTxId?: bigint }`
+
+### `agentTransferToken(wallet, { token, to, amount })`
+Transfer ERC20 tokens, respecting spend limits.
+
+### `checkBudget(wallet, token?)`
+Check remaining autonomous spending budget.
+
+**Returns:** `{ token, perTxLimit, remainingInPeriod }`
+
+### `getPendingApprovals(wallet, fromId?, toId?)`
+List all pending (unexecuted, uncancelled) transactions awaiting owner approval.
+
+### `approveTransaction(wallet, txId)` — Owner only
+Approve and execute a queued transaction.
+
+### `cancelTransaction(wallet, txId)` — Owner only
+Cancel a queued transaction.
+
+### `setOperator(wallet, operator, authorized)` — Owner only
+Add or remove an agent operator address.
+
+### `getBudgetForecast(wallet, token?, now?)`
+**[MAX-ADDED]** Time-aware budget forecast — know not just what's left, but when it refills.
+
+**Returns:** `BudgetForecast` — includes `remainingInPeriod`, `secondsUntilReset`, `utilizationPercent`, full period metadata.
+
+```typescript
+const forecast = await getBudgetForecast(wallet, NATIVE_TOKEN);
+console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsUntilReset}s`);
+```
+
+### `getWalletHealth(wallet, operators?, tokens?, now?)`
+**[MAX-ADDED]** Single-call diagnostic snapshot for agent self-monitoring.
+
+**Returns:** `WalletHealth` — address, NFT binding, operator epoch, active operator statuses, pending queue depth, budget forecasts.
+
+```typescript
+const health = await getWalletHealth(wallet, [agentHotWallet], [NATIVE_TOKEN, usdcAddress]);
+if (health.pendingQueueDepth > 5) console.warn('Queue backing up!');
+if (!health.activeOperators[0].active) console.error('Agent operator deactivated!');
+```
+
+### `batchAgentTransfer(wallet, transfers)`
+**[MAX-ADDED]** Execute multiple token transfers sequentially — reduces boilerplate for multi-recipient payments.
+
+```typescript
+const hashes = await batchAgentTransfer(wallet, [
+  { token: USDC, to: serviceA, amount: 100n },
+  { token: USDC, to: serviceB, amount: 200n },
+]);
+```
+
+### `getActivityHistory(wallet, { fromBlock?, toBlock? })`
+**[MAX-ADDED]** Query on-chain event history for self-auditing — no external indexer needed.
+
+**Returns:** `ActivityEntry[]` — sorted by block number, covers executions, queued txs, approvals, cancellations, policy updates, operator changes.
+
+```typescript
+const history = await getActivityHistory(wallet, { fromBlock: 10000n });
+for (const entry of history) {
+  console.log(`[${entry.type}] block ${entry.blockNumber}: ${JSON.stringify(entry.args)}`);
+}
+```
+
+## Supported Chains
+
+| Chain | Status | Best For |
+|-------|--------|----------|
+| **Base** | ✅ Primary | Low gas, USDC native |
+| **Base Sepolia** | ✅ Testnet | Development |
+| **Ethereum** | ✅ | High-value operations |
+| **Arbitrum** | ✅ | DeFi agents |
+| **Polygon** | ✅ | Micropayments |
+
+## How It Works
+
+1. **Deploy** an AgentAccountV2 (ERC-6551 token-bound account tied to an NFT)
+2. **Configure** spend policies per token — set per-tx and daily limits
+3. **Register** your agent's hot wallet as an operator
+4. **Agent operates autonomously** — transactions within limits execute instantly
+5. **Over-limit transactions queue** — owner gets notified, approves or cancels
+
+All limits enforced on-chain. No off-chain dependencies. Fully auditable.
+
+## License
+
+MIT

package/dist/abi.d.ts

@@ -0,0 +1,397 @@
+export declare const AgentAccountV2Abi: readonly [{
+    readonly name: "setSpendPolicy";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "perTxLimit";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodLimit";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodLength";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "setOperator";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "authorized";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "execute";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+}, {
+    readonly name: "approvePending";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "cancelPending";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "agentExecute";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+}, {
+    readonly name: "agentTransferToken";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "remainingBudget";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "perTx";
+        readonly type: "uint256";
+    }, {
+        readonly name: "inPeriod";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "getPending";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "createdAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "executed";
+        readonly type: "bool";
+    }, {
+        readonly name: "cancelled";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "spendPolicies";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "perTxLimit";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodLimit";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodLength";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodSpent";
+        readonly type: "uint256";
+    }, {
+        readonly name: "periodStart";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "operators";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "pendingNonce";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "nonce";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "tokenContract";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "tokenId";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "operatorEpoch";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "isOperatorActive";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "TransactionExecuted";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+        readonly indexed: false;
+    }, {
+        readonly name: "executor";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "SpendPolicyUpdated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "perTxLimit";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "periodLimit";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "periodLength";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "OperatorUpdated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "authorized";
+        readonly type: "bool";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "TransactionQueued";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "TransactionApproved";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "TransactionCancelled";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "txId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }];
+}];
+export declare const AgentAccountFactoryV2Abi: readonly [{
+    readonly name: "createAccount";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "getAddress";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "wallets";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "WalletCreated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenContract";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "deployer";
+        readonly type: "address";
+        readonly indexed: false;
+    }];
+}];
+//# sourceMappingURL=abi.d.ts.map

package/dist/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsNpB,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyC3B,CAAC"}