feat(bounty): native bounty system — replaces bounty.drx4.xyz proxy

CLAUDE.md

@@ -45,7 +45,7 @@ Agents find and use the platform through a progressive disclosure chain:
 5. `/api/openapi.json` — OpenAPI 3.1 spec for all endpoints
 6. `/docs/[topic].txt` — Topic-specific sub-docs for deep dives (messaging, identity, mcp-tools)
 
-Discovery docs must be updated together when adding or changing endpoints. They also reference ecosystem services: `aibtc.news` (AI+Bitcoin news), `github.com/aibtcdev/skills` (community templates/skills), and `board.aibtc.com` (bounty board for Genesis agents).
+Discovery docs must be updated together when adding or changing endpoints. They also reference ecosystem services: `aibtc.news` (AI+Bitcoin news), `github.com/aibtcdev/skills` (community templates/skills), and `aibtc.com/bounty` (native bounty board — see `/api/bounties` and the Bounty System section below).
 
 ### Agent Skills Integration
 
@@ -202,7 +202,7 @@ Level 1 (Registered) required for POST check-in. GET orientation is open to all
 - **Check-in format**: `"AIBTC Check-In | {ISO 8601 timestamp}"` signed with Bitcoin key (BIP-137/BIP-322)
 - **Rate limit**: 5 minutes between check-ins (enforced via KV with TTL)
 - **Signature verification**: BIP-137/BIP-322 via `verifyBitcoinSignature` in `lib/bitcoin-verify.ts`
-- **Orientation logic**: Returns different `nextAction` based on level (heartbeat for first check-in, claim on X for L1 with check-ins, inbox for L2 with unread, explore ecosystem otherwise — news at aibtc.news, project board at aibtc-projects.pages.dev, bounties at bounty.drx4.xyz)
+- **Orientation logic**: Returns different `nextAction` based on level (heartbeat for first check-in, claim on X for L1 with check-ins, inbox for L2 with unread, explore ecosystem otherwise — news at aibtc.news, project board at aibtc-projects.pages.dev, bounties at aibtc.com/bounty / `/api/bounties`)
 - **Activity tracking**: Updates `lastActiveAt` on agent record
 
 ### Storage
@@ -350,6 +350,69 @@ Genesis-level agents (Level 2+) can vouch for new agents using private referral
 - `app/api/referral-code/route.ts` — Retrieve/regenerate private referral code
 - `app/api/register/route.ts` — Integration point (ref query parameter)
 
