Appearance
System overview
Four repositories, one backend, three on-chain vault contracts, and a per-chain settlement relayer. This page is the map; the rest of the section is the territory.
Trading coreQuote fan-out, swap-sdk aggregation, and the BlazpayRelayer settlement contract.Automation coreThe shared execution engine, both vault contracts, and the policy engine.AI coreThe LangGraph intent engine, the chat request path, and the action renderer.PlatformData model, frontend architecture, the SEO subsystem, and the security model.
The whole system on one page
Per-layer detail is in the pages linked at the bottom of this page; the two request paths that matter most are drawn out in quote → settle pipeline and chat request path.
Layer responsibilities
| Layer | Owns | Deliberately does not own |
|---|---|---|
defi-dex | Rendering, wallet interaction, streaming consumption, route preselection | Interpreting free text, choosing a route, holding secrets |
bz-agent | Intent classification, parameter extraction, conversational answers | Chain access, execution, token resolution |
bz-backend | Quote fan-out, provider secrets, route building, EIP-712 signing, automation crons, all persistence, the ecosystem layer | Deciding what a sentence means |
swap-sdk | One class per aggregator, relayer meta-transaction assembly, chain and address constants | API keys (injected via configure), business rules |
| Contracts | Settlement, custody guarantees, spending limits | Route selection, pricing |
Four things worth understanding first
1. The frontend consumes swap-sdk too
swap-sdk is not a server-only library. defi-dex/src/utils/trade.ts wraps it, and the frontend uses RelayerFactory directly to build and send the settlement transaction with the user's BrowserProvider.
The practical consequence: an SDK version bump is a coordinated release across two consumers. Both bz-backend/package.json and defi-dex/package.json pin github:blazpay/swap-sdk#vX.Y.Z, and they can drift. At the time of writing the backend is on v1.12.0 and the frontend has lagged in the past.
2. Quoting is two round-trips, on purpose
Provider APIs separate quoting from transaction building, and raw provider responses are too large to ship to a browser. So:
GET /defi/quotes(SSE) streams smallmetaobjects and caches the full{ data, meta, restProps }in Redis undermeta.idfor five minutes.GET /defi/swap/:idrehydrates that and calls the provider's build endpoint.
This is why a quote expires, and why the confirm screen can fail after a long pause.
3. Automation and interactive trading share the routing layer but not the settlement contract
| Path | Settles through |
|---|---|
| Interactive swap / bridge | BlazpayRelayer |
| CSIP scheduled buy | DCA vault's own batchExecuteDeposit |
| Autopilot trade | Autopilot vault's own executeTrade / batchExecuteTrades |
All three ask swap-sdk for a route. Only the first goes through the relayer. That is why the vaults have their own minOut and measured-delta logic — they cannot rely on the relayer's protections.
4. Nothing in the chat path can spend money on its own
The agent produces an intent object. The backend re-resolves every parameter against real Network and Token records and real provider quotes. The user signs. A prompt injection can at worst produce a wrong intent object, which then fails resolution or produces a card the user declines.
Request-path summaries
Interactive swap — defi-dex → SSE /defi/quotes → swap.service → swap-sdk fan-out → Redis cache → user picks → /defi/swap/:id build → /defi/sign EIP-712 → user sends executeMetaTransactionSwap. Detail: quote → settle pipeline.
Chat message — defi-dex → SSE /v1/blaz/message/stream → blaz.controller persists → agent.service → bz-agent /chat/:sessionId → LangGraph → intent + params → handler executes → { text, data, action } → SSE meta/token/done → BotMessage renders. Detail: chat request path.
Scheduled buy — dcaCron tick → read due positions → executionEngine quotes top 3 candidates → probe each with estimateGas → batchExecuteDeposit → vault credits measured delta → processAutoClaims. Detail: execution engine.
Autopilot trade — autopilotCron tick → sync on-chain state → autopilotEngine evaluates triggers against the Redis price series → RugCheck safety gate → executionEngine route + probe → batchExecuteTrades → measured delta minus 20 bps. Detail: policy engine.
Where to go next
| If you are working on… | Read |
|---|---|
| Adding or debugging a liquidity provider | swap-sdk internals, add a provider |
| A settlement bug or a fee question | BlazpayRelayer |
| Solana or TRON | non-EVM paths |
| CSIP or Autopilot execution | execution engine |
| An Autopilot policy or trigger | policy engine |
| A new AI capability | agent graph, add an intent |
| Chat rendering | action renderer |
| A schema or query question | data model |
| Bundle size, routing, or the two shells | frontend architecture |
| Landing pages, sitemaps, crawlers | SEO subsystem |
| A threat-model question | security model |
| Hosts, ports, processes | runtime topology |