Local development

Requirements

• Bun
• Fuel toolchain manager (fuelup); fuel-toolchain.toml pins Forc 0.68.1 and Fuel Core 0.43.1 to match fuels 0.101.1

Run locally

fuelup toolchain install mainnet
fuelup component add [email protected]
fuelup component add [email protected]
bun install
bun run dev

Run bunx fuels versions from the repository to confirm all three versions match before building.

The development runner creates or loads separate local deployer and price-oracle wallets, starts a controlled Fuel test node, funds only the deployer with local test assets, deploys the Sway contract with every configurable set, updates the public local deployment artifact, and starts the local application services. The price oracle signs offchain and does not need gas funds.

Deployment wallets

Wallet secrets are role- and network-separated under .secrets/fuel-credit/<env>/<role>.json, with 0700 directories and 0600 files. They are gitignored. Files store a recovery mnemonic, not a duplicate private key. Environment overrides are supported with FUEL_CREDIT_DEPLOYER_KEY and FUEL_CREDIT_PRICE_ORACLE_KEY.

# Create deployer and price-oracle wallets; prints each new mnemonic once.
bun run scripts/wallets.ts init local
bun run scripts/wallets.ts init testnet

# Print public addresses and deployer balances; never prints secrets.
bun run scripts/wallets.ts status local
bun run scripts/wallets.ts status testnet

bun run dev automatically funds the local deployer from its controlled ephemeral genesis wallet. For a separately managed local node, set FUEL_CREDIT_LOCAL_FUNDER_KEY to an explicitly funded local-only wallet and run:

bun run scripts/wallets.ts fund local

The price oracle must remain separate and unfunded unless it later submits transactions. Price attestations sign the digest returned by price_attestation_digest_for(price, timestamp) directly; signMessage() is never used because it hashes again. After a local contract is running, an explicit test attestation can be produced with:

bun run scripts/oracle.ts local <scaled-fuel-usdc-price> [tai64-timestamp]

The command reads the recorded contract, derives the current Fuel block timestamp when omitted, and prints only public attestation fields and the signature. It does not fetch a price or run unattended.

Mainnet wallet creation requires typed confirmation. Noninteractive creation additionally requires FUEL_CREDIT_MAINNET_WALLET_INIT_CONFIRM=create-mainnet-wallets. bun run testnet requires FUEL_CREDIT_TESTNET_DEPLOY_CONFIRM=deploy-testnet, uses release artifacts and storage slots, verifies owner() and price_oracle(), records the deployment, and refuses to overwrite an existing contract ID. bun run mainnet remains fail-closed pending the production price-oracle service, app transaction wiring, audit, pool funding, monitoring, and explicit release approval. The shared SDK helper sets INITIAL_OWNER, INITIAL_PRICE_ORACLE, CHAIN_ID, FUEL, and USDC configurables.

Test

bun test

This rejects toolchain drift, runs TypeScript checks, builds the frontend, runs Sway unit tests, launches Fuel Core, deploys the exact generated ABI/bytecode/storage slots, and exercises the price-attested loan lifecycle.

Testing and security coverage

Current validated coverage: 13 project tests with 538 assertions, plus 13 Sway unit tests. Contract coverage is organized by purpose:

• contracts/fuel-credit/src/main.sw: min/middle/max math values, time boundaries, attestation domain binding, supported terms, and expected-revert unit tests.
• test/contract.integration.test.ts: public ABI validation and one complete loan lifecycle.
• test/contract.multi-loan.e2e.test.ts: exact per-loan and aggregate accounting across mixed terms and statuses.
• test/contract.adversarial.e2e.test.ts: oracle, authorization, liquidity, collateral, settlement, and rollback attack attempts.
• test/contract.admin.e2e.test.ts: ownership-transfer chains, permissionless funding, and delinquency boundary/revert cases.
• test/demoLoans.test.ts: browser-only Burner simulation behavior.

Build documentation

bunx vitepress build docs

Repository

Source code and tickets are available at SilentCicero/fuel-credit.