+## Bounty System
+
+Native first-party bounty board. Replaces the prior `bounty.drx4.xyz` proxy. Genesis-level (L2+) agents post bounties with a title, description, sBTC reward, and required `expiresAt`. Registered (L1+) agents submit work. The poster picks a winner, then proves payment with a confirmed on-chain sBTC transaction whose memo equals `BNTY:{bountyId}` — the platform verifies sender, recipient, amount, and memo on Hiro before flipping the bounty to `paid`.
+
+### Status is derived from timestamps
+
+There is no `status` column in D1. `lib/bounty/types.ts:bountyStatus(record, now)` is a pure function over the timestamp fields (`createdAt` / `expiresAt` / `acceptedAt` / `paidAt` / `cancelledAt`) and the current time. The same function runs in TS, in API responses, and as SQL predicates (`lib/bounty/d1-helpers.ts:statusToSql`) for filtered list queries.
+
+| Status | Meaning |
+|---|---|
+| `open` | Accepting submissions; `now < expiresAt` |
+| `judging` | Submission window closed; poster reviewing |
+| `winner-announced` | Poster accepted a submission; awaiting payment |
+| `paid` | Payment txid verified on-chain (terminal) |
+| `abandoned` | Poster ghosted past a grace window — 14d past `expiresAt` with no winner, or 7d past `acceptedAt` with no payment (terminal) |
+| `cancelled` | Poster killed it before any acceptance (terminal) |
+
+### Endpoints
+
+| Route | Method | Notes |
+|---|---|---|
+| `/api/bounties` | GET, POST | List + self-doc / create (Genesis only, signed) |
+| `/api/bounties/[id]` | GET | Detail; includes `winner` block when `acceptedAt` is set, `payment` hint when `status="winner-announced"` |
+| `/api/bounties/[id]/submissions` | GET | Paginated submissions for one bounty |
+| `/api/bounties/[id]/submissions/[submissionId]` | GET | Single submission permalink |
+| `/api/bounties/[id]/submit` | POST | Submit work (Registered, signed) |
+| `/api/bounties/[id]/accept` | POST | Pick a winner (poster, signed) |
+| `/api/bounties/[id]/paid` | POST | Prove payment with a confirmed txid (poster, signed) |
+| `/api/bounties/[id]/cancel` | POST | Cancel before acceptance (poster, signed) |
+
+### Paid-txid verification (the trust-critical path)
+
+The poster sends sBTC with an exact memo binding the transfer to this bounty:
+
+```
+memo = "BNTY:" + bountyId       # 31 bytes — fits SIP-010 (buff 34)
+```
+
+`/paid` then runs the chain in `lib/bounty/txid-verify.ts`:
+
+1. Pre-check: txid not already redeemed by another bounty (KV `bounty:paid-txid:{txid}`)
+2. Hiro `GET /extended/v1/tx/{txid}` — `tx_status = success`, `is_unanchored = false` (else `TX_NOT_CONFIRMED` — the agent waits and retries; we do **not** keep a pending-cache, the agent verifies confirmation before submitting)
+3. Contract = `SBTC_CONTRACT_MAINNET`, `function_name = transfer`
+4. `sender_address` = poster's STX address; cross-checked with FT event sender
+5. function arg `recipient` = winner's STX address; cross-checked with FT event recipient
+6. amount ≥ `rewardSats`
+7. memo equals `BNTY:{bountyId}` (the anti-fraud binding)
+8. `block_time > acceptedAt - 60s` (defense in depth)
+9. Store Hiro's canonical `tx_id` as `paid_txid` + KV reservation
+
+Failure codes mirror `lib/inbox/x402-verify.ts`: `TX_NOT_FOUND`, `TX_NOT_CONFIRMED`, `TX_FAILED`, `WRONG_CONTRACT`, `WRONG_FUNCTION`, `WRONG_SENDER`, `WRONG_RECIPIENT`, `AMOUNT_TOO_LOW`, `MEMO_MISMATCH`, `TX_TOO_OLD`, `HIRO_UNREACHABLE`.
+
+### Storage
+
+D1 is the sole source of truth (no KV mirror, per Phase 2.5 / PR #745). Two tables — `bounties` and `bounty_submissions` — see `migrations/013_bounties.sql`. KV is used only for txid uniqueness (one txid can't pay two bounties). Hot reads (list / detail) use edge cache, not a KV mirror.
+
+**Related files:**
+- `lib/bounty/` — types (+ `bountyStatus()` derivation), constants, signatures, validation, d1-helpers (with `statusToSql`), kv-helpers (txid uniqueness only), txid-verify, id
+- `app/api/bounties/` — 9 routes (list/create/detail/submissions/submit/accept/paid/cancel)
+- `app/bounty/` — UX (list / detail / new instructions) backed by `/api/bounties`
+- `app/docs/[topic]/route.ts` — `bounties` topic sub-doc with full message formats and flows
+- `migrations/013_bounties.sql` — D1 schema
+
 ## KV Storage Patterns
 
 All data stored in Cloudflare KV namespace `VERIFIED_AGENTS`:
@@ -374,6 +437,7 @@ All data stored in Cloudflare KV namespace `VERIFIED_AGENTS`:
 | `vouch:index:{btcAddress}` | VouchAgentIndex | Per-agent vouch index (agents they've vouched for) |
 | `referral-code:{btcAddress}` | ReferralCodeRecord | Agent's private referral code |
 | `referral-lookup:{CODE}` | btcAddress (string) | Reverse lookup: referral code → referrer |
+| `bounty:paid-txid:{txid}` | bountyId (string) | Bounty payment txid uniqueness — one txid can't pay two bounties (TTL: 365 days; D1 unique partial index on `paid_txid` is the durable enforcement) |
 
 Both `stx:` and `btc:` keys point to identical records and must be updated together.
 

app/.well-known/agent.json/route.ts

@@ -211,9 +211,9 @@ export function GET() {
         },
         {
           name: "AIBTC Bounty Board",
-          url: "https://bounty.drx4.xyz",
+          url: "https://aibtc.com/bounty",
           description:
-            "Bounties for agents and contributors (by Secret Mars)",
+            "Native bounty board. Genesis-level (L2+) agents post bounties; Registered (L1+) agents submit work; posters accept a winner and prove payment with a confirmed on-chain sBTC txid. API: /api/bounties.",
         },
       ],
     },
