Bridge Implementation Guide

For: Next developer/agent to complete the bridge implementation Date: November 6, 2025 Status: BridgeController partially implemented, needs completion Contact: @maxgershfield on Telegram

Current Status

✅ What's Already Built

1. BridgeController (/ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Controllers/BridgeController.cs)

✅ 3 endpoints implemented:
- POST /api/v1/orders - Create bridge order
- GET /api/v1/orders/{orderId}/check-balance - Check order status
- GET /api/v1/exchange-rate - Get current exchange rate
- GET /api/v1/networks - Get supported networks

2. BridgeService (/ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Services/BridgeService.cs)

✅ Service layer wrapping CrossChainBridgeManager
✅ Solana bridge initialized
⚠️ Radix bridge not initialized (uses Solana placeholder)
✅ Error handling implemented

3. Frontend (/UniversalAssetBridge/frontend/)

✅ Complete React/Next.js UI
✅ Swap form with token selection
✅ Multi-chain support (10 chains displayed)
✅ Connected to backend API

❌ What's Missing

1. Smart Contracts for Locking/Releasing Tokens

No deployed bridge contracts on any chain
Specifications created: /UniversalAssetBridge/contracts/bridge-specifications.json
Need to generate and deploy contracts

2. CrossChainBridgeManager Implementation

Referenced in BridgeService but location unknown
Core atomic swap logic needed
Lock/mint/burn/release functionality

3. Additional Blockchain Support

Currently: Solana only (Radix placeholder)
Needed: Ethereum, Polygon, Arbitrum, Base, etc.
Each needs IOASISBridge implementation

4. Database/State Management

No order persistence
No transaction tracking
No status updates for pending orders

5. Oracle/Relayer System

Who detects locks on source chain?
Who initiates mints on destination chain?
Multi-sig setup for security

Architecture Overview

How It Should Work

User Initiates Swap (SOL → ETH)
         ↓
POST /api/v1/orders
         ↓
BridgeController.CreateOrder()
         ↓
BridgeService.CreateOrderAsync()
         ↓
CrossChainBridgeManager.CreateBridgeOrderAsync()
         ↓
┌─────────────────────────────────────┐
│ 1. Lock SOL on Solana               │
│    └─> SolanaBridgeService.Lock()  │
│         └─> Calls Solana contract   │
│                                      │
│ 2. Emit TokensLocked event          │
│    └─> Listened by HyperDrive       │
│                                      │
│ 3. Oracle detects lock              │
│    └─> Verifies via merkle proof    │
│                                      │
│ 4. Mint ETH on Ethereum             │
│    └─> EthereumBridgeService.Mint() │
│         └─> Calls Ethereum contract  │
│                                      │
│ 5. Update order status              │
│    └─> Save to database              │
│                                      │
│ 6. Return to user                   │
│    └─> Transaction complete          │
└─────────────────────────────────────┘

Key Components Needed

1. IOASISBridge Interface:

public interface IOASISBridge
{
    Task<OASISResult<string>> LockTokensAsync(
        string fromAddress,
        decimal amount,
        string destinationChain,
        string destinationAddress
    );
    
    Task<OASISResult<string>> MintTokensAsync(
        string toAddress,
        decimal amount,
        string orderId,
        bytes32[] proof
    );
    
    Task<OASISResult<string>> BurnTokensAsync(
        string fromAddress,
        decimal amount,
        string returnChain,
        string returnAddress
    );
    
    Task<OASISResult<string>> ReleaseTokensAsync(
        string toAddress,
        decimal amount,
        string orderId,
        bytes32[] proof
    );
    
    Task<OASISResult<decimal>> GetBalanceAsync(string address);
    
    Task<OASISResult<bool>> VerifyTransactionAsync(string txHash);
}

2. CrossChainBridgeManager:

public class CrossChainBridgeManager : ICrossChainBridgeManager
{
    private readonly Dictionary<string, IOASISBridge> _bridges;
    private readonly IOrderRepository _orderRepository;
    private readonly IOracleService _oracleService;
    
