Architecture

Robin’s Reserve combines a static web application, a read and quote API, and on-chain basket contracts. A connected wallet signs and broadcasts transactions. The API does not hold user assets, signing keys, or authority to approve community basket creation.

System boundaries

Layer	Current implementation	Responsibility
Web application	React 19, Vinext/Vite, TypeScript, viem	Discovery, wallet connection, previews, transaction preparation, receipt recovery
API	Node.js 24, TypeScript, native HTTP server	Public configuration, read-only RPC gateway, discovery, execution quotes, signed metadata uploads
Index	SQLite using Node’s node:sqlite	Canonical factory creation events, pagination, block checkpoints
Media	Content-addressed JSON and WebP files	Immutable metadata URLs and re-encoded raster images
Wallet	Selected injected EIP-1193 provider	Account authorization, message signatures, transaction signing and broadcast
Contracts	Solidity, Foundry, OpenZeppelin primitives	Asset accounting, share issuance, redemptions, claims, and bounded router execution

The frontend is exported to static files in frontend/dist/client. Application reads go to the configured API’s /rpc route. Dedicated upstream RPC credentials remain in the backend environment.

Source layout

Directory or module	What to find there
frontend/app/	Static routes, including the basket detail page
frontend/components/ and frontend/hooks/	Interface and wallet/application lifecycle
frontend/lib/protocol.ts	Contract ABIs, reads, signed metadata, exact approvals, common transaction handling
frontend/lib/native-launch.ts and native-trading.ts	ETH launch/trade quote validation and execution
frontend/lib/liquidity.ts and token-pool-trading.ts	Pool discovery, liquidity funding, ETH and ERC-20 pool trades
backend/src/server.ts	Standard HTTP routes and request limits
backend/src/config.ts and main.ts	Environment validation, public configuration, startup checks
backend/src/indexer.ts and store.ts	Event replay, canonicality checks, storage
backend/src/native-launch.ts, native-trade.ts, liquidity.ts	Bounded route discovery and simulation
contracts/src/ and contracts/abi/	Contract implementation and exported ABIs
backend/tests/, frontend/tests/, contracts/test/	Automated checks

Contract roles

CommunityBasketFactory creates and seeds fixed baskets through in-kind token transfers. NativeBasketFactory adds atomic ETH-funded creation using a configured V3 venue. Each factory maintains its own isBasket registry.

FixedBasketVault exposes ERC-20 shares and a custom multi-asset interface. It is not an ERC-4626 vault. BasketVaultCore accounts separately for active reserves and pending per-token redemption claims. Direct issuance uses previewMint and mint; redemption uses previewRedeem, requestRedeem, and independent claim calls.

NativeBasketRouter buys or sells through proportional issuance and redemption for registered community/native baskets. BasketLiquidityRouter instead funds full-range share-token pools and trades existing shares. A secondary-market pool trade does not mint or burn basket shares. ERC-20-settled pool trades use the configured DEX Router02 directly.

Managed factories, vaults, and the optional settlement-token router are separate integrations. Configuring a managed registry does not grant authority over community vaults. Read network and deployment references for deployment-specific availability.

One launch, end to end

1. Read /v1/config and confirm the application, wallet, and API use the same chain.
2. Discover assets or import addresses. Inspect selected contracts through RPC and check ETH route availability.
3. Request an amount-specific launch quote. Show allocations, minimum outputs, price impact, and expiry.
4. Ask the wallet to sign the exact metadata upload message. Store the returned metadata URI in the launch configuration.
5. Recheck the account, network, draft, deployment, and quote. Simulate the transaction and estimate gas.
6. Ask the wallet to submit the atomic launch transaction. Verify the receipt and factory event.
7. Open the created basket through direct contract reads. The discovery index catches up independently.

Read-only page loads and wallet restoration do not require signatures. A metadata message signature and a funded contract transaction are distinct wallet actions.

Which data is authoritative?

Contract reads determine registered membership, active backing, supply, balances, fees, and claims. The creation index is a discovery aid. Its absence does not prove that a recently created basket does not exist.

Token-directory prices and screening are informational provider data. Quote outputs are estimates of executable swaps at a specified block. Neither establishes a dollar NAV, permanent liquidity, or compatibility with future token behavior.

The source architecture document includes historical proposals. This developer guide describes the current implementation: it does not imply that proposed database migrations, managed keepers, price oracles, or protocol-token economics are deployed.

Continue with local development, the HTTP API, or integration examples.