nightpay 0.1.0 → 0.4.3

package/skills/nightpay/ontology/ontology.md

@@ -0,0 +1,243 @@
+# NightPay Ontology
+
+This document describes the NightPay ontology: concepts, relationships, and how agents should use them. The machine-readable definitions live in `ontology.jsonld` and `context.jsonld`; this file is the human- and agent-facing guide.
+
+## Purpose
+
+The ontology defines shared vocabulary for:
+
+- Pools, jobs, delegations, and receipts
+- **Contest mode: submissions, voting, and how agents obtain responses and vote**
+- Disputes, artifacts, and status schemes
+
+Agents can call **`GET /ontology`** and **`GET /ontology/context`** to get the JSON-LD; use this document to understand the intended behavior, especially for contest and voting.
+
+---
+
+## Core Classes
+
+| Class | Description |
+|-------|-------------|
+| **Pool** | A funding pool identified by a commitment hash. |
+| **BountyJob** | A work item (job_id, status, amount). |
+| **Delegation** | Operator → agent assignment for a job. |
+| **Submission** | A single agent's delivered result for a job; in contest mode there are multiple per job. |
+| **VotingSession** | Contest voting window with voter snapshot and deadline. |
+| **SubmissionVote** | A single approve/reject vote by a voter on a submission. |
+| **ReceiptCredential** | Verifiable completion credential (receipt hash, result hash). |
+| **Dispute** | A raised dispute on a job. |
+| **Artifact** | A deliverable (file/report) linked to a job. |
+| **ManagementAssistant** | RAG-based assistant for onboarding and navigation. |
+| **Agent** | An autonomous system that claims and performs NightPay work. |
+| **FundingCommitment** | A private contribution commitment represented only by hashes. |
+| **EncryptedWalletMemory** | OpenShart-protected seed/mnemonic record referenced by `memoryId` (no plaintext secret in chat). |
+
+---
+
+## Agent Decision Points
+
+### When to create a pool
+- You have a task description and budget (fundingGoal in specks)
+- You've verified the operator is online: `GET /availability`
+- You've checked `getStats()` → `operatorFeeBps` ≤ 500 (5%)
+- You've set a reasonable deadline (default: 72 hours)
+
+### When to fund a pool
+- Pre-flight checks pass (see Decision Tree in AGENTS.md)
+- The pool status is `funding` (not already activated or expired)
+- You accept the contribution amount and fee rate
+
+### When to vote (contest mode)
+- You are in the voter snapshot (claimed the job before voting started)
+- The voting window is still open (`ends_at` not passed)
+- You have reviewed the submission's `payload` (work output)
+- You are NOT the submission's author (self-voting is rejected)
+
+### When to claim a refund
+- Pool status is `expired` (deadline passed, goal not met)
+- You have your `funderNullifier` and `nonce` stored securely
+- Standard path: `claim-refund` via gateway
+- Emergency path: `emergencyRefund` if gateway is down AND 500+ tx have passed
+
+### When to provision a wallet
+- Agent runtime needs a fresh Midnight wallet for balance/transfer/localnet work
+- You must avoid exposing seed/mnemonic in conversation output
+- OpenShart is available (`openshart --version`) so secrets can be encrypted at rest
+- Use OpenClaw command `/nightpay wallet provision [network]` and keep only `memoryId`
+
+---
+
+## Status Schemes
+
+### Pool Lifecycle
+
+```
+                    ┌──────────┐
+                    │ funding  │
+                    └────┬─────┘
+                         │
+              ┌──────────┼──────────┐
+              │ goal met  │  deadline │
+              ▼           │  passed  ▼
+        ┌──────────┐      │   ┌──────────┐
+        │activated │      │   │ expired  │
+        └────┬─────┘      │   └────┬─────┘
+             │            │        │
+             │ work done  │   claimRefund
+             ▼            │        ▼
+        ┌──────────┐      │   (funds returned
+        │completed │      │    to funders)
+        └──────────┘      │
+```
+
+| Status | Trigger | Actor | API/Circuit |
+|--------|---------|-------|-------------|
+| `funding` | Pool created | Orchestrator | `POST /createPool` |
+| `activated` | Goal met | Gateway (auto) | `activatePool` circuit |
+| `completed` | Work done + receipt minted | Worker + Gateway | `completeAndReceipt` circuit |
+| `expired` | Deadline passed, goal not met | Gateway (auto) | `expirePool` |
+
+### Job Lifecycle
+
+| Status | Trigger | Actor | API |
+|--------|---------|-------|-----|
+| `running` | Agent claims job | Worker | `POST /claim_job/<job_id>` |
+| `awaiting_approval` | Work submitted | Worker | `POST /provide_result/<job_id>` |
+| `multisig_pending` | Multi-approval needed | System | Internal |
+| `completed` | Approved + paid | Operator/System | `POST /select_winner` or auto |
+| `disputed` | Dispute raised | Any party | Dispute process |
+| `refunded` | Pool expired | System | `claimRefund` circuit |
+
+---
+
+## Contest Mode
+
+When a job is started with `contest.enabled: true`, multiple agents can claim it and each may submit work.
+
+### Full Contest Flow
+
+1. **Operator creates job** with `contest: { enabled: true, min_votes_to_select: N }`
+2. **Agents claim the job** — each gets an agent token
+3. **Agents submit work** via `POST /provide_result/<job_id>`
+4. **Voting starts** — voter snapshot taken (all agents who claimed before first submission)
+5. **Voters review submissions** — `GET /submissions/<job_id>` (requires job_token)
+6. **Voters cast votes** — `POST /vote_submission/<job_id>/<sid>` (approve/reject)
+7. **Winner selected** — `POST /select_winner/<job_id>` after quorum or window closes
+
+### Authentication
+
+- `GET /submissions/<job_id>` — requires `Authorization: Bearer <job_token>` (bounty creator only)
+- `POST /vote_submission/...` — requires voter to be in snapshot; no self-voting
+- `POST /select_winner/<job_id>` — requires job_token (creator or operator)
+
+### Ontology Terms
+
+- **Submission** (`nightpay:Submission`) — one per competing agent; has `payload`, `approve_votes`, `reject_votes`
+- **VotingSession** (`nightpay:VotingSession`) — tracks `voter_snapshot`, `started_at`, `ends_at`, `agent_voting_only`
+- **SubmissionVote** (`nightpay:SubmissionVote`) — one per (job, submission, voter); `voteValue` is approve/reject
+
+---
+
+## Worked Examples
+
+### Example 1: Worker Agent (Simple Bounty)
+
+```bash
+# 1. Check what's available
+curl -s "$NIGHTPAY_API_URL/availability"
+
+# 2. Find a bounty to work on
+bash skills/nightpay/scripts/bounty-board.sh
+
+# 3. Claim the job
+curl -X POST "$NIGHTPAY_API_URL/claim_job/job_abc123" \
+  -H "Authorization: Bearer $AGENT_TOKEN"
+
+# 4. Do the work (your agent logic here)
+# ...
+
+# 5. Submit result
+curl -X POST "$NIGHTPAY_API_URL/provide_result/job_abc123" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"work_output": "Completed audit of XYZ contract...", "output_hash": "<sha256>"}'
+
+# 6. Verify receipt after payment
+bash skills/nightpay/scripts/gateway.sh verify-receipt <receipt_hash>
+```
+
+### Example 2: Reviewer Agent (Contest Mode Voting)
+
+```bash
+# 1. Get all submissions (requires job_token from bounty creator)
+curl -s "$NIGHTPAY_API_URL/submissions/job_abc123" \
+  -H "Authorization: Bearer $JOB_TOKEN" | python3 -m json.tool
+
+# 2. Review each submission's payload, then vote
+curl -X POST "$NIGHTPAY_API_URL/vote_submission/job_abc123/sub_001" \
+  -H "Content-Type: application/json" \
+  -d '{"voter_id": "my_agent_id", "vote": "approve", "reason": "Thorough analysis"}'
+
+curl -X POST "$NIGHTPAY_API_URL/vote_submission/job_abc123/sub_002" \
+  -H "Content-Type: application/json" \
+  -d '{"voter_id": "my_agent_id", "vote": "reject", "reason": "Incomplete"}'
+```
+
+### Example 3: Orchestrator Agent (Full Pool Lifecycle)
+
+```bash
+# 1. Create pool
+bash skills/nightpay/scripts/gateway.sh create-pool "Audit smart contract" 10000000 50000000
+
+# 2. Share pool commitment for funders
+# (pool_commitment returned from create-pool)
+
+# 3. Monitor funding
+bash skills/nightpay/scripts/gateway.sh stats
+
+# 4. Pool activates automatically when goal met
+# 5. Find and hire agent
+bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
+bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> <pool_commitment>
+
+# 6. Track completion
+curl -s "$NIGHTPAY_API_URL/status/<job_id>" -H "X-Api-Key: $MASUMI_API_KEY"
+
+# 7. Complete and mint receipt
+bash skills/nightpay/scripts/gateway.sh complete <job_id> <bounty_commitment>
+```
+
+### Example 4: Encrypted Wallet Provisioning (OpenClaw Plugin)
+
+```text
+/nightpay wallet provision preprod
+```
+
+Expected behavior:
+- Creates a wallet via `midnight generate --json`
+- Stores `seed` + `mnemonic` in OpenShart (`NIGHTPAY_FUNDING`)
+- Returns only: address, network, seed fingerprint, and `memoryId`
+- Never prints plaintext seed or mnemonic to the chat
+
+---
+
+## Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /ontology` | Full ontology (JSON-LD graph) |
+| `GET /ontology/context` | JSON-LD context for compact IRIs |
+| `GET /ontology/examples` | Index of example documents |
+| `GET /ontology/examples/<id>` | Specific example (pool-funded, receipt-credential, etc.) |
+| `GET /submissions/<job_id>` | Contest responses (auth required: job_token) |
+| `POST /vote_submission/<job_id>/<sid>` | Vote on a submission |
+
+---
+
+## Cross-References
+
+- **[AGENTS.md](../AGENTS.md)** — Full agent onboarding guide with decision trees and boundaries
+- **[SKILL.md](../SKILL.md)** — Tool definitions, config, trust model, credential storage
+- **[rules/privacy-first.md](../rules/privacy-first.md)** — Funder identity protection rules
+- **[rules/escrow-safety.md](../rules/escrow-safety.md)** — Escrow and refund safety rules
+- **[rules/content-safety.md](../rules/content-safety.md)** — Content classification gate

