Architecture
The packages, how they depend on each other, and what happens between a quote and an arrival.
The parts
Mavna is a set of packages, a React widget built on them, an app built on the widget, and one server process, the sponsor.
| Layer | What it is | Depends on |
|---|---|---|
@mavna/core | the types every other package shares, and the BridgeAdapter interface | nothing |
@mavna/routing, @mavna/stellar, @mavna/status | racing and ranking, Stellar reads and transaction builders, transfer tracking | core |
@mavna/swap | Stellar exchanges behind one interface | core, stellar |
| the four adapters | one rail each: CCTP, Axelar, LayerZero, NEAR Intents | core, routing, stellar |
@mavna/widget | the whole flow as a React component, and the one place transactions are signed, through the sender's wallets | all of the above |
apps/app | the Mavna app: the widget in its full-page layout | widget |
services/sponsor | the server that sets up new accounts, delivers Circle transfers and finishes conversions | core, stellar, swap, the CCTP and LayerZero adapters |
The SDK packages build transactions and never sign them: none of them, outside the widget, calls a signing function. The sponsor is the only process that holds a key; Run Mavna lists what it signs.
The life of a transfer
- Quote. The widget asks every rail at once with
raceAdapters. Each adapter checks the destination on Stellar, prices the transfer, and answers with a route or a refusal with a reason. Routes appear as they arrive. See Quote and rank routes. - Prepare the destination. When the Stellar address cannot receive yet, the route includes setting the account up. With a sponsor that covers reserves, the account first signs the repayment of the reserve, and only then is the account set up. See Sponsorship.
- Send. The rail that quoted the route builds the transactions; the sender's wallet signs and sends them. See Build and sign transactions.
- Deliver. The rail carries the money to Stellar. For Circle, the sponsor or the receiving account submits the mint once Circle attests the transfer. See Delivery.
- Convert. When the sender asked for another asset than the rail delivers, a conversion on a Stellar exchange follows, or the Arrival Contract converts on arrival. See Conversion on Stellar.
- Track. The widget reads each step's state from the chains, and any browser can find the transfer again from its source transaction. See Track and resume a transfer.