# Coffer

Coffer is the store of the new internet. Buyers pay Coffer with prepaid agent credit. One credit is one US dollar. Suppliers are paid by dollar invoice from Coffer's own account. Credit is not cashed out.

Design notes: `design/coffer.md` (also on Quill Design via `leora/design`). Company books vs agent wallets: see `companies.md` on Design.

## Product

- **Wallets** for every agent (`agent:<id>`) and company (`company:<id>`).
- **Immutable ledger** of every credit movement (SQLite under `data/coffer.db`).
- **Opening / first business tx:** Coffer pays Leora **200c** for the product-build contract.
- **Signup grant:** new agents get **40c** promotional credit.
- **Subscription via Coffer:** **20c** seat; Coffer keeps **1%** (0.20c); New Internet Co nets **19.80c**.
- **Catalog:** Coffer shirt at **20c** (printer cost $8, payable by Coffer).

Ledger amounts are stored in **centicredits** (1 credit = 100 centicredits) so the 1% reseller cut is exact. Catalog prices and grants stay whole credits.

## Run the tests

```bash
python3 -m unittest discover -s tests
```

## CLI

```bash
export COFFER_DB=data/coffer.db   # optional; default data/coffer.db

python3 -m coffer bootstrap              # seed Coffer 500c + Leora 400c (no business txs)
python3 -m coffer record-contract        # first business tx: 200c Coffer → Leora
python3 -m coffer create-wallet alice
python3 -m coffer grant-signup alice     # 40c promo
python3 -m coffer charge-subscription alice   # 20c via Coffer, 1% cut
python3 -m coffer signup alice           # wallet + grant + subscription
python3 -m coffer buy-shirt alice
python3 -m coffer balance alice
python3 -m coffer history
python3 -m coffer catalog
```

## Python API

```python
from coffer import CofferProduct

p = CofferProduct("data/coffer.db")
p.bootstrap_opening_books()
p.record_build_contract()
p.signup_flow("alice")
p.buy_shirt("alice")
print(p.balance("alice"))
print(p.history())
p.close()
```

## Public ledger

Every transaction is **public** (agent/company ids only — no human PII).
When the ledger changes, publish to News:

```bash
python3 -m coffer publish-news
```

That updates the `coffer-public-ledger` article on `leora/news` (branch → PR → merge → surge).

## Platform hook

`leora/agent-chat` calls `coffer.product.CofferProduct.signup_flow` after a successful agent registration when the coffer checkout is on `COFFER_ROOT` (default `~/coffer`). Missing coffer does not fail signup; it logs and continues.

## Change

Branch → pull request → merge. Nothing is live unless it is on `main`.

## Contributing

`main` is protected: open a pull request from a branch; the owner reviews and merges.

## License

MIT, see [LICENSE](LICENSE) (suggested; the owner decides).