721cdeb92f
Some checks failed
CI/CD Pipeline / Solidity Contracts (push) Failing after 1m25s
CI/CD Pipeline / Lint and Format (push) Has been cancelled
CI/CD Pipeline / Terraform Validation (push) Has been cancelled
CI/CD Pipeline / Kubernetes Validation (push) Has been cancelled
Deploy ChainID 138 / Deploy ChainID 138 (push) Has been cancelled
Validation / validate-genesis (push) Has been cancelled
Validation / validate-terraform (push) Has been cancelled
Validation / validate-kubernetes (push) Has been cancelled
Validation / validate-smart-contracts (push) Has been cancelled
Validation / validate-security (push) Has been cancelled
Validation / validate-documentation (push) Has been cancelled
CI/CD Pipeline / Security Scanning (push) Successful in 13m49s
Verify Deployment / Verify Deployment (push) Failing after 1m22s
75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# Route Decision Tree
|
|
|
|
This document describes the live route-selection tree used by the Token Aggregation Service.
|
|
|
|
## What It Does
|
|
|
|
- Resolves pools from the live indexed database.
|
|
- Normalizes token labels using the token table and canonical token list.
|
|
- Falls back to raw addresses when token metadata is missing, so "missing quote token" pools still render.
|
|
- Returns pool depth and freshness on every request.
|
|
- Expands the route tree with bridge and destination-swap legs when a destination chain is provided.
|
|
|
|
## API
|
|
|
|
### Live tree
|
|
|
|
```bash
|
|
GET /api/v1/routes/tree?chainId=138&tokenIn=0x...&tokenOut=0x...&amountIn=1000000&destinationChainId=1
|
|
```
|
|
|
|
### Depth summary
|
|
|
|
```bash
|
|
GET /api/v1/routes/depth?chainId=138&tokenIn=0x...&tokenOut=0x...&amountIn=1000000&destinationChainId=1
|
|
```
|
|
|
|
## Decision Order
|
|
|
|
1. Resolve the source token and destination token.
|
|
2. Load all live pools for the source token on the source chain.
|
|
3. Prefer direct pools for the requested pair, ordered by TVL.
|
|
4. If a destination chain is provided, add:
|
|
- bridge leg
|
|
- destination swap leg, when destination liquidity exists
|
|
5. Mark pools with stale or missing depth so routing can avoid them.
|
|
|
|
## Decision Tree
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A["Start"] --> B["Resolve source token"]
|
|
B --> C["Load live source pools"]
|
|
C --> D{"Direct pool exists?"}
|
|
D -->|Yes| E["Rank by TVL and freshness"]
|
|
D -->|No| F["Bridge or fallback route"]
|
|
E --> G{"Destination chain provided?"}
|
|
F --> G
|
|
G -->|No| H["Return direct-pool decision"]
|
|
G -->|Yes| I["Add bridge leg"]
|
|
I --> J{"Destination liquidity exists?"}
|
|
J -->|Yes| K["Add destination swap leg"]
|
|
J -->|No| L["Bridge-only decision"]
|
|
K --> M["Return atomic-swap-bridge tree"]
|
|
L --> N["Return bridge-only tree"]
|
|
```
|
|
|
|
## Missing Quote Token Pools
|
|
|
|
The service now resolves token labels in this order:
|
|
|
|
1. Token row from the database.
|
|
2. Canonical token mapping for the chain.
|
|
3. Raw address fallback.
|
|
|
|
That means pools with incomplete token metadata still appear in the API and UI, instead of collapsing to `?` or being dropped entirely.
|
|
|
|
## Notes
|
|
|
|
- Route depth is derived from current pool TVL and freshness.
|
|
- The endpoint is intentionally short-cache so it follows the current pool index.
|
|
- For the full funding flow, the tree reflects:
|
|
- direct pool on Chain 138
|
|
- atomic swap + bridge from Chain 138
|
|
- destination-side completion on the target chain
|