coinbase-crypto: htlc_escrow payments plugin (hash- & time-locked conditional payments)

Description

The pitch.

## Piece picked: **Payments layer** — a new bundled plugin `htlc_escrow`

The default `prepaid_credits` plugin transfers funds the instant `pay()` is
called. That works for cooperative simulation but it silently *assumes*
counterparty trust: the payee can take the money and never deliver, and the
payer's only recourse is to report after-the-fact. Trying to stress-test a
marketplace protocol against an adversarial seller is hard when your
payments primitive can't even express "funds locked until delivery".

NEST is a test rig for protocols; it should ship a payments primitive that
can express **trust-minimized settlement**. That's what this PR adds.

## Core idea

`htlc_escrow` implements Hash Time-Locked Contracts — the same primitive
behind Bitcoin Lightning, atomic swaps, and rollup bridges:

1. **`pay()`** debits the payer and credits a sentinel `ESCROW_AGENT`
   account. Funds are *locked*, not transferred. A `_Contract` records
   the hashlock + timelock + payer/payee.
2. **`claim(ref, preimage)`** releases escrow to the payee iff
   `sha256(preimage) == hashlock` and `now() < expiry_tick`.
3. **`refund_expired(ref)`** returns escrow to the payer iff
   `now() >= expiry_tick`.
4. The base `Payments` interface still works: `pay()` without a hashlock
   auto-claims, behaving like prepaid_credits — so it's a drop-in
   substitute for protocols that don't yet speak HTLC.

Invariants enforced (and tested):

- **Conservation.** `sum(balances) + escrow` is invariant across **every**
  op, including failed ones — there's a Hypothesis property test that
  hammers random op sequences and asserts conservation after each step.
- **Exactly-one terminal state.** Every contract reaches `CONFIRMED` *xor*
  `REFUNDED`, exactly once.
- **Hashlock atomicity.** Wrong preimage → reject. Malformed (non-32-byte)
  hashlock → atomic abort that does not touch the ledger.
- **Timelock safety.** Refund before expiry rejected; claim after expiry
  rejected. Payee can't claim after payer refunds; payer can't refund
  after payee claims.
- **No double-spend.** Duplicate `PaymentRef` and self-pay rejected.
- **Deterministic preimages.** `make_secret(seed)` is reproducible so
  scenario traces stay byte-identical under the same RNG seed.

## Files

- `packages/nest-plugins-reference/nest_plugins_reference/payments/htlc_escrow.py` — the plugin
- `packages/nest-plugins-reference/tests/test_htlc_escrow.py` — 29 tests (27 example-based + 2 Hypothesis property tests)
- `packages/nest-core/nest_core/plugins.py` — registers `htlc_escrow` as a built-in
- `README.md` + `docs/layers/payments.md` — docs

## How to test

```bash
uv sync
uv run pytest packages/nest-plugins-reference/tests/test_htlc_escrow.py -v
# 29 passed

# Full CI parity locally:
uv run pytest                       # 288 passed
uv run ruff check . && uv run ruff format --check .
uv run pyright                      # 0 errors (strict mode)

# Confirm it's discoverable:
uv run nest plugins list | grep htlc_escrow
uv run nest doctor                  # 7/7 checks passed
```

Drop-in use in any scenario:

```yaml
layers:
  payments: htlc_escrow
```

I verified end-to-end that the marketplace scenario runs cleanly with
`payments: htlc_escrow` swapped in (the auto-claim compat path makes it a
transparent replacement for protocols that don't yet wire up
`claim`/`refund_expired`).

## Key assumptions

- **Clock model.** Timelocks use a shared logical `tick` counter. Tests
  drive it via `advance_clock()`; in a fuller integration the simulator's
  virtual clock would feed in here. I deliberately kept the clock plumbing
  decoupled from `nest_core.sim` so the plugin stays self-contained and
  the existing simulator wiring doesn't change.
- **Hashlock = SHA-256.** Standard choice; same construction Bitcoin uses
  for HTLCs. Easy to swap to BLAKE3 or Poseidon if a future ZK plugin
  wants to do in-circuit verification.
- **In-memory shared state.** Matches the other reference plugins. The
  shared `contracts` / `balances` / `clock` dicts let all per-agent
  handles see the same ledger, exactly like `prepaid_credits` does.
- **No fees, no streaming, no multi-hop routing.** Out of scope for one
  hackathon PR; the timelock + hashlock primitive is the load-bearing
  contribution.

## Persona

ex-Coinbase senior engineer (payment protocols, ledgers, ZKPs). I don't
trust counterparties — I verify them.

## Future work

- Wire the plugin's `clock` to the simulator's `VirtualClock` so timelocks
  expire on real virtual time, not test-driven `advance_clock` calls.
- Add a `marketplace_escrow` built-in scenario where buyers reveal
  preimages on delivery and sellers can grief by withholding (so
  validators can verify the refund-liveness property end-to-end).
- Add a trace validator: parse the JSONL and assert the conservation
  invariant over the whole run (`ESCROW_AGENT` is already exported for
  this purpose).
- Multi-hop atomic routing (LN-style): same hashlock across a chain of
  escrows, enabling cross-agent atomic-swap experiments.
- ZK-friendly hashlock variant (Poseidon) for a future privacy-layer
  integration where preimage knowledge is proven without revealing it.

https://claude.ai/code/session_01C5j2D4MgCkPgsjSCqBVpWW

---
_Generated by [Claude Code](https://claude.ai/code/session_01C5j2D4MgCkPgsjSCqBVpWW)_

## Summary by Sourcery

Introduce an HTLC-based escrow payments plugin and register it as an alternative Payments backend with comprehensive tests and documentation.

New Features:
- Add an `htlc_escrow` payments plugin implementing hash- and time-locked escrow contracts with optional drop-in prepaid-style behaviour.
- Register `htlc_escrow` as a built-in `Payments` implementation in the core plugin registry and top-level layer table.

Documentation:
- Document the `htlc_escrow` payments layer, its usage, and an example HTLC flow in the payments layer guide and README.

Tests:
- Add extensive unit and property-based tests covering HTLC escrow behaviour, invariants, error cases, and plugin registry resolution.