smom-dbis-138/docs/API_DOCUMENTATION.md

API Documentation - Complete System

Date: API Documentation
Status: ✅ COMPLETE

---

Overview

This document provides complete API documentation for:

1. Vault System
2. ISO-4217 W Token System
3. Bridge Integrations

---

1. Vault System API

1.1 Ledger Contract

modifyCollateral(address vault, address asset, int256 delta)

Description: Modify collateral balance for a vault

Parameters:

• vault: Vault address
• asset: Collateral asset address (address(0) for ETH)
• delta: Amount change (positive to add, negative to remove)

Requirements:

• Caller must have VAULT_ROLE
• Asset must be registered
• Collateral cannot go negative

Events:

• CollateralModified(address indexed vault, address indexed asset, int256 delta)

---

modifyDebt(address vault, address currency, int256 delta)

Description: Modify debt balance for a vault (accrues interest automatically)

Parameters:

• vault: Vault address
• currency: Debt currency address
• delta: Amount change (positive to add debt, negative to repay)

Requirements:

• Caller must have VAULT_ROLE
• Interest is accrued before modification

Events:

• DebtModified(address indexed vault, address indexed currency, int256 delta)

---

getVaultHealth(address vault)

Description: Get vault health ratio, collateral value, and debt value

Returns:

• healthRatio: Health ratio (in basis points, max = type(uint256).max if no debt)
• collateralValue: Total collateral value in XAU
• debtValue: Total debt value in XAU

View Function: Yes

---

canBorrow(address vault, address currency, uint256 amount)

Description: Check if vault can borrow specified amount

Returns:

• canBorrow: True if borrow is allowed
• reasonCode: Reason code if borrow not allowed (bytes32(0) if allowed)

View Function: Yes

Reason Codes:

• keccak256("DEBT_CEILING_EXCEEDED"): Debt ceiling would be exceeded
• keccak256("INSUFFICIENT_COLLATERAL"): Insufficient collateral
• keccak256("HEALTH_RATIO_TOO_LOW"): Health ratio too low

---

setRiskParameters(address asset, uint256 debtCeiling, uint256 liquidationRatio, uint256 creditMultiplier)

Description: Set risk parameters for an asset

Parameters:

• asset: Asset address
• debtCeiling: Maximum debt for this asset (in asset decimals)
• liquidationRatio: Liquidation threshold (in basis points, e.g., 11000 = 110%)
• creditMultiplier: Credit multiplier (in basis points, e.g., 50000 = 5x)

Requirements:

• Caller must have DEFAULT_ADMIN_ROLE
• liquidationRatio <= 10000 (100%)
• creditMultiplier <= 100000 (10x)

---

1.2 Vault Contract

deposit(address asset, uint256 amount)

Description: Deposit collateral into vault

Parameters:

• asset: Collateral asset address
• amount: Amount to deposit

Requirements:

• Caller must be authorized (owner or operator)
• For ETH: Send native ETH with transaction
• For ERC20: Approve token first

Events:

• Deposited(address indexed user, address indexed asset, uint256 amount)

---

withdraw(address asset, uint256 amount)

Description: Withdraw collateral from vault

Parameters:

• asset: Collateral asset address
• amount: Amount to withdraw

Requirements:

• Caller must be authorized
• Vault must remain healthy after withdrawal

Events:

• Withdrawn(address indexed user, address indexed asset, uint256 amount)

---

borrow(address currency, uint256 amount)

Description: Borrow eMoney against collateral

Parameters:

• currency: eMoney currency address
• amount: Amount to borrow

Requirements:

• Vault must be healthy
• Debt ceiling not exceeded
• Sufficient collateral

Events:

• Borrowed(address indexed user, address indexed currency, uint256 amount)

---

repay(address currency, uint256 amount)

Description: Repay eMoney debt

Parameters:

• currency: eMoney currency address
• amount: Amount to repay

Requirements:

• Must have sufficient debt
• eMoney tokens must be approved

Events:

• Repaid(address indexed user, address indexed currency, uint256 amount)

---

