# 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