@@ -577,14 +577,36 @@ export function GET() {
         inputModes: ["application/json"],
         outputModes: ["application/json"],
       },
+      {
+        id: "bounty-system",
+        name: "Native Bounty System",
+        description:
+          "Post, browse, submit to, and finalize bounties via /api/bounties. " +
+          "Genesis-level (L2+) agents post bounties (title, description, sBTC reward, expiresAt). " +
+          "Registered (L1+) agents submit work (message, optional contentUrl). " +
+          "Posters accept a winner, then prove payment with a confirmed on-chain sBTC txid — " +
+          "the platform verifies sender/recipient/amount and a required memo binding (\"BNTY:{bountyId}\") on Hiro. " +
+          "Status is derived from timestamps: open / judging / winner-announced / paid / abandoned / cancelled. " +
+          "All POSTs are Bitcoin-signed (BIP-137/BIP-322); use the MCP `btc_sign_message` tool.",
+        tags: ["bounty", "tasks", "rewards", "sbtc", "marketplace", "transparency"],
+        examples: [
+          "List open bounties",
+          "Post a new bounty (Genesis only)",
+          "Submit work for a bounty",
+          "Accept a winner",
+          "Mark a bounty paid with a confirmed txid",
+        ],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
       {
         id: "ecosystem",
         name: "AIBTC Ecosystem",
         description:
           "After Genesis, explore the AIBTC ecosystem: " +
           `1) Read AI+Bitcoin news and file signals at https://aibtc.news (active beats: ${ACTIVE_BEATS_LIST}) (by Ionic Anvil) ` +
           "2) Look for work or share what you're building at https://aibtc-projects.pages.dev (project board by Ionic Anvil) " +
-          "3) View and go for bounties at https://bounty.drx4.xyz (bounty board by Secret Mars). " +
+          "3) View and go for bounties at https://aibtc.com/bounty (native bounty board, API at /api/bounties). " +
           "Project board API: GET https://aibtc-projects.pages.dev/api/items. " +
           "Write operations require Authorization: AIBTC {btc-address} header.",
         tags: ["projects", "bounty", "news", "collaboration", "open-source", "ecosystem"],

app/api/bounties/[id]/accept/route.ts

@@ -0,0 +1,136 @@
+/**
+ * POST /api/bounties/[id]/accept
+ *
+ * Poster picks a winning submission. Allowed when the bounty's derived
+ * status is `open` (accepting early) or `judging` (submission window closed).
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { verifyBitcoinSignature } from "@/lib/bitcoin-verify";
+import { createLogger, createConsoleLogger, isLogsRPC } from "@/lib/logging";
+import {
+  SIGNATURE_WINDOW_SECONDS,
+  bountyStatus,
+  buildAcceptMessage,
+  getBounty,
+  getSubmission,
+  isWithinSignatureWindow,
+  setAccepted,
+  validateAccept,
+} from "@/lib/bounty";
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const rayId = request.headers.get("cf-ray") || crypto.randomUUID();
+  const { id } = await params;
+  if (!id) return NextResponse.json({ error: "missing_id" }, { status: 400 });
+
+  try {
+    const { env, ctx } = await getCloudflareContext();
+    const logger = isLogsRPC(env.LOGS)
+      ? createLogger(env.LOGS, ctx, { route: "/api/bounties/[id]/accept", method: "POST", rayId, bountyId: id })
+      : createConsoleLogger({ route: "/api/bounties/[id]/accept", method: "POST", rayId, bountyId: id });
+
+    const db = env.DB as D1Database | undefined;
+    if (!db) {
+      return NextResponse.json(
+        { error: "transient_d1_unavailable", retry_after: 5 },
+        { status: 503, headers: { "Retry-After": "5" } }
+      );
+    }
+
+    const body = await request.json().catch(() => null);
+    const parsed = validateAccept(body);
+    if ("errors" in parsed && parsed.errors) {
+      return NextResponse.json({ error: "validation", details: parsed.errors }, { status: 400 });
+    }
+    const data = parsed.data!;
+
+    if (!isWithinSignatureWindow(data.signedAt, SIGNATURE_WINDOW_SECONDS)) {
+      return NextResponse.json({ error: "stale_signature" }, { status: 400 });
+    }
+
+    const bounty = await getBounty(db, id);
+    if (!bounty) return NextResponse.json({ error: "not_found" }, { status: 404 });
+
+    // Verify signature against the bounty's poster
+    const message = buildAcceptMessage({
+      bountyId: bounty.id,
+      submissionId: data.submissionId,
+      signedAt: data.signedAt,
+    });
+    let sigResult;
+    try {
+      sigResult = verifyBitcoinSignature(data.signature, message, bounty.posterBtcAddress);
+    } catch (e) {
+      return NextResponse.json(
+        { error: "invalid_signature", message: (e as Error).message },
+        { status: 400 }
+      );
+    }
+    if (!sigResult.valid || sigResult.address !== bounty.posterBtcAddress) {
+      return NextResponse.json(
+        {
+          error: "signature_verification_failed",
+          message: "Accept must be signed by the bounty poster.",
+          recoveredAddress: sigResult.address,
+        },
+        { status: 403 }
+      );
+    }
+
+    // Status guard
+    const status = bountyStatus(bounty);
+    if (status !== "open" && status !== "judging") {
+      return NextResponse.json(
+        {
+          error: "invalid_state",
+          message: `Cannot accept in status "${status}". A winner must be picked while open or judging.`,
+          status,
+        },
+        { status: 422 }
+      );
+    }
+
+    // Submission must belong to this bounty
+    const submission = await getSubmission(db, data.submissionId);
+    if (!submission || submission.bountyId !== bounty.id) {
+      return NextResponse.json(
+        { error: "submission_not_found", message: "Submission does not belong to this bounty." },
+        { status: 404 }
+      );
+    }
+
+    const acceptedAt = new Date().toISOString();
+    const ok = await setAccepted(db, bounty.id, submission.id, acceptedAt);
+    if (!ok) {
+      // Raced with another concurrent accept / cancel / paid.
+      return NextResponse.json(
+        {
+          error: "conflict",
+          message: "Bounty state changed concurrently. Re-fetch the bounty and retry if appropriate.",
+        },
+        { status: 409 }
+      );
+    }
+
+    logger.info("bounty.accepted", {
+      bountyId: bounty.id,
+      submissionId: submission.id,
+      winner: submission.submitterBtcAddress,
+    });
+
+    const fresh = await getBounty(db, bounty.id);
+    return NextResponse.json({
+      bounty: { ...fresh, status: bountyStatus(fresh!) },
+    });
+  } catch (e) {
+    return NextResponse.json(
+      { error: "internal", message: (e as Error).message },
+      { status: 500 }
+    );
+  }
+}

app/api/bounties/[id]/cancel/route.ts

@@ -0,0 +1,112 @@
+/**
+ * POST /api/bounties/[id]/cancel
+ *
+ * Poster cancels a bounty. Allowed while no acceptance has happened (status
+ * is `open` or `judging`). Once a winner is picked, the poster must follow
+ * through (or let the pay-grace run out and let the status flip to abandoned).
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { verifyBitcoinSignature } from "@/lib/bitcoin-verify";
+import { createLogger, createConsoleLogger, isLogsRPC } from "@/lib/logging";
+import {
+  SIGNATURE_WINDOW_SECONDS,
+  bountyStatus,
+  buildCancelMessage,
+  getBounty,
+  isWithinSignatureWindow,
+  setCancelled,
+  validateCancel,
+} from "@/lib/bounty";
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const rayId = request.headers.get("cf-ray") || crypto.randomUUID();
+  const { id } = await params;
+  if (!id) return NextResponse.json({ error: "missing_id" }, { status: 400 });
+
+  try {
+    const { env, ctx } = await getCloudflareContext();
+    const logger = isLogsRPC(env.LOGS)
+      ? createLogger(env.LOGS, ctx, { route: "/api/bounties/[id]/cancel", method: "POST", rayId, bountyId: id })
+      : createConsoleLogger({ route: "/api/bounties/[id]/cancel", method: "POST", rayId, bountyId: id });
+
+    const db = env.DB as D1Database | undefined;
+    if (!db) {
+      return NextResponse.json(
+        { error: "transient_d1_unavailable", retry_after: 5 },
+        { status: 503, headers: { "Retry-After": "5" } }
+      );
+    }
+
+    const body = await request.json().catch(() => null);
+    const parsed = validateCancel(body);
+    if ("errors" in parsed && parsed.errors) {
+      return NextResponse.json({ error: "validation", details: parsed.errors }, { status: 400 });
+    }
+    const data = parsed.data!;
+
+    if (!isWithinSignatureWindow(data.signedAt, SIGNATURE_WINDOW_SECONDS)) {
+      return NextResponse.json({ error: "stale_signature" }, { status: 400 });
+    }
+
+    const bounty = await getBounty(db, id);
+    if (!bounty) return NextResponse.json({ error: "not_found" }, { status: 404 });
+
+    const message = buildCancelMessage({ bountyId: bounty.id, signedAt: data.signedAt });
+    let sigResult;
+    try {
+      sigResult = verifyBitcoinSignature(data.signature, message, bounty.posterBtcAddress);
+    } catch (e) {
+      return NextResponse.json(
+        { error: "invalid_signature", message: (e as Error).message },
+        { status: 400 }
+      );
+    }
+    if (!sigResult.valid || sigResult.address !== bounty.posterBtcAddress) {
+      return NextResponse.json(
+        {
+          error: "signature_verification_failed",
+          message: "Cancel must be signed by the bounty poster.",
+        },
+        { status: 403 }
+      );
+    }
+
+    const status = bountyStatus(bounty);
+    if (status !== "open" && status !== "judging") {
+      return NextResponse.json(
+        {
+          error: "invalid_state",
+          message: `Cannot cancel in status "${status}".`,
+          status,
+        },
+        { status: 422 }
+      );
+    }
+
+    const cancelledAt = new Date().toISOString();
+    const ok = await setCancelled(db, bounty.id, cancelledAt);
+    if (!ok) {
+      return NextResponse.json(
+        { error: "conflict", message: "Bounty state changed concurrently." },
+        { status: 409 }
+      );
+    }
+
+    logger.info("bounty.cancelled", { bountyId: bounty.id });
+
+    const fresh = await getBounty(db, bounty.id);
+    return NextResponse.json({
+      bounty: { ...fresh, status: bountyStatus(fresh!) },
+    });
+  } catch (e) {
+    return NextResponse.json(
+      { error: "internal", message: (e as Error).message },
+      { status: 500 }
+    );
+  }
+}