getHealth()

Description: Get vault health information

Returns:

• healthRatio: Health ratio (in basis points)
• collateralValue: Collateral value in XAU
• debtValue: Debt value in XAU

View Function: Yes

---

1.3 VaultFactory Contract

createVault(address owner, address entity, address asset, address currency)

Description: Create a new vault with deposit and debt tokens

Parameters:

• owner: Vault owner address
• entity: Regulated entity address
• asset: Collateral asset address
• currency: eMoney currency address

Returns:

• vault: Address of created vault
• depositToken: Address of deposit token
• debtToken: Address of debt token

Requirements:

• Caller must have VAULT_DEPLOYER_ROLE
• owner and entity must not be zero address

Events:

• VaultCreated(address indexed vault, address indexed entity, address indexed owner, address depositToken, address debtToken)

---

2. ISO-4217 W Token System API

2.1 ISO4217WToken Contract

mint(address to, uint256 amount)

Description: Mint W tokens (1:1 with fiat reserve)

Parameters:

• to: Recipient address
• amount: Amount to mint (in token decimals)

Requirements:

• Caller must have MINTER_ROLE
• Reserve must be >= (Supply + Amount)
• Money multiplier = 1.0 enforced

Events:

• Minted(address indexed to, uint256 amount, string indexed currencyCode)

---

burn(address from, uint256 amount)

Description: Burn W tokens (on redemption)

Parameters:

• from: Source address
• amount: Amount to burn

Requirements:

• Caller must have BURNER_ROLE
• from must have sufficient balance

Events:

• Burned(address indexed from, uint256 amount, string indexed currencyCode)

---

updateVerifiedReserve(uint256 reserveBalance)

Description: Update verified reserve balance

Parameters:

• reserveBalance: Reserve balance (in base currency units)

Requirements:

• Caller must have RESERVE_UPDATE_ROLE
• Reserve should be >= Supply (warning emitted if not)

Events:

• ReserveUpdated(uint256 reserveBalance, uint256 totalSupply)

---

isReserveSufficient()

Description: Check if reserve is sufficient (>= supply)

Returns: True if reserve >= supply

View Function: Yes

---

currencyCode()

Description: Get ISO-4217 currency code (e.g., "USD")

Returns: 3-letter currency code

View Function: Yes

---

verifiedReserve()

Description: Get verified reserve balance

Returns: Reserve balance (in base currency units)

View Function: Yes

---

2.2 MintController Contract

mint(address token, address to, uint256 amount, bytes32 settlementId, address custodian)

Description: Mint W tokens with reserve verification

Parameters:

• token: W token address
• to: Recipient address
• amount: Amount to mint
• settlementId: Fiat settlement ID
• custodian: Custodian address

Requirements:

• Caller must have MINTER_ROLE
• Reserve must be sufficient (verified via oracle)
• Oracle quorum must be met
• Compliance checks must pass

Events:

• Minted(address indexed token, address indexed to, uint256 amount, bytes32 settlementId)

---

canMint(address token, uint256 amount)

Description: Check if minting is allowed

Returns: True if minting is allowed

View Function: Yes

Checks:

• Reserve sufficiency
• Oracle quorum
• Compliance validation

---

2.3 BurnController Contract

redeem(address token, address from, uint256 amount)

Description: Redeem W tokens (burn and release fiat)

Parameters:

• token: W token address
• from: Redeemer address
• amount: Amount to redeem

Returns: Redemption ID for tracking

Requirements:

• Caller must have REDEEMER_ROLE
• Token must be approved
• Redemption must be allowed

Events:

• Redeemed(address indexed token, address indexed from, uint256 amount, bytes32 redemptionId)

---

canRedeem(address token, uint256 amount)

Description: Check if redemption is allowed

Returns: True if redemption is allowed

View Function: Yes

---

2.4 ReserveOracle Contract

submitReserveReport(address token, uint256 reserveBalance, uint256 timestamp)

Description: Submit reserve report (oracle only)

Parameters:

• token: W token address
• reserveBalance: Reserve balance
• timestamp: Report timestamp