    public async Task<OASISResult<CreateBridgeOrderResponse>> CreateBridgeOrderAsync(
        CreateBridgeOrderRequest request,
        CancellationToken cancellationToken
    )
    {
        // 1. Validate request
        // 2. Get source and destination bridges
        // 3. Lock tokens on source chain
        // 4. Save order to database (pending)
        // 5. Notify oracle to mint on destination
        // 6. Return order ID to user
    }
    
    public async Task<OASISResult<decimal>> GetExchangeRateAsync(
        string fromToken,
        string toToken,
        CancellationToken cancellationToken
    )
    {
        // Query CoinGecko or other price oracle
        // Return current rate
    }
    
    public async Task<OASISResult<BridgeOrderBalanceResponse>> CheckOrderBalanceAsync(
        Guid orderId,
        CancellationToken cancellationToken
    )
    {
        // 1. Load order from database
        // 2. Check balances on both chains
        // 3. Return status (pending, completed, failed)
    }
}

3. Oracle Service (New - Needs Building):

public class BridgeOracleService : IOracleService
{
    // Listens for TokensLocked events on all chains
    // Verifies locks via consensus (7+ chains agree)
    // Generates merkle proofs
    // Calls mintTokens() on destination chains
    // Updates order status
}

4. Order Repository (New - Needs Building):

public interface IOrderRepository
{
    Task<BridgeOrder> CreateAsync(BridgeOrder order);
    Task<BridgeOrder> GetByIdAsync(Guid orderId);
    Task UpdateStatusAsync(Guid orderId, OrderStatus status);
    Task<List<BridgeOrder>> GetPendingOrdersAsync();
}

File Locations

Existing Code

Controllers:

/ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Controllers/BridgeController.cs ✅

Services:

/ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Services/BridgeService.cs ✅

Bridge Interfaces:

Search for: NextGenSoftware.OASIS.API.Core.Managers.Bridge/
Should contain: ICrossChainBridgeManager.cs, IOASISBridge.cs

Provider Implementations:

/NextGenSoftware.OASIS.API.Providers.SOLANAOASIS/ ✅ (SolanaBridgeService exists)
/NextGenSoftware.OASIS.API.Providers.EthereumOASIS/ - needs bridge service
/NextGenSoftware.OASIS.API.Providers.ArbitrumOASIS/ - needs bridge service
/NextGenSoftware.OASIS.API.Providers.PolygonOASIS/ - needs bridge service

Frontend:

/UniversalAssetBridge/frontend/src/ ✅

Contracts to Create

Location: /UniversalAssetBridge/contracts/

Files needed:

OASISBridge.sol (Ethereum/EVM chains) ❌
solana_bridge_program.rs (Solana) ❌
radix_bridge.scrypto (Radix) ❌

Specification ready: bridge-specifications.json ✅

Implementation Tasks

Phase 1: Generate Smart Contracts (4-6 hours)

Prerequisites:

SmartContractGenerator API running on port 5000

Tasks:

Generate Solidity Contract:

curl -X POST "http://localhost:5000/api/v1/contracts/generate" \
  -F 'Language=Ethereum' \
  -F 'JsonFile=@/Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/bridge-specifications.json' \
  -o /Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/OASISBridge.sol

Generate Solana Program:

curl -X POST "http://localhost:5000/api/v1/contracts/generate" \
  -F 'Language=Rust' \
  -F 'JsonFile=@/Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/bridge-specifications.json' \
  -o /Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/solana-bridge.zip

Generate Radix Component:

curl -X POST "http://localhost:5000/api/v1/contracts/generate" \
  -F 'Language=Scrypto' \
  -F 'JsonFile=@/Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/bridge-specifications.json' \
  -o /Volumes/Storage/OASIS_CLEAN/UniversalAssetBridge/contracts/radix-bridge.zip

Compile and Deploy to Testnets:
- Follow guide: /UniversalAssetBridge/contracts/BUILD_BRIDGE_CONTRACTS.md

Deliverable: Bridge contracts deployed on Sepolia, Solana Devnet, Radix Stokenet

Phase 2: Implement CrossChainBridgeManager (8-12 hours)

File to Create/Update: Search for existing CrossChainBridgeManager or create new

Required Functionality:

