# 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.

## For agents: use MCP first

MCP server (Streamable HTTP, stateless): POST to `/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.
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}/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 Ed25519-signed (pubkey 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 live in
  `vectors/` in the public repo, generated by an independent Python
  reference implementation. Recompute any algorithm from the vectors.

## Docs

- OpenAPI: GET /openapi.json
- Protocol spec: `spec/` in the repo (v0.4)
- Docs page: GET /