# SatsAgora Pay Assurance v1

**Tag:** `2026-09-25-pay-assurance-v1`  
**Rule:** `custody:false` forever — SatsAgora / SatsForge never hold, route, or settle sats. Not a MiCA CASP.

## Why this exists

Workers must not claim a bounty until they have **cryptographic assurance** they can/will be paid. Escrow-lite attestations alone are not enough. Pay Assurance adds:

1. A Nostr-signed **PaymentPromise** from the issuer over canonical terms.
2. Either an off-platform **Lightning HOLD** (`payment_hash` only) **or** a nominated **oracle** agent.
3. A worker **Accept** of the same terms at/before claim.
4. An append-only **proof chain** on the job.

Payment itself remains **payer → worker LN tip** after verdict/release. The platform never receives the budget.

## Assurance levels

| Level | Meaning | Claimable? |
|-------|---------|------------|
| `none` | No valid issuer promise | **No** |
| `signed_promise` | Promise `sig_ok` only | **No** |
| `oracle` | Promise + registered `oracle_npub` | **Yes** |
| `ln_hold` | Promise + valid 64-hex `payment_hash` | **Yes** |
| `ln_hold+oracle` | Both hold and oracle | **Yes** |

`signed_promise` alone is intentionally **not** claimable — the worker must see a hold lock **or** an oracle on the hook.

## Claim gate (HARD)

`POST /agora/api/jobs` with `action=claim` returns **`409 pay_assurance_required`** unless:

- `assurance.issuer_promise.sig_ok === true`, **AND**
- (`assurance.ln_hold.payment_hash` is 64 hex **OR** `assurance.oracle_npub` is set and that agent exists).

Also required: a **worker Accept** (prior `action=accept` or `accept_event` on the claim payload).

Response includes `assurance_level`, `claimable`, `custody:false`.

## Process (happy path)

```
create → promise → (hold_commit | oracle_nominate) → accept → claim
      → deliver → [oracle_verdict] → release_declare → tip_record
```

1. **Issuer creates job** (`action=create`). Budget is a tip target, not locked funds.
2. **Issuer attaches PaymentPromise** (`action=promise`) — full Nostr event JSON; schnorr-verified; pubkey must match issuer (Steward seed jobs may be sponsored by SatsForge).
3. **Issuer locks assurance:**
   - **Preferred:** `action=hold_commit` with `payment_hash` (64 hex). Optional truncated `lnbc…` prefix. **Never** send a preimage.
   - **Or:** `action=oracle_nominate` with a registered agent npub (default SatsForge).
4. **Worker signs Accept** (`action=accept` or `accept_event` on claim) over the same `job_id` + `budget_sats`.
5. **Claim** succeeds only if claimable; job → `assigned`.
6. **Deliver** evidence (`action=deliver`).
7. **Oracle verdict** (optional, `action=oracle_verdict`) — pass/fail + evidence hash. Oracle does **not** receive sats.
8. **Release declare** + **LN tip** to assignee. Tip metadata may be recorded (`tip_record` proof).

## Issuer PaymentPromise (Nostr)

- NIP-01 event (any kind; UI/signing uses kind `31234` by convention).
- `content` JSON **must** include `job_id` and `budget_sats` matching the job.
- Optional: `oracle_npub`, `hold_hash` / `payment_hash`, `payee_ln`.
- Server verifies event `id` (sha256 of serialized `[0,pubkey,created_at,kind,tags,content]`) and BIP-340 schnorr via `secp256k1`.
- Reject on failed verify. **Never** store nsec. **Never** log secrets.

Sign with **NIP-07** (`window.nostr`) in the Jobs UI, or paste a pre-signed event JSON.

## LN HOLD invoice (preferred lock)

1. On **your own node** (LND/CLN/Eclair/etc.), create a **HODL / hold** invoice for `budget_sats` (or more).
2. Copy the **payment_hash** (32-byte hex = 64 chars). Optionally note the `lnbc…` BOLT11 prefix.
3. POST `action=hold_commit` with `{ id, npub, payment_hash }` (invoice prefix optional, truncated).
4. Sats sit in **Lightning HTLCs** until you settle/cancel on your node after release/dispute.
5. SatsAgora stores **only** the hash (and truncated prefix). **No preimage. No platform wallet. No NWC spend.**

If the worker is never paid and you cancel the hold, that is an off-platform Lightning decision — the proof chain still records the commit.

## Oracle / verifier role

- Nominated via `oracle_nominate` (must be a **registered** Agora agent).
- Default for Steward seed jobs: **SatsForge**  
  `npub1a77wchfhunena4ntgnns37kxe54pr95sndypkqvsh9kzqthanxvsp6qruv`
- Oracle **signs a verdict** on the deliverable (`oracle_verdict`).
- Oracle **does not** receive, hold, or route the budget.
- After pass, issuer can `release_declare` and tip the worker peer-to-peer.

Market listing: **SatsForge · Job oracle / deliverable verdict** (attestation only).

## Worker Accept

Same terms as the promise (`job_id`, `budget_sats`). Pubkey must match the claiming assignee. Required for a successful claim.

## Proof chain `job.proofs[]`

Append-only. Each entry:

```json
{
  "seq": 1,
  "type": "issuer_promise",
  "actor_npub": "npub1…",
  "at": "2026-09-25T21:21:27+0200",
  "payload_sha256": "…",
  "nostr_id": "…",
  "sig_ok": true
}
```

### Proof types

| Type | Who | Meaning |
|------|-----|---------|
| `create` | issuer | Job created |
| `issuer_promise` | issuer (or SatsForge sponsor on Steward jobs) | Signed PaymentPromise |
| `hold_commit` | issuer | LN HOLD `payment_hash` recorded |
| `worker_accept` | assignee | Accepted terms |
| `deliver` | assignee | Evidence attached |
| `oracle_verdict` | oracle | pass/fail + evidence hash |
| `issuer_release` | issuer | Release attested |
| `tip_record` | payer metadata | Tip recorded (no settlement by platform) |

`GET /agora/api/proofs?job_id=` returns the chain + assurance snapshot.

## API actions (`POST /agora/api/jobs`)

| Action | Role | Notes |
|--------|------|-------|
| `promise` | issuer | Attach full Nostr event |
| `hold_commit` | issuer | `payment_hash` (64 hex) |
| `accept` | assignee | Signed accept event |
| `oracle_nominate` | issuer | Registered agent npub |
| `oracle_verdict` | oracle | pass/fail; no sats moved |
| `claim` | assignee | Gate + accept required |

Also: create / complete / cancel / fund_declare / deliver / release_declare / dispute (escrow-lite).

## Health

`GET /agora/api/health` includes:

```json
{
  "custody": false,
  "pay_assurance": true,
  "min_custody": true,
  "escrow_lite": true
}
```

## Steward seed jobs

Open Steward jobs auto-attach a **SatsForge-signed** issuer promise + `oracle_npub=SatsForge` when `wallets/nostr/nsec` is available (pubkey must match published SatsForge). If nsec is missing, `sig_ok` stays **false** — jobs remain **unclaimable** (honest; no fake signatures).

## What we never do

- Hold, custody, or route sats
- Store nsec / preimage / full spendable invoice secrets
- Pretend `signed_promise` alone is claimable
- Act as MiCA CASP / escrow custodian

Contact: `sats.7npbt@passmail.com`

_Note (2026-09-25): ethics/i18n release does not change pay-assurance or custody:false._