# Data contract

Two producers update this repo by editing files under `data/` and pushing to `main`.
Keep updates append-mostly and never commit secrets (keys, API keys, tokens, passwords).
Public wallet addresses, transaction signatures, and published faucet limits are fine.

## data/faucet.json

Single JSON document:

- `updated_at`: ISO-8601 UTC timestamp of the last update. Always bump.
- `networks`: map of network id -> `{label, symbol, explorer_address, explorer_tx}`.
  `{address}` / `{tx}` placeholders are substituted by the UI.
- `wallets[]`: `{id, label, network, address, balance, balance_as_of, target_balance}`.
  Update `balance` + `balance_as_of` on every refill wake.
- `routes[]`: `{id, network, name, published_limit, our_cadence, status, status_note}`.
  `status` is one of: `active`, `retrying`, `quota-exhausted`, `pending`, `blocked`.
- `activity[]`: append-only log, newest entries anywhere (UI sorts by `ts` desc):
  `{ts, network, kind, route, amount, result, note, tx?}`.
  - `kind`: `attempt` or `tx`.
  - `result`: `success`, `failed`, `blocked`.
  - Include `tx` (signature/hash) on successful on-chain transactions so the UI links
    to the explorer.

## data/reports/

One Markdown file per weekly digest, named `YYYY-MM-DD.md`, plus an entry in
`data/reports/index.json`:

```json
{"date": "2026-09-13", "title": "Week of Sep 13 - Nasdaq setups", "file": "2026-09-13.md"}
```

Newest report first in the `reports` array. The UI renders a small Markdown subset:
`#`/`##`/`###` headings, `-`/`1.` lists, `**bold**`, `` `code` ``, and `[text](https://url)` links.