nightpay 0.1.0 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/LICENSE +666 -21
  2. package/README.md +99 -158
  3. package/bin/cli.js +527 -24
  4. package/nightpay_sdk.py +398 -0
  5. package/openclaw.plugin.json +10 -0
  6. package/package.json +18 -7
  7. package/plugin.js +712 -0
  8. package/skills/nightpay/AGENTS.md +302 -0
  9. package/skills/nightpay/HEARTBEAT.md +55 -0
  10. package/skills/nightpay/SKILL.md +420 -61
  11. package/skills/nightpay/contracts/receipt.compact +358 -97
  12. package/skills/nightpay/contracts/receipt.stub.compact +55 -0
  13. package/skills/nightpay/ontology/context.jsonld +179 -0
  14. package/skills/nightpay/ontology/examples/job-delegation.example.jsonld +50 -0
  15. package/skills/nightpay/ontology/examples/pool-funded.example.jsonld +31 -0
  16. package/skills/nightpay/ontology/examples/receipt-credential.example.jsonld +33 -0
  17. package/skills/nightpay/ontology/ontology.jsonld +396 -0
  18. package/skills/nightpay/ontology/ontology.md +243 -0
  19. package/skills/nightpay/openclaw-fragment.json +16 -33
  20. package/skills/nightpay/rules/escrow-safety.md +62 -0
  21. package/skills/nightpay/rules/privacy-first.md +21 -0
  22. package/skills/nightpay/scripts/gateway.sh +962 -66
  23. package/skills/nightpay/scripts/mip003-server.sh +4739 -93
package/README.md CHANGED
@@ -1,210 +1,151 @@
1
- # nightpay
1
+ # NightPay
2
2
 
3
- **Anonymous community bounties for AI agents.**
3
+ <img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-logo.jpg">
4
4
 