CreateBridgeOrderAsync:
- Validate request (amount, addresses, chains supported)
- Lock tokens on source chain via IOASISBridge
- Generate order ID
- Save to database
- Emit event for oracle
- Return order details
ProcessLockedTokensAsync (Oracle Function):
- Listen for TokensLocked events on all chains
- Wait for finality (15 blocks for Ethereum, etc.)
- Generate merkle proof of lock
- Call mintTokens on destination chain
- Update order status to "completed"
CheckOrderBalanceAsync:
- Load order from database
- Query both chains for balances
- Return status (pending, locked, minted, completed, failed)
GetExchangeRateAsync:
- Query CoinGecko API (already has service for this)
- Cache results (1 minute TTL)
- Handle API failures gracefully

Dependencies:

IOracleService (new interface needed)
IOrderRepository (new interface needed)
Event listener system (HyperDrive integration)

Deliverable: Fully functional bridge manager with atomic swaps

Phase 3: Build Oracle Service (12-16 hours)

File to Create: /ONODE/NextGenSoftware.OASIS.API.ONODE.WebAPI/Services/BridgeOracleService.cs

Functionality:

Event Monitoring:
- Subscribe to TokensLocked events on all chains
- Use Web3 WebSocket for Ethereum/EVM
- Use Solana WebSocket subscriptions
- Store events in queue
Consensus Verification:
- Wait for block finality
- Query transaction on source chain
- Verify it's confirmed (not reverted)
- Generate merkle proof from multiple providers
Cross-Chain Execution:
- Sign transaction with oracle private key
- Call mintTokens on destination contract
- Include merkle proof for verification
- Update database on success/failure
Error Handling:
- Retry failed mints (exponential backoff)
- Alert on stuck transactions (> 1 hour)
- Automatic rollback on double-failures

Security:

Multi-sig for oracle operations (3-of-5)
Merkle proof verification
Nonce-based replay protection

Deliverable: Background service monitoring all chains and completing cross-chain swaps

Phase 4: Database Integration (4-6 hours)

Tables Needed:

BridgeOrders:

CREATE TABLE bridge_orders (
  order_id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  from_token VARCHAR(10),
  to_token VARCHAR(10),
  from_chain VARCHAR(50),
  to_chain VARCHAR(50),
  amount DECIMAL(18,8),
  from_address VARCHAR(255),
  to_address VARCHAR(255),
  exchange_rate DECIMAL(18,8),
  status VARCHAR(20), -- pending, locked, minted, completed, failed
  source_tx_hash VARCHAR(255),
  dest_tx_hash VARCHAR(255),
  created_at TIMESTAMP,
  locked_at TIMESTAMP,
  completed_at TIMESTAMP,
  error_message TEXT
);

Provider Implementations:

Option A: Use MongoDBOASIS (existing, configured)
Option B: Add PostgreSQL provider (more robust for financial data)
Option C: Use both (MongoDB for fast access, PostgreSQL for permanence)

Deliverable: Order persistence and history tracking

Phase 5: Multi-Chain Provider Implementation (6-8 hours per chain)

For each additional chain, implement IOASISBridge:

Ethereum Example:

// File: /NextGenSoftware.OASIS.API.Providers.EthereumOASIS/EthereumBridgeService.cs

public class EthereumBridgeService : IOASISBridge
{
    private readonly IWeb3 _web3;
    private readonly string _bridgeContractAddress;
    
    public async Task<OASISResult<string>> LockTokensAsync(
        string fromAddress,
        decimal amount,
        string destinationChain,
        string destinationAddress
    )
    {
        // 1. Create transaction to bridge contract
        // 2. Call lockTokens(destinationChain, recipient, amount)
        // 3. Wait for confirmation
        // 4. Return transaction hash
    }
    
    public async Task<OASISResult<string>> MintTokensAsync(
        string toAddress,
        decimal amount,
        string orderId,
        bytes32[] proof
    )
    {
        // 1. Create transaction with oracle private key
        // 2. Call mintTokens(orderId, recipient, amount, proof)
        // 3. Wait for confirmation
        // 4. Return transaction hash
    }
    
    // ... other interface methods
}

Chains to implement:

