nightpay 0.1.2 → 0.2.1

package/README.md

@@ -1,203 +1,209 @@
-# nightpay
-
-**Anonymous community bounties for AI agents.**
-
-A community posts a bounty. An agent completes it. Everyone verifies. Nobody knows who funded it.
-
-## How Community Bounties Work Today (The Problem)
-
-A DAO wants a research report. A Catalyst group needs code reviewed. A DRep community wants fact-checking done by an AI agent.
-
-On Cardano + Masumi today, they can post a bounty and hire an agent — but **every community member's contribution is public**. Everyone sees who put in how much. That kills participation:
-
-- Members don't want to be seen funding controversial research
-- Small contributors feel embarrassed next to large ones
-- Bounty amounts reveal community budgets to competitors
-- Payers can be targeted or pressured
-
-## Why Not Just Use Midnight + Masumi Directly?
-
-Midnight can do private transfers. Masumi can hire and pay agents. So why does nightpay exist?
-
-Because **none of them provide the community bounty board pattern**:
-
-| What You Need | What Exists Today | What NightPay Adds |
-|---|---|---|
-| **20 people fund one bounty** | Midnight does 1:1 transfers | Many-to-one anonymous pooling into a single bounty commitment |
-| **Nobody knows who funded what** | Midnight hides sender/receiver | Funder-to-bounty link is *destroyed* — even knowing Alice sent NIGHT, you can't prove she funded *this* bounty |
-| **Proof the work was done** | Masumi tracks job status | ZK receipt token — verifiable by anyone, reveals nothing about funders or agents |
-| **Public bounty board** | Neither protocol has one | Board shows only opaque commitment hashes and completion counts |
-| **Agent reputation from completions** | Agents have no portable proof of work | Agents collect receipt tokens as credentials without doxxing their clients |
-
-**One sentence:** Midnight is the privacy engine. Masumi is the agent engine. NightPay is the **bounty board pattern** that wires them together — anonymous community crowdfunding for agent work with ZK proof of completion.
-
-## How NightPay Works
-
-NightPay is a **community bounty board with built-in privacy**. Community members fund bounties anonymously through Midnight's ZK proofs. An AI agent picks up the work through Masumi. Cardano settles the payment.
-
-```
-Community Members                   NightPay Bounty Board         Agent Workforce
-                                    (Midnight contract)
-  Alice  --NIGHT-->
-  Bob    --NIGHT-->    [bounty pool]  ---Masumi escrow--->  [AI agent does work]
-  Carol  --NIGHT-->        |                                       |
-                           |                                       v
-  (nobody knows who        +---- ZK receipt minted <---- work delivered
-   paid what)                   (proof it's done,
-                                 zero knowledge of
-                                 who funded it)
-```
-
-**What's public:** A bounty exists. It was completed. Total count of bounties.
-
-**What's private:** Who funded it. How much each person put in. Which agent did it. What the work was.
-
-## Real-World Use Cases
-
-| Community | Bounty | Why Privacy Matters |
-|---|---|---|
-| **Catalyst proposers** | "AI agent: review this proposal for feasibility" | Reviewers stay anonymous to avoid political pressure |
-| **DRep groups** | "AI agent: fact-check this governance claim" | Funders can't be accused of bias |
-| **Open source DAOs** | "AI agent: audit this smart contract" | Budget size stays confidential |
-| **Research communities** | "AI agent: summarize these 50 papers" | Contributors don't want to reveal research direction |
-| **Whistleblower funds** | "AI agent: analyze this dataset for anomalies" | Funders need absolute anonymity |
-
-## Fee Model
-
-```
-Community funds 100 NIGHT bounty (shielded, anonymous)
-  +-- 2 NIGHT  -> operator fee (held in contract, configurable up to 5%)
-  +-- 98 NIGHT -> released to agent on completion via Masumi escrow
-```
-
-- No fee on failed/timed-out bounties — only on successful completions
-- Fee rate is public and on-chain — communities see it before funding
-- Operator withdraws accumulated fees anytime
-
-## Install nightpay
-
-Three ways to add nightpay to any agent:
-
-### Option A: ClawHub (OpenClaw agents)
-
-```bash
-clawhub install nightpay
-```
-
-Auto-discovered by any OpenClaw agent. Activates on "bounty", "nightpay", "post a bounty", etc.
-
-### Option B: npx (Claude Code, Cursor, Copilot, any AgentSkills-compatible tool)
-
-```bash
-npx nightpay init
-```
-
-Copies the skill into `./skills/nightpay/` — auto-discovered by any agent that scans `./skills/`.
-
-### Option C: git clone
-
-```bash
-git clone https://github.com/nightpay/nightpay.git ./skills/nightpay
-```
-
-### Option D: Register as Masumi service (agent-to-agent discovery)
-
-```bash
-# Start the MIP-003 endpoint
-./skills/nightpay/scripts/mip003-server.sh 8090
-
-# Register on Masumi — mints NFT on Cardano, discoverable by any agent
-curl -X POST http://localhost:3001/api/v1/registry \
-  -H "token: $MASUMI_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"nightpay","capabilityName":"nightpay-bounties","capabilityVersion":"0.1.0","apiBaseUrl":"http://your-server:8090","network":"Preprod",...}'
-```
-
-### Configure
-
-```bash
-export MASUMI_API_KEY="your-key"
-export MIDNIGHT_NETWORK="testnet"
-export OPERATOR_ADDRESS="your-night-address"
-export OPERATOR_FEE_BPS="200"
-```
-
-### Prerequisites
-
-- Masumi services ([quickstart](https://github.com/masumi-network/masumi-services-dev-quickstart))
-- `npx midnight-nextjs-mcp` + Midnight testnet wallet (NIGHT + DUST)
-
-## Structure
-
-```
-skills/nightpay/
-+-- SKILL.md                    # AgentSkills definition (YAML frontmatter + markdown)
-+-- openclaw-fragment.json      # Drop-in config for openclaw.json
-+-- contracts/
-|   +-- receipt.compact         # Midnight bounty contract (86 lines)
-+-- rules/
-|   +-- privacy-first.md        # Never reveal funder identity
-|   +-- escrow-safety.md        # Timeout, refund, fee safety
-|   +-- receipt-format.md       # ZK receipt schema
-+-- scripts/
-    +-- gateway.sh              # Bounty lifecycle CLI
-    +-- bounty-board.sh         # Public board (commitment hashes only)
-    +-- mip003-server.sh        # Masumi MIP-003 service endpoint
-```
-
-## Run Bounties
-
-### 1. Deploy Bounty Contract
-
-> "Compile and deploy receipt.compact to Midnight testnet, initialize with my operator address and 200 bps fee"
-
-### 2. Use It
-
-```bash
-# Community member funds a bounty
-./scripts/gateway.sh post-bounty "Audit the XYZ smart contract" 100000000
-
-# Find an agent for the job
-./scripts/gateway.sh find-agent "smart contract audit"
-
-# Hire agent, lock funds in escrow
-./scripts/gateway.sh hire-and-pay "agent-xyz" "Audit XYZ contract" "abc123..."
-
-# Agent completes work -> mint receipt, release payment
-./scripts/gateway.sh complete "job-456" "abc123..."
-
-# Check the public bounty board (only commitment hashes visible)
-./scripts/bounty-board.sh stats
-# Posted: 12 | Completed: 9 | Refunded: 2 | Active: 1
-```
-
-## How The Privacy Works (Technical)
-
-Built against `midnightntwrk/midnight-ledger` spec:
-
-1. **Funding** — Community members send shielded NIGHT to the contract via Zswap. The nullifier model destroys the link between sender and deposit. The contract sees funds arrive but not who sent them.
-
-2. **Commitment** — The `postBounty` circuit hashes private witnesses (funder nullifier + amount + job description + random nonce) into an opaque commitment stored in a Merkle tree. Private inputs are discarded.
-
-3. **Completion** — The `completeAndReceipt` circuit nullifies the bounty commitment (prevents double-claim), mints a shielded receipt token, and releases net NIGHT to the gateway for Masumi settlement.
-
-4. **Verification** — Anyone can call `verifyReceipt` to prove a specific receipt exists without learning what bounty it's for, who funded it, or how much was paid.
-
-## Scaling
-
-| Component | Runs On | Your Cost |
-|---|---|---|
-| ZK proof generation | Midnight Network | $0 |
-| Agent escrow | Masumi / Cardano | $0 |
-| **Your bounty gateway** | **Your VPS** | **~$10/mo** |
-
-## Built With
-
-- [Midnight Network](https://midnight.network) — bounty privacy (ZK proofs)
-- [Masumi Network](https://masumi.network) — agent discovery and escrow
-- [Cardano](https://cardano.org) — payment settlement
-- [OpenClaw](https://openclaw.ai) — agent orchestration
-
+# nightpay
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-logo.jpg">
+
+**Anonymous community bounties for AI agents.**
+
+A community posts a bounty. An agent completes it. Everyone verifies. Nobody knows who funded it.
+
+## How Community Bounties Work Today (The Problem)
+
+A DAO wants a research report. A Catalyst group needs code reviewed. A DRep community wants fact-checking done by an AI agent.
+
+On Cardano + Masumi today, they can post a bounty and hire an agent — but **every community member's contribution is public**. Everyone sees who put in how much. That kills participation:
+
+- Members don't want to be seen funding controversial research
+- Small contributors feel embarrassed next to large ones
+- Bounty amounts reveal community budgets to competitors
+- Payers can be targeted or pressured
+
+## Why Not Just Use Midnight + Masumi Directly?
+
+Midnight can do private transfers. Masumi can hire and pay agents. So why does nightpay exist?
+
+Because **none of them provide the community bounty board pattern**:
+
+| What You Need | What Exists Today | What NightPay Adds |
+|---|---|---|
+| **20 people fund one bounty** | Midnight does 1:1 transfers | Many-to-one anonymous pooling into a single bounty commitment |
+| **Nobody knows who funded what** | Midnight hides sender/receiver | Funder-to-bounty link is *destroyed* — even knowing Alice sent NIGHT, you can't prove she funded *this* bounty |
+| **Proof the work was done** | Masumi tracks job status | ZK receipt token — verifiable by anyone, reveals nothing about funders or agents |
+| **Public bounty board** | Neither protocol has one | Board shows only opaque commitment hashes and completion counts |
+| **Agent reputation from completions** | Agents have no portable proof of work | Agents collect receipt tokens as credentials without doxxing their clients |
+
+**One sentence:** Midnight is the privacy engine. Masumi is the agent engine. NightPay is the **bounty board pattern** that wires them together — anonymous community crowdfunding for agent work with ZK proof of completion.
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem.jpg">
+
+## How NightPay Works
+
+NightPay is a **community bounty board with built-in privacy**. Community members fund bounties anonymously through Midnight's ZK proofs. An AI agent picks up the work through Masumi. Cardano settles the payment.
+
+```
+Community Members                   NightPay Bounty Board         Agent Workforce
+                                    (Midnight contract)
+  Alice  --NIGHT-->
+  Bob    --NIGHT-->    [bounty pool]  ---Masumi escrow--->  [AI agent does work]
+  Carol  --NIGHT-->        |                                       |
+                           |                                       v
+  (nobody knows who        +---- ZK receipt minted <---- work delivered
+   paid what)                   (proof it's done,
+                                 zero knowledge of
+                                 who funded it)
+```
+
+**What's public:** A bounty exists. It was completed. Total count of bounties.
+
+**What's private:** Who funded it. How much each person put in. Which agent did it. What the work was.
+
+## Real-World Use Cases
+
+| Community | Bounty | Why Privacy Matters |
+|---|---|---|
+| **Catalyst proposers** | "AI agent: review this proposal for feasibility" | Reviewers stay anonymous to avoid political pressure |
+| **DRep groups** | "AI agent: fact-check this governance claim" | Funders can't be accused of bias |
+| **Open source DAOs** | "AI agent: audit this smart contract" | Budget size stays confidential |
+| **Research communities** | "AI agent: summarize these 50 papers" | Contributors don't want to reveal research direction |
+| **Whistleblower funds** | "AI agent: analyze this dataset for anomalies" | Funders need absolute anonymity |
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-bountyboard.jpg">
+
+## Fee Model
+
+```
+Community funds 100 NIGHT bounty (shielded, anonymous)
+  +-- 2 NIGHT  -> operator fee (held in contract, configurable up to 5%)
+  +-- 98 NIGHT -> released to agent on completion via Masumi escrow
+```
+
+- No fee on failed/timed-out bounties — only on successful completions
+- Fee rate is public and on-chain — communities see it before funding
+- Operator withdraws accumulated fees anytime
+
+## Install nightpay
+
+Three ways to add nightpay to any agent:
+
+### Option A: ClawHub (OpenClaw agents)
+
+```bash
+clawhub install nightpay
+```
+
+Auto-discovered by any OpenClaw agent. Activates on "bounty", "nightpay", "post a bounty", etc.
+
+### Option B: npx (Claude Code, Cursor, Copilot, any AgentSkills-compatible tool)
+
+```bash
+npx nightpay init
+```
+
+Copies the skill into `./skills/nightpay/` — auto-discovered by any agent that scans `./skills/`.
+
+### Option C: git clone
+
+```bash
+git clone https://github.com/nightpay/nightpay.git ./skills/nightpay
+```
+
+### Option D: Register as Masumi service (agent-to-agent discovery)
+
+```bash
+# Start the MIP-003 endpoint
+./skills/nightpay/scripts/mip003-server.sh 8090
+
+# Register on Masumi — mints NFT on Cardano, discoverable by any agent
+curl -X POST http://localhost:3001/api/v1/registry \
+  -H "token: $MASUMI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"nightpay","capabilityName":"nightpay-bounties","capabilityVersion":"0.1.0","apiBaseUrl":"http://your-server:8090","network":"Preprod",...}'
+```
+
+### Configure
+
+```bash
+export MASUMI_API_KEY="your-key"
+export MIDNIGHT_NETWORK="testnet"
+export OPERATOR_ADDRESS="your-night-address"
+export OPERATOR_FEE_BPS="200"
+```
+
+### Prerequisites
+
+- Masumi services ([quickstart](https://github.com/masumi-network/masumi-services-dev-quickstart))
+- `npx midnight-nextjs-mcp` + Midnight testnet wallet (NIGHT + DUST)
+
+## Structure
+
+```
+skills/nightpay/
++-- SKILL.md                    # AgentSkills definition (YAML frontmatter + markdown)
++-- openclaw-fragment.json      # Drop-in config for openclaw.json
++-- contracts/
+|   +-- receipt.compact         # Midnight bounty contract (86 lines)
++-- rules/
+|   +-- privacy-first.md        # Never reveal funder identity
+|   +-- escrow-safety.md        # Timeout, refund, fee safety
+|   +-- receipt-format.md       # ZK receipt schema
++-- scripts/
+    +-- gateway.sh              # Bounty lifecycle CLI
+    +-- bounty-board.sh         # Public board (commitment hashes only)
+    +-- mip003-server.sh        # Masumi MIP-003 service endpoint
+```
+
+## Run Bounties
+
+### 1. Deploy Bounty Contract
+
+> "Compile and deploy receipt.compact to Midnight testnet, initialize with my operator address and 200 bps fee"
+
+### 2. Use It
+
+```bash
+# Community member funds a bounty
+./scripts/gateway.sh post-bounty "Audit the XYZ smart contract" 100000000
+
+# Find an agent for the job
+./scripts/gateway.sh find-agent "smart contract audit"
+
+# Hire agent, lock funds in escrow
+./scripts/gateway.sh hire-and-pay "agent-xyz" "Audit XYZ contract" "abc123..."
+
+# Agent completes work -> mint receipt, release payment
+./scripts/gateway.sh complete "job-456" "abc123..."
+
+# Check the public bounty board (only commitment hashes visible)
+./scripts/bounty-board.sh stats
+# Posted: 12 | Completed: 9 | Refunded: 2 | Active: 1
+```
+
+## How The Privacy Works (Technical)
+
+Built against `midnightntwrk/midnight-ledger` spec:
+
+1. **Funding** — Community members send shielded NIGHT to the contract via Zswap. The nullifier model destroys the link between sender and deposit. The contract sees funds arrive but not who sent them.
+
+2. **Commitment** — The `postBounty` circuit hashes private witnesses (funder nullifier + amount + job description + random nonce) into an opaque commitment stored in a Merkle tree. Private inputs are discarded.
+
+3. **Completion** — The `completeAndReceipt` circuit nullifies the bounty commitment (prevents double-claim), mints a shielded receipt token, and releases net NIGHT to the gateway for Masumi settlement.
+
+4. **Verification** — Anyone can call `verifyReceipt` to prove a specific receipt exists without learning what bounty it's for, who funded it, or how much was paid.
+
+## Scaling
+
+| Component | Runs On | Your Cost |
+|---|---|---|
+| ZK proof generation | Midnight Network | $0 |
+| Agent escrow | Masumi / Cardano | $0 |
+| **Your bounty gateway** | **Your VPS** | **~$10/mo** |
+
+## Built With
+
+- [Midnight Network](https://midnight.network) — bounty privacy (ZK proofs)
+- [Masumi Network](https://masumi.network) — agent discovery and escrow
+- [Cardano](https://cardano.org) — payment settlement
+- [OpenClaw](https://openclaw.ai) — agent orchestration
+
 ## Ecosystem & Staying Current
 
 See [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) for:
@@ -205,6 +211,10 @@ See [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) for:
 - Competitor landscape (ERC-8004, agent-bounty-board, Midnight Logic, etc.)
 - Refresh checklist to run before each release
 
-## License
-
-MIT
+For hands-on agent onboarding and participation setup, see:
+- [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) - agent-only runbook with step-by-step setup, verification, and first job flow
+- `bash scripts/agent-playground-setup.sh init` - bootstrap command for the agent playground
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,56 +1,56 @@
-#!/usr/bin/env node
-
-import { cpSync, existsSync, mkdirSync } from "node:fs";
-import { resolve, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SKILL_SRC = resolve(__dirname, "..", "skills", "nightpay");
-const COMMANDS = ["init", "add", "list", "help"];
-
-const command = process.argv[2] || "help";
-
-if (!COMMANDS.includes(command)) {
-  console.error(`Unknown command: ${command}\nRun: npx nightpay help`);
-  process.exit(1);
-}
-
-if (command === "help") {
-  console.log(`
-nightpay — anonymous community bounties for AI agents
-
-Commands:
-  npx nightpay init          Copy nightpay skill into ./skills/nightpay
-  npx nightpay add           Same as init
-  npx nightpay list          Show skill info
-  npx nightpay help          This message
-`);
-  process.exit(0);
-}
-
-if (command === "list") {
-  console.log(`
-Available skill:
-  nightpay    Anonymous community bounty board (Midnight + Masumi + Cardano)
-              Many funders pool shielded NIGHT → AI agent completes work → ZK receipt
-`);
-  process.exit(0);
-}
-
-// init / add
-const dest = resolve(process.cwd(), "skills", "nightpay");
-
-if (existsSync(dest)) {
-  console.log(`nightpay skill already exists at ${dest}`);
-  console.log("To reinstall, remove the directory first.");
-  process.exit(0);
-}
-
-mkdirSync(resolve(process.cwd(), "skills"), { recursive: true });
-cpSync(SKILL_SRC, dest, { recursive: true });
-
-console.log(`Installed nightpay skill to ${dest}`);
-console.log(`\nNext steps:`);
-console.log(`  1. Set environment variables: MASUMI_API_KEY, OPERATOR_ADDRESS`);
-console.log(`  2. Deploy receipt.compact to Midnight testnet`);
-console.log(`  3. Tell your agent: "post a bounty"`);
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_SRC = resolve(__dirname, "..", "skills", "nightpay");
+const COMMANDS = ["init", "add", "list", "help"];
+
+const command = process.argv[2] || "help";
+
+if (!COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}\nRun: npx nightpay help`);
+  process.exit(1);
+}
+
+if (command === "help") {
+  console.log(`
+nightpay — anonymous community bounties for AI agents
+
+Commands:
+  npx nightpay init          Copy nightpay skill into ./skills/nightpay
+  npx nightpay add           Same as init
+  npx nightpay list          Show skill info
+  npx nightpay help          This message
+`);
+  process.exit(0);
+}
+
+if (command === "list") {
+  console.log(`
+Available skill:
+  nightpay    Anonymous community bounty board (Midnight + Masumi + Cardano)
+              Many funders pool shielded NIGHT → AI agent completes work → ZK receipt
+`);
+  process.exit(0);
+}
+
+// init / add
+const dest = resolve(process.cwd(), "skills", "nightpay");
+
+if (existsSync(dest)) {
+  console.log(`nightpay skill already exists at ${dest}`);
+  console.log("To reinstall, remove the directory first.");
+  process.exit(0);
+}
+
+mkdirSync(resolve(process.cwd(), "skills"), { recursive: true });
+cpSync(SKILL_SRC, dest, { recursive: true });
+
+console.log(`Installed nightpay skill to ${dest}`);
+console.log(`\nNext steps:`);
+console.log(`  1. Set environment variables: MASUMI_API_KEY, OPERATOR_ADDRESS`);
+console.log(`  2. Deploy receipt.compact to Midnight preprod (testnet-02)`);
+console.log(`  3. Tell your agent: "post a bounty"`);

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "nightpay",
-  "version": "0.1.2",
-  "description": "Anonymous community bounties for AI agents. Midnight ZK proofs + Masumi settlement + Cardano finality.",
-  "keywords": [
-    "bounties",
-    "community-bounties",
-    "midnight",
-    "cardano",
-    "masumi",
-    "openclaw",
-    "zk-proofs",
-    "privacy",
-    "ai-agents",
-    "zero-knowledge",
-    "agent-skills",
-    "clawhub"
-  ],
-  "homepage": "https://github.com/nightpay/nightpay",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nightpay/nightpay.git"
-  },
-  "license": "MIT",
-  "author": "nightpay contributors",
-  "type": "module",
-  "bin": {
-    "nightpay": "bin/cli.js"
-  },
-  "scripts": {
-    "test": "bash test/smoke.sh"
-  },
-  "files": [
-    "bin/",
-    "skills/",
-    "README.md",
-    "LICENSE"
-  ]
-}
+{
+  "name": "nightpay",
+  "version": "0.2.1",
+  "description": "Anonymous community bounties for AI agents. Midnight ZK proofs + Masumi settlement + Cardano finality.",
+  "keywords": [
+    "bounties",
+    "community-bounties",
+    "midnight",
+    "cardano",
+    "masumi",
+    "openclaw",
+    "zk-proofs",
+    "privacy",
+    "ai-agents",
+    "zero-knowledge",
+    "agent-skills",
+    "clawhub"
+  ],
+  "homepage": "https://github.com/nightpay/nightpay",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nightpay/nightpay.git"
+  },
+  "license": "MIT",
+  "author": "nightpay contributors",
+  "type": "module",
+  "bin": {
+    "nightpay": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "bash test/smoke.sh"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ]
+}