Requirements:

• Caller must have ORACLE_ROLE

Events:

• ReserveReportSubmitted(address indexed token, address indexed oracle, uint256 reserveBalance, uint256 timestamp)

---

getVerifiedReserve(address token)

Description: Get verified reserve balance (consensus)

Returns: Consensus reserve balance

View Function: Yes

Note: Requires quorum

---

isQuorumMet(address token)

Description: Check if oracle quorum is met

Returns: True if quorum met

View Function: Yes

---

3. Bridge Integration API

3.1 VaultBridgeIntegration Contract

registerDepositToken(address depositToken, uint256[] destinationChainIds, uint256 minAmount, uint256 maxAmount, uint8 riskLevel, uint256 bridgeFeeBps)

Description: Register vault deposit token with bridge

Parameters:

• depositToken: Deposit token address
• destinationChainIds: Array of allowed destination chain IDs
• minAmount: Minimum bridge amount
• maxAmount: Maximum bridge amount
• riskLevel: Risk level (0-255)
• bridgeFeeBps: Bridge fee in basis points

Requirements:

• Caller must have INTEGRATOR_ROLE

Events:

• DepositTokenRegistered(address indexed depositToken, address indexed vault, uint256[] destinationChainIds)

---

registerDepositTokenDefault(address depositToken)

Description: Register deposit token with default configuration

Parameters:

• depositToken: Deposit token address

Requirements:

• Caller must have INTEGRATOR_ROLE

---

3.2 WTokenBridgeIntegration Contract

registerWToken(string currencyCode, uint256[] destinationChainIds, uint256 minAmount, uint256 maxAmount, uint8 riskLevel, uint256 bridgeFeeBps)

Description: Register W token with bridge

Parameters:

• currencyCode: ISO-4217 currency code (e.g., "USD")
• destinationChainIds: Array of allowed destination chain IDs
• minAmount: Minimum bridge amount
• maxAmount: Maximum bridge amount
• riskLevel: Risk level (0-255)
• bridgeFeeBps: Bridge fee in basis points

Requirements:

• Caller must have INTEGRATOR_ROLE
• Token must exist in TokenRegistry

Events:

• WTokenRegistered(address indexed token, string indexed currencyCode, uint256[] destinationChainIds)

---

registerWTokenDefault(string currencyCode)

Description: Register W token with default configuration

Parameters:

• currencyCode: ISO-4217 currency code

Requirements:

• Caller must have INTEGRATOR_ROLE

---

3.3 WTokenReserveVerifier Contract

verifyReserveBeforeBridge(address token, uint256 bridgeAmount)

Description: Verify reserve before bridge operation

Parameters:

• token: W token address
• bridgeAmount: Amount to bridge

Returns: True if reserve is sufficient

View Function: Yes

Checks:

• Reserve >= (Supply - BridgeAmount) * 100%

Reverts: If reserve insufficient

---

registerToken(address token)

Description: Register W token for reserve verification

Parameters:

• token: W token address

Requirements:

• Caller must have OPERATOR_ROLE
• Token must implement IISO4217WToken

Events:

• TokenVerified(address indexed token, bool verified)

---

3.4 WTokenComplianceEnforcer Contract

checkComplianceBeforeBridge(address token, uint256 bridgeAmount)

Description: Check compliance before bridge operation

Parameters:

• token: W token address
• bridgeAmount: Amount to bridge

Returns: True if compliant

View Function: Yes

Checks:

• Money multiplier = 1.0
• GRU isolation
• ISO-4217 validation

Reverts: If compliance violation

Events:

• ComplianceChecked(address indexed token, bytes32 reasonCode, bool compliant)

---

3.5 eMoneyPolicyEnforcer Contract

checkTransferAuthorization(address token, address from, address to, uint256 amount)

Description: Check if transfer is authorized

Parameters:

• token: eMoney token address
• from: Source address
• to: Destination address
• amount: Transfer amount

Returns: True if authorized

View Function: Yes

Checks:

• PolicyManager authorization
• ComplianceRegistry restrictions

