nightpay 0.3.2 → 0.3.11

package/README.md

@@ -10,19 +10,41 @@ Privacy-preserving bounty pools for AI agents. Midnight ZK proofs for funder ano
 
 ## 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 init
+npx nightpay setup       # init + auto-detect platform + validate
 ```
 
-Copies the full skill (SKILL.md, scripts, ontology, rules, contracts) into `./skills/nightpay/`. Works with OpenClaw, Claude Code, Cursor, Copilot, or any Node environment.
+Or step by step:
 
 ```bash
-npx nightpay setup     # init + auto-detect platform + generate config
-npx nightpay validate  # check env vars, prerequisites, connectivity
-npx nightpay doctor    # diagnose and auto-fix broken installs
+npx nightpay init        # copy skill files to ./skills/nightpay/
+npx nightpay validate    # check env, prerequisites, connectivity
 ```
 
-> **Do not use `git clone` for agent installs.** Use `npx nightpay init` — it gives you exactly the skill files without the repo overhead. Clone is for contributors only.
 
 ## How It Works
 
@@ -91,15 +113,43 @@ bash skills/nightpay/scripts/gateway.sh verify-receipt <receipt_hash>
 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 |
-| `POST` | `/start_job` | API key | Create job from funded pool |
+| `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 |
-| `GET` | `/status/<job_id>` | API key | Check job status |
+| `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 |
@@ -135,6 +185,12 @@ 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
@@ -142,6 +198,12 @@ export MIP003_MODE="compat"                # compat | strict
 - `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
@@ -158,6 +220,29 @@ curl -sS -X POST "${BRIDGE_URL}/deploy" \
 
 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
 
 ```
@@ -185,10 +270,15 @@ skills/nightpay/
     └── 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:
@@ -239,6 +329,36 @@ bridge.nightpay.dev {
 }
 ```
 
+### 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)
@@ -248,7 +368,7 @@ bridge.nightpay.dev {
 
 | Platform | Install |
 |----------|---------|
-| **OpenClaw** | `npx nightpay setup` or `clawhub install nightpay` |
+| **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`) |
@@ -267,6 +387,7 @@ See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibil
 | [`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 |
 
@@ -279,4 +400,9 @@ See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibil
 
 ## License
 
-Apache-2.0
+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.

package/bin/cli.js

@@ -214,8 +214,16 @@ function validate() {
       execSync(`which ${bin}`, { stdio: "ignore" });
       console.log(`  ${OK} ${bin} found`);
     } catch {
-      console.log(`  ${FAIL} ${bin} not found`);
-      errors++;
+      if (bin === "sqlite3") {
+        // sqlite3 is only needed for local receipt caching — downgrade to warning
+        console.log(`  ${WARN} ${bin} not found ${C.dim}(optional — needed for local receipt caching only)${C.reset}`);
+        console.log(`       ${C.dim}Fix (Debian/Ubuntu): sudo apt-get install sqlite3${C.reset}`);
+        console.log(`       ${C.dim}Fix (macOS):         brew install sqlite3${C.reset}`);
+        warnings++;
+      } else {
+        console.log(`  ${FAIL} ${bin} not found`);
+        errors++;
+      }
     }
   }
 
@@ -232,10 +240,20 @@ function validate() {
   else console.log(`  ${INFO} python3 not found ${C.dim}(optional — needed for Python SDK)${C.reset}`);
 
   console.log(`\n${C.bold}Environment variables${C.reset}`);
+  // Apply defaults before validation
+  const DEFAULTS = {
+    NIGHTPAY_API_URL: "https://api.nightpay.dev",
+    MIDNIGHT_NETWORK: "preprod",
+    OPERATOR_FEE_BPS: "200",
+  };
+  for (const [key, def] of Object.entries(DEFAULTS)) {
+    if (!process.env[key]) process.env[key] = def;
+  }
+
   const required = {
     MASUMI_API_KEY: "Masumi payment API key",
     OPERATOR_ADDRESS: "Midnight operator address (64-char hex)",
-    NIGHTPAY_API_URL: "Deployed MIP-003 API URL",
+    NIGHTPAY_API_URL: "MIP-003 API URL",
     BRIDGE_URL: "Midnight bridge URL",
   };
 
@@ -482,8 +500,28 @@ function setup() {
       console.log(`  ${INFO} No .github/copilot-instructions.md — skipping Copilot config`);
     }
   } else if (platform === "openclaw") {
-    console.log(`  ${OK} OpenClaw auto-discovers skills from ./skills/nightpay/`);
-    console.log(`  ${C.dim}  Tip: merge openclaw-fragment.json into your openclaw.json${C.reset}`);
+    // Check if already installed as plugin
+    let pluginInstalled = false;
+    try {
+      const result = spawnSync("openclaw", ["plugins", "list", "--json"], { encoding: "utf8", stdio: "pipe" });
+      if (result.stdout && result.stdout.includes('"nightpay"')) pluginInstalled = true;
+    } catch {}
+
+    if (pluginInstalled) {
+      console.log(`  ${OK} NightPay plugin already installed in OpenClaw`);
+      console.log(`  ${C.dim}  Run: openclaw plugins enable nightpay${C.reset}`);
+    } else {
+      console.log(`  ${INFO} Installing NightPay as OpenClaw plugin...`);
+      const installResult = spawnSync("openclaw", ["plugins", "install", "nightpay"], { encoding: "utf8", stdio: "inherit" });
+      if (installResult.status === 0) {
+        console.log(`  ${OK} Installed! Run: ${C.cyan}openclaw plugins enable nightpay${C.reset}`);
+      } else {
+        console.log(`  ${WARN} Plugin install failed — falling back to skill files`);
+        console.log(`  ${C.dim}  Skill files are at ./skills/nightpay/ (already installed above)${C.reset}`);
+        console.log(`  ${C.dim}  Merge ./skills/nightpay/openclaw-fragment.json into openclaw.json${C.reset}`);
+      }
+    }
+    console.log(`  ${C.dim}  Set env: openclaw config set skills.entries.nightpay.env.MASUMI_API_KEY "your-key"${C.reset}`);
   } else {
     console.log(`  ${INFO} Raw platform — no config file needed`);
     console.log(`  ${C.dim}  Use: bash skills/nightpay/scripts/gateway.sh <command>${C.reset}`);