Docs

Architecture

How the web app, API, shared packages, settlement contract and verifier fit together.

Overview

architecture
 Browser ──── sama-frontend (Next.js 16, React 19)
   │             │  fetch, cookie session
   │             ▼
   │          sama-backend (Elysia on Bun) ── Postgres / PGlite
   │             │  @sama/* packages: assets · oracle · portfolio · matcher
   │             │                     settlement · verifier · residual · pancakeswap
   │             ├── BNB Chain RPC (executor)      balances, snapshot, simulation
   │             ├── BNB Chain RPC (verifier)      a different provider
   │             └── Binance Web3 API              stock prices
   │
   └── Privy wallet ── EIP-712 signatures, approve, settle() ──▶ SamaSettlement (BSC 56)

Repositories

FolderWhat lives there
sama-frontendNext.js app: landing, docs, onboarding, portfolio, Circles, rounds, activity. Talks to the API or runs fully in the browser in mock mode
sama-backendElysia API on Bun: sessions, targets, Circles, the round state machine, leftovers, proof
sama-packagesDomain logic as @sama/* packages, imported by the backend without a build step
sama-contractSamaSettlement.sol, Foundry tests and the deploy script

Packages

PackageResponsibility
@sama/sharedChain config, fixed-point math, canonical JSON, logging, deployments
@sama/assetsAllowlist, on-chain checks, BEP-8056 multipliers, market calendar, TWAP reads
@sama/binance, @sama/oracleStock prices and the per-round snapshot with cross-checks
@sama/portfolioHoldings, targets, rebalance deltas, intent limits
@sama/matcherThe production solver (sama-mmcc-1)
@sama/reference-matcherIndependent solvers that check the matcher in tests
@sama/circlesMembership, assets and round scheduling
@sama/settlementEIP-712 types, canonical plans, preflight, generated contract bindings
@sama/verifierSettlement verification from chain data only
@sama/residual, @sama/pancakeswapLeftover recommendations and PancakeSwap quotes and swaps
@sama/agentOptional natural-language target interpreter; code resolves every number
@sama/api-typesWire types shared by the API and the frontend

A round, end to end

  1. 1POST /api/circles/:id/round opens a round with a price snapshot pinned to one block.
  2. 2Each member fetches GET /api/rounds/:id/intent, signs the EIP-712 payload, and posts it back.
  3. 3At the freeze time the background loop runs the matcher and builds a canonical plan.
  4. 4Participants fetch GET /api/rounds/:id/approval, sign the plan and send exact approve transactions.
  5. 5Any participant fetches GET /api/rounds/:id/settle, sends settle(), and reports the hash with POST.
  6. 6The API checks the hash against the plan, waits for the receipt, runs the verifier on a second RPC and records the result.

Data

Postgres holds offchain state only: users, targets, Circles, memberships, invites, rounds and their history, intents, approvals, leftover decisions and activity. Balances, prices and settlements are always re-read from BNB Chain. Local development uses PGlite with the same schema.