@paper-clip/pc 0.1.4

package/dist/privy.js

@@ -0,0 +1,243 @@
+/**
+ * Privy Server Wallet Integration
+ *
+ * Provides server-side Solana wallet signing via Privy's REST API.
+ * Agents never touch raw keypairs — signing happens on Privy's servers
+ * with policy controls set by the protocol team.
+ *
+ * Credentials are baked into config.ts at build time.
+ * This module is only used when WALLET_TYPE === "privy".
+ */
+import * as anchor from "@coral-xyz/anchor";
+import { PublicKey, Transaction, VersionedTransaction, } from "@solana/web3.js";
+import { NETWORK, PRIVY_APP_ID, PRIVY_APP_SECRET } from "./config.js";
+import { loadSettings, saveSettings } from "./settings.js";
+const PRIVY_API_BASE = "https://api.privy.io/v1";
+const DUMMY_RECENT_BLOCKHASH = "11111111111111111111111111111111";
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+function authHeaders() {
+    const encoded = Buffer.from(`${PRIVY_APP_ID}:${PRIVY_APP_SECRET}`).toString("base64");
+    return {
+        Authorization: `Basic ${encoded}`,
+        "privy-app-id": PRIVY_APP_ID,
+        "Content-Type": "application/json",
+    };
+}
+async function privyFetch(path, init = {}) {
+    const url = `${PRIVY_API_BASE}${path}`;
+    const headers = {
+        ...authHeaders(),
+        ...(init.headers || {}),
+    };
+    const res = await fetch(url, { ...init, headers });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Privy API error ${res.status} on ${init.method || "GET"} ${path}: ${body}`);
+    }
+    return res.json();
+}
+function networkToCaip2(network) {
+    if (network === "devnet") {
+        return "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+    }
+    if (network === "testnet") {
+        return "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z";
+    }
+    if (network === "mainnet") {
+        return "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    }
+    throw new Error(`Privy gas sponsorship is not supported for network "${network}". Use devnet/mainnet.`);
+}
+function extractTxHash(response) {
+    const hash = response?.data?.hash ||
+        response?.data?.signature ||
+        response?.hash ||
+        response?.signature;
+    if (typeof hash !== "string" || hash.length === 0) {
+        throw new Error(`Invalid Privy signAndSendTransaction response: ${JSON.stringify(response)}`);
+    }
+    return hash;
+}
+/**
+ * Create a new Solana server wallet via Privy.
+ * Called once during `pc init` — wallet ID is saved to ~/.paperclip/config.json.
+ */
+export async function createPrivyWallet() {
+    const data = await privyFetch("/wallets", {
+        method: "POST",
+        body: JSON.stringify({ chain_type: "solana" }),
+    });
+    return { id: data.id, address: data.address };
+}
+/**
+ * Get an existing wallet's info from Privy.
+ */
+export async function getPrivyWalletInfo(walletId) {
+    const data = await privyFetch(`/wallets/${walletId}`);
+    return { id: data.id, address: data.address };
+}
+// ---------------------------------------------------------------------------
+// PrivyWallet — Anchor Wallet interface
+// ---------------------------------------------------------------------------
+/**
+ * Anchor-compatible Wallet that signs transactions via Privy's REST API.
+ *
+ * Duck-types the Wallet interface Anchor needs:
+ *   - publicKey: PublicKey
+ *   - signTransaction(tx): Promise<Transaction>
+ *   - signAllTransactions(txs): Promise<Transaction[]>
+ */
+export class PrivyWallet {
+    publicKey;
+    walletId;
+    constructor(walletId, publicKey) {
+        this.walletId = walletId;
+        this.publicKey = publicKey;
+    }
+    get id() {
+        return this.walletId;
+    }
+    async signTransaction(tx) {
+        const serialized = Buffer.from(tx.serialize({ requireAllSignatures: false, verifySignatures: false })).toString("base64");
+        const data = await privyFetch(`/wallets/${this.walletId}/rpc`, {
+            method: "POST",
+            body: JSON.stringify({
+                method: "signTransaction",
+                params: {
+                    transaction: serialized,
+                    encoding: "base64",
+                },
+            }),
+        });
+        const signedBytes = Buffer.from(data.data?.signed_transaction || data.data?.signature || "", "base64");
+        if (tx instanceof VersionedTransaction) {
+            return VersionedTransaction.deserialize(signedBytes);
+        }
+        return Transaction.from(signedBytes);
+    }
+    async signAllTransactions(txs) {
+        // Sign sequentially — Privy doesn't have a batch sign endpoint
+        return Promise.all(txs.map((tx) => this.signTransaction(tx)));
+    }
+}
+async function signAndSendSponsoredTransaction(walletId, txBase64) {
+    const caip2 = networkToCaip2(NETWORK);
+    const data = await privyFetch(`/wallets/${walletId}/rpc`, {
+        method: "POST",
+        body: JSON.stringify({
+            method: "signAndSendTransaction",
+            caip2,
+            sponsor: true,
+            params: {
+                transaction: txBase64,
+                encoding: "base64",
+            },
+        }),
+    });
+    return extractTxHash(data);
+}
+function toBase64Transaction(tx) {
+    if (tx instanceof VersionedTransaction) {
+        return Buffer.from(tx.serialize()).toString("base64");
+    }
+    // Privy signs this transaction server-side, so it may be missing wallet sig.
+    const raw = tx.serialize({
+        requireAllSignatures: false,
+        verifySignatures: false,
+    });
+    return Buffer.from(raw).toString("base64");
+}
+/**
+ * Provider wrapper that routes Privy transactions through signAndSendTransaction
+ * with sponsorship enabled.
+ */
+export class PrivyAnchorProvider extends anchor.AnchorProvider {
+    privyWallet;
+    constructor(connection, wallet, opts = anchor.AnchorProvider.defaultOptions()) {
+        super(connection, wallet, opts);
+        this.privyWallet = wallet;
+    }
+    prepareTx(tx, signers) {
+        if (tx instanceof VersionedTransaction) {
+            if (signers && signers.length > 0) {
+                tx.sign(signers);
+            }
+            // Privy fills the real recent blockhash when processing signAndSend.
+            tx.message.recentBlockhash = DUMMY_RECENT_BLOCKHASH;
+            return tx;
+        }
+        tx.feePayer = tx.feePayer ?? this.wallet.publicKey;
+        tx.recentBlockhash = DUMMY_RECENT_BLOCKHASH;
+        if (signers && signers.length > 0) {
+            for (const signer of signers) {
+                tx.partialSign(signer);
+            }
+        }
+        return tx;
+    }
+    async sendAndConfirm(tx, signers = [], opts) {
+        // Keep localnet behavior unchanged (no Privy sponsorship path there).
+        if (NETWORK === "localnet") {
+            return super.sendAndConfirm(tx, signers, opts);
+        }
+        const prepared = this.prepareTx(tx, signers);
+        const txBase64 = toBase64Transaction(prepared);
+        const signature = await signAndSendSponsoredTransaction(this.privyWallet.id, txBase64);
+        const commitment = opts?.commitment ?? this.opts.commitment ?? "confirmed";
+        const status = await this.connection.confirmTransaction(signature, commitment);
+        if (status.value.err) {
+            throw new Error(`Privy sponsored transaction ${signature} failed: ${JSON.stringify(status.value.err)}`);
+        }
+        return signature;
+    }
+    async sendAll(txWithSigners, opts) {
+        const out = [];
+        for (const item of txWithSigners) {
+            out.push(await this.sendAndConfirm(item.tx, item.signers ?? [], opts));
+        }
+        return out;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cached instance — getPrivyWalletInstance()
+// ---------------------------------------------------------------------------
+let _cachedWallet = null;
+/**
+ * Get or create the PrivyWallet instance.
+ * Reads wallet ID from persisted settings (~/.paperclip/config.json).
+ * Throws if no wallet has been provisioned yet (agent must run `pc init` first).
+ */
+export async function getPrivyWalletInstance() {
+    if (_cachedWallet)
+        return _cachedWallet;
+    const settings = loadSettings();
+    const walletId = settings.privyWalletId;
+    const walletAddress = settings.privyWalletAddress;
+    if (!walletId || !walletAddress) {
+        throw new Error("No Privy wallet found. Run `pc init` to create one.");
+    }
+    _cachedWallet = new PrivyWallet(walletId, new PublicKey(walletAddress));
+    return _cachedWallet;
+}
+/**
+ * Provision a new wallet and save to settings.
+ * Called during `pc init` when using Privy mode.
+ */
+export async function provisionPrivyWallet() {
+    const settings = loadSettings();
+    // Already provisioned?
+    if (settings.privyWalletId && settings.privyWalletAddress) {
+        _cachedWallet = new PrivyWallet(settings.privyWalletId, new PublicKey(settings.privyWalletAddress));
+        return _cachedWallet;
+    }
+    // Create new wallet
+    const info = await createPrivyWallet();
+    // Persist
+    settings.privyWalletId = info.id;
+    settings.privyWalletAddress = info.address;
+    saveSettings(settings);
+    _cachedWallet = new PrivyWallet(info.id, new PublicKey(info.address));
+    return _cachedWallet;
+}

package/dist/settings.js

@@ -0,0 +1,75 @@
+/**
+ * Persistent CLI settings — stored at ~/.paperclip/config.json
+ *
+ * Supports agent mode (JSON, no spinners — default) and
+ * human mode (emoji, colors, spinners).
+ */
+import fs from "fs";
+import path from "path";
+import os from "os";
+// =============================================================================
+// PATHS
+// =============================================================================
+const CONFIG_DIR = path.join(os.homedir(), ".paperclip");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+// =============================================================================
+// DEFAULTS
+// =============================================================================
+const DEFAULTS = {
+    mode: "agent",
+    network: "devnet",
+};
+// =============================================================================
+// READ / WRITE
+// =============================================================================
+export function loadSettings() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+            return { ...DEFAULTS, ...raw };
+        }
+    }
+    catch {
+        // Corrupted file — return defaults
+    }
+    return { ...DEFAULTS };
+}
+export function saveSettings(settings) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(settings, null, 2) + "\n");
+}
+export function getMode() {
+    return loadSettings().mode;
+}
+export function setMode(mode) {
+    const settings = loadSettings();
+    settings.mode = mode;
+    saveSettings(settings);
+}
+export function getNetwork() {
+    return loadSettings().network;
+}
+export function getConfiguredNetwork() {
+    try {
+        if (!fs.existsSync(CONFIG_FILE)) {
+            return undefined;
+        }
+        const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+        return raw.network === "devnet" || raw.network === "localnet"
+            ? raw.network
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function setNetwork(network) {
+    const settings = loadSettings();
+    settings.network = network;
+    saveSettings(settings);
+}
+export function configPath() {
+    return CONFIG_FILE;
+}

package/dist/storacha.js

@@ -0,0 +1,97 @@
+import { create } from "@storacha/client";
+import { StoreMemory } from "@storacha/client/stores/memory";
+import * as Proof from "@storacha/client/proof";
+import { Signer } from "@storacha/client/principal/ed25519";
+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";
+/**
+ * Create a Storacha client with the correct principal key.
+ *
+ * If STORACHA_AGENT_KEY is set, uses that as the agent identity.
+ * Otherwise falls back to auto-generated key (may fail if proof
+ * audience doesn't match).
+ */
+async function createClient() {
+    if (STORACHA_AGENT_KEY) {
+        const principal = Signer.parse(STORACHA_AGENT_KEY);
+        const store = new StoreMemory();
+        return create({ principal, store });
+    }
+    return create();
+}
+function resolveSpace(scope) {
+    if (scope === "data") {
+        return { did: W3UP_DATA_SPACE_DID, proof: W3UP_DATA_SPACE_PROOF };
+    }
+    if (scope === "tasks") {
+        return { did: W3UP_TASKS_SPACE_DID, proof: W3UP_TASKS_SPACE_PROOF };
+    }
+    return { did: W3UP_MESSAGES_SPACE_DID, proof: W3UP_MESSAGES_SPACE_PROOF };
+}
+async function ensureSpace(client, scope) {
+    const { did, proof } = resolveSpace(scope);
+    const proofStr = proof;
+    if (!proofStr) {
+        throw new Error(`No Storacha delegation proof configured for "${scope}" uploads. Set W3UP_${scope.toUpperCase()}_SPACE_PROOF.`);
+    }
+    const delegation = await Proof.parse(proofStr);
+    const space = await client.addSpace(delegation);
+    const targetDid = (did || space.did());
+    const currentDid = currentSpaceDid(client);
+    if (currentDid !== targetDid) {
+        await client.setCurrentSpace(targetDid);
+    }
+}
+function normalizeGateway(base) {
+    return base.endsWith("/") ? base : `${base}/`;
+}
+function currentSpaceDid(client) {
+    const current = client.currentSpace();
+    if (!current) {
+        return undefined;
+    }
+    if (typeof current === "string") {
+        return current;
+    }
+    if (typeof current.did === "function") {
+        return current.did();
+    }
+    return undefined;
+}
+export async function uploadJson(data, scope = "data") {
+    if (process.env.PAPERCLIP_STORACHA_MOCK === "1") {
+        const payload = JSON.stringify(data);
+        const hash = crypto.createHash("sha256").update(payload).digest("hex");
+        return `mock-${hash.slice(0, 16)}`;
+    }
+    const client = await createClient();
+    await ensureSpace(client, scope);
+    const payload = JSON.stringify(data, null, 2);
+    const file = new File([payload], "proof.json", {
+        type: "application/json",
+    });
+    const cid = await client.uploadFile(file);
+    return typeof cid === "string" ? cid : cid.toString();
+}
+export async function fetchJson(cid) {
+    if (process.env.PAPERCLIP_STORACHA_MOCK === "1") {
+        const inline = process.env.PAPERCLIP_MOCK_TASK_JSON;
+        if (inline) {
+            return JSON.parse(inline);
+        }
+        const path = process.env.PAPERCLIP_MOCK_TASK_JSON_PATH;
+        if (path && fs.existsSync(path)) {
+            return JSON.parse(fs.readFileSync(path, "utf8"));
+        }
+        return { mock: true, cid };
+    }
+    const base = normalizeGateway(STORACHA_GATEWAY_URL);
+    const url = `${base}${cid}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch CID ${cid}: ${res.status}`);
+    }
+    return res.json();
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// =============================================================================
+// TYPES
+// =============================================================================
+export {};

package/dist/ui.js

@@ -0,0 +1,127 @@
+/**
+ * UI helpers — spinners, colored output, error parsing, formatted tables.
+ */
+import ora from "ora";
+import chalk from "chalk";
+// =============================================================================
+// BRANDING
+// =============================================================================
+const BRAND = chalk.bold.magenta("📎 Paperclip");
+const DIVIDER = chalk.dim("━".repeat(50));
+export function banner() {
+    console.log();
+    console.log(DIVIDER);
+    console.log(`  ${BRAND} ${chalk.dim("Protocol CLI")}`);
+    console.log(DIVIDER);
+}
+// =============================================================================
+// SPINNERS
+// =============================================================================
+export function spin(text) {
+    return ora({ text, color: "magenta" }).start();
+}
+// =============================================================================
+// OUTPUT HELPERS
+// =============================================================================
+export function success(msg) {
+    console.log(chalk.green(`  ✅ ${msg}`));
+}
+export function info(label, value) {
+    console.log(`  ${chalk.dim(label)} ${chalk.white(String(value))}`);
+}
+export function warn(msg) {
+    console.log(chalk.yellow(`  ⚠️  ${msg}`));
+}
+export function fail(msg) {
+    console.log(chalk.red(`  ❌ ${msg}`));
+}
+export function heading(title) {
+    console.log();
+    console.log(`  ${chalk.bold(title)}`);
+    console.log(`  ${chalk.dim("─".repeat(40))}`);
+}
+export function blank() {
+    console.log();
+}
+// =============================================================================
+// TABLE
+// =============================================================================
+export function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)));
+    const sep = widths.map((w) => "─".repeat(w + 2)).join("┼");
+    const headerRow = headers
+        .map((h, i) => ` ${chalk.bold(h.padEnd(widths[i]))} `)
+        .join("│");
+    const dataRows = rows.map((r) => r.map((c, i) => ` ${String(c).padEnd(widths[i])} `).join("│"));
+    console.log(`  ${chalk.dim("┌" + widths.map((w) => "─".repeat(w + 2)).join("┬") + "┐")}`);
+    console.log(`  ${chalk.dim("│")}${headerRow}${chalk.dim("│")}`);
+    console.log(`  ${chalk.dim("├" + sep + "┤")}`);
+    for (const row of dataRows) {
+        console.log(`  ${chalk.dim("│")}${row}${chalk.dim("│")}`);
+    }
+    console.log(`  ${chalk.dim("└" + widths.map((w) => "─".repeat(w + 2)).join("┴") + "┘")}`);
+}
+// =============================================================================
+// ERROR PARSING
+// =============================================================================
+/** Known Anchor program errors from the IDL */
+const PROGRAM_ERRORS = {
+    6000: "Unauthorized — only the protocol authority can do this",
+    6001: "Task is not active",
+    6002: "Task has reached its maximum claims",
+    6003: "Math overflow",
+    6004: "Agent tier is too low for this task",
+    6005: "Complete the prerequisite task before submitting this one",
+    6006: "Invalid prerequisite account",
+    6007: "Task cannot require itself as a prerequisite",
+    6008: "Invalid invite code",
+    6009: "Invite is inactive",
+    6010: "Self-referral is not allowed",
+};
+/** System-level Solana errors */
+const SYSTEM_ERRORS = {
+    "already in use": "Account already exists — you may already be registered",
+    "insufficient funds": "Not enough SOL in your wallet to pay for the transaction",
+    AccountNotFound: "Account not found on-chain",
+};
+/**
+ * Parse a raw Anchor/Solana error into a human-readable message.
+ */
+export function parseError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const maybeLogs = err?.logs || err?.transactionLogs;
+    if (Array.isArray(maybeLogs) && maybeLogs.length > 0) {
+        const tail = maybeLogs.slice(-3).join(" | ");
+        return `${msg} Logs: ${tail}`;
+    }
+    // Check program errors (custom error code)
+    const codeMatch = msg.match(/custom program error: 0x([0-9a-fA-F]+)/);
+    if (codeMatch) {
+        const code = parseInt(codeMatch[1], 16);
+        if (code === 0) {
+            // System program error 0x0 = account already in use
+            if (msg.includes("already in use")) {
+                return "Agent already registered. Run: pc status";
+            }
+            return "Account already exists on-chain";
+        }
+        const known = PROGRAM_ERRORS[code];
+        if (known)
+            return known;
+        return `Program error 0x${codeMatch[1]} (${code})`;
+    }
+    // Check named Anchor errors
+    const anchorMatch = msg.match(/Error Code: (\w+)\. .* Error Message: (.+)\./);
+    if (anchorMatch) {
+        return anchorMatch[2];
+    }
+    // Check system-level patterns
+    for (const [pattern, human] of Object.entries(SYSTEM_ERRORS)) {
+        if (msg.toLowerCase().includes(pattern.toLowerCase())) {
+            return human;
+        }
+    }
+    // Fallback: return first meaningful line
+    const first = msg.split("\n")[0];
+    return first.length > 120 ? first.slice(0, 117) + "..." : first;
+}