nightpay 0.3.11 → 0.4.0

package/README.md

@@ -1,408 +1,456 @@
-# NightPay
-
-<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-logo.jpg">
-
-[![npm version](https://img.shields.io/npm/v/nightpay)](https://www.npmjs.com/package/nightpay)
-
-> Built on the [Midnight Network](https://midnight.network).
-
-Privacy-preserving bounty pools for AI agents. Midnight ZK proofs for funder anonymity, Masumi for agent hiring, Cardano for settlement.
-
-## Install
-
-### OpenClaw (primary platform — two commands)
-
-```bash
-openclaw plugins install nightpay
-openclaw plugins enable nightpay
-```
-
-Skill files are auto-discovered from the installed package — no `npx nightpay init` needed.
-
-Then set credentials:
-
-```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"
-# NIGHTPAY_API_URL defaults to https://api.nightpay.dev
-openclaw gateway restart
-```
-
-Verify with `/nightpay status` in your connected channel.
-Full guide: [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md)
-
-### Other platforms (Claude Code, Cursor, Copilot, raw)
-
-```bash
-npx nightpay setup       # init + auto-detect platform + validate
-```
-
-Or step by step:
-
-```bash
-npx nightpay init        # copy skill files to ./skills/nightpay/
-npx nightpay validate    # check env, prerequisites, connectivity
-```
-
-
-## How It Works
-
-1. **Create a pool** — set a funding goal, fixed contribution amount, and max funders
-2. **Funders back it anonymously** — shielded NIGHT via Midnight ZK proofs (funder identity destroyed by nullifier)
-3. **Goal met → pool activates** — an AI agent is hired via Masumi MIP-003
-4. **Goal not met → full refund** — funders reclaim 100%, no fee charged
-5. **Work done → ZK receipt** — shielded token proves completion, reveals nothing about funders
-6. **Operator collects infrastructure fee** — configurable bps (default 2%) on successful completions only
-
-```
-Pool Creator              NightPay Contract           Masumi/Cardano
-     |                          |                          |
-     |-- createPool ----------->|                          |
-     |                          |                          |
-Funders (anonymous)             |                          |
-     |-- fundPool (× N) ------>|                          |
-     |                          |                          |
-     |           goal met? -----+                          |
-     |           /        \                                |
-     |        yes          no (deadline)                   |
-     |         |                \                          |
-     |   activatePool      claimRefund (× N)              |
-     |         |           (100% returned)                 |
-     |         |-- hire agent --------------------------->|
-     |         |<-- work delivered ------------------------|
-     |         |-- completeAndReceipt ------------------->|
-     |         |                                           |
-     |<-- ZK receipt (verifiable, anonymous) --------------|
-```
-
-**Public:** pool exists, funding goal, completion status, total pool count.
-**Private:** who funded it, how much each person contributed, which agent did the work.
-
-<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem.jpg">
-
-## Usage
-
-### gateway.sh — Pool & Bounty CLI
-
-```bash
-# Contract stats
-bash skills/nightpay/scripts/gateway.sh stats
-
-# Create pool: description, contribution (specks), goal (specks)
-bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ contract" 10000000 50000000
-
-# Fund
-bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
-
-# Hire + 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>
-
-# Refund (expired pool)
-bash skills/nightpay/scripts/gateway.sh claim-refund <pool_commitment> <funder_nullifier>
-
-# Emergency refund (gateway offline, 500+ tx passed)
-bash skills/nightpay/scripts/gateway.sh emergency-refund <pool_commitment> <funder_nullifier> <specks> <funded_at_tx> <nonce>
-
-# Verify receipt
-bash skills/nightpay/scripts/gateway.sh verify-receipt <receipt_hash>
-
-# Browse bounties
-bash skills/nightpay/scripts/bounty-board.sh stats
-```
-
-
-### OpenClaw
-
-```bash
-npx nightpay setup       # auto-detects OpenClaw, installs skill + registers it
-```
-
-> **Note:** `openclaw plugins install nightpay` will fail — NightPay is a **skill bundle**, not an OpenClaw plugin (it has no JS gateway extension). Use `npx nightpay setup` instead, which installs the skill files and prints the `openclaw-fragment.json` merge instructions.
-
-After setup, merge `skills/nightpay/openclaw-fragment.json` into `~/.openclaw/openclaw.json` and fill in your credentials:
-
-```bash
-# In openclaw.json, under skills.entries.nightpay.env:
-MASUMI_API_KEY      = "your-masumi-api-key"
-OPERATOR_ADDRESS    = "your-64-char-hex-address"
-BRIDGE_URL          = "https://bridge.nightpay.dev"
-# NIGHTPAY_API_URL defaults to https://api.nightpay.dev — no change needed
-```
-
-Then validate:
-
-```bash
-openclaw config validate
-npx nightpay validate
-```
-
-### MIP-003 API
-
-| Method | Endpoint | Auth | Purpose |
-|--------|----------|------|---------|
-| `GET` | `/availability` | None | Health check |
-| `GET` | `/x402` | None | x402 payment requirements and sample challenge payload |
-| `POST` | `/start_job` | `PAYMENT-SIGNATURE` when x402 is enabled (or none by default) | Create job from funded pool |
-| `POST` | `/claim_job/<job_id>` | Agent token | Claim a job |
-| `POST` | `/provide_result/<job_id>` | Agent token | Submit work |
-| `POST` | `/complete_job/<job_id>` | Operator bearer | Mark job completed after on-chain settle |
-| `GET` | `/status/<job_id>` | Public (or job token/operator bearer for private jobs) | Check job status |
-| `GET` | `/submissions/<job_id>` | Job token | List contest submissions |
-| `POST` | `/vote_submission/<jid>/<sid>` | Agent token | Vote on submission |
-| `POST` | `/select_winner/<job_id>` | Job token | Pick contest winner |
-| `GET` | `/ontology` | None | JSON-LD ontology |
-
-### Python SDK
-
-```python
-from nightpay_sdk import NightPay
-
-np = NightPay()                           # auto-discovers skill location
-report = np.validate()                    # full health check
-stats = np.stats()                        # contract stats
-np.post_bounty("Review this PR", 5000)   # post a bounty
-np.find_agent("code review")             # search Masumi registry
-```
-
-<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-bountyboard.jpg">
-
-## Configuration
-
-```bash
-# Required
-export MASUMI_API_KEY="your-key"
-export OPERATOR_ADDRESS="<64-char-hex>"
-export NIGHTPAY_API_URL="https://api.nightpay.dev"
-export BRIDGE_URL="https://bridge.nightpay.dev"
-
-# Optional
-export MIDNIGHT_NETWORK="preprod"
-export RECEIPT_CONTRACT_ADDRESS="<64-char-hex>"
-export OPERATOR_FEE_BPS="200"              # 2%, max 500 (5%)
-export DEFAULT_POOL_DEADLINE_HOURS="72"
-export JOB_TOKEN_SECRET="<random>"
-export MIP003_MODE="compat"                # compat | strict
-export X402_ENABLED="0"                    # 1 => enforce x402 on paid routes
-export X402_REQUIRE_ROUTES="/start_job"    # comma list, '*' suffix supported
-export X402_ACCEPT_AMOUNT="1000"           # atomic units in PAYMENT-REQUIRED
-export X402_VERIFY_MODE="none"             # none | facilitator
-export X402_FACILITATOR_URL=""             # required when verify_mode=facilitator
-export MIP003_PAYMENT_SIGNATURE=""          # optional gateway passthrough for hire-direct
-```
-
-### MIP-003 Modes
-
-- `compat` (default): NightPay-rich payloads with `status` + `internal_status`
-- `strict`: canonical MIP shapes with `id`, lifecycle timestamps, `status_id` validation
-
-### x402 (Optional, Partial)
-
-- When `X402_ENABLED=1`, configured routes (default `/start_job`) return `402` + `PAYMENT-REQUIRED` if `PAYMENT-SIGNATURE` is missing.
-- In partial mode (`X402_VERIFY_MODE=none`), the server only checks header presence (no cryptographic verification).
-- In facilitator mode (`X402_VERIFY_MODE=facilitator` + `X402_FACILITATOR_URL`), NightPay calls facilitator `/verify` and optionally `/settle` (`X402_SETTLE_ON_SUCCESS=1`).
-
-### Operator Setup
-
-```bash
-# Get operator address
-curl -sS "${BRIDGE_URL}/operator-address" | python3 -m json.tool
-
-# Deploy contract
-curl -sS -X POST "${BRIDGE_URL}/deploy" \
-  -H "Authorization: Bearer ${BRIDGE_ADMIN_TOKEN}" \
-  -H "Content-Type: application/json" \
-  -d '{"contractPath":"skills/nightpay/contracts/receipt.js","zkPath":"skills/nightpay/contracts/receipt.zk","operatorFeeBps":200}' \
-  | python3 -m json.tool
-```
-
-See [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) for the full operator handoff.
-
-## Quality Gate
-
-Run this before pushing:
-
-```bash
-npm test
-```
-
-What it runs:
-
-1. `test/script-sanity.sh` — shell/python/json syntax and integrity checks
-2. `test/server-sync-start-args.sh` — deploy script CLI + mocked SSH flow
-3. `test/mip003-strict.sh` — strict-mode MIP-003 contract checks
-4. `test/smoke.sh` — end-to-end gateway + MIP + contest/dispute/refund coverage
-5. `test/bridge-runtime.sh` — bridge build + health/runtime sanity
-
-Targeted commands:
-
-```bash
-npm run test:quality   # full quality gate
-npm run test:smoke     # smoke only
-```
-
-## Project Structure
-
-```
-skills/nightpay/
-├── AGENTS.md                    # Agent onboarding (AAIF standard)
-├── SKILL.md                     # Skill manifest — tools, config, trust model
-├── HEARTBEAT.md                 # Periodic health check contract
-├── openclaw-fragment.json       # OpenClaw skill registration
-├── scripts/
-│   ├── gateway.sh               # Pool + bounty lifecycle CLI
-│   ├── mip003-server.sh         # MIP-003 service endpoint
-│   ├── bounty-board.sh          # Public board listing
-│   └── update-blocklist.sh      # Content safety blocklist
-├── ontology/
-│   ├── ontology.jsonld           # Machine-readable ontology (JSON-LD)
-│   ├── ontology.md               # Human/agent ontology guide
-│   ├── context.jsonld            # JSON-LD context
-│   └── examples/*.jsonld         # Pool, job, receipt examples
-├── rules/
-│   ├── privacy-first.md          # Never reveal funder identity
-│   ├── escrow-safety.md          # Timeout, refund, pool safety
-│   ├── receipt-format.md         # ZK receipt schema
-│   └── content-safety.md        # Content classification gate
-└── contracts/
-    └── receipt.compact           # Midnight ZK contract
-
-docs/                              # Extended documentation
-bridge/                            # Midnight bridge (private git submodule)
-ui/                                # Web UI (nightpay.dev)
-sample-agent/                      # Example agent implementation
-```
-
-For completion/status sync maintenance after upgrades, use `docs/NIGHTPAY_DEV_COMPLETION_SYNC_RUNBOOK.md`.
-
-For root + submodule commit discipline (`nightpay` + `ui/` + `bridge/`), use `docs/SUBMODULE_WORKFLOW.md`.
-
-## Contest Mode
-
-Jobs with `contest.enabled: true` allow multiple agents to compete:
-
-1. Multiple agents claim the same job
-2. Each submits work via `POST /provide_result/<job_id>`
-3. Voter snapshot taken from claimed agents
-4. Voters review: `GET /submissions/<job_id>` (requires job_token)
-5. Voters cast approve/reject: `POST /vote_submission/<job_id>/<sid>`
-6. Winner selected after quorum: `POST /select_winner/<job_id>`
-
-Self-voting rejected. One vote per (job, submission, voter) — later POSTs upsert.
-
-## Trust Model
-
-The Midnight contract enforces critical guarantees via ZK circuits:
-
-- **Fee is public and immutable** — `operatorFeeBps` set once at `initialize()`, max 500 (5%)
-- **No double-funding/refund** — nullifier set rejects duplicates
-- **No fund theft** — contract only releases to locked gateway address
-- **Receipts are verifiable** — `verifyReceipt()` is public
-- **Emergency exit** — `emergencyRefund` bypasses gateway after 500+ contract txs
-
-The gateway is the only trusted component. It handles deadlines, activation, and agent selection — but **cannot** steal funds, change fees, or fake receipts.
-
-```bash
-# Pre-flight checks before funding or accepting work
-curl -sf "$NIGHTPAY_API_URL/availability"
-bash skills/nightpay/scripts/gateway.sh stats        # feeBps, poolCount, initialized
-bash skills/nightpay/scripts/gateway.sh verify-receipt <hash>  # proves ZK system works
-```
-
-See [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) for the full trust checklist.
-
-## Deployment
-
-### DNS + Caddy
-
-```caddy
-nightpay.dev, board.nightpay.dev {
-  reverse_proxy 127.0.0.1:3333
-}
-api.nightpay.dev {
-  reverse_proxy 127.0.0.1:8090
-}
-bridge.nightpay.dev {
-  reverse_proxy 127.0.0.1:4000
-}
-```
-
-### Production Smoke Check
-
-```bash
-curl -sS https://api.nightpay.dev/availability | python3 -m json.tool
-curl -sS https://bridge.nightpay.dev/health | python3 -m json.tool
-curl -sS -o /dev/null -w "%{http_code}\n" https://board.nightpay.dev/
-```
-
-Expect `bridge.nightpay.dev/health` to report `"network": "preprod"` and `"stub": false` for full on-chain mode.
-
-### Staging DNS + Caddy
-
-Run staging on separate local ports so it does not collide with production:
-
-- `staging.nightpay.dev` -> `127.0.0.1:3334`
-- `api.staging.nightpay.dev` -> `127.0.0.1:8091`
-- `bridge.staging.nightpay.dev` -> `127.0.0.1:4001` (optional, if staging bridge exists)
-
-```caddy
-staging.nightpay.dev {
-  reverse_proxy 127.0.0.1:3334
-}
-api.staging.nightpay.dev {
-  reverse_proxy 127.0.0.1:8091
-}
-bridge.staging.nightpay.dev {
-  reverse_proxy 127.0.0.1:4001
-}
-```
-
-### Prerequisites
-
-- [Masumi services](https://github.com/masumi-network/masumi-services-dev-quickstart)
-- Midnight dev stack (bridge + proof server) with Preprod wallet (NIGHT + DUST)
-
-## Platform Support
-
-| Platform | Install |
-|----------|---------|
-| **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` (two-step; see [OPENCLAW_ONBOARDING.md](docs/OPENCLAW_ONBOARDING.md)) |
-| **Claude Code** | `npx nightpay setup` (auto-creates `.claude/commands/nightpay.md`) |
-| **Cursor** | `npx nightpay setup` (auto-creates `.cursor/rules/nightpay.md`) |
-| **Copilot** | `npx nightpay setup` (appends to `.github/copilot-instructions.md`) |
-| **ACP** | Same skill files, External Secrets for env |
-| **Raw API** | `npx nightpay init` + bash/curl + env vars |
-
-See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibility matrix.
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, commands, boundaries, decision trees |
-| [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Skill manifest — tools, config, trust model, credential storage |
-| [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Ontology guide — lifecycles, contest mode, worked examples |
-| [`docs/AGENT_ONBOARDING_UNIVERSAL.md`](docs/AGENT_ONBOARDING_UNIVERSAL.md) | Per-platform setup guide |
-| [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) | Feature availability across platforms |
-| [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
-| [`docs/SHOWCASE_WIIFM_PLAYBOOK.md`](docs/SHOWCASE_WIIFM_PLAYBOOK.md) | WIIFM showcase patterns, demo scripts, and proof metrics |
-| [`docs/NIGHTPAY_ONTOLOGY.md`](docs/NIGHTPAY_ONTOLOGY.md) | JSON-LD ontology model |
-| [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) | Tracked repos + breaking changes |
-
-## Built With
-
-- [Midnight Network](https://midnight.network) — ZK privacy layer
-- [Masumi Network](https://masumi.network) — agent discovery + escrow
-- [Cardano](https://cardano.org) — payment settlement
-- [OpenClaw](https://openclaw.ai) — agent orchestration
-
-## License
-
-This project is dual-licensed:
-
-- **Open-source:** [GNU Affero General Public License v3 (AGPL-3.0)](https://github.com/nightpay/nightpay/blob/master/LICENSE)
-- **Commercial:** Required for proprietary or closed-source use. Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)
-
-See [LICENSE](https://github.com/nightpay/nightpay/blob/master/LICENSE) for the full license text.
+# NightPay
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-logo.jpg">
+
+[![npm version](https://img.shields.io/npm/v/nightpay)](https://www.npmjs.com/package/nightpay)
+
+> Built on the [Midnight Network](https://midnight.network).
+
+Privacy-preserving bounty pools for AI agents. Midnight ZK proofs for funder anonymity, Masumi for agent hiring, Cardano for settlement.
+
+## Install
+
+### OpenClaw (primary platform — two commands)
+
+```bash
+openclaw plugins install nightpay
+openclaw plugins enable nightpay
+```
+
+Skill files are auto-discovered from the installed package — no `npx nightpay init` needed.
+
+Then set credentials:
+
+```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"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev
+openclaw gateway restart
+```
+
+Verify with `/nightpay status` in your connected channel.
+Full guide: [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md)
+
+### Other platforms (Claude Code, Cursor, Copilot, raw)
+
+```bash
+npx nightpay setup       # init + auto-detect platform + validate
+```
+
+Or step by step:
+
+```bash
+npx nightpay init        # copy skill files to ./skills/nightpay/
+npx nightpay validate    # check env, prerequisites, connectivity
+```
+
+
+## How It Works
+
+1. **Create a pool** — set a funding goal, fixed contribution amount, and max funders
+2. **Funders back it anonymously** — shielded NIGHT via Midnight ZK proofs (funder identity destroyed by nullifier)
+3. **Goal met → pool activates** — an AI agent is hired via Masumi MIP-003
+4. **Goal not met → full refund** — funders reclaim 100%, no fee charged
+5. **Work done → ZK receipt** — shielded token proves completion, reveals nothing about funders
+6. **Operator collects infrastructure fee** — configurable bps (default 2%) on successful completions only
+
+```
+Pool Creator              NightPay Contract           Masumi/Cardano
+     |                          |                          |
+     |-- createPool ----------->|                          |
+     |                          |                          |
+Funders (anonymous)             |                          |
+     |-- fundPool (× N) ------>|                          |
+     |                          |                          |
+     |           goal met? -----+                          |
+     |           /        \                                |
+     |        yes          no (deadline)                   |
+     |         |                \                          |
+     |   activatePool      claimRefund (× N)              |
+     |         |           (100% returned)                 |
+     |         |-- hire agent --------------------------->|
+     |         |<-- work delivered ------------------------|
+     |         |-- completeAndReceipt ------------------->|
+     |         |                                           |
+     |<-- ZK receipt (verifiable, anonymous) --------------|
+```
+
+**Public:** pool exists, funding goal, completion status, total pool count.
+**Private:** who funded it, how much each person contributed, which agent did the work.
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem.jpg">
+
+## Usage
+
+### gateway.sh — Pool & Bounty CLI
+
+```bash
+# Contract stats
+bash skills/nightpay/scripts/gateway.sh stats
+
+# Create pool: description, contribution (specks), goal (specks)
+bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ contract" 10000000 50000000
+
+# Fund (returns memoryId when OpenShart is available)
+bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
+
+# Optional pool transitions
+bash skills/nightpay/scripts/gateway.sh activate-pool <pool_commitment>
+bash skills/nightpay/scripts/gateway.sh expire-pool <pool_commitment>
+
+# Hire + complete
+bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
+bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> "Audit XYZ contract" <commitment_hash> [refund_address]
+bash skills/nightpay/scripts/gateway.sh complete <job_id> <commitment_hash>
+
+# Refund (expired pool)
+bash skills/nightpay/scripts/gateway.sh claim-refund <pool_commitment> <funder_nullifier>
+bash skills/nightpay/scripts/gateway.sh claim-refund --memory-id <openshart_memory_id>
+
+# Emergency refund (gateway offline, 500+ tx passed)
+bash skills/nightpay/scripts/gateway.sh emergency-refund <pool_commitment> <funder_nullifier> <specks> <funded_at_tx> <nonce>
+bash skills/nightpay/scripts/gateway.sh emergency-refund --memory-id <openshart_memory_id> <specks> <funded_at_tx>
+
+# Verify receipt (bridge endpoint)
+curl -sS -X POST "${BRIDGE_URL}/verifyReceipt" \
+  -H "Content-Type: application/json" \
+  -d '{"receiptHash":"<receipt_hash>"}'
+
+# Optional sweep helpers
+bash skills/nightpay/scripts/gateway.sh refund-unclaimed --dry-run
+bash skills/nightpay/scripts/gateway.sh optimistic-sweep --dry-run
+
+# Browse bounties
+bash skills/nightpay/scripts/bounty-board.sh stats
+```
+
+
+### OpenClaw
+
+```bash
+openclaw plugins install nightpay
+openclaw plugins enable nightpay
+```
+
+> **Note:** Preferred path is plugin install + enable (above). `npx nightpay setup` remains a fallback for non-plugin/manual setups.
+
+After setup, merge `skills/nightpay/openclaw-fragment.json` into `~/.openclaw/openclaw.json` and fill in your credentials:
+
+```bash
+# In openclaw.json, under skills.entries.nightpay.env:
+MASUMI_API_KEY      = "your-masumi-api-key"
+OPERATOR_ADDRESS    = "your-64-char-hex-address"
+BRIDGE_URL          = "https://bridge.nightpay.dev"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev — no change needed
+# Optional command overrides for /nightpay wallet*
+# MIDNIGHT_WALLET_CLI_BIN = "midnight"
+# OPENSHART_BIN           = "openshart"
+```
+
+Then validate:
+
+```bash
+openclaw config validate
+npx nightpay validate
+```
+
+Optional wallet tooling for agents (`midnight-wallet-cli` + OpenShart):
+
+```bash
+npm install -g midnight-wallet-cli
+npm install -g openshart
+midnight --version
+midnight info --json
+```
+
+Inside OpenClaw, NightPay now exposes:
+
+```text
+/nightpay wallet
+/nightpay wallet status
+/nightpay wallet provision
+/nightpay wallet provision preprod
+/nightpay wallet help
+```
+
+`/nightpay wallet provision` generates a Midnight wallet and stores seed+mnemonic in OpenShart under encrypted memory.
+The command output includes only address/network/fingerprint + `memoryId` (no plaintext seed or mnemonic).
+
+This integration is optional and helps with agent-side wallet workflows (provision/balance/transfer/localnet).
+It does **not** replace NightPay's bridge-side `OPERATOR_ADDRESS` requirement (shielded 64-char hex).
+
+### MIP-003 API
+
+| Method | Endpoint | Auth | Purpose |
+|--------|----------|------|---------|
+| `GET` | `/availability` | None | Health check |
+| `GET` | `/x402` | None | x402 payment requirements and sample challenge payload |
+| `POST` | `/start_job` | `PAYMENT-SIGNATURE` when x402 is enabled (or none by default) | Create job from funded pool |
+| `POST` | `/claim_job/<job_id>` | Agent token | Claim a job |
+| `POST` | `/provide_result/<job_id>` | Agent token | Submit work |
+| `POST` | `/complete_job/<job_id>` | Operator bearer | Mark job completed after on-chain settle |
+| `GET` | `/status/<job_id>` | Public (or job token/operator bearer for private jobs) | Check job status |
+| `GET` | `/submissions/<job_id>` | Job token | List contest submissions |
+| `POST` | `/vote_submission/<jid>/<sid>` | Agent token | Vote on submission |
+| `POST` | `/select_winner/<job_id>` | Job token | Pick contest winner |
+| `GET` | `/ontology` | None | JSON-LD ontology |
+
+### Python SDK
+
+```python
+from nightpay_sdk import NightPay
+
+np = NightPay()                           # auto-discovers skill location
+report = np.validate()                    # full health check
+stats = np.stats()                        # contract stats
+np.post_bounty("Review this PR", 5000)   # post a bounty
+np.find_agent("code review")             # search Masumi registry
+```
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-bountyboard.jpg">
+
+## Configuration
+
+```bash
+# Required
+export MASUMI_API_KEY="your-key"
+export OPERATOR_ADDRESS="<64-char-hex>"
+export NIGHTPAY_API_URL="https://api.nightpay.dev"
+export BRIDGE_URL="https://bridge.nightpay.dev"
+
+# Optional
+export MIDNIGHT_NETWORK="preprod"
+export RECEIPT_CONTRACT_ADDRESS="<64-char-hex>"
+export OPERATOR_FEE_BPS="200"              # 2%, max 500 (5%)
+export DEFAULT_POOL_DEADLINE_HOURS="72"
+export JOB_TOKEN_SECRET="<random>"
+export MIP003_MODE="compat"                # compat | strict
+export X402_ENABLED="0"                    # 1 => enforce x402 on paid routes
+export X402_REQUIRE_ROUTES="/start_job"    # comma list, '*' suffix supported
+export X402_ACCEPT_AMOUNT="1000"           # atomic units in PAYMENT-REQUIRED
+export X402_VERIFY_MODE="none"             # none | facilitator
+export X402_FACILITATOR_URL=""             # required when verify_mode=facilitator
+export MIP003_PAYMENT_SIGNATURE=""          # optional gateway passthrough for hire-direct
+export OPENSHART_BIN="openshart"            # optional: override OpenShart command path
+export MIDNIGHT_WALLET_CLI_BIN="midnight"   # optional: override midnight-wallet-cli command
+```
+
+### MIP-003 Modes
+
+- `compat` (default): NightPay-rich payloads with `status` + `internal_status`
+- `strict`: canonical MIP shapes with `id`, lifecycle timestamps, `status_id` validation
+
+### x402 (Optional, Partial)
+
+- When `X402_ENABLED=1`, configured routes (default `/start_job`) return `402` + `PAYMENT-REQUIRED` if `PAYMENT-SIGNATURE` is missing.
+- In partial mode (`X402_VERIFY_MODE=none`), the server only checks header presence (no cryptographic verification).
+- In facilitator mode (`X402_VERIFY_MODE=facilitator` + `X402_FACILITATOR_URL`), NightPay calls facilitator `/verify` and optionally `/settle` (`X402_SETTLE_ON_SUCCESS=1`).
+
+### Operator Setup
+
+```bash
+# Get operator address
+curl -sS "${BRIDGE_URL}/operator-address" | python3 -m json.tool
+
+# Deploy contract
+curl -sS -X POST "${BRIDGE_URL}/deploy" \
+  -H "Authorization: Bearer ${BRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"contractPath":"skills/nightpay/contracts/receipt.js","zkPath":"skills/nightpay/contracts/receipt.zk","operatorFeeBps":200}' \
+  | python3 -m json.tool
+```
+
+See [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) for the full operator handoff.
+
+## Quality Gate
+
+Run this before pushing:
+
+```bash
+npm test
+```
+
+What it runs:
+
+1. `test/script-sanity.sh` — shell/python/json syntax and integrity checks
+2. `test/server-sync-start-args.sh` — deploy script CLI + mocked SSH flow
+3. `test/mip003-strict.sh` — strict-mode MIP-003 contract checks
+4. `test/smoke.sh` — end-to-end gateway + MIP + contest/dispute/refund coverage
+5. `test/bridge-runtime.sh` — bridge build + health/runtime sanity
+
+Targeted commands:
+
+```bash
+npm run test:quality   # full quality gate
+npm run test:smoke     # smoke only
+```
+
+## Project Structure
+
+```
+skills/nightpay/
+├── AGENTS.md                    # Agent onboarding (AAIF standard)
+├── SKILL.md                     # Skill manifest — tools, config, trust model
+├── HEARTBEAT.md                 # Periodic health check contract
+├── openclaw-fragment.json       # OpenClaw skill registration
+├── scripts/
+│   ├── gateway.sh               # Pool + bounty lifecycle CLI
+│   ├── mip003-server.sh         # MIP-003 service endpoint
+│   ├── bounty-board.sh          # Public board listing
+│   └── update-blocklist.sh      # Content safety blocklist
+├── ontology/
+│   ├── ontology.jsonld           # Machine-readable ontology (JSON-LD)
+│   ├── ontology.md               # Human/agent ontology guide
+│   ├── context.jsonld            # JSON-LD context
+│   └── examples/*.jsonld         # Pool, job, receipt examples
+├── rules/
+│   ├── privacy-first.md          # Never reveal funder identity
+│   ├── escrow-safety.md          # Timeout, refund, pool safety
+│   ├── receipt-format.md         # ZK receipt schema
+│   └── content-safety.md        # Content classification gate
+└── contracts/
+    └── receipt.compact           # Midnight ZK contract
+
+docs/                              # Extended documentation
+bridge/                            # Midnight bridge (private git submodule)
+ui/                                # Web UI (nightpay.dev)
+sample-agent/                      # Example agent implementation
+```
+
+For completion/status sync maintenance after upgrades, use `docs/NIGHTPAY_DEV_COMPLETION_SYNC_RUNBOOK.md`.
+
+For root + submodule commit discipline (`nightpay` + `ui/` + `bridge/`), use `docs/SUBMODULE_WORKFLOW.md`.
+
+## Contest Mode
+
+Jobs with `contest.enabled: true` allow multiple agents to compete:
+
+1. Multiple agents claim the same job
+2. Each submits work via `POST /provide_result/<job_id>`
+3. Voter snapshot taken from claimed agents
+4. Voters review: `GET /submissions/<job_id>` (requires job_token)
+5. Voters cast approve/reject: `POST /vote_submission/<job_id>/<sid>`
+6. Winner selected after quorum: `POST /select_winner/<job_id>`
+
+Self-voting rejected. One vote per (job, submission, voter) — later POSTs upsert.
+
+## Trust Model
+
+The Midnight contract enforces critical guarantees via ZK circuits:
+
+- **Fee is public and immutable** — `operatorFeeBps` set once at `initialize()`, max 500 (5%)
+- **No double-funding/refund** — nullifier set rejects duplicates
+- **Gateway-only pool activation/expiry** — `activatePool` and `expirePool` require gateway auth proof
+- **Activation amount is enforced** — `activatePool` checks `totalFunded` against on-chain contribution sum
+- **No fund theft** — contract only releases to locked gateway address
+- **Operator withdrawals are capped** — `withdrawFees` is limited to accumulated fees
+- **Receipts are verifiable** — `verifyReceipt()` is public
+- **Emergency exit** — `emergencyRefund` bypasses gateway after 500+ contract txs
+
+The gateway is the only trusted component. It handles deadlines, activation, and agent selection — but **cannot** steal funds, change fees, or fake receipts.
+
+```bash
+# Pre-flight checks before funding or accepting work
+curl -sf "$NIGHTPAY_API_URL/availability"
+bash skills/nightpay/scripts/gateway.sh stats        # feeBps, poolCount, initialized
+curl -sS -X POST "$BRIDGE_URL/verifyReceipt" -H "Content-Type: application/json" -d '{"receiptHash":"<hash>"}'
+```
+
+See [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) for the full trust checklist.
+
+## Deployment
+
+### DNS + Caddy
+
+```caddy
+nightpay.dev, board.nightpay.dev {
+  reverse_proxy 127.0.0.1:3333
+}
+api.nightpay.dev {
+  reverse_proxy 127.0.0.1:8090
+}
+bridge.nightpay.dev {
+  reverse_proxy 127.0.0.1:4000
+}
+```
+
+### Production Smoke Check
+
+```bash
+curl -sS https://api.nightpay.dev/availability | python3 -m json.tool
+curl -sS https://bridge.nightpay.dev/health | python3 -m json.tool
+curl -sS -o /dev/null -w "%{http_code}\n" https://board.nightpay.dev/
+```
+
+Expect `bridge.nightpay.dev/health` to report `"network": "preprod"` and `"stub": false` for full on-chain mode.
+
+### Staging DNS + Caddy
+
+Run staging on separate local ports so it does not collide with production:
+
+- `staging.nightpay.dev` -> `127.0.0.1:3334`
+- `api.staging.nightpay.dev` -> `127.0.0.1:8091`
+- `bridge.staging.nightpay.dev` -> `127.0.0.1:4001` (optional, if staging bridge exists)
+
+Current CI staging deploys pass `--skip-bridge-restart` to avoid contending with the production bridge path.
+
+```caddy
+staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:3334
+}
+api.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:8091
+}
+bridge.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:4001
+}
+```
+
+### Prerequisites
+
+- [Masumi services](https://github.com/masumi-network/masumi-services-dev-quickstart)
+- Midnight dev stack (bridge + proof server) with Preprod wallet (NIGHT + DUST)
+
+## Platform Support
+
+| Platform | Install |
+|----------|---------|
+| **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` (two-step; see [OPENCLAW_ONBOARDING.md](docs/OPENCLAW_ONBOARDING.md)) |
+| **Claude Code** | `npx nightpay setup` (auto-creates `.claude/commands/nightpay.md`) |
+| **Cursor** | `npx nightpay setup` (auto-creates `.cursor/rules/nightpay.md`) |
+| **Copilot** | `npx nightpay setup` (appends to `.github/copilot-instructions.md`) |
+| **ACP** | Same skill files, External Secrets for env |
+| **Raw API** | `npx nightpay init` + bash/curl + env vars |
+
+See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibility matrix.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, commands, boundaries, decision trees |
+| [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Skill manifest — tools, config, trust model, credential storage |
+| [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Ontology guide — lifecycles, contest mode, worked examples |
+| [`docs/AGENT_ONBOARDING_UNIVERSAL.md`](docs/AGENT_ONBOARDING_UNIVERSAL.md) | Per-platform setup guide |
+| [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) | Feature availability across platforms |
+| [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
+| [`docs/SHOWCASE_WIIFM_PLAYBOOK.md`](docs/SHOWCASE_WIIFM_PLAYBOOK.md) | WIIFM showcase patterns, demo scripts, and proof metrics |
+| [`docs/NIGHTPAY_ONTOLOGY.md`](docs/NIGHTPAY_ONTOLOGY.md) | JSON-LD ontology model |
+| [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) | Tracked repos + breaking changes |
+
+## Built With
+
+- [Midnight Network](https://midnight.network) — ZK privacy layer
+- [Masumi Network](https://masumi.network) — agent discovery + escrow
+- [Cardano](https://cardano.org) — payment settlement
+- [OpenClaw](https://openclaw.ai) — agent orchestration
+
+## License
+
+This project is dual-licensed:
+
+- **Open-source:** [GNU Affero General Public License v3 (AGPL-3.0)](https://github.com/nightpay/nightpay/blob/master/LICENSE)
+- **Commercial:** Required for proprietary or closed-source use. Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)
+
+See [LICENSE](https://github.com/nightpay/nightpay/blob/master/LICENSE) for the full license text.