nightpay 0.2.0 → 0.2.1

package/skills/nightpay/scripts/gateway.sh

@@ -26,11 +26,21 @@
 
 set -euo pipefail
 
+# ─── Terminal colors ───────────────────────────────────────────────────────────
+# Gracefully disabled when stderr is not a TTY (CI, logs, pipes)
+if [[ -t 2 ]]; then
+  RED=$'\e[31m'; GREEN=$'\e[32m'; YELLOW=$'\e[33m'
+  CYAN=$'\e[36m'; BOLD=$'\e[1m'; DIM=$'\e[2m'; RESET=$'\e[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; CYAN=''; BOLD=''; DIM=''; RESET=''
+fi
+
 # ─── Required env vars ────────────────────────────────────────────────────────
 MASUMI_PAYMENT_URL="${MASUMI_PAYMENT_URL:-http://localhost:3001/api/v1}"
 MASUMI_REGISTRY_URL="${MASUMI_REGISTRY_URL:-http://localhost:3000/api/v1}"
 MASUMI_API_KEY="${MASUMI_API_KEY:?SECURITY: Set MASUMI_API_KEY}"
-MIDNIGHT_NETWORK="${MIDNIGHT_NETWORK:-testnet}"
+# Keep preprod default until Midnight mainnet is live.
+MIDNIGHT_NETWORK="${MIDNIGHT_NETWORK:-preprod}"
 OPERATOR_ADDRESS="${OPERATOR_ADDRESS:?SECURITY: Set OPERATOR_ADDRESS}"
 OPERATOR_FEE_BPS="${OPERATOR_FEE_BPS:-200}"
 MAX_BOUNTY_SPECKS="${MAX_BOUNTY_SPECKS:-500000000}"
@@ -102,7 +112,7 @@ for url in sys.argv[1:]:
         print(f'ERROR: {url} — must be http/https'); sys.exit(1)
 print('ok')
 " "$MASUMI_PAYMENT_URL" "$MASUMI_REGISTRY_URL" 2>&1) || {
-    echo "SECURITY ERROR: Invalid Masumi URL — $_url_check" >&2; exit 1
+    echo -e "${RED}SECURITY ERROR${RESET}: Invalid Masumi URL — $_url_check" >&2; exit 1
   }
 fi
 
@@ -127,10 +137,12 @@ try:
             print(f'SSRF blocked: {ip}', file=sys.stderr); sys.exit(1)
 except socket.gaierror as e:
     print(f'DNS error: {e}', file=sys.stderr); sys.exit(1)
-" "$url" || { echo "SECURITY ERROR: SSRF guard blocked request to $url" >&2; exit 1; }
+" "$url" || { echo -e "${RED}SECURITY ERROR${RESET}: SSRF guard blocked request to $url" >&2; exit 1; }
   curl -sf --max-time 30 "$@" "$url"
 }
 
