b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
415 lines
14 KiB
Markdown
415 lines
14 KiB
Markdown
# VAULT SYSTEM MASTER TECHNICAL PLAN
|
||
|
||
## ChainID 138 + Alltra Network Deployment
|
||
|
||
**Last Updated:** 2026-02-14
|
||
**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):
|
||
|
||
Stable M1 Tokens:
|
||
|
||
* cUSDT
|
||
* cUSDC
|
||
* cEURT
|
||
|
||
Anchor Asset:
|
||
|
||
* XAU (Triangulation Anchor)
|
||
|
||
GRU Assets:
|
||
|
||
* M0 (ETH)
|
||
* M1 Factory Tokens
|
||
* M00 (GRU Diamond) — architecture: [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md), [GRU_M00_DIAMOND_FACET_MAP.md](04-configuration/GRU_M00_DIAMOND_FACET_MAP.md)
|
||
|
||
---
|
||
|
||
# 4. PUBLIC LIQUIDITY LAYER (DODO PMM)
|
||
|
||
Public pools are deployed for:
|
||
|
||
* cUSDT / cUSDC
|
||
* cUSDT / XAU
|
||
* cUSDC / XAU
|
||
* cEURT / XAU
|
||
|
||
DODO PMM Price Model:
|
||
|
||
Price = OraclePrice × (1 + k × InventoryDeviation)
|
||
|
||
Where:
|
||
InventoryDeviation = (CurrentInventory - TargetInventory) / TargetInventory
|
||
|
||
Public pools serve:
|
||
|
||
* User routing
|
||
* Price discovery
|
||
* Flash loan access
|
||
|
||
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.
|
||
* **Docs:** [DODO_PMM_INTEGRATION.md](../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) describes deployment.
|
||
|
||
---
|
||
|
||
# 5. PRIVATE STABILIZATION MESH
|
||
|
||
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).
|
||
|
||
---
|
||
|
||
# 7. RESERVE SIZING MODEL
|
||
|
||
Let:
|
||
PeakMinuteOutflow = P
|
||
RebalanceRate = R
|
||
StabilizationWindow = T
|
||
|
||
Required Reserve:
|
||
|
||
Reserve ≥ P × T
|
||
|
||
Recommended Safety Factor: 3–5× peak minute outflow.
|
||
|
||
Example:
|
||
PeakMinuteOutflow = 10,000
|
||
T = 5 minutes
|
||
Reserve ≥ 50,000
|
||
With 3× safety → 150,000
|
||
|
||
### Implementation
|
||
|
||
[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.
|
||
|
||
---
|
||
|
||
# 8. FLASH LOAN CONTAINMENT LOGIC
|
||
|
||
Problem:
|
||
Flash loans create single-block artificial imbalance.
|
||
|
||
Solution:
|
||
|
||
1. Use TWAP deviation detection
|
||
2. Ignore single-block imbalance
|
||
3. Require sustained deviation for X blocks
|
||
4. Cap per-block stabilization volume
|
||
|
||
Stabilizer Trigger:
|
||
If TWAPDeviation > θ for ≥ N blocks → rebalance.
|
||
|
||
### Implementation
|
||
|
||
* **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).
|
||
|
||
---
|
||
|
||
# 9. CROSS-CHAIN SYNCHRONIZATION
|
||
|
||
Variables:
|
||
Δ138 = imbalance on Chain 138
|
||
ΔAlltra = imbalance on Alltra
|
||
BridgeLatency = L
|
||
|
||
Rule:
|
||
|Price138 − PriceAlltra| < ArbitrageThreshold
|
||
|
||
Cross-chain private arbitrage bots maintain parity.
|
||
|
||
Bridge liquidity buffers must satisfy:
|
||
BridgeReserve ≥ PeakBridgeOutflow × Latency
|
||
|
||
### Implementation
|
||
|
||
* **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).)*
|
||
|
||
---
|
||
|
||
# 14. RISK MANAGEMENT MATRIX
|
||
|
||
| Risk | Mitigation |
|
||
|------|------------|
|
||
| Flash Loan Manipulation | TWAP + block filtering |
|
||
| Cross-chain desync | Arbitrage bots + oracle sync |
|
||
| Liquidity exhaustion | 5× reserve policy |
|
||
| MEV exploitation | Private routing + batch execution |
|
||
|
||
---
|
||
|
||
# 15. DEPLOYMENT ROADMAP
|
||
|
||
**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.
|
||
|
||
**Phase 2:** Deploy private XAU-anchored stabilization pools
|
||
Design and implement "private" pool creation and access control, or document as DODO pools with restricted liquidity providers.
|
||
|
||
**Phase 3:** Implement deviation-triggered stabilizer contract
|
||
Implement on-chain `checkDeviation` + `executePrivateSwap` with block delay and gas-aware execution; hook to peg managers where appropriate.
|
||
|
||
**Phase 4:** Deploy cross-chain arbitrage engine
|
||
Document as off-chain bot or optional contract; link to AlltraAdapter, AlltraCustomBridge, and CCIP.
|
||
|
||
**Phase 5:** Simulate stress testing at 5× projected volume
|
||
Document 5× volume simulation and runbook.
|
||
|
||
**Phase 6:** Activate flash loan containment filters
|
||
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.
|
||
|
||
---
|
||
|
||
# 18. REFERENCES AND RELATED DOCS
|
||
|
||
| Document | Description |
|
||
|----------|-------------|
|
||
| [CONTRACT_DEPLOYMENT_RUNBOOK](03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | Vault + ac/vdc/sdc deployment (Option A/B), EnhancedSwapRouter, DODOPMMProvider |
|
||
| [MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT](runbooks/MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md) | CREATE2, DeployAcVdcSdcVaults |
|
||
| [REQUIRED_FIXES_UPDATES_GAPS](REQUIRED_FIXES_UPDATES_GAPS.md) | Current status and optional items |
|
||
| [DODO_PMM_INTEGRATION.md](../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) | DODO PMM deployment and integration |
|
||
| [PEG_MECHANISMS.md](../smom-dbis-138/docs/bridge/trustless/integration/PEG_MECHANISMS.md) | Pegging mechanisms and XAU triangulation |
|
||
| [OPERATIONS_RUNBOOK.md](../smom-dbis-138/docs/OPERATIONS_RUNBOOK.md) | Vault, ISO-4217 W, bridge operations and alerts |
|
||
|
||
---
|
||
|
||
# Appendix A. Stabilizer contract interface (Phase 3)
|
||
|
||
For Phase 3 implementation, the deviation-triggered stabilizer contract should conform to the following interface and rules.
|
||
|
||
**Interface (pseudocode):**
|
||
|
||
```text
|
||
function checkDeviation() external view returns (int256 deviationBps, bool shouldRebalance);
|
||
// deviationBps = getInventoryDeviation() in basis points (e.g. from peg or TWAP)
|
||
// shouldRebalance = (abs(deviationBps) > thresholdBps) && sustainedForNBlocks()
|
||
|
||
function executePrivateSwap(uint256 tradeSize, address tokenIn, address tokenOut) external;
|
||
// Only callable when checkDeviation() returns shouldRebalance == true
|
||
// tradeSize = min(k * deviation, perBlockCap)
|
||
// Enforce block delay: last execution block + MIN_BLOCKS <= block.number
|
||
// Enforce slippage cap (e.g. maxSlippageBps)
|
||
// 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.
|
||
|
||
END OF MASTER TECHNICAL PLAN
|