# Redeal

> Neutral computation escrow for agents. Two or more parties commit to sealed
> inputs, Redeal runs a published deterministic algorithm on the revealed
> inputs, and issues a signed certificate — appended to a public transparency
> log — that anyone can verify. Use it when agents (or people) need a fair
> outcome nobody has to trust anyone for.

## Site

- Homepage: https://redeal.dev/
- Verify a certificate (free, no account): https://redeal.dev/verify
- How the protocol works: https://redeal.dev/how-it-works
- Trust mechanisms: https://redeal.dev/trust
- Data policy: https://redeal.dev/trust/data-policy
- Status + signing-key custody: https://redeal.dev/trust/status
- Docs (this file's subject): https://redeal.dev/docs

## API

Base URL for everything below: **https://api.redeal.dev**
(also reachable same-origin via https://redeal.dev for GET /v1/*)

## For agents: use MCP first

MCP server (Streamable HTTP, stateless): POST to `https://api.redeal.dev/mcp`.
The `initialize` response includes full onboarding instructions.

Tools: `create_key` (no signup — start here), `list_algorithms`,
`create_deal`, `commit_input`, `reveal_input`, `get_deal`, `get_certificate`,
`verify_certificate`, `compute_commitment_tool`.

Secrets are passed as tool arguments (`api_key`, `invite_token`). Tool errors
are instructive: they name the error code and the next action.

## The protocol (5 steps)

1. `create_key` → api_key (`fp_...`), shown once.
2. `create_deal(api_key, algorithm, party_labels, commit_deadline,
   reveal_deadline, algorithm_params)` → deal_id + one invite token per party.
   Send each party their token.
3. Each party: `compute_commitment_tool(input, salt)` then
   `commit_input(invite_token, deal_id, commitment)`.
4. Each party: `reveal_input(invite_token, deal_id, input, salt)`.
   When all reveal, the algorithm runs automatically and the certificate
   is issued. Missing a deadline VOIDs the deal and the certificate names
   the flakers — griefing becomes reputation evidence.
   (random.v1: after all reveals the deal rests until the pinned drand round
   publishes; then `POST /v1/deals/{id}/entropy` completes it — the server
   fetches the beacon value itself, so no caller can choose the entropy.)
5. `get_certificate` → the cert. Anyone, no auth:
   `verify_certificate(cert_id)` → signature + transparency-log inclusion.

## Algorithms

- `split.v1` — fair division (adjusted winner for 2 parties, proportional
  for n). params: `{"items": [...]}`; input: `{"valuations": {"item": int}}`.
- `random.v1` — verifiable random selection (XOR nonces + drand, lowest
  sha256 wins). params: `{"drand_round": int}`; input: `{"nonce": hex}`.
- `shapley.v1` — Shapley value shares. params: `{"coalition_values": {...}}`;
  input: `{"accept": true|false}`.

## REST (canonical surface, all under /v1/)

- `POST /v1/keys` — issue an API key (201, `{"api_key"}`)
- `GET  /v1/algorithms` — catalogue with input contracts
- `GET  /v1/status` — service status + certificate-signing pubkey
- `POST /v1/deals` — create deal (Bearer api_key; `Idempotency-Key` header)
- `GET  /v1/deals/{id}` — deal view (Bearer api_key or invite token;
  never contains revealed inputs)
- `POST /v1/deals/{id}/commit` — `{"commitment": "sha256:..."}` (Bearer invite token)
- `POST /v1/deals/{id}/reveal` — `{"input": {...}, "salt": "..."}` (Bearer invite token)
- `POST /v1/deals/{id}/entropy` — random.v1 only, after all reveals: the
  server fetches the deal's pre-declared drand round from the public League
  of Entropy beacon (quicknet) itself, pins the value, computes, certifies.
  Callers never supply the value. Idempotent; 502 until the round publishes.
- `POST /v1/deals/{id}/cancel` — initiator only
- `GET  /v1/deals/{id}/certificate` — parties only
- `GET  /v1/verify/{cert_id}` — PUBLIC, no auth, free forever
- `GET  /v1/log/tree-head` — signed transparency tree head

Commitment scheme: `sha256:<hex of sha256(JCS(party_input) ++ salt_bytes)>`
where JCS is RFC 8785 JSON Canonicalization (integers only — no floats).

## Guarantees

- Certificates are signed with a scheme-labelled `es256:` ECDSA P-256
  signature from a key held in AWS KMS (sign-via-API; the server can never
  hold or export it). The verifying pubkey is at GET /v1/status.
- Every certificate carries a Merkle inclusion proof against the
  transparency log; the log is append-only and its tree head is signed.
- The engine is deterministic and pure; independent test vectors,
  generated by a separate Python reference implementation, ship with the
  public source repo at launch. Recompute any algorithm from the vectors.

## Docs

- OpenAPI: GET /openapi.json
- Docs page: https://redeal.dev/docs (also served by the API itself at
  https://api.redeal.dev/)