​

Bridge Architecture

​

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         SOLANA                                   │
│                                                                  │
│   xyz-bridge program (Anchor 0.30.1)                            │
│   ├── BridgePool (admin, relayer, vault, totals)                │
│   ├── UserAccount (owner, xyz_chain_address, tracking)          │
│   └── Pool vault (holds all deposited XYZ)                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         RELAYER                                  │
│                                                                  │
│   PoolMonitor ─────────► EventProcessor ─────────► XyzExecutor  │
│   (WebSocket + polling)                           (Mint)        │
│                                                                  │
│   BurnMonitor ─────────► EventProcessor ─────────► PoolExecutor │
│   (XYZ Chain blocks)                              (Withdraw)    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         XYZ CHAIN                                │
│                                                                  │
│   x/bridge module                                                │
│   ├── MsgMintFromBridge (relayer-controlled)                    │
│   └── MsgBurnForBridgeOut (user-initiated)                      │
│                                                                  │
│   Governance parameters:                                         │
│   ├── max_burn_per_tx: 1,000,000 XYZ                           │
│   └── max_burns_per_block: 10                                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

​

Solana Bridge Program

​

Key Accounts

​

Instructions

​

Address Validation

• XYZ Chain addresses must start with xyz1 and be 39+ characters
• Solana addresses must be valid Base58 (32 bytes)

​

XYZ Chain Bridge Module

​

Messages

​

Burn Event Format

burn_id:        burn-{block_height}-{tx_index}
sender:         xyz1...  (the burner's address)
amount:         1000000  (in uxyz)
solana_address: Base58 Solana address

​

Relayer Components

​

PoolMonitor (Solana Deposits)

• Primary: WebSocket subscription to program logs with finalized commitment
• Backup: Polls last 10 signatures for resilience
• Parses DepositEvent from transaction logs
• Waits for 32-slot finality before forwarding to the EventProcessor

​

BurnMonitor (XYZ Chain Withdrawals)

• Polls XYZ Chain blocks for burn_for_bridge_out events
• Extracts burn_id, sender, amount, and Solana address from event attributes
• Uses burn_id as deduplication key (not transaction hash)

​

XyzExecutor

• Signs and broadcasts MsgMintFromBridge on XYZ Chain
• Uses the authorized relayer address
• Exponential backoff retry on transient failures

​

PoolExecutor

• Executes withdraw instruction on the Solana bridge program
• Derives PDAs: bridge_pool, user_account, pool_vault
• Creates or resolves the recipient’s Associated Token Account (ATA)
• No auto-retry on failures — alerts for manual intervention

​

EventProcessor

• Routes events to the appropriate executor
• Validates event data before processing
• Database-first recording (creates record before queueing action)

​

Security Features

​

Solana Side

• Admin controls — Pause, upgrade, and emergency withdraw capabilities
• Relayer authorization — Only the authorized relayer can execute withdrawals
• Minimum deposit — Prevents dust attacks (default: 1 XYZ)
• Event emission — Full audit trail via DepositEvent and WithdrawEvent

​

XYZ Chain Side

• Rate limiting — max_burn_per_tx and max_burns_per_block parameters
• User-initiated burns — Users sign their own burns; the relayer cannot move funds
• Burn ID tracking — Unique burn-{height}-{tx_index} format prevents duplicates
• Governance control — Rate limits are adjustable via governance proposals

​

Relayer

• Finality wait — 32-slot confirmation before processing deposits
• Deduplication — Database checks prevent double-processing
• No auto-retry on withdrawals — Failed withdrawals require manual review
• Database-first — Records are persisted before actions are queued

​

Failure Handling

​

Failed Withdrawals

1. PoolExecutor logs the error with burn_id and failure reason
2. Database record is marked as failed
3. No auto-retry — manual intervention required
4. Admin investigates and manually re-executes if needed

​

Relayer Downtime

• Deposits: PoolMonitor resumes from the last processed Solana signature
• Burns: BurnMonitor resumes from the last processed block height
• No transactions are lost (database tracks processing state)

​

Next Steps