proxmox/docs/11-references/TEZOS_USDTZ_IMPLEMENTATION_ROADMAP.md

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 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:
   • 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: 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: 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 — if it exposes swap quotes
   • Option B: 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 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:
   • 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 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 — or similar path
2. Implement POST /api/v1/routes/chain138-to-usdtz calling planRoutes from route-planner.service
3. Register in 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 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_TOKEN_REGISTRY.md
• CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md