337 lines
12 KiB
Markdown
337 lines
12 KiB
Markdown
# DBIS ChainID 138 Vault System - Implementation Summary
|
||
|
||
## Overview
|
||
|
||
The DBIS ChainID 138 Vault and Token framework has been fully implemented. This system provides a regulated, gold-anchored collateralized credit system combining MakerDAO-style ledger accounting with Aave-style vault operations.
|
||
|
||
## Implementation Status: ✅ COMPLETE
|
||
|
||
All core components have been implemented as specified in the plan.
|
||
|
||
## Components Implemented
|
||
|
||
### 1. Core Ledger (`contracts/vault/Ledger.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Tracks collateral and debt balances per vault
|
||
- Stores per-asset risk parameters (debt ceiling, liquidation ratio, credit multiplier)
|
||
- Maintains rate accumulator for interest accrual
|
||
- Enforces collateralization constraints in XAU terms
|
||
- Provides vault health calculations
|
||
|
||
**Key Functions**:
|
||
- `modifyCollateral()` - Update collateral balance
|
||
- `modifyDebt()` - Update debt balance with interest accrual
|
||
- `getVaultHealth()` - Returns collateralization ratio in XAU
|
||
- `canBorrow()` - Checks if borrow is allowed
|
||
- `setRiskParameters()` - Configure asset risk parameters
|
||
|
||
### 2. Regulated Entity Registry (`contracts/vault/RegulatedEntityRegistry.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Registers regulated financial entities with jurisdiction flags
|
||
- Tracks authorized wallets per entity
|
||
- Manages operator roles
|
||
- Supports suspension/revocation
|
||
- Separate from eMoney ComplianceRegistry
|
||
|
||
**Key Functions**:
|
||
- `registerEntity()` - Register a new entity
|
||
- `isEligible()` - Check entity eligibility
|
||
- `isAuthorized()` - Check wallet authorization
|
||
- `setOperator()` - Grant/revoke operator status
|
||
- `suspendEntity()` / `unsuspendEntity()` - Entity management
|
||
|
||
### 3. XAU Oracle Module (`contracts/vault/XAUOracle.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Multi-source oracle aggregation for ETH/XAU pricing
|
||
- Weighted price feed system
|
||
- Safety margins for liquidation prices
|
||
- Emergency freeze capability
|
||
- Admin-controlled feed selection
|
||
|
||
**Key Functions**:
|
||
- `getETHPriceInXAU()` - Get current ETH price in XAU (18 decimals)
|
||
- `getLiquidationPrice()` - Get liquidation threshold with safety margin
|
||
- `addPriceFeed()` / `removePriceFeed()` - Manage price feeds
|
||
- `updatePrice()` - Aggregate prices from all feeds
|
||
- `freeze()` / `unfreeze()` - Emergency controls
|
||
|
||
### 4. Rate & Accrual Module (`contracts/vault/RateAccrual.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Continuous compounding interest model
|
||
- Per-asset interest rates
|
||
- Debt index tracking (similar to Aave)
|
||
- Accrual triggered on system interactions
|
||
|
||
**Key Functions**:
|
||
- `accrueInterest()` - Accrue interest for an asset
|
||
- `getRateAccumulator()` - Get current accumulator (with view-only accrual)
|
||
- `setInterestRate()` - Set annual interest rate in basis points
|
||
- `calculateDebtWithInterest()` - Calculate debt with accrued interest
|
||
|
||
### 5. Liquidation Module (`contracts/vault/Liquidation.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Permissioned liquidators only
|
||
- Seizes collateral and offsets debt
|
||
- Liquidation bonus (penalty) system
|
||
- No public auctions
|
||
|
||
**Key Functions**:
|
||
- `liquidate()` - Liquidate an undercollateralized vault
|
||
- `canLiquidate()` - Check if vault can be liquidated
|
||
- `setLiquidationBonus()` - Configure liquidation bonus
|
||
|
||
### 6. Deposit Token (`contracts/vault/tokens/DepositToken.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- ERC20 token representing supplied collateral position
|
||
- Minted when M0 collateral is deposited
|
||
- Burned on withdrawal
|
||
- UUPS upgradeable pattern
|
||
- Extends eMoneyToken pattern
|
||
|
||
**Key Functions**:
|
||
- `mint()` - Mint deposit tokens (vault only)
|
||
- `burn()` - Burn deposit tokens (vault only)
|
||
|
||
### 7. Debt Token (`contracts/vault/tokens/DebtToken.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- ERC20 token representing outstanding debt obligation
|
||
- Minted when borrow occurs
|
||
- Burned on repayment
|
||
- Interest-accruing
|
||
- Non-freely transferable (restricted transfers)
|
||
- UUPS upgradeable pattern
|
||
|
||
**Key Functions**:
|
||
- `mint()` - Mint debt tokens (vault only)
|
||
- `burn()` - Burn debt tokens (vault only)
|
||
- Transfer restrictions enforced in `_update()`
|
||
|
||
### 8. Collateral Adapter (`contracts/vault/adapters/CollateralAdapter.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Handles M0 collateral deposits and withdrawals
|
||
- Only callable by Vaults
|
||
- Only accepts approved assets
|
||
- Supports native ETH and ERC20 tokens
|
||
- Seizure functionality for liquidations
|
||
|
||
**Key Functions**:
|
||
- `deposit()` - Deposit M0 collateral
|
||
- `withdraw()` - Withdraw M0 collateral
|
||
- `seize()` - Seize collateral during liquidation
|
||
- `approveAsset()` / `revokeAsset()` - Asset management
|
||
|
||
### 9. eMoney Join Adapter (`contracts/vault/adapters/eMoneyJoin.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Mint/burn restricted to this adapter
|
||
- Transfer restricted via Compliance Registry (inherited from eMoneyToken)
|
||
- Only approved currencies
|
||
|
||
**Key Functions**:
|
||
- `mint()` - Mint eMoney to borrowers
|
||
- `burn()` - Burn eMoney on repayment
|
||
- `approveCurrency()` / `revokeCurrency()` - Currency management
|
||
|
||
### 10. Vault Contract (`contracts/vault/Vault.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Aave-style operations (deposit, borrow, repay, withdraw)
|
||
- Owned by regulated entity
|
||
- Authorization checks via RegulatedEntityRegistry
|
||
- Integrates with all adapters and ledger
|
||
|
||
**Key Functions**:
|
||
- `deposit()` - Deposit M0 collateral
|
||
- `borrow()` - Borrow eMoney against collateral
|
||
- `repay()` - Repay borrowed eMoney
|
||
- `withdraw()` - Withdraw collateral
|
||
- `getHealth()` - Get vault health metrics
|
||
|
||
### 11. Vault Factory (`contracts/vault/VaultFactory.sol`) ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**Features**:
|
||
- Creates vault instances
|
||
- Deploys DepositToken and DebtToken for each vault
|
||
- Registers vaults with ledger
|
||
- Tracks vaults by entity
|
||
|
||
**Key Functions**:
|
||
- `createVault()` - Create new vault with associated tokens
|
||
- `getVaultsByEntity()` - Get all vaults for an entity
|
||
|
||
### 12. Interfaces ✅
|
||
|
||
**Status**: Complete
|
||
|
||
All interfaces have been created:
|
||
- `ILedger.sol`
|
||
- `IRegulatedEntityRegistry.sol`
|
||
- `IXAUOracle.sol`
|
||
- `IRateAccrual.sol`
|
||
- `IVault.sol`
|
||
- `ILiquidation.sol`
|
||
- `ICollateralAdapter.sol`
|
||
- `IeMoneyJoin.sol`
|
||
|
||
### 13. Error Library ✅
|
||
|
||
**Status**: Complete
|
||
|
||
- `VaultErrors.sol` - Custom errors for the vault system
|
||
|
||
### 14. Compliance Libraries ✅
|
||
|
||
**Status**: Complete
|
||
|
||
**CurrencyValidation.sol**:
|
||
- ISO 4217 currency code validation
|
||
- Currency type classification (ISO 4217 fiat, synthetic, commodity)
|
||
- Legal tender identification
|
||
- GRU recognition as non-ISO synthetic unit
|
||
|
||
**GRUConstants.sol**:
|
||
- GRU conversion ratios (1 M00 = 5 M0 = 25 M1)
|
||
- GRU layer validation
|
||
- Conversion functions between GRU layers
|
||
- Explicit non-ISO classification
|
||
|
||
**MonetaryFormulas.sol**:
|
||
- Money Supply: M = C + D and M = MB × m
|
||
- Money Velocity: V = PQ / M
|
||
- Money Multiplier: m = 1 / r and m = (1 + c) / (r + c)
|
||
- Exact formula implementations without modification
|
||
|
||
**XAUTriangulation.sol**:
|
||
- XAU triangulation for all currency conversions
|
||
- CurrencyA → XAU → CurrencyB enforcement
|
||
- XAU conversion utilities
|
||
|
||
## File Structure
|
||
|
||
```
|
||
contracts/vault/
|
||
├── interfaces/
|
||
│ ├── ILedger.sol
|
||
│ ├── IRegulatedEntityRegistry.sol
|
||
│ ├── IXAUOracle.sol
|
||
│ ├── IRateAccrual.sol
|
||
│ ├── IVault.sol
|
||
│ ├── ILiquidation.sol
|
||
│ ├── ICollateralAdapter.sol
|
||
│ └── IeMoneyJoin.sol
|
||
├── adapters/
|
||
│ ├── CollateralAdapter.sol
|
||
│ └── eMoneyJoin.sol
|
||
├── tokens/
|
||
│ ├── DepositToken.sol
|
||
│ └── DebtToken.sol
|
||
├── libraries/
|
||
│ ├── CurrencyValidation.sol ✅ ISO 4217 compliance
|
||
│ ├── GRUConstants.sol ✅ GRU relationships
|
||
│ ├── MonetaryFormulas.sol ✅ Mandatory formulas
|
||
│ └── XAUTriangulation.sol ✅ XAU triangulation
|
||
├── errors/
|
||
│ └── VaultErrors.sol
|
||
├── Ledger.sol
|
||
├── RegulatedEntityRegistry.sol
|
||
├── XAUOracle.sol
|
||
├── RateAccrual.sol
|
||
├── Liquidation.sol
|
||
├── Vault.sol
|
||
└── VaultFactory.sol
|
||
```
|
||
|
||
## Key Design Decisions
|
||
|
||
1. **XAU Normalization**: All valuations are normalized to XAU (gold) as the universal unit of account
|
||
2. **Regulated Entities**: Only registered, non-suspended entities can operate vaults
|
||
3. **Interest Accrual**: Continuous compounding model with per-asset rates
|
||
4. **Liquidation**: Permissioned liquidators with bonus system
|
||
5. **Token Pattern**: Deposit and Debt tokens extend eMoneyToken pattern for consistency
|
||
6. **Access Control**: Role-based access control throughout using OpenZeppelin
|
||
|
||
## Integration Points
|
||
|
||
- **eMoney System**: Uses existing `IeMoneyToken` interface for eMoney operations
|
||
- **Compliance**: Uses existing eMoney `ComplianceRegistry` for transfer restrictions
|
||
- **Oracle**: Uses existing `IAggregator` interface for price feeds
|
||
- **OpenZeppelin**: Uses AccessControl, ReentrancyGuard, ERC20, UUPS patterns
|
||
|
||
## Next Steps
|
||
|
||
1. **Testing**: Create comprehensive test suite
|
||
2. **Deployment Scripts**: Create deployment and initialization scripts
|
||
3. **Documentation**: Expand documentation with usage examples
|
||
4. **Security Audit**: Conduct security review
|
||
5. **Gas Optimization**: Review and optimize gas usage
|
||
|
||
## Compliance Implementation
|
||
|
||
### ISO 4217 Compliance ✅
|
||
- All currency codes validated against ISO 4217 standards
|
||
- Non-ISO currencies explicitly identified and classified
|
||
- Legal tender vs. synthetic unit distinction enforced
|
||
|
||
### GRU Classification ✅
|
||
- GRU explicitly recognized as NON-ISO 4217 synthetic unit of account
|
||
- GRU is NOT treated as legal tender
|
||
- GRU conversion ratios enforced exactly: 1 M00 = 5 M0 = 25 M1
|
||
- All GRU triangulations go through XAU
|
||
|
||
### XAU Triangulation ✅
|
||
- All currency conversions MUST go through XAU
|
||
- XAU is the universal unit of account
|
||
- Triangulation formula enforced: CurrencyA → XAU → CurrencyB
|
||
|
||
### Monetary Formulas ✅
|
||
- All mandatory formulas implemented exactly as specified
|
||
- No modifications to formula structure
|
||
- Formulas available for use in calculations
|
||
|
||
See `docs/vault/COMPLIANCE_REQUIREMENTS.md` for complete compliance documentation.
|
||
|
||
### GRU Smart Vault and PMM Integration
|
||
|
||
- **PMM price for vault valuation**: When collateral or debt is a token that has a PMM pool (e.g. cUSDT, cUSDC), price can be obtained from **PMMPriceProvider** (`contracts/vault/adapters/PMMPriceProvider.sol`). It wraps DODOPMMIntegration and exposes `getPrice(asset, quoteToken)` using `getPoolPriceOrOracle` (oracle-backed when ReserveSystem is set on DODOPMMIntegration). The Ledger’s primary valuation remains XAU via XAUOracle; PMMPriceProvider is for optional use by keepers, UIs, or a future Ledger extension that supports a secondary price source per asset.
|
||
- **Vault as LP / PMM liquidity**: A vault (or its regulated entity) can add liquidity to PMM pools by calling **DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)**. The vault (or entity) must hold base and quote tokens and approve the integration contract. Required role on DODOPMMIntegration: none for addLiquidity (anyone can add); pool creation requires **POOL_MANAGER_ROLE**. LP positions are not currently accepted as collateral in the Ledger; that would require a future extension (e.g. LP token as approved asset and a valuation path for LP shares).
|
||
- **GRUHandler / registry**: GRU assets used in vaults should be validated via **GRUHandler** (`contracts/registry/handlers/GRUHandler.sol`). Register any new PMM-related or GRU asset types in **ChainRegistry** / **UniversalAssetRegistry** as applicable.
|
||
|
||
See also: `docs/integration/DODO_PMM_INTEGRATION.md`, `docs/integration/ORACLE_AND_KEEPER_CHAIN138.md`.
|
||
|
||
## Notes
|
||
|
||
- The system is designed for regulated, institutional, and sovereign-grade deployment
|
||
- All contracts follow OpenZeppelin security best practices
|
||
- The system enforces strict access controls and compliance checks
|
||
- XAU normalization ensures consistent valuation across all operations
|
||
- **MANDATORY COMPLIANCE**: All currency codes, GRU relationships, and monetary formulas are enforced |