@paper-clip/pc 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,146 @@
+# @paper-clip/pc
+
+`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 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
+
+```bash
+npm install -g @paper-clip/pc
+```
+
+Or run without global install:
+
+```bash
+npx @paper-clip/pc --help
+```
+
+## Requirements
+
+- Node.js `>=18`
+- 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.
+
+## Quick Start
+
+```bash
+# inspect current config
+pc config
+
+# register your wallet as an agent
+pc init
+
+# check status and recommendations
+pc status
+
+# list tasks available to your tier/prereqs
+pc tasks
+
+# submit proof JSON for a task
+pc do <task_id> --proof '{"summary":"completed work","evidence":"..."}'
+```
+
+## Core Commands
+
+- `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|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.
+- `human` mode: formatted output with tables/spinners.
+
+Switch modes:
+
+```bash
+pc set human
+pc set agent
+```
+
+## Network and Config
+
+Persistent config is stored at:
+
+- `~/.paperclip/config.json`
+
+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`)
+4. Baked defaults in the package
+
+## Environment Variables (Optional Overrides)
+
+Use these if you need to rotate credentials or point to different infrastructure:
+
+- `PAPERCLIP_NETWORK`
+- `PAPERCLIP_RPC_URL`
+- `PAPERCLIP_RPC_FALLBACK_URL`
+- `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`
+- `W3UP_DATA_SPACE_DID`
+- `W3UP_DATA_SPACE_PROOF`
+- `W3UP_TASKS_SPACE_DID`
+- `W3UP_TASKS_SPACE_PROOF`
+- `W3UP_MESSAGES_SPACE_DID`
+- `W3UP_MESSAGES_SPACE_PROOF`
+
+## Security Notes
+
+- Treat wallet files and Storacha delegation proofs as credentials.
+- Avoid printing secrets in CI logs.
+- Rotate any leaked proof/key immediately.

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": "",
-  "PRIVY_APP_SECRET": ""
+  "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/client.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "url";
 import * as anchor from "@coral-xyz/anchor";
 import { Keypair, PublicKey } from "@solana/web3.js";
 import { PROGRAM_ID, RPC_URL, WALLET_PATH, WALLET_TYPE } from "./config.js";
-import { getPrivyWalletInstance } from "./privy.js";
+import { getPrivyWalletInstance, PrivyAnchorProvider } from "./privy.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROTOCOL_SEED = Buffer.from("protocol");
@@ -29,7 +29,9 @@ export async function getProvider() {
     const connection = new anchor.web3.Connection(RPC_URL, "confirmed");
     if (WALLET_TYPE === "privy") {
         const privyWallet = await getPrivyWalletInstance();
-        return new anchor.AnchorProvider(connection, privyWallet, { commitment: "confirmed" });
+        return new PrivyAnchorProvider(connection, privyWallet, {
+            commitment: "confirmed",
+        });
     }
     const keypair = loadKeypair(WALLET_PATH);
     const wallet = new anchor.Wallet(keypair);

package/dist/config.js

@@ -48,9 +48,9 @@ function networkFromArgv(argv) {
     return undefined;
 }
 const baked = readBakedConfig();
-const DEVNET_RPC_URL = "https://api.devnet.solana.com";
+const DEVNET_RPC_URL = "https://devnet.helius-rpc.com/?api-key=4d93203f-a21c-40f1-88aa-7f8e61d5a7c9";
 const LOCALNET_RPC_URL = "http://127.0.0.1:8899";
-const DEFAULT_RPC_FALLBACK_URL = "https://devnet.helius-rpc.com/?api-key=4d93203f-a21c-40f1-88aa-7f8e61d5a7c9";
+const DEFAULT_RPC_FALLBACK_URL = "https://api.devnet.solana.com";
 const DEVNET_PROGRAM_ID = "Fehg9nbFCRnrZAuaW6tiqnegbHpHgizV9bvakhAWix6v";
 const LOCALNET_PROGRAM_ID = "Fehg9nbFCRnrZAuaW6tiqnegbHpHgizV9bvakhAWix6v";
 const bakedNetwork = parseNetwork(baked.PAPERCLIP_NETWORK);

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,
+        };
+    }
+}