Taskmaster Bridge

A production-ready Solana smart contract for bridging assets between Solana and multiple EVM chains (Ethereum, Arbitrum, and BSC).

Features

Core Bridge Operations

• Lock Tokens: Lock native SPL tokens on Solana to bridge to external chains
• Unlock Tokens: Release previously locked tokens when bridging back from external chains
• Mint Wrapped Tokens: Create wrapped SPL tokens representing assets from external chains
• Burn Wrapped Tokens: Burn wrapped tokens to release assets on the origin chain

Security & Governance

• Multi-signature Validation: Configurable validator set with threshold signatures (default: 3-of-5)
• Multi-signature Admin: Admin operations require multiple signatures for enhanced security
• Replay Protection: Nonce-based transaction tracking prevents double-spending
• Emergency Pause: Circuit breaker mechanism for emergency situations
• Token Whitelisting: Only approved token pairs can be bridged

Administrative Functions

• Add/remove validators and admins dynamically
• Update validator and admin thresholds
• Configure bridge fees (percentage-based with minimum fee)
• Enable/disable specific token pairs
• Update fee collector address

Architecture

Program Structure

programs/taskmaster-bridge/src/
├── lib.rs                          # Main program entry point
├── constants.rs                    # Program constants and configuration
├── errors.rs                       # Custom error definitions
├── state/                          # Account structures
│   ├── bridge.rs                   # Main bridge configuration
│   ├── validator.rs                # Validator set management
│   ├── admin.rs                    # Admin set management
│   ├── token_pair.rs               # Token pair mappings
│   └── bridge_transaction.rs       # Transaction records
└── instructions/                   # Instruction handlers
    ├── initialize.rs               # Bridge initialization
    ├── lock_tokens.rs              # Lock native tokens
    ├── unlock_tokens.rs            # Unlock native tokens
    ├── mint_wrapped.rs             # Mint wrapped tokens
    ├── burn_wrapped.rs             # Burn wrapped tokens
    ├── verify_transaction.rs       # Multi-sig verification
    ├── pause.rs                    # Emergency pause/unpause
    ├── update_validators.rs        # Validator management
    ├── register_token_pair.rs      # Token pair registration
    └── update_fee.rs               # Fee management

Supported Chains

• Solana (Chain ID: 0)
• Ethereum (Chain ID: 1)
• BSC (Chain ID: 56)
• Arbitrum (Chain ID: 42161)

Configuration

Default Parameters

• Validator Threshold: 3 out of 5 validators required
• Admin Threshold: 3 out of 5 admins required
• Bridge Fee: 0.1% (10 basis points)
• Minimum Fee: 0.001 SOL (1,000,000 lamports)
• Maximum Fee: 5% (500 basis points)
• Max Validators: 10
• Max Admins: 10

Usage

1. Initialize Bridge

initialize(
    initial_validators: Vec<Pubkey>,     // List of validator public keys
    validator_threshold: u8,             // Number of signatures required (e.g., 3)
    initial_admins: Vec<Pubkey>,         // List of admin public keys
    admin_threshold: u8,                 // Number of admin signatures required (e.g., 3)
    fee_basis_points: u16,               // Fee in basis points (e.g., 10 = 0.1%)
)

2. Register Token Pairs

Native Token (Lock/Unlock)

register_native_token_pair(
    external_chain_id: u64,              // Target chain ID (1=Ethereum, 56=BSC, 42161=Arbitrum)
    external_token_address: String,      // Token address on external chain (e.g., "0x...")
)

Wrapped Token (Mint/Burn)

register_wrapped_token_pair(
    external_chain_id: u64,              // Source chain ID
    external_token_address: String,      // Token address on external chain
    decimals: u8,                        // Token decimals
)

3. Bridge Operations

Lock Native Tokens (Solana → External Chain)

lock_tokens(
    nonce: u64,                          // Current bridge nonce
    amount: u64,                         // Amount to lock (in token units)
    destination_chain_id: u64,           // Target chain ID
    recipient_address: String,           // Recipient address on external chain
)

Burn Wrapped Tokens (Solana → External Chain)

burn_wrapped(
    nonce: u64,                          // Current bridge nonce
    amount: u64,                         // Amount to burn
    destination_chain_id: u64,           // Target chain ID
    recipient_address: String,           // Recipient address on external chain
)

Unlock Native Tokens (External Chain → Solana)

1. Validator initiates unlock:

unlock_tokens(
    nonce: u64,                          // Current bridge nonce
    amount: u64,                         // Amount to unlock
    source_chain_id: u64,                // Source chain ID
    external_tx_hash: String,            // Transaction hash on external chain
    recipient: Pubkey,                   // Recipient on Solana
)

