# Quiver documentation

**Verifiable on-chain randomness for Robinhood Chain** — a two-party commit–reveal
entropy protocol. Start here.

## Read in order

1. **[Architecture](architecture.md)** — the components, roles, and request flows.
2. **[Protocol design](protocol-design.md)** — how randomness is produced and why it's
   secure (the hash-chain / anchor mechanism, in depth).
3. **[Integration guide](integration-guide.md)** — consume randomness from a contract
   (push & pull) or from TypeScript.
4. **[API reference](api-reference.md)** — every function, event, error, and type.
5. **[Security model](security.md)** — trust assumptions, threat model, mitigations.
6. **[Deployment runbook](deployment.md)** — testnet → mainnet, step by step.
7. **[Keeper operations](fletcher-operations.md)** — running the keeper (Fletcher) in
   production.

## Concepts

| Term | Meaning |
| --- | --- |
| **Coordinator** | The on-chain contract (`QuiverCoordinator`) — verifies reveals, combines the two values, delivers callbacks |
| **Provider** | Registers a hash-chain commitment and serves the random values behind it |
| **Keeper** | The provider's off-chain service (`Fletcher`) that watches for requests and submits reveals |
| **Requester / Consumer** | A contract or account that requests randomness |
| **Sequence number** | The id assigned to each request; used to track it through fulfillment |
| **Commitment** | The tip of the provider's keccak hash chain, `chain[N]` |
| **Push flow** | `requestWithCallback` → keeper `revealWithCallback` → your `quiverCallback` |
| **Pull flow** | `request` → you `reveal` and read the result |

## The one-line mental model

```
randomNumber = keccak256(userRandom ‖ providerReveal ‖ blockHash?)
```

Two values, each committed before either is revealed. Neither party can bias the result;
a fair outcome holds as long as one party is honest.

## Try it

```bash
forge test            # 38 tests (unit, adversarial, fuzz)
./demo/local-demo.sh  # full end-to-end on a local node
```