bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
# Tezos USDtz Integration — Implementation Roadmap
|
|
|
|
**Last Updated:** 2026-02-01
|
|
**Status:** Active — Gap remediation and integration
|
|
|
|
---
|
|
|
|
## Priority Overview
|
|
|
|
| Priority | Focus | Blockers Removed |
|
|
|----------|-------|------------------|
|
|
| **P1** | Validation & bridge discovery | Production-ready route plans |
|
|
| **P2** | Real quotes and fees | Accurate UX and routing |
|
|
| **P3** | Execution path | End-to-end execution |
|
|
| **P4** | Polish & hardening | Security and compliance |
|
|
|
|
---
|
|
|
|
## P1 — Validation & Bridge Discovery (Critical Path)
|
|
|
|
### P1-1: Verify USDtz contract on Tezos mainnet and document
|
|
|
|
**Why first:** Route targets an unverified contract; wrong address breaks delivery.
|
|
|
|
**Steps:**
|
|
1. Query TzKT API: `GET https://api.tzkt.io/v1/contracts/KT1LN4LPSqTMS7Sd2CJw4bbDGR5Mv2t68Fy9`
|
|
2. Confirm FA1.2 interface (balanceOf, transfer entrypoints)
|
|
3. Verify token metadata (symbol, decimals) via `GET .../bigmaps/...`
|
|
4. Update [TEZOS_TOKEN_REGISTRY.md](TEZOS_TOKEN_REGISTRY.md) with verified address and metadata
|
|
5. Add optional runtime check in `tezos-dex-quote.service.ts` (fetch token info on init)
|
|
|
|
---
|
|
|
|
### P1-2: Research and add active ETH→Tezos bridge to capability matrix
|
|
|
|
**Why:** Without an active bridge, Route Class B cannot execute.
|
|
|
|
**Steps:**
|
|
1. Check current status of:
|
|
- **Wrap Protocol** — wrap.xyz / Wrap
|
|
- **Allbridge** — allbridge.io
|
|
- **Multichain** — multichain.xyz (deprecated/inactive?)
|
|
- **Plenty bridge** — plenty defi ecosystem
|
|
- **MVM Bridge** — Tezos↔Ethereum (Chainspot)
|
|
2. For each candidate:
|
|
- Confirm USDC/USDT support
|
|
- Note API/docs for quotes and execution
|
|
- Classify method (lock/mint, wrapped, custodial)
|
|
3. Update [bridge-capability-matrix.ts](../../dbis_core/src/core/defi/tezos-usdtz/bridge-capability-matrix.ts):
|
|
- Set `status: 'active'` for verified bridges
|
|
- Add `apiUrl`, `docsUrl` if useful
|
|
4. Add bridge-specific quote/execute adapters (new files per bridge)
|
|
|
|
---
|
|
|
|
### P1-3: Replace TBD bridge provider in route-routes and route-planner
|
|
|
|
**Why:** Eliminates placeholder in route output.
|
|
|
|
**Status:** route-routes.ts uses constant `ETH_TO_TEZOS_PROVIDER = 'Wrap Protocol'` (no "TBD"). To make provider dynamic, use `eth2tz[0]?.provider ?? 'Wrap Protocol'` when loading from bridge-capability-matrix.
|
|
|
|
**Steps:**
|
|
1. In [route-routes.ts](../../multi-chain-execution/src/api/route-routes.ts): Currently uses `ETH_TO_TEZOS_PROVIDER` constant; optional: replace with `eth2tz[0]?.provider ?? 'Wrap Protocol'` when matrix is queried
|
|
2. In [route-planner.service.ts](../../dbis_core/src/core/defi/tezos-usdtz/route-planner.service.ts): Use `getCandidateBridgesForPlanning` (already done) — verify it returns a provider when one is active
|
|
3. When no active bridge: return clear error, e.g. `"No active Ethereum→Tezos bridge; check bridge-capability-matrix"`
|
|
|
|
---
|
|
|
|
## P2 — Real Quotes and Fees (Accuracy)
|
|
|
|
### P2-1: Integrate Tezos DEX quote APIs (Plenty/Quipuswap/SpicySwap)
|
|
|
|
**Why:** USDC/USDT→USDtz quotes are currently 1:1 stubs.
|
|
|
|
**Steps:**
|
|
1. Identify DEX APIs:
|
|
- **Plenty:** `https://api.plenty.network` or equivalent
|
|
- **Quipuswap:** `https://api.quipuswap.com` or similar
|
|
- **SpicySwap:** API docs
|
|
2. Add `TezosDexQuoteProvider` interface in `tezos-dex-quote.service.ts`
|
|
3. Implement one provider (e.g. Plenty) first:
|
|
- Map USDC/USDT and USDtz token addresses
|
|
- Call swap quote endpoint
|
|
- Parse `amountOut`, `amountOutMin`, `priceImpact`
|
|
4. Add aggregator: call all providers, pick best quote
|
|
5. Handle failures: fallback to next provider or 1:1 with warning
|
|
|
|
---
|
|
|
|
### P2-2: Integrate Chain138 swap quotes (EnhancedSwapRouter/1inch) in route planner
|
|
|
|
**Why:** First-hop swap (asset→cUSDC) has no real quote.
|
|
|
|
**Steps:**
|
|
1. In route planner, detect when `source_asset !== cUSDC` (or cUSDT)
|
|
2. Call existing services:
|
|
- **Option A:** [smom-dbis-138/orchestration/bridge/quote-service.ts](../../smom-dbis-138/orchestration/bridge/quote-service.ts) — if it exposes swap quotes
|
|
- **Option B:** [alltra-lifi-settlement](../../alltra-lifi-settlement) — 1inch/ParaSwap/0x (Chain138 may need custom chain config)
|
|
- **Option C:** Direct 1inch API — `https://api.1inch.dev/swap/v5.2/138/quote`
|
|
3. Add `getChain138SwapQuote(sourceAsset, amount, targetAsset)` in route planner or shared service
|
|
4. Populate hop 1 `amount_out`, `min_amount_out`, `estimated_fees` from quote
|
|
5. When source is already cUSDC: skip swap or use 1:1
|
|
|
|
---
|
|
|
|
### P2-3: Integrate real CCIP fee estimation in route planner
|
|
|
|
**Why:** Bridge fees are currently `"0"`.
|
|
|
|
**Steps:**
|
|
1. Locate CCIP fee logic:
|
|
- [smom-dbis-138/services/relay](../../smom-dbis-138/services/relay) or CCIP router contract
|
|
- CCIP Router `getFee()` or equivalent
|
|
2. Add `getCCIPFee(sourceChain, destChain, token, amount)` helper
|
|
3. In route planner hop 2 (CCIP): call helper, set `estimated_fees`
|
|
4. Add to `totalEstimatedFees` aggregation
|
|
|
|
---
|
|
|
|
## P3 — Execution Path (End-to-End)
|
|
|
|
### P3-1: Implement Tezos sendTransaction (Taquito injection)
|
|
|
|
**Why:** TezosAdapter `sendTransaction` currently throws.
|
|
|
|
**Steps:**
|
|
1. Add `@taquito/taquito` to multi-chain-execution
|
|
2. In [adapter-tezos.ts](../../multi-chain-execution/src/chain-adapters/adapter-tezos.ts):
|
|
- Accept signed operation bytes (hex or Uint8Array)
|
|
- Use `TezosToolkit` + `rpc.injectOperation(signedBytes)` or direct `fetch('https://mainnet.api.tez.ie/injection/operation', { method: 'POST', body: ... })`
|
|
3. Return `{ hash, from, nonce }` — Tezos op hash as `hash`
|
|
4. For MVP: support pre-signed payload from external signer; in-house signing can come later
|
|
|
|
---
|
|
|
|
### P3-2: Map RoutePlan hops to TRPE/EO execution steps
|
|
|
|
**Why:** Route planner outputs 4 hops; TRPE/EO use 2-step message_send/receive.
|
|
|
|
**Steps:**
|
|
1. Extend TRPE to accept optional `route_plan` in IntentRequest
|
|
2. When `route_plan` present:
|
|
- Build `PlannedStep[]` from `route_plan.hops` (one step per hop)
|
|
- Set `step_type` from hop `action` (SWAP→swap, BRIDGE→bridge, etc.)
|
|
- Set `chain_id` from hop `chain` (CHAIN138→138, HUB_EVM→1, TEZOS→1729)
|
|
3. EO: when executing, for each step call the appropriate adapter (138, 1, 1729)
|
|
4. For BRIDGE steps: delegate to bridge-specific execution (CCIP, ETH→Tezos bridge) — may need `BridgeExecutor` abstraction
|
|
|
|
---
|
|
|
|
### P3-3: Add Tezos wallet signing (Taquito + Kukai/Material)
|
|
|
|
**Why:** Final Tezos swap/transfer requires a Tezos signer.
|
|
|
|
**Steps:**
|
|
1. Add `@taquito/signer` or use `@taquito/wallet` for browser integration
|
|
2. Create `TezosSigner` interface: `signOperation(operation): Promise<SignedOperation>`
|
|
3. Integrate with Kukai / Temple / Material wallet:
|
|
- Use `@taquito/beacon-wallet` or similar for dApp wallet connection
|
|
- Or server-side: `InMemorySigner` with encrypted key (operational wallet)
|
|
4. Wire into execution flow: when EO reaches Tezos step, use TezosSigner to sign before `adapter.sendTransaction`
|
|
|
|
---
|
|
|
|
## P4 — Polish & Hardening
|
|
|
|
### P4-1: Populate TEZOS_TOKEN_REGISTRY intermediary stablecoins (USDC/USDT)
|
|
|
|
**Steps:**
|
|
1. Query TzKT for USDC/USDT (or wrapped) contracts on Tezos mainnet
|
|
2. Update [TEZOS_TOKEN_REGISTRY.md](TEZOS_TOKEN_REGISTRY.md) with addresses, decimals, FA standard
|
|
3. Add to `tezos-dex-quote.service.ts` token config for lookup
|
|
|
|
---
|
|
|
|
### P4-2: Add dbis_core route API endpoint (optional)
|
|
|
|
**Steps:**
|
|
1. Create [dbis_core/.../tezos-usdtz.routes.ts](../../dbis_core/src/integration/api-gateway/routes/) — or similar path
|
|
2. Implement `POST /api/v1/routes/chain138-to-usdtz` calling `planRoutes` from route-planner.service
|
|
3. Register in [app.ts](../../dbis_core/src/integration/api-gateway/app.ts)
|
|
4. Use when clients should hit dbis_core API instead of multi-chain-execution
|
|
|
|
---
|
|
|
|
### P4-3: Implement security: allowlists, slippage caps, approval reuse prevention
|
|
|
|
**Steps:**
|
|
1. **Allowlists:** Add config (JSON/env) of approved DEX routers, bridge contracts, token addresses
|
|
- Validate in route planner: all hop protocols/addresses must be allowlisted
|
|
2. **Slippage caps:** Enforce `max_slippage_bps` in quotes; reject routes exceeding cap
|
|
3. **Approval reuse:** For ERC-20 approvals, use `approve(spender, amount)` with exact amount; after swap/bridge, call `approve(spender, 0)` or document pattern
|
|
4. **Tezos FA verification:** Before transfer, optionally verify USDtz contract has expected entrypoints via TzKT
|
|
|
|
---
|
|
|
|
### P4-4: EO production env checks
|
|
|
|
**Why:** Placeholder wallet and placeholder tx hashes must not be used in production.
|
|
|
|
**Steps:**
|
|
1. Set `WALLET_ADDRESS` for the operational hot wallet
|
|
2. Set `SIGNER_ENABLED=true` when real signing is active — EO will throw if `WALLET_ADDRESS` is unset
|
|
3. Replace placeholder tx hashes with real `adapter.sendTransaction` when signer is integrated
|
|
4. See [execution-orchestrator.ts](../../multi-chain-execution/src/eo/execution-orchestrator.ts) for env usage
|
|
|
|
---
|
|
|
|
## Dependency Graph
|
|
|
|
```
|
|
P1-1 (USDtz verify) ─────────────────────────────────────────────┐
|
|
│
|
|
P1-2 (ETH→Tezos bridge) ─── P1-3 (Replace TBD) │
|
|
│
|
|
P2-1 (Tezos DEX quotes) ─────────────────────────────────────────┤
|
|
P2-2 (Chain138 swap quotes) ─────────────────────────────────────┤
|
|
P2-3 (CCIP fees) ────────────────────────────────────────────────┼──> Production Route
|
|
│
|
|
P3-1 (Tezos sendTransaction) ────────────────────────────────────┤
|
|
P3-2 (RoutePlan→EO mapping) ─── P3-3 (Tezos wallet) ─────────────┤
|
|
│
|
|
P4-1 (Token registry) ───────────────────────────────────────────┘
|
|
P4-2 (dbis_core API) ─── optional
|
|
P4-3 (Security) ─── parallel to P3
|
|
```
|
|
|
|
---
|
|
|
|
## Suggested Execution Order
|
|
|
|
1. **P1-1** → **P1-2** → **P1-3** (sequential)
|
|
2. **P2-1, P2-2, P2-3** (parallel where possible)
|
|
3. **P3-1** → **P3-2** → **P3-3** (P3-2 can start once RoutePlan shape is stable)
|
|
4. **P4-1** with P2; **P4-2** when convenient; **P4-3** in parallel with P3
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [TEZOS_USDTZ_INTEGRATION.md](TEZOS_USDTZ_INTEGRATION.md)
|
|
- [TEZOS_TOKEN_REGISTRY.md](TEZOS_TOKEN_REGISTRY.md)
|
|
- [CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md](CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md)
|