smom-dbis-138/docs/INTEGRATION_GUIDE.md

Integration Guide - Complete System

Date: Integration Complete
Status: ✅ ALL CRITICAL INTEGRATIONS IMPLEMENTED

---

Overview

This guide explains how all systems integrate together:

• Vault System
• ISO-4217 W Token System
• eMoney System
• ChainID 138 Bridge

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        ChainID 138                               │
│                                                                   │
│  ┌──────────────────┐    ┌──────────────────┐                  │
│  │  Vault System    │    │  ISO-4217 W      │                  │
│  │                  │    │  Token System    │                  │
│  │  - Ledger        │    │  - USDW, EURW    │                  │
│  │  - Vaults        │    │  - GBPW, etc.    │                  │
│  │  - Collateral    │    │  - 1:1 fiat      │                  │
│  │  - eMoney debt   │    │  - m = 1.0       │                  │
│  └────────┬─────────┘    └────────┬─────────┘                  │
│           │                       │                             │
│           │                       │                             │
│           └───────────┬───────────┘                             │
│                       │                                         │
│           ┌───────────▼───────────┐                            │
│           │   Bridge System       │                            │
│           │                       │                            │
│           │  - BridgeRegistry     │                            │
│           │  - BridgeEscrowVault  │                            │
│           │  - Integrations       │                            │
│           │  - Verifiers          │                            │
│           └───────────┬───────────┘                            │
│                       │                                        │
└───────────────────────┼────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
   EVM Chains        XRPL          Hyperledger
   (Polygon,        (Native XRP)     Fabric
    Optimism,                       (Enterprise)
    Base, etc.)

---

2. Integration Points

2.1 Vault System ↔ Bridge

Integration Contract: VaultBridgeIntegration.sol

Purpose: Automatically register vault deposit tokens (aTokens) with BridgeRegistry

Flow:

1. VaultFactory creates new vault and deposit token
2. VaultBridgeIntegration registers deposit token in BridgeRegistry
3. Deposit token becomes bridgeable to EVM chains

Configuration:

• Default destinations: Polygon, Optimism, Base, Arbitrum, Avalanche, BNB Chain, Monad
• Default min bridge: 1 token
• Default max bridge: 1M tokens
• Default fee: 0.1% (10 bps)
• Default risk: 50 (medium)

Usage:

// Register deposit token with default config
vaultBridgeIntegration.registerDepositTokenDefault(depositToken);

// Register with custom config
vaultBridgeIntegration.registerDepositToken(
    depositToken,
    destinationChainIds,
    minAmount,
    maxAmount,
    riskLevel,
    bridgeFeeBps
);

---

2.2 ISO-4217 W Token System ↔ Bridge

Integration Contracts:

• WTokenBridgeIntegration.sol - Token registration
• WTokenReserveVerifier.sol - Reserve verification
• WTokenComplianceEnforcer.sol - Compliance enforcement

Purpose:

1. Register W tokens with BridgeRegistry
2. Verify reserves before bridge operations
3. Enforce compliance (money multiplier = 1.0, GRU isolation)

Flow:

1. TokenFactory deploys W token (e.g., USDW)
2. WTokenBridgeIntegration registers USDW in BridgeRegistry
3. User initiates bridge:
   • WTokenReserveVerifier checks reserves
   • WTokenComplianceEnforcer checks compliance
   • BridgeEscrowVault escrows tokens
   • Bridge executes to destination
4. Destination chain:
   • Verifies reserve sufficiency
   • Verifies compliance
   • Mints W tokens 1:1

Configuration:

• Default destinations: EVM chains + XRPL + Fabric
• Default min bridge: 100 USD
• Default max bridge: 10M USD
• Default fee: 0.05% (5 bps) - lower due to compliance
• Default risk: 20 (low - fiat-backed)

Reserve Verification:

• Source chain: Reserve >= (Supply - BridgeAmount) * 100%
• Destination chain: Reserve >= (Supply + BridgeAmount) * 100%

Compliance Checks:

• Money multiplier = 1.0 (hard constraint)
• GRU isolation (no GRU conversion)
• ISO-4217 validation

Usage:

// Register W token with default config
wTokenBridgeIntegration.registerWTokenDefault("USD");

// Register multiple tokens
string[] memory currencies = new string[](3);
currencies[0] = "USD";
currencies[1] = "EUR";
currencies[2] = "GBP";
wTokenBridgeIntegration.registerMultipleWTokensDefault(currencies);

// Verify reserve before bridge
wTokenReserveVerifier.verifyReserveBeforeBridge(token, bridgeAmount);

// Check compliance before bridge
wTokenComplianceEnforcer.checkComplianceBeforeBridge(token, bridgeAmount);

