Services and storage
The BlockFinaX API is one Node.js service exposing /api/v2. Chain-specific code is isolated in adapters; everything else is chain-neutral.
| Service | Role |
|---|---|
| Quote service | Turns a protection request into a signed, executable quote: finds candidate pools, prices with the engine (Pricing methodology), checks terms and capacity, picks the cheapest, signs. |
| Pricing engine | Fair price per contract: Garman-Kohlhagen with Merton jumps and GARCH variance. See Pricing model. |
| Market data | Live rates (cached 5 minutes), daily history, intraday snapshots for charts. |
| Stellar adapter | Reads pools and positions, prepares unsigned transactions, signs quotes with the pricing key, relays user-signed transactions. |
| Stellar relayer | Checks a user-signed transaction against an allowlist (USDC transfers, USDC approvals to Circle's TokenMessengerMinter, Circle's deposit_for_burn_with_hook from the user's own wallet, BlockFinaX contracts, the user's own wallet for add_signer) and submits it through OpenZeppelin Channels, with BlockFinaX's fee account paying only if Channels cannot. For a business account it also applies the member's role: admins may change the account's signers and rules, operators may send pool calls only, viewers nothing. |
| Business account service | Business accounts: deploys each one, keeps members, roles and invitations, prepares each change to the account's signers and rules for an admin to approve, and confirms it by reading the account back from chain. |
| EVM relayer | Builds ERC-4337 user operations for the user's passkey smart account and gets them sponsored by a paymaster: Coinbase Developer Platform first, Pimlico as automatic fallback. Only allowlisted calls are sponsored: USDC approve and transfer, Circle's TokenMessengerV2, BlockFinaX contracts. |
| Deposit watcher | Every 20 seconds, reads the canonical USDC balance of every user's deposit address (Multicall3) and, at or above the minimum, records a route and calls factory.flush from the platform smart account. |
| Platform smart account | A Coinbase Smart Wallet owned by a BlockFinaX key, used to trigger deposit flushes. Its operations go through the same paymasters. It can trigger a flush but cannot change where funds go. |
| Oracle job | Every 5 minutes: finds expired positions, submits rates as each operator, settles positions with an agreed rate. |
| Account service | Users, their chain accounts, passkeys and sessions. |
| Routing | Funding and withdrawal between EVM networks and Stellar through Circle CCTP: follows each burn to Circle's attestation, mints on Stellar through CctpForwarder.mint_and_forward, and keeps a ledger of every step. A worker advances open routes every 20 seconds. |
Off-chain storage
PostgreSQL holds data that is not on chain:
| Data | Purpose |
|---|---|
| Users, sessions | Sign-in (sessions expire after 12 hours) |
| Chain accounts, passkeys | Mapping a user to wallet addresses and public keys |
Business accounts (business_accounts, business_account_members, business_account_events) | Each business's account and rule ids, its members and roles, invitations (stored as hashes), and a history of changes with transaction hashes |
| Rate history and snapshots | Pricing inputs and charts |
Routing records and ledger (routing_routes, routing_ledger) | Every cross-network transfer and every ledger entry, so a restart never loses money in transit |
| Verification submissions | Account verification review |
Balances, positions and pool state are always read from chain. The database is never the source of truth for funds.