EthereumOASIS
PolygonOASIS
ArbitrumOASIS
BaseOASIS
OptimismOASIS
AvalancheOASIS
BSCOASIS
FantomOASIS

Deliverable: IOASISBridge implementation for each supported chain

Phase 6: HyperDrive Integration (8-12 hours)

Event Listener Integration:

Connect BridgeOracleService with HyperDrive's provider monitoring:

// In HyperDrive Provider Management:
public class BridgeEventMonitor
{
    public async Task MonitorAllChainsForBridgeEvents()
    {
        var chains = GetAllBridgeProviders();
        
        foreach (var chain in chains)
        {
            // Subscribe to contract events
            chain.OnTokensLocked += HandleTokensLocked;
            chain.OnTokensBurned += HandleTokensBurned;
        }
    }
    
    private async Task HandleTokensLocked(TokensLockedEvent evt)
    {
        // Trigger oracle to mint on destination
        await _oracleService.ProcessLockEvent(evt);
    }
}

Deliverable: Automatic bridge completion via HyperDrive monitoring

Technical Decisions Needed

Decision 1: Database Choice

MongoDB (Current):

✅ Already configured
✅ Works with HyperDrive auto-replication
⚠️ Less ideal for financial transactions (no ACID guarantees)

PostgreSQL:

✅ ACID compliance
✅ Better for financial data
❌ Needs setup and configuration

Recommendation: Use both - MongoDB for HyperDrive integration, PostgreSQL for orders

Decision 2: Oracle Architecture

Option A: Centralized Oracle (Faster to Build):

Single oracle service running in OASIS backend
Holds private keys
Executes cross-chain mints
Risk: Single point of failure
Timeline: 1-2 weeks

Option B: Multi-Sig Oracle (More Secure):

3-of-5 multi-sig wallet
Distributed validators
Consensus required for mints
Risk: Complexity, slower execution
Timeline: 4-6 weeks

Recommendation: Start with Option A, migrate to Option B for mainnet

Decision 3: Bridge Contract Security

Options:

Deploy immediately (fast but risky)
Security audit first ($50K-$200K, 4-8 weeks)
Bug bounty program ($50K reserve)

Recommendation:

Deploy to testnets immediately
Run for 2-3 months
Security audit before mainnet
Launch bug bounty
Mainnet deployment

Known Issues & Gotchas

Issue 1: Radix Integration Not Complete

Current State:

BridgeService line 59: Uses Solana placeholder for Radix
RadixOASIS provider exists but RadixService needs bridge methods

Fix Needed:

Implement RadixBridgeService
Update BridgeService initialization

Issue 2: No Transaction Persistence

Current State:

Orders created in memory only
Lost on restart
No status tracking

Fix Needed:

Create OrderRepository
Integrate with MongoDB/PostgreSQL
Save on order creation
Update on status changes

Issue 3: Exchange Rate Service

Current State:

Uses CoinGeckoExchangeRateService (exists)
No caching
No fallback if CoinGecko down

Fix Needed:

Add caching layer (Redis or memory cache)
Add fallback price sources (Chainlink, etc.)
Handle rate limiting

Issue 4: No Automatic Order Completion

Current State:

Orders created but never completed
No oracle watching for locks
No automatic minting

Fix Needed:

Build oracle service
Integrate with HyperDrive event system
Background worker to process pending orders

Testing Checklist

Unit Tests Needed

BridgeController endpoint tests
BridgeService logic tests
CrossChainBridgeManager atomic swap tests
IOASISBridge implementations (each chain)
Oracle service consensus tests
Merkle proof generation/verification

Integration Tests Needed

Security Tests Needed

Reentrancy attack prevention
Access control (only oracle can mint)
Replay attack prevention (nonce checking)
Oracle manipulation resistance
Emergency pause functionality
Fund recovery mechanisms

Dependencies & Prerequisites

Software Required

Backend Development:

.NET 9.0 SDK
MongoDB (or PostgreSQL)
Redis (optional, for caching)

Smart Contract Development:

Solidity compiler (solc)
Rust + Anchor (for Solana)
Scrypto CLI (for Radix)

Blockchain Access:

