Architecture and Flows

Real Bridge is infrastructure for seamless cross‑chain transfers, unlocking liquidity by connecting tokenized real-world assets on Real to other major blockchains.

High‑Level Architecture

flowchart LR
  subgraph REAL[REAL L2 App-Chain]
    A[Asset Token (ERC-20/721/1155)]
    B[Bridge Gateway Contract]
    C[Compliance Hook(s)]
    D[Escrow Vault]
  end

  subgraph Transport[Cross-Chain Transport Layer]
    E[Event Oracle Set / Light Client]
    F[Relayer Network]
    G[Message Bus]
  end

  subgraph DEST[Destination Chain (ETH, Polygon, BNB, Solana*, etc.)]
    H[Bridge Router]
    I[Wrapped Asset (wRWA)]
    J[Compliance Hook(s)]
  end

  A --> B --> C --> D
  D -- lock event --> E
  E --> F --> G --> H
  H --> J --> I

  classDef chain fill:#f6f7ff,stroke:#aab,stroke-width:1px;
  class REAL,DEST chain;

Key roles

  • Bridge Gateway Contract (REAL): Entry point for deposit (lock) requests; holds assets in Escrow Vault.

  • Oracle/Light Client: Verifies source-chain finality (proof-of-state or committee signatures).

  • Relayers: Submit verified messages to destination routers; stateless, permissionless where possible.

  • Bridge Router (Destination): Mints/burns Wrapped Assets (wRWA) and executes post-transfer logic.

  • Compliance Hooks: Pluggable policy modules (KYC/AML lists, geo rules, transfer ceilings, freeze).

Core Flows

A. REAL → Destination (Lock and Mint)

sequenceDiagram
  autonumber
  actor User
  participant Asset as Asset Token (REAL)
  participant GW as Bridge Gateway (REAL)
  participant Vault as Escrow Vault (REAL)
  participant Oracles as Oracle/Light Client
  participant Relayer
  participant Router as Bridge Router (Dest)
  participant Wrapped as Wrapped Asset (Dest)
  participant Hook as Compliance Hooks (Dest)

  User->>GW: deposit(asset, amount, destChain, recipient, data)
  GW->>Hook: preDepositCheck(User, asset, amount)
  Hook-->>GW: ok
  GW->>Vault: lock(asset, amount)
  GW->>Oracles: emit DepositLocked(event)
  Oracles-->>Relayer: attest(eventProof)
  Relayer->>Router: submit(eventProof, message)
  Router->>Hook: preMintCheck(recipient, asset, amount)
  Hook-->>Router: ok
  Router->>Wrapped: mint(recipient, amount)
  Router-->>User: Transfer Completed (wRWA)

B. Destination → REAL (Burn and Release)

sequenceDiagram
  autonumber
  actor User
  participant Wrapped as Wrapped Asset (Dest)
  participant Router as Bridge Router (Dest)
  participant Oracles as Oracle/Light Client
  participant Relayer
  participant GW as Bridge Gateway (REAL)
  participant Vault as Escrow Vault (REAL)
  participant Hook as Compliance Hooks (REAL)

  User->>Router: redeem(wRWA, amount, REAL, recipient)
  Router->>Wrapped: burn(amount)
  Router->>Oracles: emit RedemptionBurned(event)
  Oracles-->>Relayer: attest(eventProof)
  Relayer->>GW: submit(eventProof, message)
  GW->>Hook: preReleaseCheck(recipient, asset, amount)
  Hook-->>GW: ok
  GW->>Vault: release(asset, amount, recipient)
  GW-->>User: Transfer Completed (native RWA)

Contracts and Interfaces (example)

Example interfaces; names/spaces are illustrative. Final ABIs may differ.

interface IRealBridgeGateway {
  event DepositLocked(address indexed asset, address indexed from, bytes32 destChain, bytes to, uint256 amount, bytes data);
  event Released(address indexed asset, address indexed to, uint256 amount, bytes32 srcChain, bytes32 depositId);

  function deposit(
    address asset,
    uint256 amount,
    bytes32 destChain,
    bytes calldata recipient,
    bytes calldata data
  ) external payable; // supports gas abstraction

  function submitRelease(
    bytes calldata proof, // oracle/light-client proof
    bytes calldata message
  ) external;
}

interface IRealBridgeRouter {
  event Minted(address indexed wrapped, address indexed to, uint256 amount, bytes32 srcChain, bytes32 depositId);
  event Redeemed(address indexed wrapped, address indexed from, uint256 amount, bytes32 destChain, bytes recipient);

  function submitMint(bytes calldata proof, bytes calldata message) external;
  function redeem(address wrapped, uint256 amount, bytes32 destChain, bytes calldata recipient) external;
}

Message format (TLV suggestion)

| version | srcChain | srcTxHash | asset | amount | from | to | nonce | memo |

