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
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)

*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 diffCheckout locally
git fetch origin pull/212/head:pr-212
git checkout pr-212