proxmox/docs/VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md

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, 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 provides createCUSDTUSDTPool, createCUSDCUSDCPool, and generic createPool(baseToken, quoteToken, lpFeeRate, initialPrice, k, isOpenTWAP). Pool config uses i, k, isOpenTWAP (TWAP for price discovery). 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 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, Ledger, and XAUOracle implement XAU as unit of account and triangulation (CurrencyA → XAU → CurrencyB). StablecoinPegManager, CommodityPegManager check deviation and trigger rebalancing; BridgeReserveCoordinator 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 and StablecoinReserveVault exist; 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 and CommodityPegManager 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 and AlltraCustomBridge 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:

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 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 and ReserveSystem.)

---

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 and runbooks; EnhancedSwapRouter and DODOPMMProvider post-deploy configuration per CONTRACT_DEPLOYMENT_RUNBOOK.

Phase 1: Deploy public PMM pools on Chain 138
Use existing DODOPMMIntegration and DeployDODOPMMIntegration 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 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	Vault + ac/vdc/sdc deployment (Option A/B), EnhancedSwapRouter, DODOPMMProvider
MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT	CREATE2, DeployAcVdcSdcVaults
REQUIRED_FIXES_UPDATES_GAPS	Current status and optional items
DODO_PMM_INTEGRATION.md	DODO PMM deployment and integration
PEG_MECHANISMS.md	Pegging mechanisms and XAU triangulation
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):

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 / CommodityPegManager 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