**Status:** Canonical technical spec and implementation roadmap
---
# 1. EXECUTIVE SUMMARY
This Master Technical Plan defines the full-stack liquidity, stabilization, cross-chain, and smart contract architecture for deploying the Vault System on:
* ChainID 138
* Alltra Networks
Using:
* DODO PMM public liquidity pools
* Private stabilization mesh pools
* Cross-chain atomic routing
* Flash loan-enabled liquidity
* GRU/XAU triangulation logic
Primary Objectives:
1. Maintain deterministic price stability
2. Preserve peg integrity across tokens
3. Enable cross-chain liquidity parity
4. Protect against flash loan manipulation
5. Optimize capital efficiency
6. Maintain scalable liquidity mesh architecture
---
# 2. SYSTEM ARCHITECTURE OVERVIEW
The system is composed of five layers:
Layer 1: Public Liquidity Layer (DODO PMM)
Layer 2: Private Stabilization Mesh
Layer 3: Cross-Chain Synchronization Layer
Layer 4: Flash Loan Containment Logic
Layer 5: Vault Reserve Engine
---
# 3. TOKEN TOPOLOGY
Supported Asset Classes (symbols aligned with repo):
They DO NOT serve as primary stabilization engines.
### Implementation
* **Contracts:** [DODOPMMIntegration.sol](../smom-dbis-138/contracts/dex/DODOPMMIntegration.sol) provides `createCUSDTUSDTPool`, `createCUSDCUSDCPool`, and generic `createPool(baseToken, quoteToken, lpFeeRate, initialPrice, k, isOpenTWAP)`. Pool config uses `i`, `k`, `isOpenTWAP` (TWAP for price discovery). [DODOPMMProvider.sol](../smom-dbis-138/contracts/liquidity/providers/DODOPMMProvider.sol) registers pools and exposes `getQuote` / `executeSwap`.
* **Pool pairs:** cUSDT/cUSDC can use a dedicated path or generic `createPool`; cUSDT/XAU, cUSDC/XAU, and cEURT/XAU use generic `createPool` and require XAU and cEURT token addresses on Chain 138. No explicit "public vs private" pool designation in contracts yet.
Instead of full N² mesh, the system uses XAU as universal anchor.
For N tokens:
Total Required Private Pools = N (anchored to XAU)
Example:
* cUSDT ↔ XAU (private)
* cUSDC ↔ XAU (private)
* cEURT ↔ XAU (private)
Triangular arbitrage ensures:
TokenA ↔ XAU ↔ TokenB parity.
### Implementation
* **XAU triangulation:** [XAUTriangulation.sol](../smom-dbis-138/contracts/vault/libraries/XAUTriangulation.sol), [Ledger](../smom-dbis-138/contracts/vault/Ledger.sol), and [XAUOracle](../smom-dbis-138/contracts/vault/XAUOracle.sol) implement XAU as unit of account and triangulation (CurrencyA → XAU → CurrencyB). [StablecoinPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/StablecoinPegManager.sol), [CommodityPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/CommodityPegManager.sol) check deviation and trigger rebalancing; [BridgeReserveCoordinator](../smom-dbis-138/contracts/bridge/trustless/integration/BridgeReserveCoordinator.sol) emits `RebalancingTriggered` and has cooldowns.
* **Gap:** No first-class "private" XAU-anchored **pools** (N pools: Token↔XAU). No on-chain execution of private swaps from deviation (e.g. `executePrivateSwap`). Triangular parity is conceptual; dedicated private mesh with access-controlled pools is not yet implemented.
---
# 6. CANTILEVER STABILIZATION MODEL
Let:
s = micro trade size
f = micro trade frequency
Δ = net imbalance per minute
Required Condition:
s × f ≥ Δ
Example:
s = 5 units
f = 33 trades/minute
Total stabilization throughput = 165 units/minute
This offsets macro flow up to 165 units/minute.
Dynamic Rebalancing Rule:
If deviation > θ:
s = k × deviation
This eliminates fixed frequency dependency.
### Implementation
The formula and dynamic rule are spec. Not yet encoded in contracts; candidate for stabilizer contract or off-chain bot (see Deployment roadmap Phase 3).
[ReserveSystem](../smom-dbis-138/contracts/reserve/ReserveSystem.sol) and [StablecoinReserveVault](../smom-dbis-138/contracts/reserve/StablecoinReserveVault.sol) exist; [OPERATIONS_RUNBOOK.md](../smom-dbis-138/docs/OPERATIONS_RUNBOOK.md) has health and reserve checks. The formula (P×T, 3–5× safety) is documented in this plan and may be added to the operations runbook or a dedicated reserve-sizing doc.
* **Existing:** DODO pool config supports `isOpenTWAP`. [StablecoinPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/StablecoinPegManager.sol) and [CommodityPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/CommodityPegManager.sol) use deviation thresholds (e.g. 50 bps). No flash-specific logic in vault or stabilizer.
* **Gap:** Required behaviors for a future stabilizer or modifier: TWAP-based sustained deviation (over N blocks), ignore single-block rule, per-block stabilization volume cap, explicit flash drain recovery target (e.g. <3 blocks per §16).
* **Existing:** [AlltraAdapter](../smom-dbis-138/contracts/bridge/adapters/evm/AlltraAdapter.sol) and [AlltraCustomBridge](../smom-dbis-138/contracts/bridge/AlltraCustomBridge.sol) for 138 ↔ 651940; CCIP for other chains. Runbook and .env document AlltraAdapter and bridge fee.
* **Gap:** Cross-chain arbitrage engine (bot or contract) and explicit "BridgeReserve ≥ PeakBridgeOutflow × Latency" are not implemented; parity rule is doc-only. Arbitrage engine is documented as off-chain bot or optional contract (see Phase 4).
---
# 10. SMART CONTRACT STABILIZER LOGIC
Stabilizer Pseudocode:
```text
function checkDeviation():
deviation = getInventoryDeviation()
if deviation > threshold:
tradeSize = k * deviation
executePrivateSwap(tradeSize)
```
Protection Features:
* Block delay filters
* Gas-aware execution
* MEV-resistant routing
* Slippage cap
### Implementation
* **Existing:** Peg managers and [BridgeReserveCoordinator](../smom-dbis-138/contracts/bridge/trustless/integration/BridgeReserveCoordinator.sol) trigger rebalancing and emit events; deviation checks and cooldowns are present.
* **Gap:** Full on-chain `checkDeviation` → `executePrivateSwap` with block delay and slippage cap is not implemented (Phase 3 in Deployment roadmap).
---
# 11. VOLUME SIMULATION MODEL
Public Pool Depth: 1,000,000
Allowed Deviation: 0.2%
Max Drift = 2,000 units
If external flow = 50,000/hr
= 833/minute
Required Stabilization ≥ 833/minute
Optimized:
TradeSize = 25
Frequency = 33/minute
*(Reference only; no code.)*
---
# 12. COMPLETE OPERATIONAL FLOW
1. User trades on public PMM
2. Inventory deviation increases
3. TWAP confirms sustained deviation
4. Private mesh executes proportional rebalance
5. XAU anchor redistributes across tokens
6. Cross-chain bot syncs price
7. Vault engine updates reserve ratios
---
# 13. CAPITAL EFFICIENCY STRATEGY
Avoid full mesh (N² growth)
Use XAU anchor
Separate:
* Public liquidity
* Stabilization liquidity
* Flash liquidity
* Bridge liquidity
Capital Buckets:
Bucket A: Public PMM Liquidity
Bucket B: Private Stabilization
Bucket C: Flash Loan Liquidity
Bucket D: Cross-chain Buffer
Bucket E: Long-term Vault Reserves
*(Optionally reference [DODOPMMIntegration](../smom-dbis-138/contracts/dex/DODOPMMIntegration.sol) and [ReserveSystem](../smom-dbis-138/contracts/reserve/ReserveSystem.sol).)*
**Pre-requisite (already done):** Vault System + ac/vdc/sdc deployment via [deploy-vault-system-and-ac-vdc-sdc.sh](../smom-dbis-138/scripts/deployment/deploy-vault-system-and-ac-vdc-sdc.sh) and runbooks; EnhancedSwapRouter and DODOPMMProvider post-deploy configuration per [CONTRACT_DEPLOYMENT_RUNBOOK](03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md).
**Phase 1:** Deploy public PMM pools on Chain 138
Use existing [DODOPMMIntegration](../smom-dbis-138/contracts/dex/DODOPMMIntegration.sol) and [DeployDODOPMMIntegration](../smom-dbis-138/script/dex/DeployDODOPMMIntegration.s.sol) and scripts. Document creation of cUSDT/cUSDC, then cUSDT/XAU, cUSDC/XAU, cEURT/XAU when XAU and cEURT token addresses exist on Chain 138.
Add TWAP + N-block sustain + per-block cap to stabilizer or vault interactions.
---
# 16. PERFORMANCE TARGETS
| Target | Value |
|--------|--------|
| Peg Stability | ±0.10% |
| Cross-chain Spread | <0.15% |
| Rebalance Latency | <5 blocks |
| Flash Drain Recovery | <3 blocks |
### Verification
[OPERATIONS_RUNBOOK.md](../smom-dbis-138/docs/OPERATIONS_RUNBOOK.md) defines alert thresholds (e.g. health ratio, reserve ratio, oracle staleness). Peg ±0.10%, cross-chain spread <0.15%, rebalance <5 blocks, and flash recovery <3 blocks are design targets to be verified in production and stress tests.
---
# 17. CONCLUSION
This architecture provides:
* Deterministic peg stability
* Cross-chain parity
* Capital efficiency via XAU anchoring
* Flash-resistant stabilization
* Scalable token mesh
The system is elastic, dynamic, and capital-efficient.
// Route to private mesh (XAU-anchored) or DODO private pool
```
**Rules:**
| Rule | Description |
|------|-------------|
| Block delay | Do not execute more than once per MIN_BLOCKS (e.g. 3–5 blocks) to avoid single-block flash manipulation. |
| TWAP / sustained deviation | Trigger only when deviation exceeds threshold for ≥ N blocks (not single-block spike). |
| Per-block cap | Cap total stabilization volume per block (e.g. maxStabilizationVolumePerBlock). |
| Slippage cap | Enforce maxSlippageBps on executePrivateSwap. |
| Gas-aware execution | Revert or skip if gas price exceeds maxGasPriceForStabilizer (MEV resistance). |
**Integration:** Hook to existing [StablecoinPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/StablecoinPegManager.sol) / [CommodityPegManager](../smom-dbis-138/contracts/bridge/trustless/integration/CommodityPegManager.sol) deviation checks where appropriate; or call from a keeper that reads peg manager and calls executePrivateSwap when conditions are met.
