12. Data Model (Reference)

The protocol can be modeled with a small set of persistent entities: Swap/Exchange, RoutePlan, Leg, and Asset metadata.

---

Entity Diagram

Figure 8. Reference data model (Swap/Exchange ↔ RoutePlan ↔ Leg).

---

Entities

SwapExchange

Field	Type	Description
id	string	Unique exchange identifier.
type	enum	standard, private, or defi.
status	enum	Current state in the exchange lifecycle.
created	datetime	Timestamp of exchange creation.
request	object	Swap intent: from/to assets, networks, amount.
deposit_instructions	object	Address and memo for the user's inbound deposit.
recipient	string	Destination address for the output asset.

RoutePlan

Field	Type	Description
swap_id	string	Reference to the parent SwapExchange.
snapshot_id	string	Graph snapshot used to compute this plan.
legs	array	Ordered list of leg references.
score	number	Composite score from the routing engine.
ttl	number	Expiry time; plan is stale after this.

Leg

Field	Type	Description
leg_id	string	Unique leg identifier.
swap_id	string	Reference to the parent SwapExchange.
kind	enum	DEX, CEX, provider, or relay.
status	enum	Current execution state of this leg.
external_refs	object	Tx hashes, order IDs, or provider references.
amounts	object	Input/output amounts and fees for this leg.
timestamps	object	Created, updated, and confirmed timestamps.

Asset

Field	Type	Description
ticker	string	Asset symbol (e.g. USDT).
address	string	Contract or native address on the network.
network	string	Network identifier (e.g. eth, sol).
decimals	number	Token decimal precision.
regexAddress	string	Validation pattern for recipient addresses.
explorers	array	Block explorer URLs for this network.

---

Relationships

Relationship	Cardinality	Description
SwapExchange → RoutePlan	1:1	Each exchange has exactly one locked route plan.
RoutePlan → Leg	1:N	A route plan is composed of one or more ordered legs.
SwapExchange → Leg	1:N	A swap directly references all its legs for status tracking.
SwapExchange → Asset	uses	Exchange references Asset metadata for validation and display.