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.

```bash
# 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:

```bash
# 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**:
```solidity
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**:
```solidity
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

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

### Deposit Reserves

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

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

### Check Reserve Balance

```solidity
uint256 balance = reserveSystem.getReserveBalance(asset);
```

---

## Complete Setup Example

### Full Configuration Script

```bash
#!/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

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

---

## Verification

### Check Supported Assets

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

### Check Reserve Balances

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

### Check Asset Liquidity Status

```solidity
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](./INTEGRATION_COMPLETE.md)
- [Price Feed Setup](./PRICE_FEED_SETUP.md)
- [Reserve System Contract](../../contracts/reserve/ReserveSystem.sol)