clc-core

HTTP API, SIWE sessions, catalog, contract deploy jobs, EIP-7702 relayer.

Staging: https://gnosis-staging.cosmolocal.credit

Auth

Two credentials, mutually exclusive on a request:

	User	Service
Proof	SIWE or WebAuthn	EdDSA JWT from `gen-service-token`
Transport	cookie `__clc_auth` (HttpOnly, 30d)	`Authorization: Bearer` or `__ge_cust_auth`
Claims	`userId`, `ethereumAddress`, `role`	`publicKey`, `service: true`

Service tokens skip user quotas and cannot hit /api/v2/users/*.

SIWE (EOA / paper wallet):

POST /auth/nonce  →  sign EIP-4361  →  POST /auth/signin | /auth/signup | /auth/siwe/verify

Nonce TTL 5 minutes, one-time. Verification is local (go-ethereum ecrecover), no RPC.

Passkey: POST /auth/webauthn/verify. No SIWE. Relies on P-256 assertion.

User lifecycle: PENDING at signup → superadmin PUT /api/v2/admin/users/:address/approve → APPROVED. Sign-in of a pending address fails.

GET /auth/session: 204 = no session, 200 { address, chainId } = ok.

Shape

/auth/*          public
/api/v2/*        cookie or service JWT
/api/v2/users/*  user JWT only
/api/v2/admin/*  SUPERADMIN
/api/v2/relayer/*  see Relayer

Public catalog (no auth): GET /api/v2/vouchers, GET /api/v2/vouchers/:address, offerings under those.

Errors:

{ "ok": false, "description": "Not Found", "code": "E03" }

Full route list: clc-core/docs/API.md and docs/swagger.yaml.

Chain config

CORE_CHAIN__ID=100
CORE_CHAIN__RPC_ENDPOINT=https://gnosis-rpc.publicnode.com
CORE_CHAIN__GE_REGISTRY=0xaC95B1A09f2dbaf4542e3Ba8c4Cce0234895D389
CORE_CHAIN__DIVVI_CONSUMER=0x0000000000000000000000000000000000000000
CORE_RELAYER__CALIBUR_ADDRESS=0x48A910C8e9FF0b14051b78d0c96dB069E57f0729

Keystore

Master signing key is created on first boot and stored in keystore. That address must be an AccountsIndex writer. A volume rebuild generates a new key:

docker compose exec -T postgres psql -U postgres -d clc_core -tAc \
  "SELECT public_key FROM keystore;"
 
cast send 0xB1Ec3942dc9258de62056Febb0dc544D9EB1ED1a \
  "addWriter(address)" <that address> \
  --rpc-url "$RPC_URL" --private-key $DEPLOYER_KEY