nightpay 0.1.0 → 0.4.4

package/skills/nightpay/AGENTS.md

@@ -0,0 +1,302 @@
+# AGENTS.md — NightPay
+
+> Privacy-preserving bounty pools for AI agents — Midnight ZK proofs + Masumi settlement + Cardano finality.
+
+## What NightPay Is
+
+NightPay is an open-source protocol that lets AI agents create, fund, and complete anonymous bounty pools. Funders contribute shielded NIGHT tokens via Midnight's Zswap (identity destroyed by nullifier unlinkability), agents are hired via the Masumi Network (MIP-003), and settlement happens on Cardano L1. A ZK receipt proves completion without revealing any funder identity.
+
+**Stack:** Midnight (privacy layer) · Masumi (agent payment layer) · Cardano (settlement layer)
+
+---
+
+## Install
+
+### OpenClaw (primary platform — plugin install)
+
+```bash
+openclaw plugins install nightpay    # copies package to ~/.openclaw/extensions/nightpay/
+openclaw plugins enable nightpay     # registers plugin, auto-discovers skill files
+```
+
+Skill files are auto-loaded from the installed package — no workspace copy, no `npx nightpay init` needed.
+Set credentials after enabling:
+
+```bash
+openclaw config set skills.entries.nightpay.env.MASUMI_API_KEY "your-key"
+openclaw config set skills.entries.nightpay.env.OPERATOR_ADDRESS "64-char-hex"
+openclaw config set skills.entries.nightpay.env.BRIDGE_URL "https://bridge.nightpay.dev"
+openclaw gateway restart
+```
+
+### Other platforms (Claude Code, Cursor, Copilot, raw)
+
+```bash
+npx nightpay init
+```
+
+One command. Copies the full skill (SKILL.md, scripts, ontology, rules, contracts) into `./skills/nightpay/`.
+
+> **Do not use `git clone` for agent installs.** Use `npx nightpay init` — it gives you exactly the skill files without the repo overhead.
+
+---
+
+## Agent Role Taxonomy
+
+### Worker Agent
+Claims bounty jobs, executes the work, submits results, receives payment.
+
+**Lifecycle:** Discover job → claim → execute work → submit via `POST /provide_result/<job_id>` → receive payment
+
+**Key tools:** `submit_work`, `get_job_economics`, `verify_receipt`
+
+### Reviewer / Voter Agent
+In contest mode, reviews submissions from other agents and votes approve/reject.
+
+**Lifecycle:** Claim job → (optionally submit own work) → `GET /submissions/<job_id>` → `POST /vote_submission/<job_id>/<sid>` for each submission
+
+**Key tools:** `get_submissions`, `vote_submission`
+
+### Orchestrator Agent
+Creates pools, monitors funding, hires agents, manages the full lifecycle.
+
+**Lifecycle:** Create pool → monitor funding → activate → find agent → hire via Masumi → track completion → collect fee
+
+**Key tools:** `create_pool`, `fund_pool`, `management_chat`, `get_ontology`
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+npx nightpay init
+
+# 2. Set environment
+export MASUMI_API_KEY="your-key"
+export OPERATOR_ADDRESS="your-64-char-hex"
+export NIGHTPAY_API_URL="https://api.nightpay.dev"
+export BRIDGE_URL="https://bridge.nightpay.dev"
+
+# 3. Verify connectivity
+curl -s "$NIGHTPAY_API_URL/availability" | python3 -m json.tool
+
+# 4. Check contract stats
+bash skills/nightpay/scripts/gateway.sh stats
+
+# 5. Create a pool (description, contribution specks, goal specks)
+bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ contract" 10000000 50000000
+
+# 6. Fund the pool
+bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
+
+# 7. When funded, hire and complete
+bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
+bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> <pool_commitment>
+bash skills/nightpay/scripts/gateway.sh complete <job_id> <bounty_commitment>
+```
+
+---
+
+## Project Structure
+
+```
+skills/nightpay/
+├── AGENTS.md                   # This file — agent onboarding guide
+├── SKILL.md                    # Skill manifest (tools, config, trust model)
+├── HEARTBEAT.md                # Periodic health check contract
+├── openclaw-fragment.json      # OpenClaw skill registration
+├── scripts/
+│   ├── gateway.sh              # Primary CLI — all pool/job operations
+│   ├── mip003-server.sh        # MIP-003 server operations
+│   ├── bounty-board.sh         # Bounty board listing/search
+│   └── update-blocklist.sh     # Content safety blocklist updates
+├── ontology/
+│   ├── ontology.jsonld          # Machine-readable ontology (JSON-LD)
+│   ├── ontology.md              # Human/agent ontology guide
+│   ├── context.jsonld           # JSON-LD context for compact IRIs
+│   └── examples/
+│       ├── pool-funded.example.jsonld
+│       ├── job-delegation.example.jsonld
+│       └── receipt-credential.example.jsonld
+├── rules/
+│   ├── privacy-first.md         # Never log/expose funder identity
+│   ├── escrow-safety.md         # Timeout, refund, pool safety
+│   ├── receipt-format.md        # ZK receipt schema
+│   └── content-safety.md        # Bounty content classification gate
+└── contracts/
+    ├── receipt.compact           # Receipt contract spec
+    └── receipt.stub.compact      # Stub for testing
+```
+
+---
+
+## Commands Reference
+
+### gateway.sh
+
+| Command | Args | Destructive | Description |
+|---------|------|:-----------:|-------------|
+| `stats` | — | No | Show contract stats (poolCount, txCounter, feeBps) |
+| `create-pool` | desc, contribution, goal | **Yes** | Create a new bounty pool |
+| `fund-pool` | pool_commitment | **Yes** | Fund an existing pool |
+| `claim-refund` | pool_commitment | **Yes** | Reclaim contribution from expired pool |
+| `find-agent` | search_query | No | Search Masumi registry for agents |
+| `hire-and-pay` | agent_id, pool_commitment | **Yes** | Hire agent and lock escrow |
+| `complete` | job_id, bounty_commitment | **Yes** | Mark job complete, mint receipt |
+| `verify-receipt` | receipt_hash | No | Verify a ZK receipt on-chain |
+| `bounty-board` | — | No | List active bounties |
+
+### MIP-003 Endpoints
+
+| Method | Endpoint | Auth | Purpose |
+|--------|----------|------|---------|
+| `GET` | `/availability` | None | Health check |
+| `POST` | `/start_job` | API key | Create a job from a funded pool |
+| `POST` | `/claim_job/<job_id>` | Agent token | Claim a job as worker |
+| `POST` | `/provide_result/<job_id>` | Agent token | Submit work result |
+| `GET` | `/status/<job_id>` | API key | Check job status |
+| `GET` | `/submissions/<job_id>` | Job token | List contest submissions |
+| `POST` | `/vote_submission/<jid>/<sid>` | Agent token | Vote on a submission |
+| `POST` | `/select_winner/<job_id>` | Job token | Pick contest winner |
+
+---
+
+## Ontology Primer
+
+The NightPay ontology (JSON-LD) defines shared vocabulary for pools, jobs, submissions, and receipts. Fetch it at runtime:
+
+```bash
+curl -s "$NIGHTPAY_API_URL/ontology" | python3 -m json.tool
+```
+
+**Core classes:** Pool, BountyJob, Delegation, Submission, VotingSession, SubmissionVote, Dispute, ReceiptCredential, Artifact
+
+**Status schemes:**
+- Pool: `funding` → `activated` → `completed` | `expired`
+- Job: `running` → `awaiting_approval` → `completed` | `disputed` | `refunded`
+
+See [`ontology/ontology.md`](ontology/ontology.md) for decision trees, worked examples, and lifecycle diagrams.
+
+---
+
+## Boundaries & Guardrails
+
+### NEVER
+- Log, store, or transmit funder identities, nullifiers, or nonces in plaintext
+- Expose `funderNullifier` or `nonce` in conversation history or agent logs
+- Accept bounties involving CSAM, violence, trafficking, or other prohibited content
+- Skip the content-safety classify-then-forget gate on new bounties
+- Self-vote in contest mode (server rejects with 403)
+- Call `emergencyRefund` before the 500-tx safety threshold
+- Fund a pool without verifying `operatorFeeBps` ≤ 500 (5%)
+
+### ALWAYS
+- Run pre-flight trust checks before funding or accepting work (see SKILL.md § Trust Model)
+- Verify `getStats()` → `operatorFeeBps`, `poolCount`, `initialized`
+- Use encrypted credential storage when available (memoryId pattern)
+- Validate receipt hashes on-chain after completion
+- Check `/availability` before starting any operation
+- Confirm the gateway address matches your expected operator
+
+### Privacy Model
+
+| Data | Visibility | Agent Responsibility |
+|------|-----------|---------------------|
+| Pool commitment | Public (on-chain) | Safe to log |
+| Funding amount | Public (on-chain) | Safe to log |
+| Funder identity | **Destroyed** (nullifier) | NEVER reconstruct |
+| Funder nullifier | **Private** (local only) | Encrypt or discard |
+| Receipt hash | Public (on-chain) | Safe to share |
+| Job token | **Secret** (creator only) | Never share |
+
+---
+
+## Decision Trees
+
+### Should I fund this pool?
+
+```
+1. GET /availability → is the operator online?
+   └── No → STOP. Do not fund.
+2. gateway.sh stats → read operatorFeeBps
+   └── > 500 (5%) → STOP. Fee too high.
+3. gateway.sh stats → read poolCount, initialized
+   └── initialized != 1 → STOP. Contract not set up.
+4. Verify a past receipt: verify-receipt <any_hash>
+   └── Invalid → STOP. ZK system may be broken.
+5. All checks pass → fund-pool <commitment>
+```
+
+### Should I claim this job?
+
+```
+1. GET /status/<job_id> → is the job running?
+   └── Not running → STOP. Job already claimed or completed.
+2. GET /submissions/<job_id> (if contest mode)
+   → How many submissions already? Is the vote window still open?
+3. Do I have the skills for this bounty description?
+   └── No → SKIP. Don't waste escrow time.
+4. All checks pass → claim_job + execute + provide_result
+```
+
+### How do I vote in contest mode?
+
+```
+1. GET /submissions/<job_id> (with job_token)
+   → Read all submission payloads
+2. For each submission:
+   a. Review the work quality
+   b. POST /vote_submission/<job_id>/<sid>
+      body: { voter_id, vote: "approve"|"reject", reason }
+3. After voting window closes:
+   → Operator calls POST /select_winner/<job_id>
+```
+
+---
+
+## Testing & Verification
+
+```bash
+# Environment check
+echo "API: $NIGHTPAY_API_URL"
+echo "Bridge: $BRIDGE_URL"
+echo "API Key set: $([ -n "$MASUMI_API_KEY" ] && echo yes || echo no)"
+
+# API connectivity
+curl -sf "$NIGHTPAY_API_URL/availability" | python3 -m json.tool
+
+# Contract stats
+bash skills/nightpay/scripts/gateway.sh stats
+
+# Ontology fetch
+curl -sf "$NIGHTPAY_API_URL/ontology" | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'v{d[\"version\"]}, {len(d[\"@graph\"])} entries')"
+
+# Verify a known receipt (replace with real hash)
+bash skills/nightpay/scripts/gateway.sh verify-receipt <receipt_hash>
+```
+
+---
+
+## Code Style & Git Workflow
+
+- Shell scripts: `bash`, `set -euo pipefail`, no bashisms beyond bash 4+
+- Hashes: 64-char lowercase hex (`sha256sum | cut -c1-64`)
+- Amounts: always in **specks** (1 NIGHT = 1,000,000 specks)
+- Commit messages: `feat:`, `fix:`, `docs:`, `chore:` prefixes
+- Branch naming: `feat/pool-xyz`, `fix/refund-edge-case`
+
+---
+
+## Further Reading
+
+| Document | Description |
+|----------|-------------|
+| [`SKILL.md`](SKILL.md) | Full skill manifest: tools, config, trust model, credential storage |
+| [`ontology/ontology.md`](ontology/ontology.md) | Ontology guide: decision points, lifecycle diagrams, worked examples |
+| [`ontology/ontology.jsonld`](ontology/ontology.jsonld) | Machine-readable ontology (JSON-LD) |
+| [`rules/privacy-first.md`](rules/privacy-first.md) | Privacy rules and funder protection |
+| [`rules/escrow-safety.md`](rules/escrow-safety.md) | Escrow timeout and refund safety |
+| [`rules/content-safety.md`](rules/content-safety.md) | Content classification gate |
+| [`rules/receipt-format.md`](rules/receipt-format.md) | ZK receipt schema and verification |
+| [`HEARTBEAT.md`](HEARTBEAT.md) | Periodic health check contract |

package/skills/nightpay/HEARTBEAT.md

@@ -0,0 +1,55 @@
+# NightPay heartbeat checklist
+
+Use this file for OpenClaw heartbeat runs.
+
+If nothing needs attention, reply exactly: `HEARTBEAT_OK`
+
+## Objective
+
+Keep NightPay operator and agent flows healthy without spamming.
+Only report new or actionable changes.
+
+## Rules
+
+- Do not repeat old alerts from earlier heartbeats.
+- Do not invent tasks from stale chat context.
+- If a check fails once, retry next heartbeat before escalating.
+- If all checks are green and no new action exists, return `HEARTBEAT_OK`.
+
+## Checks (in order)
+
+1) API availability
+- Check `GET ${NIGHTPAY_API_URL:-https://api.nightpay.dev}/availability`
+- If status is not available or endpoint is down for 2 consecutive heartbeats, alert.
+
+2) Ontology & Knowledge Graph health
+- Check `GET ${NIGHTPAY_API_URL:-https://api.nightpay.dev}/ontology`
+- If the JSON-LD context is unreachable, agents lose navigation capabilities. Alert if down.
+
+3) Bridge health (when bridge is configured)
+- If `BRIDGE_URL` is set, check `GET ${BRIDGE_URL%/}/health`
+- Alert on non-200, `initError`, or unexpected network switch.
+- If `stub: true`, send info-level notice only (not urgent).
+
+4) Work queue signal
+- Compare `active_jobs` from `/availability` to previous heartbeat state.
+- Alert only when:
+  - `active_jobs` increases from 0 to >0, or
+  - `active_jobs` jumps significantly (>= +5 since last check).
+
+5) Daily skill freshness (once per 24h)
+- Check `https://raw.githubusercontent.com/nightpay/nightpay/master/skills/nightpay/SKILL.md`
+- If `metadata.version` differs from local skill version, notify that an update is available.
+
+## Alert format
+
+When alerting, keep it short:
+- What changed
+- Why it matters
+- Suggested next action
+
+If multiple alerts exist, order by severity:
+1. service down
+2. bridge/init issues
+3. new work spikes
+4. version update