---

2.3 eMoney System ↔ Bridge

Integration Contracts:

• eMoneyBridgeIntegration.sol - Token registration
• eMoneyPolicyEnforcer.sol - Transfer restrictions

Purpose:

1. Register eMoney tokens with BridgeRegistry
2. Enforce transfer restrictions (PolicyManager + ComplianceRegistry)

Flow:

1. eMoney token deployed (via TokenFactory138)
2. eMoneyBridgeIntegration registers token in BridgeRegistry
3. User initiates bridge:
   • eMoneyPolicyEnforcer checks PolicyManager authorization
   • eMoneyPolicyEnforcer checks ComplianceRegistry restrictions
   • BridgeEscrowVault escrows tokens
   • Bridge executes to destination
4. Destination chain:
   • Verifies authorization
   • Verifies compliance
   • Mints/releases eMoney tokens

Configuration:

• Default destinations: EVM chains only (regulated entities)
• Default min bridge: 100 tokens
• Default max bridge: 1M tokens
• Default fee: 0.15% (15 bps)
• Default risk: 60 (medium-high - credit instrument)

Transfer Restrictions:

• PolicyManager checks (whitelist, blacklist, limits)
• ComplianceRegistry checks (regulatory restrictions)
• Context-aware authorization (for complex policies)

Usage:

// Register eMoney token with default config
eMoneyBridgeIntegration.registereMoneyTokenDefault(token, "USDC");

// Check transfer authorization
eMoneyPolicyEnforcer.checkTransferAuthorization(
    token,
    from,
    to,
    amount
);

// Check with context
eMoneyPolicyEnforcer.checkTransferAuthorizationWithContext(
    token,
    from,
    to,
    amount,
    context
);

---

3. Deployment Order

Step 1: Deploy Core Systems

1. Deploy Vault System

   forge script script/vault/DeployVaultSystem.s.sol:DeployVaultSystem --rpc-url $RPC_URL --broadcast
   

2. Deploy ISO-4217 W Token System

   forge script script/iso4217w/DeployWTokenSystem.s.sol:DeployWTokenSystem --rpc-url $RPC_URL --broadcast
   

Step 2: Deploy Bridge Integrations

3. Deploy Bridge Integrations

   forge script script/bridge/DeployBridgeIntegrations.s.sol:DeployBridgeIntegrations --rpc-url $RPC_URL --broadcast
   

Step 3: Configure Bridge Registry

4. Grant REGISTRAR_ROLE to integration contracts

   bridgeRegistry.grantRole(keccak256("REGISTRAR_ROLE"), address(vaultBridgeIntegration));
   bridgeRegistry.grantRole(keccak256("REGISTRAR_ROLE"), address(wTokenBridgeIntegration));
   bridgeRegistry.grantRole(keccak256("REGISTRAR_ROLE"), address(eMoneyBridgeIntegration));
   

Step 4: Register Tokens

5. Register vault deposit tokens

   vaultBridgeIntegration.registerDepositTokenDefault(depositToken);
   

6. Register W tokens

   wTokenBridgeIntegration.registerWTokenDefault("USD");
   wTokenBridgeIntegration.registerWTokenDefault("EUR");
   wTokenBridgeIntegration.registerWTokenDefault("GBP");
   

7. Register eMoney tokens

   eMoneyBridgeIntegration.registereMoneyTokenDefault(eMoneyToken, "USDC");
   

Step 5: Configure Verifiers

8. Register W tokens in Reserve Verifier

   wTokenReserveVerifier.registerToken(usdwToken);
   wTokenReserveVerifier.registerToken(eurwToken);
   

9. Register W tokens in Compliance Enforcer

   wTokenComplianceEnforcer.enableToken(usdwToken);
   wTokenComplianceEnforcer.enableToken(eurwToken);
   

10. Register eMoney tokens in Policy Enforcer

    eMoneyPolicyEnforcer.enableToken(eMoneyToken);
    

---

4. Bridge Operation Flows

4.1 Bridge Vault Deposit Token

Flow:

1. User deposits collateral in vault → receives deposit token (aToken)
2. User initiates bridge: bridgeEscrowVault.deposit(depositToken, amount, destinationType, destinationData)
3. BridgeEscrowVault escrows deposit token
4. Bridge executes to destination chain
5. Destination chain receives deposit token

Verification:

• Token registered in BridgeRegistry ✅
• Amount within min/max limits ✅
• Destination enabled ✅

---

4.2 Bridge ISO-4217 W Token

Flow:

1. User holds USDW token
2. User initiates bridge: bridgeEscrowVault.deposit(usdwToken, amount, destinationType, destinationData)
3. Reserve Verification: wTokenReserveVerifier.verifyReserveBeforeBridge(usdwToken, amount)
   • Checks: Reserve >= (Supply - Amount) * 100%
