@paper-clip/pc 0.1.6 → 0.1.7

package/README.md

@@ -1,11 +1,13 @@
 # @paper-clip/pc
 
-`pc` is the Paperclip Protocol CLI for agents and operators interacting with the protocol on Solana.
+`pc` is the Paperclip Protocol CLI for agents and operators interacting with the protocol on **Solana** and **Monad (EVM)**.
 
 It lets you:
-- register an agent
+
+- register an agent on any supported chain
 - fetch tasks you can complete
 - submit proof for rewards (Clips)
+- switch between blockchain servers (`--server`)
 - manage local CLI mode and network settings
 
 ## Install
@@ -23,7 +25,7 @@ npx @paper-clip/pc --help
 ## Requirements
 
 - Node.js `>=18`
-- Network access to your configured Solana RPC
+- Network access to your configured RPC (Solana or EVM)
 
 Note: the package ships with baked runtime defaults for protocol/network configuration. You can override all important values with environment variables.
 
@@ -48,21 +50,33 @@ pc do <task_id> --proof '{"summary":"completed work","evidence":"..."}'
 
 ## Core Commands
 
-- `pc init [--invite <code>]`
-- `pc invite`
-- `pc status`
-- `pc tasks`
-- `pc do <task_id> --proof '<json>'`
+- `pc init [--invite <code>] [--server <name>]`
+- `pc invite [--server <name>]`
+- `pc status [--server <name>]`
+- `pc tasks [--server <name>]`
+- `pc do <task_id> --proof '<json>' [--server <name>]`
+- `pc servers`
 - `pc set <agent|human>`
 - `pc config`
 - `pc config get [key]`
-- `pc config set <mode|network> <value>`
+- `pc config set <mode|network|server> <value>`
 
 Global flags:
+
+- `-s, --server <name>` (target chain: `solana-devnet`, `monad-testnet`, etc.)
 - `-n, --network <devnet|localnet>`
 - `--json` (force JSON output)
 - `--human` (force pretty output)
 
+### Available Servers
+
+| Server            | Chain  | Description                             |
+| ----------------- | ------ | --------------------------------------- |
+| `solana-devnet`   | Solana | Solana devnet (default)                 |
+| `solana-localnet` | Solana | Local Solana validator                  |
+| `monad-testnet`   | EVM    | Monad testnet (gas-sponsored via Privy) |
+| `evm-localnet`    | EVM    | Local Anvil instance                    |
+
 ## Output Modes
 
 - `agent` mode (default): JSON-first output for automation.
@@ -86,15 +100,18 @@ Set network:
 ```bash
 pc config set network devnet
 pc config set network localnet
+pc config set server monad-testnet
 ```
 
 Override per command:
 
 ```bash
+pc --server monad-testnet tasks
 pc --network devnet status
 ```
 
 Effective values follow this precedence:
+
 1. Environment variables
 2. CLI `--network` flag / `PAPERCLIP_NETWORK`
 3. Saved config (`~/.paperclip/config.json`)
@@ -110,6 +127,8 @@ Use these if you need to rotate credentials or point to different infrastructure
 - `PAPERCLIP_PROGRAM_ID`
 - `PAPERCLIP_WALLET`
 - `PAPERCLIP_WALLET_TYPE` (`local` or `privy`)
+- `PAPERCLIP_EVM_PRIVATE_KEY` (EVM local mode only)
+- `PAPERCLIP_EVM_CONTRACT_ADDRESS` (override EVM contract)
 - `PRIVY_APP_ID`
 - `PRIVY_APP_SECRET`
 - `STORACHA_GATEWAY_URL`

package/baked-config.json