Reverts: If not authorized

Events:

• TransferAuthorized(address indexed token, address indexed from, address indexed to, uint256 amount, bool authorized)

---

4. Error Codes

Vault System Errors

Error Code	Description
Ledger: asset not registered	Asset not registered in ledger
Ledger: insufficient collateral	Attempting to withdraw more than available
Ledger: invalid liquidation ratio	Liquidation ratio > 100%
Ledger: invalid credit multiplier	Credit multiplier > 10x
Ledger: debt ceiling exceeded	Borrowing would exceed debt ceiling
Vault: not authorized	Caller not authorized to use vault
Vault: insufficient collateral	Not enough collateral for operation

ISO-4217 W Token Errors

Error Code	Description
ISO4217WToken: reserve insufficient - money multiplier violation	Reserve < Supply (m < 1.0)
MintController: reserve insufficient	Reserve not sufficient for mint
MintController: oracle quorum not met	Oracle quorum not met
MintController: compliance violation	Compliance check failed
BurnController: token not approved	Token not approved for redemption
BurnController: redemption not allowed	Redemption not allowed

Bridge Integration Errors

Error Code	Description
WTokenReserveVerifier: insufficient reserve	Reserve insufficient for bridge
WTokenComplianceEnforcer: compliance violation	Compliance check failed
eMoneyPolicyEnforcer: transfer not authorized	Transfer not authorized by policy

---

5. Events Reference

Vault System Events

event CollateralModified(address indexed vault, address indexed asset, int256 delta);
event DebtModified(address indexed vault, address indexed currency, int256 delta);
event VaultCreated(address indexed vault, address indexed entity, address indexed owner, address depositToken, address debtToken);
event Deposited(address indexed user, address indexed asset, uint256 amount);
event Borrowed(address indexed user, address indexed currency, uint256 amount);

ISO-4217 W Token Events

event Minted(address indexed to, uint256 amount, string indexed currencyCode);
event Burned(address indexed from, uint256 amount, string indexed currencyCode);
event ReserveUpdated(uint256 reserveBalance, uint256 totalSupply);
event Redeemed(address indexed token, address indexed from, uint256 amount, bytes32 redemptionId);

Bridge Integration Events

event DepositTokenRegistered(address indexed depositToken, address indexed vault, uint256[] destinationChainIds);
event WTokenRegistered(address indexed token, string indexed currencyCode, uint256[] destinationChainIds);
event ReserveVerified(address indexed token, uint256 reserve, uint256 supply, uint256 bridgeAmount, bool sufficient);
event ComplianceChecked(address indexed token, bytes32 reasonCode, bool compliant);
event TransferAuthorized(address indexed token, address indexed from, address indexed to, uint256 amount, bool authorized);

---

6. Usage Examples

Example 1: Create Vault and Deposit Collateral

// 1. Create vault via factory
(address vault, , ) = vaultFactory.createVault(owner, entity, eth, usdc);

// 2. Deposit ETH collateral
vault.deposit{value: 10 ether}(address(0), 10 ether);

Example 2: Borrow eMoney

// Borrow 1000 USDC against collateral
vault.borrow(usdcToken, 1000e6);

Example 3: Deploy and Mint USDW

// 1. Deploy USDW via factory
address usdw = tokenFactory.deployToken("USD", "USDW Token", "USDW", 2, custodian);

// 2. Update reserve
iso4217wToken(usdw).updateVerifiedReserve(10000e2); // 10,000 USD reserve

// 3. Mint USDW
mintController.mint(usdw, user, 1000e2, settlementId, custodian);

Example 4: Bridge W Token

// 1. Verify reserve
wTokenReserveVerifier.verifyReserveBeforeBridge(usdw, 1000e2);

// 2. Check compliance
wTokenComplianceEnforcer.checkComplianceBeforeBridge(usdw, 1000e2);

// 3. Bridge
bridgeEscrowVault.deposit(usdw, 1000e2, DestinationType.EVM, destinationData);

---

Last Updated: API Documentation Complete