Skip to content

README.md

Latest commit

 

History

History
338 lines (271 loc) · 9.99 KB

README.md

File metadata and controls

338 lines (271 loc) · 9.99 KB
Raw

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
)
  1. Other validators verify:
verify_transaction(tx_nonce: u64)
  1. 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,
)
  1. Other validators verify:
verify_transaction(tx_nonce: u64)
  1. 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.