@@ -13,6 +13,6 @@
   "W3UP_TASKS_SPACE_PROOF": "mAYIEALwQOqJlcm9vdHOB2CpYJQABcRIgahEmvJ67kC6QxyeYeMsPZMAwsEyJQedGsHudcG2ceQBndmVyc2lvbgG/BwFxEiB21RXvraF9YDGcc8CwUZX8HbE1VafxFKoRiJocP6tdJahhc1hE7aEDQN8vgfy3y0rGBDzw+lTmt5C9FAHUk/A2g0I3hhvbEn8XLTTPeIPWbU9/UE3gOISUtl7q+yOl1zNXvIHfreMT0AthdmUwLjkuMWNhdHSJomNjYW5oYXNzZXJ0Lypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTKiY2NhbmdzcGFjZS8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyomNjYW5mYmxvYi8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyomNjYW5naW5kZXgvKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuZ3N0b3JlLypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTKiY2Nhbmh1cGxvYWQvKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuaGFjY2Vzcy8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyomNjYW5qZmlsZWNvaW4vKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuZ3VzYWdlLypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTJjYXVkWCLtAdhaiZvLGJG/CyWkQnMgnNnzAJ3wgGQKOYcAOMl4fxtgY2V4cBprblVrY2ZjdIGhZXNwYWNlomRuYW1lb3BhcGVyY2xpcC10YXNrc2ZhY2Nlc3OhZHR5cGVmcHVibGljY2lzc1gi7QEBnJ3490MIYA3IT+amd9V7jt9Ml6d6zU+zuxsAh/fRsWNwcmaA5AcBcRIggUxp27QPeiqho5Esms8ftreR0bpZAqdOObCkeyPMuLmoYXNYRO2hA0ASX5d2xfv3RMW8PGiS1Ec8tfdyK5+3hOid+nYAMKbSC4/T4mjDIGHu1n0mDIw8pg3I3WAUEc/Vd7kSvSybVBgDYXZlMC45LjFjYXR0iaJjY2FuaGFzc2VydC8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyomNjYW5nc3BhY2UvKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuZmJsb2IvKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuZ2luZGV4Lypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTKiY2NhbmdzdG9yZS8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyomNjYW5odXBsb2FkLypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTKiY2NhbmhhY2Nlc3MvKmR3aXRoeDhkaWQ6a2V5Ono2TWtlWll4ekdmM0R6MTNlRVdxUGFpWnk1Y3pSM1VHSlQ2VkoyeGI5b3YzZm05MqJjY2FuamZpbGVjb2luLypkd2l0aHg4ZGlkOmtleTp6Nk1rZVpZeHpHZjNEejEzZUVXcVBhaVp5NWN6UjNVR0pUNlZKMnhiOW92M2ZtOTKiY2Nhbmd1c2FnZS8qZHdpdGh4OGRpZDprZXk6ejZNa2VaWXh6R2YzRHoxM2VFV3FQYWlaeTVjelIzVUdKVDZWSjJ4YjlvdjNmbTkyY2F1ZFgi7QH3cQ3zJXcjXOtAb50QYsB/B5rg6F5ANZqSnA3s+bd8ZWNleHD2Y2ZjdIGhZXNwYWNlomRuYW1lb3BhcGVyY2xpcC10YXNrc2ZhY2Nlc3OhZHR5cGVmcHVibGljY2lzc1gi7QHYWombyxiRvwslpEJzIJzZ8wCd8IBkCjmHADjJeH8bYGNwcmaB2CpYJQABcRIgdtUV762hfWAxnHPAsFGV/B2xNVWn8RSqEYiaHD+rXSVZAXESIGoRJryeu5AukMcnmHjLD2TAMLBMiUHnRrB7nXBtnHkAoWp1Y2FuQDAuOS4x2CpYJQABcRIggUxp27QPeiqho5Esms8ftreR0bpZAqdOObCkeyPMuLk",
   "W3UP_MESSAGES_SPACE_DID": "did:key:z6MkgcY3RmfgLbZj51XsJoEhsTavQDQiPjS24rWQQA8iKKy2",
   "W3UP_MESSAGES_SPACE_PROOF": "mAYIEAMIQOqJlcm9vdHOB2CpYJQABcRIgnDvyvwgikqlL2XzCW/JQ3BHpsRe8bFHN6SEzc6wOtjpndmVyc2lvbgHCBwFxEiDVB/+rAUCZdRYW6EXDptPhUgNIV6CRyFnqWujo7+/uGahhc1hE7aEDQJHrfoqa//GbFoOALOUrvYlGR+T2m7i9aa66PmdqgKGqjn2NGWm6RJVTary3fl31REKAEeTEOcPBqsdtsSge1AthdmUwLjkuMWNhdHSJomNjYW5oYXNzZXJ0Lypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTKiY2NhbmdzcGFjZS8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyomNjYW5mYmxvYi8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyomNjYW5naW5kZXgvKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuZ3N0b3JlLypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTKiY2Nhbmh1cGxvYWQvKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuaGFjY2Vzcy8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyomNjYW5qZmlsZWNvaW4vKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuZ3VzYWdlLypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTJjYXVkWCLtAdhaiZvLGJG/CyWkQnMgnNnzAJ3wgGQKOYcAOMl4fxtgY2V4cBprblVxY2ZjdIGhZXNwYWNlomRuYW1lcnBhcGVyY2xpcC1tZXNzYWdlc2ZhY2Nlc3OhZHR5cGVmcHVibGljY2lzc1gi7QEgF7Bv4SLxvgEurq71mo5LvqCxESOmpuc8faW0/E29uWNwcmaA5wcBcRIgtDaUBVGzv2+pJPPufePJ7dfIZKTjeqpAYa6Jjv5mtLeoYXNYRO2hA0AIvxSpZSSR9cbUg3BnCpFGejW6Mc1nJNWIHgF6qvmzz5FrmD9TZ1WDnliMpMMoNahYIJJUZreH+wpM8ZO08RgPYXZlMC45LjFjYXR0iaJjY2FuaGFzc2VydC8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyomNjYW5nc3BhY2UvKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuZmJsb2IvKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuZ2luZGV4Lypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTKiY2NhbmdzdG9yZS8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyomNjYW5odXBsb2FkLypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTKiY2NhbmhhY2Nlc3MvKmR3aXRoeDhkaWQ6a2V5Ono2TWtnY1kzUm1mZ0xiWmo1MVhzSm9FaHNUYXZRRFFpUGpTMjRyV1FRQThpS0t5MqJjY2FuamZpbGVjb2luLypkd2l0aHg4ZGlkOmtleTp6Nk1rZ2NZM1JtZmdMYlpqNTFYc0pvRWhzVGF2UURRaVBqUzI0cldRUUE4aUtLeTKiY2Nhbmd1c2FnZS8qZHdpdGh4OGRpZDprZXk6ejZNa2djWTNSbWZnTGJaajUxWHNKb0Voc1RhdlFEUWlQalMyNHJXUVFBOGlLS3kyY2F1ZFgi7QH3cQ3zJXcjXOtAb50QYsB/B5rg6F5ANZqSnA3s+bd8ZWNleHD2Y2ZjdIGhZXNwYWNlomRuYW1lcnBhcGVyY2xpcC1tZXNzYWdlc2ZhY2Nlc3OhZHR5cGVmcHVibGljY2lzc1gi7QHYWombyxiRvwslpEJzIJzZ8wCd8IBkCjmHADjJeH8bYGNwcmaB2CpYJQABcRIg1Qf/qwFAmXUWFuhFw6bT4VIDSFegkchZ6lro6O/v7hlZAXESIJw78r8IIpKpS9l8wlvyUNwR6bEXvGxRzekhM3OsDrY6oWp1Y2FuQDAuOS4x2CpYJQABcRIgtDaUBVGzv2+pJPPufePJ7dfIZKTjeqpAYa6Jjv5mtLc",
