smom-dbis-138/docs/integration/RESERVE_ASSETS_CONFIG.md

Reserve Assets Configuration Guide

Date: 2025-01-27 Status: ✅ COMPLETE

---

Overview

This guide explains how to configure initial reserve assets for the Reserve System, including adding supported assets and making initial deposits.

---

Configuration Steps

Step 1: Add Supported Assets

Supported assets must be added before they can be used in the Reserve System.

# Set environment variables
export RESERVE_SYSTEM=<reserve_system_address>
export RESERVE_ADMIN=<admin_address>

# Asset addresses
export XAU_ASSET=<xau_token_address>
export USDC_ASSET=<usdc_token_address>
export ETH_ASSET=<eth_token_address>
export WETH_ASSET=<weth_token_address>
export SOVEREIGN_ASSET=<sovereign_instrument_address>

# Run configuration script
forge script script/reserve/ConfigureInitialReserves.s.sol:ConfigureInitialReserves \
  --rpc-url chain138 \
  --broadcast

Step 2: Make Initial Deposits

After adding supported assets, make initial reserve deposits:

# Set deposit amounts (in token units with decimals)
export XAU_INITIAL_DEPOSIT=1000000000000000000000  # 1000 tokens (18 decimals)
export USDC_INITIAL_DEPOSIT=1000000000000          # 1000000 USDC (6 decimals)
export ETH_INITIAL_DEPOSIT=1000000000000000000     # 1 ETH (18 decimals)
export WETH_INITIAL_DEPOSIT=500000000000000000     # 0.5 WETH (18 decimals)

# Ensure tokens are approved
# Run configuration script
forge script script/reserve/ConfigureInitialReserves.s.sol:ConfigureInitialReserves \
  --rpc-url chain138 \
  --broadcast

---

Asset Types

Liquid Assets

Liquid assets have lower slippage tolerance and faster conversion:

• Gold (XAU): Physical gold tokens
• USDC: USD Coin stablecoin
• ETH: Ethereum native token
• WETH: Wrapped Ethereum

Configuration:

reserve.addSupportedAsset(assetAddress, true); // true = liquid

Less Liquid Assets

Less liquid assets have higher slippage tolerance:

• Sovereign Instruments: Government bonds, securities
• Other Assets: As approved by governance

Configuration:

reserve.addSupportedAsset(assetAddress, false); // false = less liquid

---

Initial Reserve Recommendations

Minimum Reserves

For a production system, consider these minimum reserves:

Asset	Minimum Reserve	Purpose
XAU	1000 oz	Primary reserve asset
USDC	1,000,000	Liquidity buffer
ETH	100	Network operations
WETH	50	DeFi operations

Reserve Ratios

Maintain reserve ratios based on system requirements:

• Primary Reserve: 60-70% (XAU)
• Liquidity Reserve: 20-30% (USDC, ETH)
• Operational Reserve: 10% (WETH, other)

---

Configuration Script Details

Environment Variables

Required:

• RESERVE_SYSTEM: Address of ReserveSystem contract
• PRIVATE_KEY: Deployer private key

Optional:

• RESERVE_ADMIN: Admin address (defaults to deployer)
• RESERVE_MANAGER: Reserve manager address (defaults to deployer)

Asset Configuration:

• XAU_ASSET: Gold token address
• USDC_ASSET: USDC token address
• ETH_ASSET: ETH token address
• WETH_ASSET: WETH token address
• SOVEREIGN_ASSET: Sovereign instrument address

Initial Deposits:

• XAU_INITIAL_DEPOSIT: Initial XAU deposit amount
• USDC_INITIAL_DEPOSIT: Initial USDC deposit amount
• ETH_INITIAL_DEPOSIT: Initial ETH deposit amount
• WETH_INITIAL_DEPOSIT: Initial WETH deposit amount

Script Functions

The ConfigureInitialReserves script:

1. Adds Supported Assets: Configures assets as liquid or less liquid
2. Makes Initial Deposits: Deposits initial reserves (if amounts provided)
3. Verifies Configuration: Checks reserve balances and supported assets

---

Manual Configuration

Add Supported Asset

// Via contract call
reserveSystem.addSupportedAsset(assetAddress, isLiquid);

Deposit Reserves

// Approve tokens
IERC20(asset).approve(reserveSystem, amount);

// Deposit
reserveSystem.depositReserve(asset, amount);

Check Reserve Balance

uint256 balance = reserveSystem.getReserveBalance(asset);

---

Complete Setup Example

Full Configuration Script

#!/bin/bash

# Load environment variables
source .env

# Step 1: Setup Price Feeds
echo "Setting up price feeds..."
forge script script/reserve/SetupPriceFeeds.s.sol:SetupPriceFeeds \
  --rpc-url chain138 \
  --broadcast

# Step 2: Configure Initial Reserves
echo "Configuring initial reserves..."
forge script script/reserve/ConfigureInitialReserves.s.sol:ConfigureInitialReserves \
  --rpc-url chain138 \
  --broadcast

# Step 3: Verify Configuration
echo "Verifying configuration..."
forge script script/reserve/VerifyReserves.s.sol:VerifyReserves \
  --rpc-url chain138

Or Use Complete Setup Script

forge script script/reserve/SetupComplete.s.sol:SetupComplete \
  --rpc-url chain138 \
  --broadcast

---

Verification

Check Supported Assets

address[] memory assets = reserveSystem.getSupportedAssets();
for (uint256 i = 0; i < assets.length; i++) {
    console.log("Asset", i, ":", assets[i]);
}

Check Reserve Balances

uint256 xauBalance = reserveSystem.getReserveBalance(xauAsset);
uint256 usdcBalance = reserveSystem.getReserveBalance(usdcAsset);
uint256 ethBalance = reserveSystem.getReserveBalance(ethAsset);

Check Asset Liquidity Status

bool isLiquid = reserveSystem.isLiquidAsset(asset);

---

Best Practices

1. Start Small: Begin with small deposits for testing
2. Gradual Scaling: Increase reserves gradually as system stabilizes
3. Diversification: Maintain diversified reserve portfolio
4. Monitoring: Regularly monitor reserve balances and ratios
5. Access Control: Use multi-sig for reserve management operations

---

Security Considerations

1. Multi-Sig: Use multi-sig wallets for admin and manager roles
2. Access Control: Limit who can add assets and make deposits
3. Audit: Audit all asset addresses before adding
4. Monitoring: Set up alerts for reserve balance changes
5. Backup: Maintain backup of configuration and addresses

---

Troubleshooting

Asset Not Supported

Error: ReserveSystem: unsupported asset

Solution:

1. Add asset as supported: reserveSystem.addSupportedAsset(asset, true)
2. Verify asset address is correct

Insufficient Balance

Error: ReserveSystem: insufficient reserve

Solution:

1. Check reserve balance: reserveSystem.getReserveBalance(asset)
2. Deposit more reserves if needed
3. Verify token approval before deposit

Invalid Amount

Error: ReserveSystem: zero amount

Solution:

1. Verify deposit amount is greater than zero
2. Check token decimals and amount format

---

References

• Reserve System Documentation
• Price Feed Setup
• Reserve System Contract