2. Other validators verify:

verify_transaction(tx_nonce: u64)

3. Execute once verified:

execute_unlock(tx_nonce: u64)

Mint Wrapped Tokens (External Chain → Solana)

1. Validator initiates mint:

mint_wrapped(
    nonce: u64,
    amount: u64,
    source_chain_id: u64,
    external_tx_hash: String,
    recipient: Pubkey,
)

2. Other validators verify:

verify_transaction(tx_nonce: u64)

3. Execute once verified:

execute_mint_wrapped(tx_nonce: u64)

4. Administrative Operations

Pause/Unpause Bridge

pause_bridge()      // Emergency stop
unpause_bridge()    // Resume operations

Manage Validators

add_validator(new_validator: Pubkey)
remove_validator(validator_to_remove: Pubkey)
update_validator_threshold(new_threshold: u8)

Manage Admins

add_admin(new_admin: Pubkey)
remove_admin(admin_to_remove: Pubkey)

Update Fees

update_fee(
    new_fee_basis_points: Option<u16>,
    new_min_fee_lamports: Option<u64>,
)
update_fee_collector(new_fee_collector: Pubkey)

Toggle Token Pair Status

toggle_token_pair()  // Enable/disable a specific token pair

Security Features

Multi-signature Verification

• All cross-chain transactions (unlock/mint) require validator signatures
• Threshold-based approval (default: 3 out of 5)
• Duplicate signature prevention

Replay Protection

• Unique nonce for each transaction
• Transaction history tracking
• State transition validation

Access Control

• Admin-only operations protected by multi-sig
• Validator-only transaction initiation
• PDA-based account ownership

Emergency Controls

• Bridge can be paused by any admin
• Paused state prevents all bridging operations
• Individual token pairs can be deactivated

Development

Build

anchor build

Test

anchor test

Deploy

# Deploy to devnet
anchor deploy --provider.cluster devnet

# Deploy to mainnet
anchor deploy --provider.cluster mainnet

Account Structure

Bridge (PDA)

• Seeds: ["bridge"]
• Stores: Configuration, fees, pause state, global nonce

ValidatorSet (PDA)

• Seeds: ["validator_set", bridge_pubkey]
• Stores: List of validators, threshold

AdminSet (PDA)

• Seeds: ["admin_set", bridge_pubkey]
• Stores: List of admins, threshold

TokenPair (PDA)

• Seeds: ["token_pair", bridge_pubkey, mint_pubkey, chain_id]
• Stores: Token mapping, activity status, totals

BridgeTransaction (PDA)

• Seeds: ["bridge_tx", bridge_pubkey, nonce]
• Stores: Transaction details, signatures, status

Vault (PDA)

• Seeds: ["vault", bridge_pubkey, mint_pubkey]
• Stores: Locked native tokens (SPL Token Account)

WrappedMint (PDA)

• Seeds: ["wrapped_mint", bridge_pubkey, external_address, chain_id]
• Stores: Wrapped token mint (controlled by bridge)

Transaction Flow

Outbound (Solana → External Chain)

1. User calls lock_tokens or burn_wrapped
2. Tokens are locked/burned, fee is collected
3. Transaction is recorded with status Executed
4. Relayers monitor and process on external chain

Inbound (External Chain → Solana)

1. Validator detects external chain transaction
2. Validator calls unlock_tokens or mint_wrapped (status: Pending)
3. Other validators call verify_transaction to add signatures
4. Once threshold is met, status changes to Verified
5. Anyone can call execute_unlock or execute_mint_wrapped
6. Tokens are released/minted, status changes to Executed

Fee Structure

Percentage Fee

• Calculated as: (amount * fee_basis_points) / 10000
• Default: 0.1% (10 basis points)
• Configurable by admins

Minimum Fee

• Ensures minimum fee is collected even on small transactions
• Default: 0.001 SOL (1,000,000 lamports)

Fee Collection

• Fees collected in the same token being bridged
• Sent to designated fee collector account

Error Codes

See src/errors.rs for complete list of error codes:

• BridgePaused: Bridge operations are paused
• Unauthorized: Caller lacks required permissions
• InvalidValidatorThreshold: Invalid threshold configuration
• InsufficientSignatures: Not enough validator signatures
• TokenPairNotRegistered: Token pair not whitelisted
• TransactionAlreadyProcessed: Replay attack detected
• And more...

License

This project is licensed under the terms specified in the LICENSE file.

Security Audit

⚠️ WARNING: This smart contract has not been audited. Use at your own risk. Always conduct a thorough security audit before deploying to mainnet with real assets.

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code follows Rust best practices
• Security considerations are documented

Support

For issues, questions, or contributions, please open an issue on the project repository.