# CLC Software

> Technical docs for the Cosmo-Local Credit stack on Gnosis Chain.

## Docs

- [Addresses](/addresses): Gnosis mainnet, chain ID `100`. Explorer: [Gnosisscan](https://gnosisscan.io).
- [Architecture](/architecture): Two layers: **protocol** (on-chain) and **stack** (off-chain). Apps talk to the stack; the stack talks to Gnosis.
- [Components](/components): Repos under [github.com/cosmo-local-credit](https://github.com/cosmo-local-credit) unless noted.
- [clc-core](/stack/clc-core): HTTP API, SIWE sessions, catalog, contract deploy jobs, EIP-7702 relayer.
- [eth-indexer](/stack/indexer): NATS consumer. Writes `chain_data`. Uses RPC for metadata, not for logs.
- [NATS](/stack/nats): JetStream, single node on staging (`stream_replicas = 1`).
- [Notifications](/stack/notifications): `notification-service` (Go). SMS via Africa's Talking, email via Resend. Not in the Gnosis compose.
- [Stack](/stack/overview): Staging host: Tailscale `clc-gnosis` (`100.108.72.127`), compose in `clc-gnosis-repo`.
- [Relayer](/stack/relayer): Gasless path inside clc-core. User signs, clc-core pays, tx lands as an EIP-7702 Calibur batch.
- [Storage](/stack/storage): `storage-server`. Browsers upload **directly**; clc-core never sees the bytes. Auth is an Ed25519 signature whose public key matches `CORE_API__PRIVATE_KEY`.
- [eth-tracker](/stack/tracker): Follows Gnosis, filters CLC-related txs (including reverts), publishes to NATS JetStream.
- [ethutils](/libraries/ethutils): Go helpers: addresses, registry load, index walk, balances scanner, simulate, reverted-reason dump.
- [ge-publish](/libraries/ge-publish): Go library + CLI in `clc-protocol` (`pkg/publish`, `cmd/ge-publish`).
- [chain_data](/data/schema): Postgres schema written by eth-indexer. Full column notes: `eth-indexer/DATA_GUIDE.md`.
- [Calibur](/contracts/calibur): Minimal **non-upgradeable** EIP-7702 delegation target. User EOAs set code to Calibur; clc-core relays batches and pays gas.
- [Deploy](/contracts/deploy): Full recipes: `clc-protocol/docs/DEPLOY.md` and `docs/PUBLISH.md`.
- [EthFaucet + PeriodSimple](/contracts/faucet): Native xDAI faucet. Registry and period checker are both required.
- [Fees](/contracts/fees): Two layers: pool fee (steward) and protocol fee (network). Both come out of the user's output. The pool owner always receives the full pool fee.
- [GiftableToken](/contracts/giftable-token): ERC-20 voucher: mint, optional expiry, writer minters.
- [Indexes](/contracts/indexes): Two contracts, three proxies.
- [Limiter](/contracts/limiter): Per-token, per-holder balance cap. SwapPool checks it on deposit against **the pool's own balance**.
- [Other contracts](/contracts/other): On-chain preference list: up to 5 ERC-20s per account, index 0 most preferred.
- [Contracts](/contracts/overview): Source: [clc-protocol](https://github.com/cosmo-local-credit/protocol). Spec: `docs/SPEC.md`.
- [Quoters](/contracts/quoters): All implement `IQuoter`. SwapPool calls them during swap / quote.
- [ContractRegistry](/contracts/registry): `bytes32` identifier → address. Identifiers are fixed in `initialize`; each `set` can run once.
- [SwapRouter](/contracts/router): Stateless multi-hop quoter. Holds no funds, executes no swaps. Call via `eth_call` (functions are non-`view` because pool quotes may be non-view).
- [SwapPool](/contracts/swap-pool): Vault + swap engine. ERC-20 metadata (name/symbol/decimals) but **no LP tokens**.
- [Gnosis](/chain/gnosis): `START_BLOCK` is the registry deploy. `POOL_SETTLEMENT_BLOCK` stays `0` until a pool emits `SwapSettlement`; then set it to that pool's first block.
- [Full node](/chain/node): Repo: `gnosis-node`. Docker Compose: **reth** (execution) + **nimbus** (consensus).
- [RPC](/chain/rpc): Staging uses **publicnode** for every process. WS and HTTP must be the same provider.
- [Admin](/apps/admin): `clc-app` workspace, `apps/admin`. Superadmin console.
- [Web app](/apps/web): `clc-app` workspace, `apps/web`. PWA. Vite+.