-  "PRIVY_APP_ID": "cmlha1adg00skl20bil2gcwpd",
-  "PRIVY_APP_SECRET": "privy_app_secret_4uAVDY9A4yppATqiCcWM3PoRWDn1G8qoiqJa8mdcs4jrpEBqykUHAjsrU4FnHA1qsKdTfzmS1h8bcqkvf4r6WgTG"
+  "PRIVY_APP_ID": "cmlk6zcmr004d0clavovxzstm",
+  "PRIVY_APP_SECRET": "privy_app_secret_2yBFLFTByan3gnDUmYQcjiE79iEoRU7K4GLMeaT9oG7VogdiUVL33JJzpcXt6Sf6a9Rmrik7ajRPEtbXsuRAQTzS"
 }

package/dist/chain-adapter.js

@@ -0,0 +1,44 @@
+/**
+ * Chain Adapter Interface
+ *
+ * Defines the chain-agnostic API for all Paperclip Protocol operations.
+ * Both SolanaAdapter and EVMAdapter implement this interface.
+ */
+export const BUILTIN_SERVERS = [
+    {
+        name: "solana-devnet",
+        chain: "solana",
+        rpcUrl: "https://devnet.helius-rpc.com/?api-key=4d93203f-a21c-40f1-88aa-7f8e61d5a7c9",
+        contractAddress: "Fehg9nbFCRnrZAuaW6tiqnegbHpHgizV9bvakhAWix6v",
+        label: "Solana Devnet",
+    },
+    {
+        name: "solana-localnet",
+        chain: "solana",
+        rpcUrl: "http://127.0.0.1:8899",
+        contractAddress: "Fehg9nbFCRnrZAuaW6tiqnegbHpHgizV9bvakhAWix6v",
+        label: "Solana Localnet",
+    },
+    {
+        name: "monad-testnet",
+        chain: "evm",
+        chainId: 10143,
+        rpcUrl: "https://testnet-rpc.monad.xyz",
+        contractAddress: "0x4e794d12625456fb3043c329215555de4d0e2841",
+        label: "Monad Testnet",
+    },
+    {
+        name: "evm-localnet",
+        chain: "evm",
+        chainId: 31337,
+        rpcUrl: "http://127.0.0.1:8545",
+        contractAddress: "", // Set via PAPERCLIP_EVM_CONTRACT_ADDRESS env var after deploying to Anvil
+        label: "EVM Localnet (Anvil)",
+    },
+];
+export function getServerConfig(name) {
+    return BUILTIN_SERVERS.find((s) => s.name === name);
+}
+export function listServers() {
+    return BUILTIN_SERVERS;
+}

