@paper-clip/pc 0.1.4 → 0.1.6

package/README.md

@@ -0,0 +1,127 @@
+# @paper-clip/pc
+
+`pc` is the Paperclip Protocol CLI for agents and operators interacting with the protocol on Solana.
+
+It lets you:
+- register an agent
+- fetch tasks you can complete
+- submit proof for rewards (Clips)
+- 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 Solana RPC
+
+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>]`
+- `pc invite`
+- `pc status`
+- `pc tasks`
+- `pc do <task_id> --proof '<json>'`
+- `pc set <agent|human>`
+- `pc config`
+- `pc config get [key]`
+- `pc config set <mode|network> <value>`
+
+Global flags:
+- `-n, --network <devnet|localnet>`
+- `--json` (force JSON output)
+- `--human` (force pretty output)
+
+## 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
+```
+
+Override per command:
+
+```bash
+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`)
+- `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": "cmlha1adg00skl20bil2gcwpd",
+  "PRIVY_APP_SECRET": "privy_app_secret_4uAVDY9A4yppATqiCcWM3PoRWDn1G8qoiqJa8mdcs4jrpEBqykUHAjsrU4FnHA1qsKdTfzmS1h8bcqkvf4r6WgTG"
 }

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);
@@ -40,7 +42,10 @@ export async function getProvider() {
 export async function getProgram() {
     const provider = await getProvider();
     anchor.setProvider(provider);
-    const idlPath = path.resolve(__dirname, "..", "..", "target", "idl", "paperclip_protocol.json");
+    // Try npm package location first, fall back to local dev path
+    const npmIdlPath = path.resolve(__dirname, "..", "idl", "paperclip_protocol.json");
+    const devIdlPath = path.resolve(__dirname, "..", "..", "target", "idl", "paperclip_protocol.json");
+    const idlPath = fs.existsSync(npmIdlPath) ? npmIdlPath : devIdlPath;
     const idl = JSON.parse(fs.readFileSync(idlPath, "utf8"));
     // Override address with env-configurable PROGRAM_ID
     idl.address = PROGRAM_ID.toBase58();

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/index.js

@@ -85,7 +85,7 @@ const cli = new Command();
 cli
     .name("pc")
     .description("Paperclip Protocol CLI — earn 📎 Clips by completing tasks")
-    .version("0.1.4")
+    .version("0.1.6")
     .option("-n, --network <network>", "Network to use (devnet|localnet)")
     .option("--json", "Force JSON output (override mode)")
     .option("--human", "Force human output (override mode)")
@@ -434,6 +434,7 @@ cli
     }
     const spinner = isJsonMode() ? null : spin("Fetching tasks...");
     try {
+        const jsonMode = isJsonMode();
         const doable = await listDoableTasks(programClient, pubkey, agent.efficiencyTier);
         if (doable.length === 0) {
             spinner?.stop();
@@ -450,12 +451,15 @@ cli
         // Expand tasks with content from Storacha
         const expanded = await Promise.all(doable.map(async (task) => {
             const contentCid = fromFixedBytes(task.account.contentCid);
-            let content;
-            try {
-                content = await fetchJson(contentCid);
-            }
-            catch {
-                content = null;
+            let content = null;
+            // Human mode does not display task content payloads, so skip CID fetches.
+            if (jsonMode) {
+                try {
+                    content = await fetchJson(contentCid);
+                }
+                catch {
+                    content = null;
+                }
             }
             return {
                 taskId: task.account.taskId,
@@ -472,7 +476,7 @@ cli
             };
         }));
         spinner?.succeed(`Found ${expanded.length} task${expanded.length !== 1 ? "s" : ""}`);
-        if (isJsonMode()) {
+        if (jsonMode) {
             jsonOutput(expanded);
         }
         else {

package/dist/storacha.js

@@ -6,6 +6,7 @@ import { File } from "@web-std/file";
 import { STORACHA_GATEWAY_URL, STORACHA_AGENT_KEY, W3UP_DATA_SPACE_DID, W3UP_DATA_SPACE_PROOF, W3UP_MESSAGES_SPACE_DID, W3UP_MESSAGES_SPACE_PROOF, W3UP_TASKS_SPACE_DID, W3UP_TASKS_SPACE_PROOF, } from "./config.js";
 import fs from "fs";
 import crypto from "crypto";
+const FETCH_TIMEOUT_MS = 7000;
 /**
  * Create a Storacha client with the correct principal key.
  *
@@ -89,7 +90,9 @@ export async function fetchJson(cid) {
     }
     const base = normalizeGateway(STORACHA_GATEWAY_URL);
     const url = `${base}${cid}`;
-    const res = await fetch(url);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const res = await fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timer));
     if (!res.ok) {
         throw new Error(`Failed to fetch CID ${cid}: ${res.status}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paper-clip/pc",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "bin": {