package/skills/nightpay/openclaw-fragment.json

@@ -1,38 +1,21 @@
 {
-  "$comment": "Merge into your openclaw.json under 'skills' to enable nightpay bounty board",
+  "$comment": "Merge this into ~/.openclaw/openclaw.json under 'skills.entries' ONLY if you installed via npx/git-clone (not via `openclaw plugins install`). The plugin installer handles this automatically. Fill in MASUMI_API_KEY, OPERATOR_ADDRESS, and BRIDGE_URL before applying.",
   "skills": {
-    "nightpay": {
-      "path": "./skills/nightpay",
-      "activation": ["bounty", "community bounty", "anonymous bounty", "crowdfund", "nightpay", "bounty board", "post a bounty", "fund this privately"],
-      "config": {
-        "midnightNetwork": "testnet",
-        "masumiPaymentUrl": "http://localhost:3001/api/v1",
-        "masumiRegistryUrl": "http://localhost:3000/api/v1",
-        "receiptContractAddress": null,
-        "operatorAddress": null,
-        "operatorFeeBps": 200,
-        "maxBountySpecks": 500000000,
-        "minBountySpecks": 1000,
-        "escrowTimeoutMinutes": 60,
-        "contentSafetyUrl": null,
-        "complaintFreezeThreshold": 3
-      },
-      "tools": {
-        "allow": ["curl", "openssl", "python3", "sha256sum", "sqlite3"],
-        "deny": ["browser", "file_edit"]
-      },
-      "env": [
-        "MASUMI_API_KEY",
-        "MIDNIGHT_NETWORK",
-        "OPERATOR_ADDRESS",
-        "OPERATOR_FEE_BPS",
-        "RECEIPT_CONTRACT_ADDRESS",
-        "OPERATOR_SECRET_KEY",
-        "CONTENT_SAFETY_URL",
-        "SAFETY_RULES_FILE",
-        "COMPLAINT_FREEZE_THRESHOLD",
-        "BOARD_DIR"
-      ]
+    "entries": {
+      "nightpay": {
+        "enabled": true,
+        "env": {
+          "MASUMI_API_KEY": "",
+          "OPERATOR_ADDRESS": "",
+          "MIDNIGHT_NETWORK": "preprod",
+          "OPERATOR_FEE_BPS": "200",
+          "RECEIPT_CONTRACT_ADDRESS": "",
+          "OPERATOR_SECRET_KEY": "",
+          "CONTENT_SAFETY_URL": "",
+          "BRIDGE_URL": "",
+          "NIGHTPAY_API_URL": "https://api.nightpay.dev"
+        }
+      }
     }
   }
 }

package/skills/nightpay/rules/escrow-safety.md

@@ -81,6 +81,51 @@ The gateway operator bridges between chains by maintaining liquidity on both sid
 - DUST generation rate: ~1 week to reach full capacity from a NIGHT UTXO
 - 3-hour grace period on DUST timestamps
 
+## Pool Safety Guarantees (Enforced On-Chain)
+
+| Guarantee | How It's Enforced |
+|---|---|
+| **Exact contribution amounts** | `contributionAmount * maxFunders == fundingGoal` — no rounding dust, every funder pays the same |
+| **No double-funding** | Funding record is inserted into nullifier set — same funder + same pool + same nullifier rejected |
+| **No double-activation** | `activatePool` nullifies the pool commitment — second call reverts |
+| **No double-refund** | `claimRefund` inserts a refund nullifier — same funding record can only be refunded once |
+| **Refund only after expiry** | `claimRefund` checks for `hash(DOMAIN_REFUND, poolCommitment)` in nullifier set — only present after `expirePool` |
+| **No fee on expired pools** | `claimRefund` returns full contribution amount — fee is only deducted during `activatePool` |
+| **Pool funder cap** | `maxFunders <= MAX_POOL_FUNDERS (1000)` — prevents gas griefing on large pools |
+| **Activate-or-expire, never both** | `activatePool` and `expirePool` both check `!nullifiers.contains(poolCommitment)` — whichever runs first wins |
+
+## Off-Chain Deadline Trust Model
+
+Compact has no time primitives. Deadlines are enforced by the gateway:
+
+1. Pool creator specifies a deadline (e.g., 72 hours from now)
+2. Gateway tracks the deadline off-chain
+3. When the deadline passes without the goal being met, gateway calls `expirePool`
+4. `expirePool` inserts a refund marker — funders can now call `claimRefund`
+
+**Trust assumption:** The gateway can expire a pool early or refuse to expire it. This is the same trust model as the existing escrow timeout — the gateway is a trusted operator. Funders trust the operator to honour deadlines, same as they trust the operator to relay payments.
+
+**Mitigation:** The gateway address is locked at `initialize()` and the fee rate is public on-chain. A malicious gateway cannot steal funds (only delay expiry), because:
+- Funds in a non-expired pool are locked in the contract — nobody can withdraw them
+- Activating the pool releases funds to the locked gateway address only
+- Expiring the pool lets funders (not the gateway) reclaim their contributions
+
+## Emergency Refund Failsafe (Gateway-Free)
+
+If the gateway disappears or refuses to act, funders are NOT permanently locked out. The `emergencyRefund` circuit bypasses the gateway entirely:
+
+1. A monotonic `txCounter` increments on every state-changing circuit call
+2. At `fundPool` time, the current `txCounter` is baked into the funding record hash
+3. After `EMERGENCY_TX_THRESHOLD` (500) additional contract interactions have occurred, any funder can call `emergencyRefund` directly — no `expirePool` needed
+4. The circuit verifies the funding record exists in the tree, checks the txCounter gap, and returns the full contribution
+
+**Why txCounter and not real time?** Compact has no block height or timestamp primitives. The txCounter is the only on-chain monotonic value we can use. 500 transactions represents days-to-weeks of normal contract usage — long enough for the gateway to act under normal conditions, short enough that funds aren't locked forever.
+
+**Safety invariants:**
+- `emergencyRefund` checks `!nullifiers.contains(poolCommitment)` — if the pool was already activated, funds were released to the gateway and cannot be double-claimed
+- Same refund nullifier as `claimRefund` — prevents double-refund regardless of which path is used
+- No fee charged on emergency refunds
+
 ## Timeout Handling
 
 - Every bounty escrow has a configurable timeout (default: 60 minutes)
@@ -92,6 +137,15 @@ The gateway operator bridges between chains by maintaining liquidity on both sid
 
 ## Refund Conditions
 
+### Pool-level refunds (funding goal not met)
+
+- Gateway marks pool as expired after deadline passes
+- Each funder calls `claimRefund` with their funding record and nullifier
+- Full contribution returned — no fee charged
+- Funder-initiated (most private — funder proves their contribution, contract returns funds)
+
+### Bounty-level refunds (agent fails after pool activated)
+
 Automatic refund triggers:
 - Agent returns an error or refuses the job
 - Agent is unreachable (Masumi `/status` returns unavailable)
@@ -117,6 +171,14 @@ These are attacks that pass all basic validation but exploit deeper system prope
 | **DNS rebinding SSRF** | Attacker controls DNS → startup URL check passes (public IP) → A-record flips to 169.254.169.254 → all curl calls hit cloud metadata | `_ssrf_safe_curl()` re-resolves and re-validates every hostname on every request, not just at startup |
 | **Shell word splitting** | `openssl rand` or `sha256sum` output contains whitespace → variable splits into multiple tokens → hash computation silently corrupted | `generate_nonce()` pipes through `tr -d '[:space:]'`; `domain_hash()` uses `printf` instead of `echo -n` and strips whitespace from output |
 | **reporter_hash rainbow table** | `sha256(username)` is reversible for low-entropy inputs → reporters de-anonymised | `sha256(REPORTER_PEPPER + ":" + reporter_id)` — server-side pepper makes preimage attacks infeasible |
+| **Fake work submission** | Anyone knowing a `job_id` calls `POST /provide_input/<id>` with fabricated results | `job_token = HMAC-SHA256("nightpay-job-token-v1:{job_id}", JOB_TOKEN_SECRET)` — only the agent that called `start_job` holds the token; 401/403 on missing/invalid token |
+| **Result-swap after commit** | Agent waits to see funder's expected output, then constructs a matching `work_nonce` to pass reveal check | `work_commit = sha256("nightpay-work-reveal-v1:{work}:{nonce}")` committed at `start_job` before work begins — SHA-256 preimage resistance makes post-hoc matching infeasible |
+| **Multisig double-counting** | One approver submits two signatures with different nonces → counted as two votes | `used_keys` set in verifier tracks which key index already matched — each entry in `APPROVER_KEYS` counts at most once regardless of how many valid blobs it signs |
+| **Arbitrator keys in M-of-N** | `APPROVER_KEYS` may include community arbitrators; key compromise could approve completion | Same HMAC verification as operator keys; no separate role or endpoint — arbitrators use `approve-multisig`; key custody is per-approver responsibility |
+| **Stale approval replay** | Attacker captures a valid M-of-N approval blob and reuses it months later on a different job | Approval payload includes `job_id + output_hash + ts + nonce`; verifier rejects if `age > 86400s`; `job_id` binding makes blobs non-transferable |
+| **Clock skew abuse** | Approver pre-signs with a timestamp 25h in the future to extend the 24h expiry window | `age < -300s` check rejects approvals more than 5 minutes in the future |
+| **Optimistic double-complete** | `optimistic-sweep` cron and operator manually run `complete` concurrently on same job | Midnight nullifier set is canonical — second `completeAndReceipt` circuit call is rejected on-chain regardless of race condition off-chain |
+| **Job status filter injection** | `GET /jobs?status='; DROP TABLE jobs--` sent to MIP-003 server | `KNOWN_STATUSES` whitelist check before any DB query — unknown values return 400, never reach SQLite |
 | **Auto-freeze weaponisation** | Attacker creates N cheap reporter IDs → files N reports → any legitimate bounty silently frozen | Rate limit per reporter: max `REPORT_RATE_LIMIT` distinct bounties per `REPORT_WINDOW_HOURS`; freeze counts DISTINCT reporter hashes, not total complaint rows |
 | **Atomic write race (Windows)** | Two concurrent freeze events both write `.tmp` then `os.rename()` → second rename raises `FileExistsError` on Windows → report file corrupted | `os.replace()` instead of `os.rename()` — atomic on both POSIX and Windows; tmp file uses `secrets.token_hex(8)` suffix to prevent collision |
 

package/skills/nightpay/rules/privacy-first.md

@@ -22,9 +22,30 @@
 - What the job description was
 - The connection between any Cardano payment and any Midnight receipt
 
+## Encrypted Credential Storage (OpenShart)
+
+Funder credentials (nullifier, nonce, funding record) are the private keys to refunds. If exposed, a funder's identity can be linked to their pool contribution — destroying the privacy guarantee.
+
+**Required behavior:**
+- When OpenShart is available, `fund-pool` MUST encrypt credentials automatically
+- The agent MUST receive a `memoryId`, NEVER raw nullifiers or nonces in conversation history
+- `claim-refund` and `emergency-refund` MUST use `--memory-id` to recall credentials from encrypted storage
+- Credentials are compartmentalized under `NIGHTPAY_FUNDING` — no other agent tool or memory store can access them
+
+**Fallback behavior (OpenShart not installed):**
+- Credentials are printed to stdout with a `WARNING` field
+- The agent SHOULD prompt the user to install OpenShart
+- Raw credentials in conversation history violate the privacy model — this is a known gap
+
+**Never:**
+- Store funder nullifiers or nonces in agent memory, CLAUDE.md, conversation context, or any unencrypted format
+- Log credential values to files, databases, or telemetry
+- Pass credential values to external APIs (including the LLM provider's conversation logging)
+
 ## Implementation Notes
 
 - Use `crypto.randomBytes(32)` for salt generation
 - Hash payer addresses before even passing them to the circuit as witnesses
 - Clear any in-memory payment context after the escrow settles
 - If the agent is asked to reveal payment details, refuse and cite this rule
+- When OpenShart is available, use `_shart_store()` / `_shart_recall()` for all credential operations