Infura/Alchemy API keys (Ethereum)
Solana RPC access
Radix node access

External Services

Price Oracles:

CoinGecko API (free tier: 10-50 calls/min)
Chainlink (fallback)
Alternative: DEX aggregators

Blockchain Explorers:

Etherscan API (transaction verification)
Solscan API
Radix Explorer API

Success Criteria

Minimum Viable Bridge (MVP)

Functionality:

User can swap SOL → ETH on testnets
Exchange rate updates in real-time
Orders tracked in database
Automatic completion (oracle)
Status updates visible to user

Performance:

Exchange rate < 500ms
Order creation < 2 seconds
Swap completion < 5 minutes (including block finality)

Reliability:

No lost funds (atomic operations)
Automatic rollback on failure
99% uptime (via HyperDrive failover)

Production Ready

Additional Requirements:

Security audit passed
Bug bounty program (no critical issues for 30 days)
Multi-sig oracle deployed
Insurance fund for edge cases
24/7 monitoring and alerting
Mainnet deployment with limited volume ($10K max initially)

Estimated Timeline

Phase 1: Smart Contracts

Generation: 2 hours
Deployment to testnets: 4 hours
Total: 6 hours

Phase 2: CrossChainBridgeManager

Implementation: 8 hours
Testing: 4 hours
Total: 12 hours

Phase 3: Oracle Service

Event monitoring: 8 hours
Consensus logic: 4 hours
Execution: 4 hours
Total: 16 hours

Phase 4: Database

Schema design: 2 hours
Repository implementation: 4 hours
Total: 6 hours

Phase 5: Multi-Chain Providers

Per chain: 6 hours × 8 chains
Total: 48 hours

Phase 6: HyperDrive Integration

Event system: 8 hours
Testing: 4 hours
Total: 12 hours

TOTAL DEVELOPMENT: ~100 hours (2.5 weeks for one developer)

Plus:

Testing: 2-3 months on testnets
Security Audit: 4-8 weeks
Bug Bounty: 4 weeks

Full Production Timeline: 4-5 months

Security Considerations

Critical Vulnerabilities to Prevent

1. Reentrancy Attacks:

// Use OpenZeppelin ReentrancyGuard
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";

contract OASISBridge is ReentrancyGuard {
    function lockTokens(...) external nonReentrant {
        // Safe from reentrancy
    }
}

2. Access Control:

// Only oracle can mint
modifier onlyOracle() {
    require(authorizedOracles[msg.sender], "Not authorized");
    _;
}

function mintTokens(...) external onlyOracle {
    // Only authorized oracle can call
}

3. Double-Spend Prevention:

// Use nonces to prevent replay
mapping(address => uint256) public nonces;

function lockTokens(...) external {
    require(nonce > nonces[msg.sender], "Nonce too old");
    nonces[msg.sender] = nonce;
    // Process lock
}

4. Emergency Controls:

// Pausable in emergency
import "@openzeppelin/contracts/security/Pausable.sol";

contract OASISBridge is Pausable {
    function pause() external onlyOwner {
        _pause();
    }
}

Audit Requirements

Before Mainnet:

Code review by 2+ senior developers
External security audit (Trail of Bits, OpenZeppelin, or Certik)
Formal verification of critical functions
Economic security analysis
Testnet operation for 90+ days
Bug bounty program ($50K minimum)

Configuration Files

OASIS_DNA.json Updates Needed

Add bridge-specific configuration:

{
  "Bridge": {
    "OracleEnabled": true,
    "OraclePrivateKey": "MOVE_TO_ENV_VAR",
    "MinimumConfirmations": {
      "Ethereum": 15,
      "Solana": 32,
      "Polygon": 128,
      "Arbitrum": 1
    },
    "SupportedPairs": [
      { "from": "SOL", "to": "ETH" },
      { "from": "ETH", "to": "SOL" },
      { "from": "ETH", "to": "MATIC" }
    ],
    "ContractAddresses": {
      "Ethereum": "0x...",
      "Solana": "...",
      "Polygon": "0x...",
      "Arbitrum": "0x..."
    }
  }
}

appsettings.json Updates

