closedhumanPR #212Payments

feat(payments): Prava agentic-payments adapter + trust gate + adversarial validator

In one line: the first Nanda Town payments plugin that can *refuse a bad payee* — a reusable Prava adapter (plus a validator that proves the trust gate holds) that gives every Nanda builder safe agent-to-agent money, which the default…

Author

karthikbalajikb avatar

@karthikbalajikb

github profile →
Status
Closed without merging
Opened on
Aug 2
Branch
hackathon/karthikbalajikb-prava-payments

Description

The pitch.

## Prava agentic-payments adapter for the Nanda Town payments layer

**In one line:** the first Nanda Town payments plugin that can *refuse a bad payee* — a reusable **Prava** adapter (plus a validator that proves the trust gate holds) that gives every Nanda builder safe agent-to-agent money, which the default `prepaid_credits` plugin can't do.

For the **NandaHack × Prava — Best Prava Adapter for NANDA Town** track.
Lands under `examples/prava-payments/` (per the charter: scenario under `examples/<theme>/`).

### Trust-gate failure, visualized (from the Nanda trace)

![Prava trust-gate failure in a Nanda trace](https://raw.githubusercontent.com/karthikbalajikb/nandatown/b6530ef074b1cdb11cce8368e60895f2ac268939/examples/prava-payments/docs/trust-gate-failure.png)

*A faithful render of `traces/prava_failure.jsonl` — the same event counts `nest inspect` reports, incl. `trust_refused × 1`.*

### What this adds
A reliable, reusable **Prava** implementation of the **payments** layer, plus the charter-mandatory adversarial validator.

- **Plugin** — `prava_payments/plugin.py` implements the `Payments` protocol (`quote` / `pay` / `verify_payment` / `refund`) from `nest_sdk`. Registered via entry point so any scenario selects it:
  ```yaml
  layers: { payments: prava }
  ```
- **Trust gate (failure handling)** — `prava_payments/trust.py`: a Senso-backed gate inside `pay()`. An unverified counterparty raises `TrustRefusedError` and the Prava token is withheld.
- **Adversarial validator** — `prava_payments/validator.py`: reads a trace and asserts *no value settles to an unverified payee*. The default `prepaid_credits` plugin has no trust gate, so it settles to a scammer and this validator **FAILS**; `prava` refuses (`trust_refused`) and it **PASSES** — the class of attack the gate catches.
- **Prava client** — `prava_payments/prava_client.py`: stdlib-only (`urllib`), deterministic offline mock by default; live sandbox with `PRAVA_API_KEY` + `PRAVA_LIVE=1`.
- **Scenario** — `scenarios/prava_marketplace.yaml`: the built-in marketplace wired to `payments: prava` (100 agents, seed 42).
- **Tests** — `tests/test_prava_payments.py`: happy path + trust-gate failure + refund + validator (8 passing).
- **Runnable proof** — `demo.py` (CONFIRMED → BLOCKED → REFUNDED) and `simulate_failure.py`, which writes a Nanda trace where `nest inspect` shows a first-class `trust_refused` event alongside `payment_confirmed` and `refunded`.

### Evaluation criteria
- **Successful transaction** — `pay()` settles buyer → merchant → `PaymentStatus.CONFIRMED`.
- **Handled failure** — Senso gate refuses an unverified seller (`TrustRefusedError`); Prava token not issued.
- **Refund** — `refund()` reverses the ledger → `REFUNDED`.
- **Reuse** — drop-in payments layer; one YAML line flips any scenario to it.
- **Determinism** — no wall-clock, no unseeded RNG; the offline mock keeps Tier-1 traces byte-reproducible.

### Run it
```bash
cd examples/prava-payments
pip install -e .                                  # registers payments: prava
nest plugins list                                 # payments: ... prava
python demo.py                                    # CONFIRMED -> BLOCKED -> REFUNDED
pytest -v                                         # 8 passed
python simulate_failure.py                        # writes traces/prava_failure.jsonl
nest inspect traces/prava_failure.jsonl           # event breakdown incl. trust_refused: 1
python -m prava_payments.validator traces/prava_failure.jsonl did:printsmith:store
nest run scenarios/prava_marketplace.yaml
```

`make ci-local` passes at repo root (`uv sync`, `ruff check .`, `ruff format --check .`, `pyright`, `pytest -v`). The example lives under `examples/`, which the repo excludes from pyright/pytest; it is ruff-clean and self-contained.

> Note: the reference `marketplace` task emits only agent `start`/`stop`, so the full transaction lifecycle is exercised by `demo.py` / `simulate_failure.py` / the tests (which drive the plu

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/212/head:pr-212
git checkout pr-212