+# ─── SSRF error (colored) — used by _ssrf_safe_curl ───────────────────────────
+
 masumi_get() {
   _ssrf_safe_curl "${MASUMI_REGISTRY_URL}${1}" \
     -H "Authorization: Bearer $MASUMI_API_KEY"
@@ -164,7 +176,7 @@ rate_limit() {
     local now; now=$(date +%s)
     local diff=$(( now - last_ts ))
     if (( diff < RATE_LIMIT_SECONDS )); then
-      echo "ERROR: Rate limit — wait $(( RATE_LIMIT_SECONDS - diff ))s before calling $cmd again" >&2
+      echo -e "${RED}ERROR${RESET}: Rate limit — wait ${BOLD}$(( RATE_LIMIT_SECONDS - diff ))s${RESET} before calling ${CYAN}$cmd${RESET} again" >&2
       exit 1
     fi
   fi
@@ -246,8 +258,8 @@ validate_job_id() {
 # The same HMAC can never be reused because the nonce is different every call.
 require_operator_auth() {
   if [[ -z "${OPERATOR_SECRET_KEY:-}" ]]; then
-    echo "SECURITY ERROR: withdraw-fees requires OPERATOR_SECRET_KEY env var." >&2
-    echo "This prevents unauthorized parties from draining accumulated fees." >&2
+    echo -e "${RED}SECURITY ERROR${RESET}: withdraw-fees requires ${BOLD}OPERATOR_SECRET_KEY${RESET} env var." >&2
+    echo -e "${DIM}This prevents unauthorized parties from draining accumulated fees.${RESET}" >&2
     exit 1
   fi
   local payload="$1"
@@ -365,6 +377,7 @@ OPTIMISTIC_WINDOW_HOURS="${OPTIMISTIC_WINDOW_HOURS:-48}"
 MULTISIG_THRESHOLD_SPECKS="${MULTISIG_THRESHOLD_SPECKS:-1000000}"
 MULTISIG_M="${MULTISIG_M:-2}"
 MULTISIG_N="${MULTISIG_N:-3}"
+OPTIMISTIC_SWEEP_PAGE_SIZE="${OPTIMISTIC_SWEEP_PAGE_SIZE:-200}"   # capped to <= 500
 # APPROVER_KEYS: comma-separated HMAC secrets, one per approver
 # e.g. APPROVER_KEYS="key1secret,key2secret,key3secret"
 APPROVER_KEYS="${APPROVER_KEYS:-}"
@@ -399,8 +412,8 @@ print(json.dumps({'jobHash': sys.argv[1], 'amount': int(sys.argv[2]), 'nonce': s
       BRIDGE_RESULT=$(bridge_post "/postBounty" "$BRIDGE_PAYLOAD" 2>/dev/null) && {
         TX_ID=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('txId',''))" 2>/dev/null)
         ON_CHAIN=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print('false' if d.get('stub') else 'true')" 2>/dev/null)
-        echo "  Midnight TX: $TX_ID (on-chain: $ON_CHAIN)" >&2
-      } || echo "  WARNING: Bridge unavailable — commitment computed locally only" >&2
+        echo -e "  ${GREEN}Midnight TX${RESET}: ${DIM}$TX_ID${RESET} ${CYAN}(on-chain: $ON_CHAIN)${RESET}" >&2
+      } || echo -e "  ${YELLOW}WARNING${RESET}: Bridge unavailable — commitment computed locally only" >&2
     fi
 
     # SECURITY: nonce printed once for the caller to store securely.
@@ -515,11 +528,11 @@ except: print(0)
 
     if (( JOB_AMOUNT >= MULTISIG_THRESHOLD_SPECKS )); then
       if [[ -z "$APPROVALS_RAW" || "$APPROVALS_FLAG" != "--approvals" ]]; then
-        echo "ERROR: job amount ${JOB_AMOUNT} specks >= threshold ${MULTISIG_THRESHOLD_SPECKS}" >&2
-        echo "  Multisig required. Each approver runs:" >&2
-        echo "    gateway.sh approve-multisig $JOB_ID <output_hash> <approver_key>" >&2
-        echo "  Then collect M approval_blobs and run:" >&2
-        echo "    gateway.sh complete $JOB_ID $COMMITMENT --approvals blob1,blob2" >&2
+        echo -e "${RED}ERROR${RESET}: job amount ${BOLD}${JOB_AMOUNT} specks${RESET} >= threshold ${MULTISIG_THRESHOLD_SPECKS}" >&2
+        echo -e "${YELLOW}Multisig required.${RESET} Each approver runs:" >&2
+        echo -e "  ${CYAN}gateway.sh approve-multisig${RESET} $JOB_ID <output_hash> <approver_key>" >&2
+        echo -e "Then collect M approval_blobs and run:" >&2
+        echo -e "  ${CYAN}gateway.sh complete${RESET} $JOB_ID $COMMITMENT --approvals blob1,blob2" >&2
         exit 1
       fi
 
@@ -576,10 +589,10 @@ else:
     print(f'ERROR: only {valid_count} valid approvals, need {required_m}', file=sys.stderr)
     sys.exit(1)
 " "$JOB_ID" "$COMMITMENT" "$APPROVALS_RAW" "$APPROVER_KEYS" "$MULTISIG_M" 2>&1) || {
-        echo "SECURITY ERROR: multisig verification failed — $VERIFY_OK" >&2
+        echo -e "${RED}SECURITY ERROR${RESET}: multisig verification failed — $VERIFY_OK" >&2
         exit 1
       }
-      echo "  Multisig: $VERIFY_OK approvals verified" >&2
+      echo -e "  ${GREEN}Multisig${RESET}: $VERIFY_OK approvals verified" >&2
     fi
 
     RESULT_DATA=$(masumi_get "/purchases/$JOB_ID/result")
@@ -609,8 +622,27 @@ print(json.dumps({'bountyCommitment': sys.argv[1], 'outputHash': sys.argv[2]}))
       BRIDGE_RESULT=$(bridge_post "/completeAndReceipt" "$BRIDGE_PAYLOAD" 2>/dev/null) && {
         BRIDGE_TX_ID=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('txId',''))" 2>/dev/null)
         BRIDGE_ON_CHAIN=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print('false' if d.get('stub') else 'true')" 2>/dev/null)
-        echo "  Midnight TX: $BRIDGE_TX_ID (on-chain: $BRIDGE_ON_CHAIN)" >&2
-      } || echo "  WARNING: Bridge unavailable — receipt computed locally only" >&2
+        echo -e "  ${GREEN}Midnight TX${RESET}: ${DIM}$BRIDGE_TX_ID${RESET} ${CYAN}(on-chain: $BRIDGE_ON_CHAIN)${RESET}" >&2
+      } || echo -e "  ${YELLOW}WARNING${RESET}: Bridge unavailable — receipt computed locally only" >&2
+    fi
+
+    # Fetch economics from MIP-003 for the cost footer (ClawWork pattern)
+    _ECON_AMOUNT=0
+    _ECON_FEE=0
+    _ECON_NET=0
+    if command -v curl >/dev/null 2>&1; then
+      _ECON_INFO=$(curl -sf --max-time 3 "http://localhost:${MIP003_PORT}/status/${JOB_ID}" 2>/dev/null || echo '{}')
+      read -r _ECON_AMOUNT _ECON_FEE _ECON_NET <<< "$(python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    amount = int(d.get('amount_specks') or 0)
+    fee_bps = int('${OPERATOR_FEE_BPS}')
+    fee = amount * fee_bps // 10000
+    net = amount - fee
+    print(amount, fee, net)
+except: print(0, 0, 0)
+" <<< "$_ECON_INFO" 2>/dev/null || echo "0 0 0")"
     fi
 
     python3 -c "
@@ -624,9 +656,16 @@ print(json.dumps({
     'midnightNetwork': sys.argv[5],
     'receiptContract': sys.argv[6],
     'midnightTxId': sys.argv[7] or None,
-    'onChain': sys.argv[8] == 'true'
+    'onChain': sys.argv[8] == 'true',
+    # Economics footer — ClawWork-compatible cost accounting shape
+    'economics': {
+        'amountSpecks': int(sys.argv[9]),
+        'fee':          int(sys.argv[10]),
+        'netToAgent':   int(sys.argv[11]),
+        'feeBps':       int(sys.argv[12]),
+    },
 }, indent=2))
-" "$RECEIPT_HASH" "$OUTPUT_HASH" "$COMMITMENT" "$COMPLETION_NONCE" "$MIDNIGHT_NETWORK" "$RECEIPT_CONTRACT" "$BRIDGE_TX_ID" "$BRIDGE_ON_CHAIN"
+" "$RECEIPT_HASH" "$OUTPUT_HASH" "$COMMITMENT" "$COMPLETION_NONCE" "$MIDNIGHT_NETWORK" "$RECEIPT_CONTRACT" "$BRIDGE_TX_ID" "$BRIDGE_ON_CHAIN" "$_ECON_AMOUNT" "$_ECON_FEE" "$_ECON_NET" "$OPERATOR_FEE_BPS"
     ;;
 
   refund)
@@ -637,7 +676,7 @@ print(json.dumps({
     validate_commitment "$COMMITMENT"
 
     # Step 1: Cancel Masumi escrow on Cardano
-    echo "Cancelling Masumi escrow for job $JOB_ID..." >&2
+    echo -e "${CYAN}Cancelling Masumi escrow${RESET} for job ${BOLD}$JOB_ID${RESET}..." >&2
     masumi_post "/purchases/$JOB_ID/cancel" "{}"
 
     # Step 2: Emit on-chain NIGHT refund intent for the Midnight contract.
@@ -683,10 +722,10 @@ print(json.dumps({
     ;;
 
   stats)
-    echo "Querying nightpay stats from $RECEIPT_CONTRACT on $MIDNIGHT_NETWORK..." >&2
+    echo -e "${CYAN}Querying nightpay stats${RESET} from ${DIM}$RECEIPT_CONTRACT${RESET} on ${BOLD}$MIDNIGHT_NETWORK${RESET}..." >&2
     if [[ -n "$BRIDGE_URL" ]]; then
       bridge_get "/stats" && exit 0
-      echo "  WARNING: Bridge unavailable — showing placeholder" >&2
+      echo -e "  ${YELLOW}WARNING${RESET}: Bridge unavailable — showing placeholder" >&2
     fi
     python3 -c "
 import sys, json
@@ -707,10 +746,14 @@ print(json.dumps({
     [[ "${1:-}" == "--dry-run" ]] && DRY_RUN=1
 
     MIP003_URL="http://localhost:${MIP003_PORT}"
-    echo "Scanning for auto-approvable jobs (window=${OPTIMISTIC_WINDOW_HOURS}h, url=${MIP003_URL})..." >&2
+    echo -e "${CYAN}Scanning for auto-approvable jobs${RESET} ${DIM}(window=${OPTIMISTIC_WINDOW_HOURS}h, url=${MIP003_URL}, pageSize=${OPTIMISTIC_SWEEP_PAGE_SIZE})${RESET}..." >&2
 
-    # Fetch jobs in awaiting_approval state
-    JOBS_JSON=$(curl -sf --max-time 10 "${MIP003_URL}/jobs?status=awaiting_approval" 2>/dev/null || echo '{"jobs":[]}')
+    # Fetch one paginated slice of jobs ready for optimistic completion.
+    NOW_ISO=$(python3 -c "
+from datetime import datetime, timezone
+print(datetime.now(timezone.utc).isoformat())
+")
+    JOBS_JSON=$(curl -sf --max-time 10 "${MIP003_URL}/jobs?status=awaiting_approval&approved_before=${NOW_ISO}&limit=${OPTIMISTIC_SWEEP_PAGE_SIZE}&offset=0" 2>/dev/null || echo '{"jobs":[]}')
 
     # Filter for expired windows and auto-complete each
     python3 -c "
@@ -772,7 +815,21 @@ print(f'Sweep complete: {done} completed, {errors} errors.', file=sys.stderr)
     ;;
 
   *)
-    echo "Commands: post-bounty, find-agent, hire-and-pay, check-job, complete, refund, withdraw-fees, stats, approve-multisig, optimistic-sweep"
+    echo -e "${BOLD}nightpay gateway${RESET} — anonymous bounty lifecycle CLI" >&2
+    echo "" >&2
+    echo -e "${BOLD}Commands:${RESET}" >&2
+    echo -e "  ${CYAN}post-bounty${RESET}      <desc> <amount>            Fund a bounty anonymously" >&2
+    echo -e "  ${CYAN}find-agent${RESET}       <query>                    Search Masumi for agents" >&2
+    echo -e "  ${CYAN}hire-and-pay${RESET}     <agent> <desc> <hash>      Create escrow, start job" >&2
+    echo -e "  ${CYAN}check-job${RESET}        <job_id>                   Poll job status" >&2
+    echo -e "  ${CYAN}complete${RESET}         <job_id> <hash>            Mint receipt, release payment" >&2
+    echo -e "  ${CYAN}refund${RESET}           <job_id> <hash>            Cancel escrow, refund NIGHT" >&2
+    echo -e "  ${CYAN}approve-multisig${RESET} <id> <hash> <key>          Sign high-value approval" >&2
+    echo -e "  ${CYAN}optimistic-sweep${RESET} [--dry-run]                Auto-complete expired windows" >&2
+    echo -e "  ${CYAN}withdraw-fees${RESET}    [amount]                   Operator fee withdrawal" >&2
+    echo -e "  ${CYAN}stats${RESET}                                       On-chain contract stats" >&2
+    echo "" >&2
+    echo -e "${DIM}Required: MASUMI_API_KEY  MIDNIGHT_NETWORK  OPERATOR_ADDRESS  RECEIPT_CONTRACT_ADDRESS${RESET}" >&2
     exit 1
     ;;
 esac

package/skills/nightpay/scripts/mip003-server.sh

@@ -12,6 +12,7 @@
 #   OPERATOR_SECRET_KEY    — HMAC secret for operator dispute auth
 #
 # Optional env vars:
+#   IDEMPOTENCY_TTL_SECONDS    - dedupe window for X-Idempotency-Key (default: 86400)
 #   OPTIMISTIC_WINDOW_HOURS    — hours before auto-complete fires (default: 48)
 #   MULTISIG_THRESHOLD_SPECKS  — above this value, multisig required (default: 1000000)
 #
@@ -35,6 +36,14 @@
 
 set -euo pipefail
 
+# ─── Terminal colors ───────────────────────────────────────────────────────────
+if [[ -t 2 ]]; then
+  GREEN=$'\e[32m'; YELLOW=$'\e[33m'; CYAN=$'\e[36m'
+  BOLD=$'\e[1m'; DIM=$'\e[2m'; RED=$'\e[31m'; RESET=$'\e[0m'
+else
+  GREEN=''; YELLOW=''; CYAN=''; BOLD=''; DIM=''; RED=''; RESET=''
+fi
+
 PORT="${1:-8090}"
 DATA_DIR="${DATA_DIR:-${HOME}/.nightpay}"
 DB_PATH="${DATA_DIR}/jobs.db"
@@ -43,13 +52,17 @@ JOB_TOKEN_SECRET="${JOB_TOKEN_SECRET:?SECURITY: Set JOB_TOKEN_SECRET env var}"
 OPERATOR_SECRET_KEY="${OPERATOR_SECRET_KEY:?SECURITY: Set OPERATOR_SECRET_KEY env var}"
 OPTIMISTIC_WINDOW_HOURS="${OPTIMISTIC_WINDOW_HOURS:-48}"
 MULTISIG_THRESHOLD_SPECKS="${MULTISIG_THRESHOLD_SPECKS:-1000000}"
+OPERATOR_FEE_BPS="${OPERATOR_FEE_BPS:-200}"
+IDEMPOTENCY_TTL_SECONDS="${IDEMPOTENCY_TTL_SECONDS:-86400}"
 
 mkdir -p "$DATA_DIR"
 chmod 700 "$DATA_DIR"
 
-command -v python3 >/dev/null 2>&1 || { echo "python3 required"; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo -e "${RED}ERROR${RESET}: python3 required" >&2; exit 1; }
 
-echo "nightpay MIP-003 service starting on port $PORT..."
+echo -e "${GREEN}◆${RESET} ${BOLD}nightpay${RESET} MIP-003 service listening on ${CYAN}:${PORT}${RESET}" >&2
+echo -e "${DIM}  DB: ${DB_PATH}${RESET}" >&2
+echo -e "${DIM}  optimistic window: ${OPTIMISTIC_WINDOW_HOURS}h  |  multisig threshold: ${MULTISIG_THRESHOLD_SPECKS} specks${RESET}" >&2
 
 python3 -c "
 import http.server, json, uuid, sys, sqlite3, threading, hmac, hashlib, re, os
@@ -62,6 +75,8 @@ JOB_TOKEN_SECRET         = sys.argv[3]
 OPERATOR_SECRET_KEY      = sys.argv[4]
 OPTIMISTIC_WINDOW_HOURS  = int(sys.argv[5])
 MULTISIG_THRESHOLD_SPECKS = int(sys.argv[6])
+os.environ['OPERATOR_FEE_BPS'] = sys.argv[7]
+IDEMPOTENCY_TTL_SECONDS  = int(sys.argv[8])
 
 KNOWN_STATUSES = ('running', 'awaiting_approval', 'multisig_pending', 'disputed', 'completed')
 
@@ -86,6 +101,13 @@ def verify_operator_sig(job_id, reason, sig):
     expected = hmac.new(OPERATOR_SECRET_KEY.encode(), msg.encode(), hashlib.sha256).hexdigest()
     return hmac.compare_digest(expected, sig)
 
+def hash_start_job_request(body):
+    # Canonical payload hash used for idempotency conflict detection.
+    payload = dict(body)
+    payload.pop('idempotency_key', None)
+    canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
 # ─── SQLite ───────────────────────────────────────────────────────────────────
 
 local = threading.local()
@@ -117,8 +139,18 @@ conn.executescript('''
         approvals      TEXT
     );
     CREATE INDEX IF NOT EXISTS idx_jobs_status   ON jobs(status);
+    CREATE INDEX IF NOT EXISTS idx_jobs_status_approved ON jobs(status, approved_at)
+        WHERE approved_at IS NOT NULL;
     CREATE INDEX IF NOT EXISTS idx_jobs_approved ON jobs(approved_at)
         WHERE approved_at IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS idempotency_keys (
+        idem_key     TEXT PRIMARY KEY,
+        request_hash TEXT NOT NULL,
+        job_id       TEXT NOT NULL,
+        created_at   TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_idempotency_created_at ON idempotency_keys(created_at);
 ''')
 # Idempotent migration for existing DBs (ALTER TABLE is safe — ignores dup column)
 for col_def in [
@@ -185,6 +217,10 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                     'work_commit': {
                         'type': 'string',
                         'description': 'sha256(nightpay-work-reveal-v1:{work}:{nonce}) — commit before reveal'
+                    },
+                    'idempotency_key': {
+                        'type': 'string',
+                        'description': 'Optional replay-safe key; also accepted via X-Idempotency-Key header'
                     }
                 },
                 'required': ['description', 'amount_specks']
@@ -210,25 +246,74 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                 self.respond(200, job)
 
         elif self.path.startswith('/jobs'):
-            # GET /jobs?status=<value> — used by optimistic-sweep in gateway.sh
+            # GET /jobs?status=<value>&limit=<n>&offset=<n>&approved_before=<iso8601>
+            # used by optimistic-sweep and dashboards.
             parsed = urlparse(self.path)
             params = parse_qs(parsed.query)
             status_filter = params.get('status', [None])[0]
+            approved_before = params.get('approved_before', [None])[0]
+
+            # SECURITY: clamp pagination to bounded values
+            try:
+                limit = int(params.get('limit', ['100'])[0])
+                offset = int(params.get('offset', ['0'])[0])
+            except ValueError:
+                self.respond(400, {'error': 'limit and offset must be integers'})
+                return
+            if limit < 1 or limit > 500:
+                self.respond(400, {'error': 'limit must be between 1 and 500'})
+                return
+            if offset < 0 or offset > 1000000:
+                self.respond(400, {'error': 'offset must be between 0 and 1000000'})
+                return
 
-            # SECURITY: whitelist status values — prevents SQL injection via status param
+            # SECURITY: whitelist status values - prevents SQL injection via status param
             if status_filter and status_filter not in KNOWN_STATUSES:
                 self.respond(400, {'error': f'unknown status filter: {status_filter}'})
                 return
 
+            if approved_before:
+                try:
+                    datetime.fromisoformat(approved_before.replace('Z', '+00:00'))
+                except ValueError:
+                    self.respond(400, {'error': 'approved_before must be ISO-8601'})
+                    return
+
             db = get_db()
-            if status_filter:
+            if status_filter and approved_before:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE status = ? AND approved_at IS NOT NULL AND approved_at <= ? '
+                    'ORDER BY approved_at ASC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (status_filter, approved_before, limit, offset)
+                ).fetchall()
+            elif status_filter:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE status = ? '
+                    'ORDER BY updated_at DESC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (status_filter, limit, offset)
+                ).fetchall()
+            elif approved_before:
                 rows = db.execute(
-                    'SELECT job_id, status, approved_at, amount_specks, input_data FROM jobs WHERE status = ? LIMIT 500',
-                    (status_filter,)
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE approved_at IS NOT NULL AND approved_at <= ? '
+                    'ORDER BY approved_at ASC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (approved_before, limit, offset)
                 ).fetchall()
             else:
                 rows = db.execute(
-                    'SELECT job_id, status, approved_at, amount_specks, input_data FROM jobs LIMIT 500'
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'ORDER BY updated_at DESC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (limit, offset)
                 ).fetchall()
 
             jobs = []
@@ -241,7 +326,13 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                         pass
                 jobs.append(j)
 
-            self.respond(200, {'jobs': jobs})
+            self.respond(200, {
+                'jobs': jobs,
+                'limit': limit,
+                'offset': offset,
+                'count': len(jobs),
+                'has_more': len(jobs) == limit
+            })
 
         else:
             self.respond(404, {'error': 'not found'})
@@ -252,14 +343,14 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
         body = self._read_body()
 
         if self.path == '/start_job':
-            # ── Validate optional work_commit ─────────────────────────────
+            # Validate optional work_commit
             work_commit = body.get('work_commit')
             if work_commit is not None:
                 if not re.match(r'^[0-9a-f]{64}$', str(work_commit)):
                     self.respond(400, {'error': 'work_commit must be 64-char lowercase hex sha256'})
                     return
 
-            # ── Validate optional amount_specks ───────────────────────────
+            # Validate optional amount_specks
             amount_specks = body.get('amount_specks')
             if amount_specks is not None:
                 try:
@@ -270,25 +361,100 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                     self.respond(400, {'error': 'amount_specks must be a non-negative integer'})
                     return
 
-            job_id = str(uuid.uuid4())
-            now    = datetime.now(timezone.utc).isoformat()
-            db     = get_db()
-            db.execute(
-                '''INSERT INTO jobs(job_id, status, input_data, work_commit, amount_specks, started_at, updated_at)
-                   VALUES (?, ?, ?, ?, ?, ?, ?)''',
-                (job_id, 'running', json.dumps(body.get('input_data', {})),
-                 work_commit, amount_specks, now, now)
-            )
-            db.commit()
+            # Optional idempotency key: header and body must match if both provided.
+            idem_header = self.headers.get('X-Idempotency-Key', '').strip()
+            idem_body_raw = body.get('idempotency_key')
+            idem_body = str(idem_body_raw).strip() if idem_body_raw is not None else ''
+            if idem_header and idem_body and idem_header != idem_body:
+                self.respond(400, {'error': 'idempotency_key body value does not match X-Idempotency-Key header'})
+                return
 
-            # SECURITY: job_token is ephemeral — derived on demand, never stored
-            job_token = make_job_token(job_id)
+            idempotency_key = idem_header or idem_body or None
+            request_hash = None
+            if idempotency_key is not None:
+                if not re.match(r'^[A-Za-z0-9._:-]{8,128}$', idempotency_key):
+                    self.respond(400, {'error': 'idempotency key must match [A-Za-z0-9._:-] and be 8-128 chars'})
+                    return
+                request_hash = hash_start_job_request(body)
 
-            self.respond(200, {
+            now_dt = datetime.now(timezone.utc)
+            now = now_dt.isoformat()
+            db = get_db()
+
+            if idempotency_key:
+                # BEGIN IMMEDIATE serializes writers and prevents duplicate inserts for same key.
+                db.execute('BEGIN IMMEDIATE')
+                try:
+                    if IDEMPOTENCY_TTL_SECONDS > 0:
+                        cutoff = (now_dt - timedelta(seconds=IDEMPOTENCY_TTL_SECONDS)).isoformat()
+                        db.execute('DELETE FROM idempotency_keys WHERE created_at < ?', (cutoff,))
+
+                    existing = db.execute(
+                        'SELECT request_hash, job_id FROM idempotency_keys WHERE idem_key = ?',
+                        (idempotency_key,)
+                    ).fetchone()
+
+                    if existing:
+                        if not hmac.compare_digest(existing['request_hash'], request_hash):
+                            db.rollback()
+                            self.respond(409, {'error': 'idempotency key already used with different payload'})
+                            return
+
+                        job_id = existing['job_id']
+                        row = db.execute(
+                            'SELECT status FROM jobs WHERE job_id = ?',
+                            (job_id,)
+                        ).fetchone()
+                        db.rollback()
+
+                        if not row:
+                            self.respond(500, {'error': 'idempotency mapping references missing job'})
+                            return
+
+                        self.respond(200, {
+                            'job_id': job_id,
+                            'job_token': make_job_token(job_id),
+                            'status': row['status'],
+                            'idempotent_replay': True
+                        })
+                        return
+
+                    job_id = str(uuid.uuid4())
+                    db.execute(
+                        '''INSERT INTO jobs(job_id, status, input_data, work_commit, amount_specks, started_at, updated_at)
+                           VALUES (?, ?, ?, ?, ?, ?, ?)''',
+                        (job_id, 'running', json.dumps(body.get('input_data', {})),
+                         work_commit, amount_specks, now, now)
+                    )
+                    db.execute(
+                        '''INSERT INTO idempotency_keys(idem_key, request_hash, job_id, created_at)
+                           VALUES (?, ?, ?, ?)''',
+                        (idempotency_key, request_hash, job_id, now)
+                    )
+                    db.commit()
+                except Exception:
+                    db.rollback()
+                    raise
+            else:
+                job_id = str(uuid.uuid4())
+                db.execute(
+                    '''INSERT INTO jobs(job_id, status, input_data, work_commit, amount_specks, started_at, updated_at)
+                       VALUES (?, ?, ?, ?, ?, ?, ?)''',
+                    (job_id, 'running', json.dumps(body.get('input_data', {})),
+                     work_commit, amount_specks, now, now)
+                )
+                db.commit()
+
+            # SECURITY: job_token is ephemeral - derived on demand, never stored
+            job_token = make_job_token(job_id)
+            response = {
                 'job_id':    job_id,
                 'job_token': job_token,
                 'status':    'running'
-            })
+            }
+            if idempotency_key:
+                response['idempotency_key'] = idempotency_key
+            self.respond(200, response)
 
         elif self.path.startswith('/provide_input/'):
             job_id = self.path.split('/')[-1]
@@ -360,6 +526,93 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                                else 'work accepted, awaiting multisig approval'
             })
 
+        elif self.path.startswith('/provide_result/'):
+            # ClawWork-compatible: agent delivers final work output + artifact paths.
+            # Mirrors ClawWork's submit_work tool: accepts work_output + artifact_file_paths,
+            # sets job to awaiting_approval (or multisig_pending for high-value jobs),
+            # and returns payment economics so the calling agent sees its net payout.
+            job_id = self.path.split('/')[-1]
+
+            if not self._validate_job_id(job_id):
+                self.respond(400, {'error': 'invalid job_id format'})
+                return
+
+            # SECURITY: require valid job_token
+            auth_header = self.headers.get('Authorization', '')
+            if not auth_header.startswith('Bearer '):
+                self.respond(401, {'error': 'Authorization: Bearer <job_token> required'})
+                return
+            provided_token = auth_header[len('Bearer '):]
+            if not verify_job_token(job_id, provided_token):
+                self.respond(403, {'error': 'invalid job_token'})
+                return
+
+            work_output = str(body.get('work_output', ''))
+            artifact_paths = body.get('artifact_file_paths', [])
+            if not isinstance(artifact_paths, list):
+                artifact_paths = []
+
+            if len(work_output) < 10:
+                self.respond(400, {'error': 'work_output must be at least 10 chars'})
+                return
+
+            db  = get_db()
+            row = db.execute(
+                'SELECT work_commit, amount_specks, status FROM jobs WHERE job_id = ?',
+                (job_id,)
+            ).fetchone()
+            if not row:
+                self.respond(404, {'error': 'job not found'})
+                return
+            if row['status'] != 'running':
+                self.respond(409, {'error': f'job is not running (status: {row["status"]})'})
+                return
+
+            now           = datetime.now(timezone.utc)
+            amount_specks = row['amount_specks'] or 0
+            fee_bps       = int(os.environ.get('OPERATOR_FEE_BPS', '200'))
+            fee           = amount_specks * fee_bps // 10000
+            net_to_agent  = amount_specks - fee
+
+            if amount_specks >= MULTISIG_THRESHOLD_SPECKS:
+                next_status = 'multisig_pending'
+                approved_at = None
+            else:
+                next_status = 'awaiting_approval'
+                approved_at = (now + timedelta(hours=OPTIMISTIC_WINDOW_HOURS)).isoformat()
+
+            result_payload = json.dumps({
+                'work_output':      work_output[:500],  # store truncated — full output is agent-side
+                'artifact_paths':   artifact_paths,
+                'artifact_count':   len(artifact_paths),
+            })
+
+            db.execute(
+                '''UPDATE jobs
+                   SET result = ?, status = ?, approved_at = ?, updated_at = ?
+                   WHERE job_id = ?''',
+                (result_payload, next_status, approved_at, now.isoformat(), job_id)
+            )
+            db.commit()
+
+            self.respond(200, {
+                'status':        next_status,
+                'approved_at':   approved_at,
+                'artifact_count': len(artifact_paths),
+                # Economics footer — ClawWork-compatible shape
+                'economics': {
+                    'amount_specks': amount_specks,
+                    'fee':           fee,
+                    'net_to_agent':  net_to_agent,
+                    'fee_bps':       fee_bps,
+                },
+                'message': (
+                    'work accepted, optimistic window started'
+                    if next_status == 'awaiting_approval'
+                    else 'work accepted, awaiting multisig approval'
+                ),
+            })
+
         elif self.path.startswith('/dispute/'):
             job_id = self.path.split('/')[-1]
 
@@ -414,7 +667,8 @@ class ThreadedHTTPServer(http.server.ThreadingHTTPServer):
 httpd = ThreadedHTTPServer(('0.0.0.0', PORT), MIP003Handler)
 print(f'[nightpay] MIP-003 threaded service ready on port {PORT}')
 print(f'[nightpay] DB: {DB_PATH}')
-print(f'[nightpay] Optimistic window: {OPTIMISTIC_WINDOW_HOURS}h | Multisig threshold: {MULTISIG_THRESHOLD_SPECKS} specks')
-print(f'[nightpay] Endpoints: /availability /input_schema /start_job /status/<id> /provide_input/<id> /dispute/<id> /jobs')
+print(f'[nightpay] Optimistic window: {OPTIMISTIC_WINDOW_HOURS}h | Multisig threshold: {MULTISIG_THRESHOLD_SPECKS} specks | Fee: {os.environ.get('OPERATOR_FEE_BPS','200')} bps')
+print(f'[nightpay] Idempotency TTL: {IDEMPOTENCY_TTL_SECONDS}s (X-Idempotency-Key)')
+print(f'[nightpay] Endpoints: /availability /input_schema /start_job /status/<id> /provide_input/<id> /provide_result/<id> /dispute/<id> /jobs?status=&limit=&offset=&approved_before=')
 httpd.serve_forever()
-" "$PORT" "$DB_PATH" "$JOB_TOKEN_SECRET" "$OPERATOR_SECRET_KEY" "$OPTIMISTIC_WINDOW_HOURS" "$MULTISIG_THRESHOLD_SPECKS"
+" "$PORT" "$DB_PATH" "$JOB_TOKEN_SECRET" "$OPERATOR_SECRET_KEY" "$OPTIMISTIC_WINDOW_HOURS" "$MULTISIG_THRESHOLD_SPECKS" "$OPERATOR_FEE_BPS" "$IDEMPOTENCY_TTL_SECONDS"