Compliance Hooks (Policy Layer)

Hooks execute on both chains and can be composed:

  • KYC/Allowlist/Blocklist (on user or wallet level)

  • Geofencing (per jurisdiction)

  • Transfer ceilings (daily/notional caps; per‑asset, per‑user)

  • Asset state controls (freeze/thaw, pause)

  • Issuer‑programmable constraints (e.g., only Qualified Purchasers, lockups)

Hook interface (minimal):

interface IComplianceHook {
  function preDepositCheck(address user, address asset, uint256 amount, bytes calldata ctx) external view returns (bool);
  function preMintCheck(bytes calldata recipient, address asset, uint256 amount, bytes calldata ctx) external view returns (bool);
  function preReleaseCheck(address recipient, address asset, uint256 amount, bytes calldata ctx) external view returns (bool);
}

Security Model

  • Finality: Light client or multi‑sig threshold attestation (≥2/3 of oracle set) before mint/release.

  • Escrow Isolation: On REAL, assets are held in a minimal‑surface Escrow Vault with no external call paths except Gateway.

  • Upgradability: Router/Gateway behind time-locked proxies; emergency pause with 2‑of‑N admin and on‑chain notice period.

  • Rate Limiting: Per‑asset daily outflow caps; circuit breaker triggers on volatility or oracle liveness loss.

  • Replay Protection: Nonce + srcTxHash binding; consumed once.

  • Audit and Monitoring: Pre‑launch audits; continuous on‑chain monitors for drift, stuck messages, anomalous flows.

Fees and Gas Abstraction

  • Bridge Fee: Basis points fee configurable per asset/direction (e.g., 5–20 bps), displayed pre‑tx.

  • Oracle Fee: Destination‑side relayer/oracle gas reimbursement via meta‑tx; optional stablecoin fee vault.

  • Gas Abstraction: Users may pay fees in the source asset; Gateway aggregates and sponsors destination gas via relayers.

Failure, Recovery, and Dispute

  • Stuck Message (no mint/release): The user can request a retry via any relayer after the challenge window or a refund path, if permitted by policy.

  • Oracle Liveness Failure: Bridge pauses new deposits; redemptions continue from the wrapped side if proofs are available.

  • Emergency Unwind: Governance may trigger a controlled unwind to return escrowed assets on REAL after a time-locked vote has been completed.

  • Dispute Window: Short challenge period (e.g., 15–30 min) before finalization on the destination chain for high‑value flows.

Asset Models

  • Fungible (ERC‑20): 1:1 wrapped supply with transparent custody proofs.

  • NFT (ERC‑721/1155): TokenId‑preserving wrap; metadata hash carried in message to protect against mismatched content.

  • Permissioned RWAs: Transfer restricted by hooks; wrapping enforces the same policies across chains.

Developer Integration

On REAL (deposit):

IERC20(ASSET).approve(GATEWAY, amount);
IRealBridgeGateway(GATEWAY).deposit(ASSET, amount, DEST_CHAIN, abi.encodePacked(recipient), "");

On Destination (redeem):

IERC20(WRAPPED).approve(ROUTER, amount);
IRealBridgeRouter(ROUTER).redeem(WRAPPED, amount, REAL_CHAIN, abi.encodePacked(recipient));

Events to watch

  • DepositLocked, Minted, Redeemed, Released

Operational Runbook (SRE)

  • Health Checks: Oracle signer quorum, message backlog, per‑asset caps utilization, chain finality lag.

  • Alerts: >X pending messages, >Y minutes finality delay, cap breach attempt, hook failures.

  • Dashboards: TVL in Vault, outstanding wRWA supply per chain, fee accruals, and liveness metrics.

Configuration and Parameters

Parameter

Default

Notes

Finality confirmations (ETH L2→L1 eqv.)

20–120 blocks

Chain‑specific tuning

Dispute window

20 minutes

High‑value lanes longer

Bridge fee

10 bps

Per asset/direction

Daily cap per asset

2% of TVL

Circuit breaker engages at 1.5%

Admin timelock

48 hours

Upgrades and pauses

Glossary

  • Gateway/Router: Source/destination bridge contracts.

  • wRWA: Wrapped representation of a REAL‑native asset on another chain.

  • Hook: Policy module executed on bridge actions.

  • Light Client: On‑chain verifier of another chain’s headers/finality.

Appendix: Example Message (JSON)

{
  "v": 1,
  "srcChain": "REAL",
  "srcTxHash": "0x…",
  "asset": "0xAssetOnREAL",
  "amount": "1000000000000000000",
  "from": "0xUser",
  "to": "0xRecipientOnDest",
  "nonce": 123456,
  "memo": "RWA-Deposit-INV-2025-08-29"
}
PreviousReal BridgeNextReal Market

Last updated