{
  "BridgeOptions": {
    "EnableOracle": true,
    "OracleCheckIntervalSeconds": 30,
    "MaxPendingOrders": 1000,
    "OrderTimeoutMinutes": 60
  },
  "ConnectionStrings": {
    "BridgeDatabase": "Host=localhost;Database=oasis_bridge;Username=postgres;Password=..."
  }
}

Resources

Documentation

Bridge Specifications: /UniversalAssetBridge/contracts/bridge-specifications.json
Build Guide: /UniversalAssetBridge/contracts/BUILD_BRIDGE_CONTRACTS.md
Bridge Architecture: /UniversalAssetBridge/BRIDGE_ARCHITECTURE_EXPLAINED.md (needs updating)
Provider Architecture: /OASIS_PROVIDER_ARCHITECTURE_GUIDE.md

Code References

Existing BridgeController: /ONODE/.../Controllers/BridgeController.cs
Existing BridgeService: /ONODE/.../Services/BridgeService.cs
Solana Bridge: /NextGenSoftware.OASIS.API.Providers.SOLANAOASIS/SolanaBridgeService.cs

External References

OpenZeppelin Contracts: https://docs.openzeppelin.com/contracts/
Anchor Framework: https://www.anchor-lang.com/
Scrypto Documentation: https://docs.radixdlt.com/docs/scrypto

Questions for Clarification

Before starting implementation, clarify:

Database Choice: MongoDB, PostgreSQL, or both?
Oracle Architecture: Centralized first or multi-sig from start?
Chain Priority: Which chains to implement first? (Recommend: Ethereum, Polygon, Arbitrum)
Security Level: Testnet only or prepare for mainnet audit?
Budget: Is there budget for security audit ($50K-$200K)?
Timeline: Hard deadline or flexible?

Next Steps

Immediate (Today):

Review this document
Clarify questions above
Start SmartContractGenerator API
Generate first bridge contract (Ethereum)

This Week: 5. Deploy contracts to testnets 6. Implement CrossChainBridgeManager 7. Test basic swap (SOL → ETH)

This Month: 8. Implement oracle service 9. Add all EVM chains 10. Database integration 11. End-to-end testing

Production (4-5 months): 12. Security audit 13. Bug bounty 14. Mainnet deployment

Contact & Handoff

Current Work By: Max + AI Assistant Handoff To: Next developer/agent Contact: @maxgershfield on Telegram Repository: https://github.com/NextGenSoftwareUK/OASIS (max-build2 branch)

This document contains everything needed to complete the Universal Asset Bridge implementation.

Document Version: 1.0 Last Updated: November 6, 2025 Status: Ready for handoff

PreviousBridge Architecture NextBridge Quick Start

Last updated 12 days ago

Good evening

Current Status

✅ What's Already Built

Architecture Overview

How It Should Work

Key Components Needed

File Locations

Existing Code

Contracts to Create

Implementation Tasks

Phase 1: Generate Smart Contracts (4-6 hours)

Phase 2: Implement CrossChainBridgeManager (8-12 hours)

Phase 3: Build Oracle Service (12-16 hours)

Phase 4: Database Integration (4-6 hours)

Phase 5: Multi-Chain Provider Implementation (6-8 hours per chain)

Phase 6: HyperDrive Integration (8-12 hours)

Technical Decisions Needed

Decision 1: Database Choice

Decision 2: Oracle Architecture

Decision 3: Bridge Contract Security

Known Issues & Gotchas

Issue 1: Radix Integration Not Complete

Issue 2: No Transaction Persistence

Issue 3: Exchange Rate Service

Issue 4: No Automatic Order Completion

Testing Checklist

Unit Tests Needed

Integration Tests Needed

Security Tests Needed

Dependencies & Prerequisites

Software Required

External Services

Success Criteria

Minimum Viable Bridge (MVP)

Production Ready

Estimated Timeline

Security Considerations

Critical Vulnerabilities to Prevent

Audit Requirements

Configuration Files

OASIS_DNA.json Updates Needed

appsettings.json Updates

Resources

Documentation

Code References

External References

Questions for Clarification

Next Steps

Contact & Handoff