5
- A community posts a bounty. An agent completes it. Everyone verifies. Nobody knows who funded it.
5
+ [![npm version](https://img.shields.io/npm/v/nightpay)](https://www.npmjs.com/package/nightpay)
6
6
 
7
- ## How Community Bounties Work Today (The Problem)
7
+ > Built on the [Midnight Network](https://midnight.network).
8
8
 
9
- A DAO wants a research report. A Catalyst group needs code reviewed. A DRep community wants fact-checking done by an AI agent.
9
+ Privacy-preserving bounty pools for AI agents. Funders back a pool anonymously via Midnight ZK proofs — if the goal is met an agent gets hired via Masumi and paid on Cardano. If not, everyone gets a full refund.
10
10
 
11
- 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:
11
+ ## Install
12
12
 
13
- - Members don't want to be seen funding controversial research
14
- - Small contributors feel embarrassed next to large ones
15
- - Bounty amounts reveal community budgets to competitors
16
- - Payers can be targeted or pressured
13
+ ### OpenClaw (primary)
17
14
 
18
- ## Why Not Just Use Midnight + Masumi Directly?
19
-
20
- Midnight can do private transfers. Masumi can hire and pay agents. So why does nightpay exist?
21
-
22
- Because **none of them provide the community bounty board pattern**:
23
-
24
- | What You Need | What Exists Today | What NightPay Adds |
25
- |---|---|---|
26
- | **20 people fund one bounty** | Midnight does 1:1 transfers | Many-to-one anonymous pooling into a single bounty commitment |
27
- | **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 |
28
- | **Proof the work was done** | Masumi tracks job status | ZK receipt token — verifiable by anyone, reveals nothing about funders or agents |
29
- | **Public bounty board** | Neither protocol has one | Board shows only opaque commitment hashes and completion counts |
30
- | **Agent reputation from completions** | Agents have no portable proof of work | Agents collect receipt tokens as credentials without doxxing their clients |
31
-
32
- **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.
33
-
34
- ## How NightPay Works
35
-
36
- 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.
37
-
38
- ```
39
- Community Members NightPay Bounty Board Agent Workforce
40
- (Midnight contract)
41
- Alice --NIGHT-->
42
- Bob --NIGHT--> [bounty pool] ---Masumi escrow---> [AI agent does work]
43
- Carol --NIGHT--> | |
44
- | v
45
- (nobody knows who +---- ZK receipt minted <---- work delivered
46
- paid what) (proof it's done,
47
- zero knowledge of
48
- who funded it)
49
- ```
50
-
51
- **What's public:** A bounty exists. It was completed. Total count of bounties.
52
-
53
- **What's private:** Who funded it. How much each person put in. Which agent did it. What the work was.
54
-
55
- ## Real-World Use Cases
56
-
57
- | Community | Bounty | Why Privacy Matters |
58
- |---|---|---|
59
- | **Catalyst proposers** | "AI agent: review this proposal for feasibility" | Reviewers stay anonymous to avoid political pressure |
60
- | **DRep groups** | "AI agent: fact-check this governance claim" | Funders can't be accused of bias |
61
- | **Open source DAOs** | "AI agent: audit this smart contract" | Budget size stays confidential |
62
- | **Research communities** | "AI agent: summarize these 50 papers" | Contributors don't want to reveal research direction |
63
- | **Whistleblower funds** | "AI agent: analyze this dataset for anomalies" | Funders need absolute anonymity |
64
-
65
- ## Fee Model
66
-
67
- ```
68
- Community funds 100 NIGHT bounty (shielded, anonymous)
69
- +-- 2 NIGHT -> operator fee (held in contract, configurable up to 5%)
70
- +-- 98 NIGHT -> released to agent on completion via Masumi escrow
15
+ ```bash
16
+ openclaw plugins install nightpay
17
+ openclaw plugins enable nightpay
71
18
  ```
72
19
 
73
- - No fee on failed/timed-out bounties — only on successful completions
74
- - Fee rate is public and on-chain — communities see it before funding
75
- - Operator withdraws accumulated fees anytime
76
-
77
- ## Install nightpay
78
-
79
- Three ways to add nightpay to any agent:
80
-
81
- ### Option A: ClawHub (OpenClaw agents)
20
+ Set credentials:
82
21
 
83
22
  ```bash
84
- clawhub install nightpay
23
+ openclaw config set skills.entries.nightpay.env.MASUMI_API_KEY "your-key"
24
+ openclaw config set skills.entries.nightpay.env.OPERATOR_ADDRESS "64-char-hex"
25
+ openclaw config set skills.entries.nightpay.env.BRIDGE_URL "https://bridge.nightpay.dev"
26
+ openclaw gateway restart
85
27
  ```
86
28
 
87
- Auto-discovered by any OpenClaw agent. Activates on "bounty", "nightpay", "post a bounty", etc.
29
+ Verify: `/nightpay status` in your connected channel.
88
30
 
89
- ### Option B: npx (Claude Code, Cursor, Copilot, any AgentSkills-compatible tool)
31
+ ### Other platforms
90
32
 
91
33
  ```bash
92
- npx nightpay init
34
+ npx nightpay setup # auto-detects platform (Claude Code, Cursor, Copilot, raw)
93
35
  ```
94
36
 
95
- Copies the skill into `./skills/nightpay/` — auto-discovered by any agent that scans `./skills/`.
37
+ ## How It Works
96
38
 
97
- ### Option C: git clone
39
+ 1. **Create a pool** — set a funding goal, contribution amount, and max funders
40
+ 2. **Funders back it anonymously** — shielded NIGHT via ZK nullifiers (identity unrecoverable)
41
+ 3. **Goal met → pool activates** — an AI agent is hired via Masumi MIP-003
42
+ 4. **Goal not met → full refund** — 100% returned, no fee
43
+ 5. **Work done → ZK receipt** — verifiable proof of completion, reveals nothing about funders
98
44
 
99
- ```bash
100
- git clone https://github.com/nightpay/nightpay.git ./skills/nightpay
101
45
  ```
102
-
103
- ### Option D: Register as Masumi service (agent-to-agent discovery)
104
-
105
- ```bash
106
- # Start the MIP-003 endpoint
107
- ./skills/nightpay/scripts/mip003-server.sh 8090
108
-
109
- # Register on Masumi — mints NFT on Cardano, discoverable by any agent
110
- curl -X POST http://localhost:3001/api/v1/registry \
111
- -H "token: $MASUMI_API_KEY" \
112
- -H "Content-Type: application/json" \
113
- -d '{"name":"nightpay","capabilityName":"nightpay-bounties","capabilityVersion":"0.1.0","apiBaseUrl":"http://your-server:8090","network":"Preprod",...}'
46
+ Pool Creator NightPay Contract Masumi / Cardano
47
+ | | |
48
+ |-- createPool -------->| |
49
+ Funders (anonymous) | |
50
+ |-- fundPool (× N) ---->| |
51
+ | goal met? -----+ |
52
+ | / \ |
53
+ | yes no (deadline) |
54
+ | | \ |
55
+ | activatePool claimRefund (100% back) |
56
+ | |-- hire agent ------------------------->|
57
+ | |<-- work delivered ---------------------|
58
+ | |-- ZK receipt (verifiable, anonymous) --|
114
59
  ```
115
60
 
116
- ### Configure
61
+ **Public:** pool exists, goal, completion status.
62
+ **Private:** who funded, how much, which agent.
63
+
64
+ ## Usage
117
65
 
118
66
  ```bash
119
- export MASUMI_API_KEY="your-key"
120
- export MIDNIGHT_NETWORK="testnet"
121
- export OPERATOR_ADDRESS="your-night-address"
122
- export OPERATOR_FEE_BPS="200"
67
+ # Pool lifecycle
68
+ bash skills/nightpay/scripts/gateway.sh stats
69
+ bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ" 10000000 50000000
70
+ bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
71
+ bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
72
+ bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> "Audit XYZ" <commitment_hash>
73
+
74
+ # Browse public bounties
75
+ bash skills/nightpay/scripts/bounty-board.sh stats
123
76
  ```
124
77
 
125
- ### Prerequisites
78
+ ### Python SDK
126
79
 
127
- - Masumi services ([quickstart](https://github.com/masumi-network/masumi-services-dev-quickstart))
128
- - `npx midnight-nextjs-mcp` + Midnight testnet wallet (NIGHT + DUST)
80
+ ```python
81
+ from nightpay_sdk import NightPay
129
82
 
130
- ## Structure
131
-
132
- ```
133
- skills/nightpay/
134
- +-- SKILL.md # AgentSkills definition (YAML frontmatter + markdown)
135
- +-- openclaw-fragment.json # Drop-in config for openclaw.json
136
- +-- contracts/
137
- | +-- receipt.compact # Midnight bounty contract (86 lines)
138
- +-- rules/
139
- | +-- privacy-first.md # Never reveal funder identity
140
- | +-- escrow-safety.md # Timeout, refund, fee safety
141
- | +-- receipt-format.md # ZK receipt schema
142
- +-- scripts/
143
- +-- gateway.sh # Bounty lifecycle CLI
144
- +-- bounty-board.sh # Public board (commitment hashes only)
145
- +-- mip003-server.sh # Masumi MIP-003 service endpoint
83
+ np = NightPay()
84
+ np.validate() # health check
85
+ np.stats() # contract stats
86
+ np.post_bounty("Review this PR", 5000)
87
+ np.find_agent("code review")
146
88
  ```
147
89
 
148
- ## Run Bounties
149
-
150
- ### 1. Deploy Bounty Contract
151
-
152
- > "Compile and deploy receipt.compact to Midnight testnet, initialize with my operator address and 200 bps fee"
153
-
154
- ### 2. Use It
90
+ ## Configuration
155
91
 
156
92
  ```bash
157
- # Community member funds a bounty
158
- ./scripts/gateway.sh post-bounty "Audit the XYZ smart contract" 100000000
93
+ # Required
94
+ MASUMI_API_KEY=your-key
95
+ OPERATOR_ADDRESS=<64-char-hex>
96
+ NIGHTPAY_API_URL=https://api.nightpay.dev
97
+ BRIDGE_URL=https://bridge.nightpay.dev
98
+ ```
159
99
 
160
- # Find an agent for the job
161
- ./scripts/gateway.sh find-agent "smart contract audit"
100
+ Full config reference → [`docs/CONFIG.md`](docs/CONFIG.md)
162
101
 
163
- # Hire agent, lock funds in escrow
164
- ./scripts/gateway.sh hire-and-pay "agent-xyz" "Audit XYZ contract" "abc123..."
102
+ ## Trust Model
165
103
 
166
- # Agent completes work -> mint receipt, release payment
167
- ./scripts/gateway.sh complete "job-456" "abc123..."
104
+ The Midnight ZK contract enforces:
168
105
 
169
- # Check the public bounty board (only commitment hashes visible)
170
- ./scripts/bounty-board.sh stats
171
- # Posted: 12 | Completed: 9 | Refunded: 2 | Active: 1
172
- ```
106
+ - **Fee is immutable** — `operatorFeeBps` set once at deploy, max 5%
107
+ - **No double-funding/refund** — nullifier set rejects duplicates
108
+ - **No fund theft** — contract only releases to the locked gateway address
109
+ - **Receipts are verifiable** — `verifyReceipt()` is public
110
+ - **Emergency exit** — `emergencyRefund` bypasses gateway after 500+ contract txs
173
111
 
174
- ## How The Privacy Works (Technical)
112
+ The gateway handles deadlines, activation, and agent selection — but cannot steal funds, change fees, or fake receipts.
175
113
 
176
- Built against `midnightntwrk/midnight-ledger` spec:
114
+ See [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) for the full trust checklist.
177
115
 
178
- 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.
116
+ ## Platform Support
179
117
 
180
- 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.
118
+ | Platform | Install |
119
+ |----------|---------|
120
+ | **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` |
121
+ | **Claude Code** | `npx nightpay setup` |
122
+ | **Cursor** | `npx nightpay setup` |
123
+ | **Copilot** | `npx nightpay setup` |
124
+ | **Raw API** | `npx nightpay init` + env vars |
181
125
 
182
- 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.
126
+ Full matrix → [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md)
183
127
 
184
- 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.
128
+ ## Documentation
185
129
 
186
- ## Scaling
187
-
188
- | Component | Runs On | Your Cost |
189
- |---|---|---|
190
- | ZK proof generation | Midnight Network | $0 |
191
- | Agent escrow | Masumi / Cardano | $0 |
192
- | **Your bounty gateway** | **Your VPS** | **~$10/mo** |
130
+ | Document | Description |
131
+ |----------|-------------|
132
+ | [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Tool manifest — commands, config, trust model |
133
+ | [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, boundaries, decision trees |
134
+ | [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Lifecycle, contest mode, worked examples |
135
+ | [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
136
+ | [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md) | Full OpenClaw setup guide |
137
+ | [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) | Feature availability across platforms |
193
138
 
194
139
  ## Built With
195
140
 
196
- - [Midnight Network](https://midnight.network) — bounty privacy (ZK proofs)
197
- - [Masumi Network](https://masumi.network) — agent discovery and escrow
141
+ - [Midnight Network](https://midnight.network) — ZK privacy layer
142
+ - [Masumi Network](https://masumi.network) — agent discovery + escrow
198
143
  - [Cardano](https://cardano.org) — payment settlement
199
144
  - [OpenClaw](https://openclaw.ai) — agent orchestration
200
145
 
201
- ## Ecosystem & Staying Current
202
-
203
- See [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) for:
204
- - Tracked repos across Midnight, Masumi, and OpenClaw with known breaking changes
205
- - Competitor landscape (ERC-8004, agent-bounty-board, Midnight Logic, etc.)
206
- - Refresh checklist to run before each release
207
-
208
146
  ## License
209
147
 
210
- MIT
148
+ Dual-licensed:
149
+
150
+ - **Open-source:** [AGPL-3.0](https://github.com/nightpay/nightpay/blob/master/LICENSE)
151
+ - **Commercial:** Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)