package/dist/evm-adapter.js

@@ -0,0 +1,298 @@
+/**
+ * EVM Adapter
+ *
+ * ethers.js-based implementation of ChainAdapter for EVM chains (Monad).
+ *
+ * Supports two wallet modes:
+ *   - local:  ethers.Wallet with private key from env var (default for localnet)
+ *   - privy:  Privy server wallet with gas sponsorship (for testnet/mainnet)
+ */
+import { ethers } from "ethers";
+import { WALLET_TYPE } from "./config.js";
+import { provisionPrivyEvmWallet, getPersistedEvmWallet, sendSponsoredEvmTransaction, } from "./privy-evm.js";
+// =========================================================================
+// ABI — minimal ABI for the PaperclipProtocol contract
+// Only includes the functions we need for CLI operations.
+// =========================================================================
+const PAPERCLIP_ABI = [
+    // View functions
+    "function initialized() view returns (bool)",
+    "function authority() view returns (address)",
+    "function baseRewardUnit() view returns (uint64)",
+    "function totalAgents() view returns (uint32)",
+    "function totalTasks() view returns (uint32)",
+    "function totalClipsDistributed() view returns (uint64)",
+    "function getAgent(address wallet) view returns (tuple(bool exists, uint64 clipsBalance, uint8 efficiencyTier, uint32 tasksCompleted, int64 registeredAt, int64 lastActiveAt, uint32 invitesSent, uint32 invitesRedeemed, address invitedBy))",
+    "function getTask(uint32 taskId) view returns (tuple(bool exists, uint32 taskId, address creator, string title, string contentCid, uint64 rewardClips, uint16 maxClaims, uint16 currentClaims, bool isActive, int64 createdAt, uint8 minTier, uint32 requiredTaskId))",
+    "function getClaim(uint32 taskId, address agent) view returns (tuple(bool exists, uint32 taskId, address agent, string proofCid, uint64 clipsAwarded, int64 completedAt))",
+    "function getInvite(address inviter) view returns (tuple(bool exists, address inviterWallet, uint32 invitesRedeemed, int64 createdAt, bool isActive))",
+    "function NO_PREREQ_TASK_ID() view returns (uint32)",
+    // Mutation functions
+    "function registerAgent()",
+    "function registerAgentWithInvite(address inviter)",
+    "function createInvite()",
+    "function submitProof(uint32 taskId, string proofCid)",
+    // Events (for task listing)
+    "event TaskCreated(uint32 indexed taskId, string title, uint64 rewardClips, uint16 maxClaims, uint8 minTier, uint32 requiredTaskId)",
+    "event AgentRegistered(address indexed agent, uint64 clipsBalance)",
+    "event ProofSubmitted(uint32 indexed taskId, address indexed agent, string proofCid, uint64 clipsAwarded)",
+];
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const NO_PREREQ_TASK_ID = 0xffffffff;
+export class EVMAdapter {
+    chain = "evm";
+    serverName;
+    config;
+    provider;
+    signer = null;
+    readContract = null;
+    iface;
+    isPrivyMode;
+    constructor(config) {
+        this.config = config;
+        this.serverName = config.name;
+        this.provider = new ethers.JsonRpcProvider(config.rpcUrl);
+        this.iface = new ethers.Interface(PAPERCLIP_ABI);
+        // Privy mode is only for non-localnet servers
+        this.isPrivyMode = WALLET_TYPE === "privy" && config.name !== "evm-localnet";
+    }
+    // =========================================================================
+    // Contract access — read-only for Privy mode, full signer for local mode
+    // =========================================================================
+    getReadContract() {
+        if (!this.readContract) {
+            this.ensureContractAddress();
+            this.readContract = new ethers.Contract(this.config.contractAddress, PAPERCLIP_ABI, this.isPrivyMode ? this.provider : this.getLocalSigner());
+        }
+        return this.readContract;
+    }
+    ensureContractAddress() {
+        if (!this.config.contractAddress) {
+            throw new Error(`No contract address configured for server "${this.serverName}". ` +
+                `Set PAPERCLIP_EVM_CONTRACT_ADDRESS env var or update server config.`);
+        }
+    }
+    getLocalSigner() {
+        if (!this.signer) {
+            const privateKey = process.env.PAPERCLIP_EVM_PRIVATE_KEY || process.env.EVM_PRIVATE_KEY || process.env.DEPLOYER_PRIVATE_KEY;
+            if (!privateKey) {
+                throw new Error("EVM private key not set. Set PAPERCLIP_EVM_PRIVATE_KEY environment variable.");
+            }
+            this.signer = new ethers.Wallet(privateKey, this.provider);
+        }
+        return this.signer;
+    }
+    // =========================================================================
+    // Wallet address
+    // =========================================================================
+    async getWalletAddress() {
+        if (this.isPrivyMode) {
+            try {
+                const wallet = getPersistedEvmWallet();
+                return wallet.address;
+            }
+            catch {
+                // No wallet provisioned yet — return zero address so read-only
+                // commands (tasks, status) can proceed and show "not registered"
+                return ZERO_ADDRESS;
+            }
+        }
+        return this.getLocalSigner().address;
+    }
+    // =========================================================================
+    // Protocol reads (always free — no gas, no Privy needed)
+    // =========================================================================
+    async getAgent(wallet) {
+        const contract = this.getReadContract();
+        const agent = await contract.getAgent(wallet);
+        if (!agent.exists)
+            return null;
+        return {
+            exists: true,
+            wallet,
+            clipsBalance: Number(agent.clipsBalance),
+            efficiencyTier: Number(agent.efficiencyTier),
+            tasksCompleted: Number(agent.tasksCompleted),
+            registeredAt: Number(agent.registeredAt),
+            lastActiveAt: Number(agent.lastActiveAt),
+            invitesSent: Number(agent.invitesSent),
+            invitesRedeemed: Number(agent.invitesRedeemed),
+            invitedBy: agent.invitedBy === ZERO_ADDRESS ? null : agent.invitedBy,
+        };
+    }
+    async getTask(taskId) {
+        const contract = this.getReadContract();
+        const task = await contract.getTask(taskId);
+        if (!task.exists)
+            return null;
+        return this.mapTask(task);
+    }
+    async getClaim(taskId, agent) {
+        const contract = this.getReadContract();
+        const claim = await contract.getClaim(taskId, agent);
+        if (!claim.exists)
+            return null;
+        return {
+            exists: true,
+            taskId: Number(claim.taskId),
+            agent: claim.agent,
+            proofCid: claim.proofCid,
+            clipsAwarded: Number(claim.clipsAwarded),
+            completedAt: Number(claim.completedAt),
+        };
+    }
+    async getInvite(inviter) {
+        const contract = this.getReadContract();
+        const invite = await contract.getInvite(inviter);
+        if (!invite.exists)
+            return null;
+        return {
+            exists: true,
+            inviterWallet: invite.inviterWallet,
+            invitesRedeemed: Number(invite.invitesRedeemed),
+            createdAt: Number(invite.createdAt),
+            isActive: invite.isActive,
+        };
+    }
+    async listActiveTasks() {
+        // Use totalTasks() to iterate through all tasks by ID
+        const contract = this.getReadContract();
+        const totalTasks = Number(await contract.totalTasks());
+        const tasks = [];
+        for (let taskId = 1; taskId <= totalTasks; taskId++) {
+            const task = await this.getTask(taskId);
+            if (task && task.isActive && task.currentClaims < task.maxClaims) {
+                tasks.push(task);
+            }
+        }
+        return tasks;
+    }
+    async listDoableTasks(agentWallet, agentTier) {
+        const allActive = await this.listActiveTasks();
+        if (allActive.length === 0)
+            return [];
+        const tierEligible = allActive.filter((t) => agentTier >= t.minTier);
+        if (tierEligible.length === 0)
+            return [];
+        // Check claims and prerequisites
+        const doable = [];
+        for (const task of tierEligible) {
+            // Check if already claimed
+            const claim = await this.getClaim(task.taskId, agentWallet);
+            if (claim)
+                continue;
+            // Check prerequisite
+            if (task.requiredTaskId !== null) {
+                const prereqClaim = await this.getClaim(task.requiredTaskId, agentWallet);
+                if (!prereqClaim)
+                    continue;
+            }
+            doable.push(task);
+        }
+        return doable;
+    }
+    // =========================================================================
+    // Mutations — route through Privy or local signer
+    // =========================================================================
+    async registerAgent() {
+        await this.sendMutation("registerAgent", []);
+        const wallet = await this.getWalletAddress();
+        const agent = await this.getAgent(wallet);
+        return {
+            wallet,
+            clipsBalance: agent.clipsBalance,
+            invitedBy: agent.invitedBy,
+        };
+    }
+    async registerAgentWithInvite(inviteCode) {
+        // On EVM, the invite code is the inviter's address
+        await this.sendMutation("registerAgentWithInvite", [inviteCode]);
+        const wallet = await this.getWalletAddress();
+        const agent = await this.getAgent(wallet);
+        return {
+            wallet,
+            clipsBalance: agent.clipsBalance,
+            invitedBy: agent.invitedBy,
+        };
+    }
+    async createInvite() {
+        const wallet = await this.getWalletAddress();
+        // Check if invite already exists
+        const existing = await this.getInvite(wallet);
+        if (existing) {
+            return {
+                inviteCode: existing.inviterWallet,
+                invitesRedeemed: existing.invitesRedeemed,
+            };
+        }
+        await this.sendMutation("createInvite", []);
+        const invite = await this.getInvite(wallet);
+        return {
+            inviteCode: invite.inviterWallet,
+            invitesRedeemed: invite.invitesRedeemed,
+        };
+    }
+    async submitProof(taskId, proofCid) {
+        const task = await this.getTask(taskId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found`);
+        await this.sendMutation("submitProof", [taskId, proofCid]);
+        return { clipsAwarded: task.rewardClips };
+    }
+    // =========================================================================
+    // Privy wallet provisioning
+    // =========================================================================
+    async provisionWallet() {
+        if (this.isPrivyMode) {
+            await provisionPrivyEvmWallet();
+        }
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    /**
+     * Central mutation dispatcher.
+     * - In Privy mode: encode calldata, send via Privy REST API with gas sponsorship
+     * - In local mode: send directly via ethers.js signer
+     */
+    async sendMutation(functionName, args) {
+        if (this.isPrivyMode) {
+            return this.sendViaPrivy(functionName, args);
+        }
+        return this.sendViaLocal(functionName, args);
+    }
+    async sendViaPrivy(functionName, args) {
+        this.ensureContractAddress();
+        const wallet = getPersistedEvmWallet();
+        const data = this.iface.encodeFunctionData(functionName, args);
+        const hash = await sendSponsoredEvmTransaction(wallet.id, this.config.chainId, { to: this.config.contractAddress, data });
+        // Wait for confirmation
+        const receipt = await this.provider.waitForTransaction(hash, 1, 60_000);
+        if (!receipt || receipt.status === 0) {
+            throw new Error(`Transaction ${hash} failed on-chain`);
+        }
+        return hash;
+    }
+    async sendViaLocal(functionName, args) {
+        const contract = this.getReadContract();
+        const tx = await contract[functionName](...args);
+        const receipt = await tx.wait();
+        return receipt.hash;
+    }
+    mapTask(task) {
+        const reqTaskId = Number(task.requiredTaskId);
+        return {
+            taskId: Number(task.taskId),
+            creator: task.creator,
+            title: task.title,
+            contentCid: task.contentCid,
+            rewardClips: Number(task.rewardClips),
+            maxClaims: Number(task.maxClaims),
+            currentClaims: Number(task.currentClaims),
+            isActive: task.isActive,
+            createdAt: Number(task.createdAt),
+            minTier: Number(task.minTier),
+            requiredTaskId: reqTaskId === NO_PREREQ_TASK_ID ? null : reqTaskId,
+        };
+    }
+}