Skip to main content

​
Architecture

Firmament has one Rust backend and two web surfaces.
  • Rust crate: RFQ runtime, Axum HTTP API, SQLite persistence, Solana/Jupiter/Gateway adapters
  • Vite app: taker swap demo at /app and runtime view at /app/runtime
  • Next.js landing page: project positioning for demos and submissions

​
Runtime path

RFQ request
  -> quote engine
  -> risk gate
  -> wallet-settlement terms
  -> taker lock / redeem records
  -> maker HTLC actions when live workers are enabled
  -> ledger and runtime events
  -> inventory repair checks

​
Backend pieces

The RFQ API accepts a friendly shape (input_asset, output_asset, decimal amount string) or the legacy mint/raw shape (input_mint, output_mint, input_amount_raw) plus the taker wallet and an optional expiry. It returns either accepted terms with display-friendly pair, input, output, and next_action fields or a stable rejection reason with a user-facing message and suggested_action. The quote engine combines reference price, spread, inventory skew, fees, and minimum-profit policy. The risk gate checks supported assets, supported pairs, notional caps, stale prices, allowlist policy, and available inventory. Settlement uses the browser wallet for taker signatures. The backend tracks trade state, observed signatures, and maker-side actions, and persists active wallet settlements so the app can recover after a browser refresh or backend restart. Legacy local-signing taker keypairs exist for tests; they are not required for the web app. SQLite stores ledger, P&L, terminal trade summaries, and active settlement recovery state. The public runtime endpoints expose derived ledger balances and global recent trade summaries; trade rows include taker-wallet attribution when the browser-wallet flow supplied it. Ledger endpoints do not expose wallet addresses or secrets. The browser keeps the settlement preimage locally until redeem time. The server stores the hash commitment and signatures it needs to recover settlement state, but it does not persist the preimage. Jupiter and Circle Gateway are live adapters. They run only when protocol workers and required credentials are configured. Jupiter config should point at Swap API V2 (https://api.jup.ag/swap/v2). The adapter uses /order plus /execute for managed swaps and keeps /build parsing covered for raw instruction tests. Circle Gateway config uses the maker’s approved Solana depositor address. Gateway deposits move Solana USDC into the unified balance; Gateway refill mints/transfers USDC back to the maker’s Solana working wallet.

​
Public boundary

Public docs cover the app-facing swap and runtime routes. Admin routes and the disabled legacy accept route are intentionally left out of the public reference.