# 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

```mermaid
erDiagram
    SwapExchange {
        string id
        string type "standard | private | defi"
        string status
        datetime created
        object request "from/to, networks, amount"
        object deposit_instructions
        string recipient
    }

    RoutePlan {
        string swap_id
        string snapshot_id
        array legs
        number score
        number ttl
    }

    Leg {
        string leg_id
        string swap_id
        string kind "DEX | CEX | provider | relay"
        string status
        object external_refs
        object amounts
        object timestamps
    }

    Asset {
        string ticker
        string address
        string network
        number decimals
        string regexAddress
        array explorers
    }

    SwapExchange ||--|| RoutePlan : "1:1"
    RoutePlan ||--|{ Leg : "1:N"
    SwapExchange ||--|{ Leg : "1:N"
    SwapExchange }|--|| Asset : "uses"
```

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

***

### Entities

#### SwapExchange

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

#### RoutePlan

<table><thead><tr><th width="138">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>swap_id</code></td><td>string</td><td>Reference to the parent SwapExchange.</td></tr><tr><td><code>snapshot_id</code></td><td>string</td><td>Graph snapshot used to compute this plan.</td></tr><tr><td><code>legs</code></td><td>array</td><td>Ordered list of leg references.</td></tr><tr><td><code>score</code></td><td>number</td><td>Composite score from the routing engine.</td></tr><tr><td><code>ttl</code></td><td>number</td><td>Expiry time; plan is stale after this.</td></tr></tbody></table>

#### 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. |