Oracle & Reserves

Who it's for: Developers building products that use cGHS prices or need proof that the stablecoin is fully backed — including lending, liquidity, and audit integrations. Why it matters: Live GHS/USD rates keep every product fairly priced, and cryptographic proof of reserves means users can verify the stablecoin is fully backed without trusting anyone's word.

Oracle

The cGHS price oracle is a Chainlink-compatible feed. The service pushes GHS/USD every 6 hours via cron, and also supports factory-deployed oracles for other currencies.

`GET /oracle/price`

{
  "currency": "ghs",
  "priceUsd": "0.065230",
  "rawAnswer": "6523000",
  "roundId": "42",
  "updatedAt": 1710854400
}

`GET /oracle/round?roundId=42`

{ "roundId": "42", "answer": "6523000", "startedAt": 1710850800, "updatedAt": 1710854400 }

`POST /oracle/push`

Manually trigger an oracle price push. Useful after deployment or emergencies.

Request: { "force": false } (set true to push even if price hasn't changed)

Response

{
  "success": true,
  "currency": "ghs",
  "fiatUsd": "0.065230",
  "price": "6523000",
  "txHash": "0xdeadbeef..."
}

Currency Conversion

GET /oracle/convert/usd-to-fiat/:amount   → { usdAmount, fiatAmount, currency, rate }
GET /oracle/convert/fiat-to-usd/:amount   → { fiatAmount, usdAmount, currency, rate }

Multi-Currency Oracle Factory

GET  /oracle/list             → { factory, currencies[] }
GET  /oracle/source           → { currency, currentFiatUsd, sqrtPriceX96 }
POST /oracle/create           Body: { currency }  → deploy new aggregator + proxy
POST /oracle/push/factory     Body: { currency }  → push price for a factory oracle

Proof of Reserves

cGHS is 100% fiat-backed. Reserves are verified on-chain using KZG — a zero-knowledge proof system that proves total fiat deposits without revealing individual accounts.

`GET /reserves/full-proof`

Triggers a full proof cycle and returns the result.

{
  "success": true,
  "preprocessDone": true,
  "kzgQueryId": "kzg-query-id",
  "provenReserves": "5012500000000",
  "onChainSupply": "5000000000000",
  "fullyBacked": true,
  "proof": "0xzkproof...",
  "timestamp": 1710854400
}

`GET /reserves/compare`

Quick check — on-chain supply vs. proven reserves.

{
  "success": true,
  "onChainSupply": "5000000000000",
  "provenReserves": "5012500000000",
  "fullyBacked": true,
  "timestamp": 1710854400
}

`GET /reserves/proof?query=...`

Submit a KZG query string and return proof details.

`POST /reserves/verify/:queryId`

Verify a previously submitted KZG proof by query ID.

`GET /reserves/db`

Returns all reserve records.

{ "success": true, "total": 1423, "rows": [ ... ] }