4. Compliance Check: wTokenComplianceEnforcer.checkComplianceBeforeBridge(usdwToken, amount)
   • Checks: Money multiplier = 1.0, GRU isolation, ISO-4217 validation
5. BridgeEscrowVault escrows USDW
6. Bridge executes to destination chain
7. Destination Verification:
   • Reserve verification: Reserve >= (Supply + Amount) * 100%
   • Compliance check: Money multiplier = 1.0
8. Destination chain mints USDW 1:1

Verification:

• Token registered ✅
• Reserve sufficient ✅
• Compliance verified ✅
• Amount within limits ✅

---

4.3 Bridge eMoney Token

Flow:

1. User holds eMoney token
2. User initiates bridge: bridgeEscrowVault.deposit(eMoneyToken, amount, destinationType, destinationData)
3. Authorization Check: eMoneyPolicyEnforcer.checkTransferAuthorization(eMoneyToken, from, bridgeEscrowVault, amount)
   • Checks: PolicyManager authorization, ComplianceRegistry restrictions
4. BridgeEscrowVault escrows eMoney token
5. Bridge executes to destination chain
6. Destination chain verifies authorization
7. Destination chain releases/mints eMoney token

Verification:

• Token registered ✅
• Transfer authorized ✅
• Compliance verified ✅
• Amount within limits ✅

---

5. Testing

5.1 Unit Tests

Vault System:

forge test --match-path test/vault/*.sol -vv

ISO-4217 W Token System:

forge test --match-path test/iso4217w/*.sol -vv

5.2 Integration Tests

Bridge Integration Tests (to be created):

forge test --match-path test/bridge/integration/*.sol -vv

---

6. Monitoring & Operations

6.1 Key Metrics

Vault System:

• Total collateral locked
• Total debt issued
• Vault health ratios
• Liquidation events

ISO-4217 W Token System:

• Total supply per token (USDW, EURW, etc.)
• Verified reserves per token
• Reserve sufficiency ratio (should be >= 100%)
• Bridge operations count

Bridge System:

• Bridge success rate
• Settlement time
• Reserve verification failures
• Compliance violations

6.2 Alerts

Critical Alerts:

• Reserve < Supply for any W token (m = 1.0 violation)
• Compliance violation detected
• Transfer authorization denied (suspicious activity)
• Bridge failure rate > 5%

Warning Alerts:

• Reserve ratio < 105% for any W token
• Bridge settlement time > 1 hour
• High number of reserve verification checks

---

7. Security Considerations

7.1 Access Control

Critical Roles:

• DEFAULT_ADMIN_ROLE: Full system control
• REGISTRAR_ROLE: BridgeRegistry token registration
• VERIFIER_ROLE: Reserve verification
• ENFORCER_ROLE: Compliance enforcement
• OPERATOR_ROLE: Token enable/disable

Principle of Least Privilege:

• Grant minimum necessary roles
• Use multi-sig for admin roles
• Audit role assignments regularly

7.2 Reserve Verification

Requirements:

• Reserve MUST be >= Supply at all times (m = 1.0)
• Reserve verification required before bridge
• Oracle quorum required for reserve reports
• Staleness detection for reserve data

7.3 Compliance Enforcement

Requirements:

• Money multiplier = 1.0 (hard constraint)
• GRU isolation (no GRU conversion)
• ISO-4217 validation
• Transfer restrictions enforced

7.4 Bridge Security

Requirements:

• Multi-attestor quorum for cross-chain verification
• Timeout-based refunds
• Reentrancy protection
• Pausable contracts for emergency stops

---

8. Troubleshooting

Issue: Reserve Verification Fails

Cause: Reserve < Supply for W token

Solution:

1. Check reserve oracle reports
2. Verify custodial account balance
3. Pause minting if reserve insufficient
4. Update reserve via oracle

Issue: Compliance Violation

Cause: Money multiplier > 1.0 or GRU isolation violation

Solution:

1. Check reserve vs supply
2. Verify no GRU conversion paths
3. Pause bridge operations
4. Fix underlying issue

Issue: Transfer Authorization Denied

Cause: PolicyManager or ComplianceRegistry restriction

Solution:

1. Check whitelist/blacklist
2. Verify transfer limits
3. Check compliance status
4. Contact admin for exception

---

9. Next Steps

1. ✅ Run all unit tests
2. ✅ Create integration tests
3. ✅ Conduct security audit
4. ✅ Set up monitoring infrastructure
5. ✅ Create runbooks
6. ✅ Production deployment

---

Last Updated: Integration Complete
Status: ✅ READY FOR TESTING