Architecture

System shape

React app ── Fuel Connector / fuels-ts ── Fuel Ignition/Testnet
   │                                      │
   │                                      └── FuelCredit Sway contract
   │                                             ├── FUEL collateral in
   │                                             ├── USDC loan out
   │                                             └── events for indexing
   │
   └── Stats API ── Cloudflare Worker + Durable Object + D1/R2
                         └── Fuel GraphQL RPC event scanner

Frontend

• React, TypeScript, vanilla CSS.
• Hosted on Cloudflare Pages at fuel.credit.
• Uses Fuel Connector skill patterns and fuels-ts.
• Default network: Fuel Ignition mainnet. Testnet/local selectable for development.
• Main page stays simple: connect wallet, choose FUEL amount, choose term, review USDC received and amount owed, confirm.
• Connected wallet shows active/expired/delinquent loans and repayment actions.
• Every transaction confirmation links to the relevant Fuel explorer.

Fuel TypeScript SDK reference: https://docs.fuel.network/docs/fuels-ts/ Fuel GraphQL reference: https://docs.fuel.network/docs/graphql/overview/

Contract

One Sway contract should own the lending pool and loans.

Core storage:

• immutable/configurable asset IDs for FUEL and USDC per environment
• owner and guardian/keeper addresses
• term configs: duration, advance bps, interest APY bps
• loan records keyed by loan_id
• user loan IDs
• pool accounting: total funded, total lent, total repaid, total collateral locked

Core calls:

• fund_pool() deposits USDC liquidity.
• withdraw_pool() lets owner/authorized liquidity manager remove idle USDC.
• open_loan(term, oracle_quote) accepts FUEL and sends USDC.
• repay(loan_id) accepts USDC and unlocks pro-rata collateral.
• repay_with_fuel(loan_id, oracle_quote) accepts FUEL-valued interest where enabled.
• claim_collateral(loan_id) returns any unlocked FUEL after repayment.
• mark_delinquent(loan_id) keeper call after maturity + 2 weeks.
• read-only views for loan and pool state.

Standards/guides to follow:

• Forc build/test/deploy harness: https://docs.fuel.network/docs/forc/
• Sway blockchain development: https://docs.fuel.network/docs/sway/blockchain-development/
• Sway standards: https://docs.fuel.network/docs/sway-standards/
• SRC-20 example for local/mock asset metadata and test tokens: https://docs.fuel.network/docs/sway-by-example-lib/src20/
• Use SRC-5 ownership/access-control patterns where practical.
• Use SRC-2 inline documentation style for public ABI functions.

Assets

Use verified Fuel asset IDs from Fuel docs. Current mainnet verified IDs captured in docs/DEPLOYMENTS.md; testnet IDs must be confirmed during implementation because the verified-addresses page may change.

Oracle

Phase 1 uses a fake signed oracle Worker for local/testnet scaffolding. It signs FUEL/USD price quotes with expiry and chain ID.

Phase 2 replaces it with Stork Fuel integration. The contract interface should keep oracle verification isolated so the fake signer can be removed without rewriting loan logic.

Stats and indexing

Cloudflare Worker + Durable Object indexes contract events using Fuel GraphQL RPC.

Fuel GraphQL endpoints:

• Testnet: https://testnet.fuel.network/v1/graphql
• Mainnet: https://mainnet.fuel.network/v1/graphql
• Testnet chain ID: 0
• Mainnet chain ID: 9889

MVP Worker endpoints:

• /health returns Worker/network health.
• /stats returns the cached stats blob.
• /stats.csv and /snapshots/latest.csv return the latest blob as downloadable CSV.
• /refresh updates the cache timestamp now and is the hook for the GraphQL scanner.

Indexer behavior:

• Start from deployment block recorded in deployments/*.json.
• Poll every 1 minute locally, 5-10 minutes in production.
• Handle 429s with exponential backoff and cursor persistence.
• Store raw cursor/event checkpoints in D1.
• Publish a compact stats blob from Durable Object memory/storage.
• Write one daily historical blob for CSV download.

Stats to expose:

• total users
• loans opened, active, expired, delinquent
• total open interest
• total funds lent out
• total funds available
• all-time pool size
• loans by size
• average loan size
• FUEL locked in loans and rough percentage of total FUEL supply

Cloudflare

• Cloudflare Pages for frontend.
• Cloudflare Worker for stats/indexer API.
• Durable Object for hourly stats aggregation cache.
• D1 for event/index checkpoints and loan-event projections.
• R2 or D1 table for daily CSV/historical snapshots; choose D1 first unless files become large.

Minimal developer CLI

bun install
bun test
bun run dev
bun run testnet
bun run mainnet

Scripts should deploy contracts, generate ABI/type artifacts, update deployment JSON, and deploy Workers/Pages for the selected environment.