feat(bridge): add Axelar cross-chain bridge stubs and design doc

Makefile

@@ -0,0 +1,10 @@
+.PHONY: sandbox sandbox-stop sandbox-logs
+
+sandbox:
+	@bash scripts/sandbox.sh
+
+sandbox-stop:
+	@docker stop skillsphere-sandbox 2>/dev/null || true
+
+sandbox-logs:
+	@docker logs -f skillsphere-sandbox

contracts/src/bridge.rs

@@ -0,0 +1,208 @@
+//! # IBC Cross-Chain Bridge (Issue #217)
+//!
+//! Enables cross-chain USDC payments from Ethereum/Polygon via Axelar.
+//! Users can pay with USDC on EVM chains and receive equivalent tokens on Stellar.
+
+#![allow(unused_imports)]
+
+use soroban_sdk::{
+    contract, contractimpl, contracterror, contracttype, symbol_short, Address, Env, String, BytesN,
+};
+
+#[contracterror]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[repr(u32)]
+pub enum BridgeError {
+    Unauthorized = 1,
+    ReplayDetected = 2,
+    InvalidChain = 3,
+    InsufficientBalance = 4,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct BridgeMessage {
+    pub source_chain: String,
+    pub source_address: String,
+    pub token: Address,
+    pub amount: i128,
+    pub recipient: Address,
+    pub nonce: u128,
+}
+
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RefundRequest {
+    pub source_chain: String,
+    pub source_address: String,
+    pub token: Address,
+    pub amount: i128,
+    pub requested_at: u64,
+}
+
+#[contract]
+pub struct BridgeContract;
+
+#[contractimpl]
+impl BridgeContract {
+    /// Validates and processes an incoming bridge message from Axelar.
+    ///
+    /// # Arguments
+    /// * `env` — The Soroban environment
+    /// * `msg` — The bridge message containing payment details
+    ///
+    /// # Errors
+    /// * `BridgeError::Unauthorized` — If sender is not the authorized relayer
+    /// * `BridgeError::ReplayDetected` — If the nonce has already been used
+    /// * `BridgeError::InvalidChain` — If source chain is not supported
+    ///
+    /// # Events
+    /// * Emits `bridge_message_received` with (source_chain, recipient, token, amount, nonce)
+    pub fn receive_bridge_message(env: Env, msg: BridgeMessage) -> Result<(), BridgeError> {
+        // TODO: Validate sender is authorized Axelar relayer address
+        // let relayer = env
+        //     .storage()
+        //     .instance()
+        //     .get(&DataKey::BridgeRelayer)
+        //     .ok_or(BridgeError::Unauthorized)?;
+        // if env.invoker_contract() != relayer {
+        //     return Err(BridgeError::Unauthorized);
+        // }
+
+        // TODO: Check nonce for replay protection
+        // let nonce_key = DataKey::BridgeNonce(msg.source_chain.clone(), msg.source_address.clone(), msg.nonce);
+        // if env.storage().persistent().has(&nonce_key) {
+        //     return Err(BridgeError::ReplayDetected);
+        // }
+
+        // TODO: Validate source chain is whitelisted
+        // let supported_chains: Vec<String> = env.storage().instance().get(&DataKey::SupportedChains).unwrap_or(Vec::new(&env));
+        // if !supported_chains.contains(&msg.source_chain) {
+        //     return Err(BridgeError::InvalidChain);
+        // }
+
+        todo!()
+    }
+
+    /// Initiates an outbound bridge transfer to another chain.
+    ///
+    /// # Arguments
+    /// * `env` — The Soroban environment
+    /// * `destination_chain` — Target chain name (e.g., "Ethereum", "Polygon")
+    /// * `recipient` — Destination address on the target chain
+    /// * `amount` — Amount of tokens to bridge
+    ///
+    /// # Errors
+    /// * `BridgeError::Unauthorized` — If caller is not authorized
+    /// * `BridgeError::InsufficientBalance` — If contract lacks sufficient tokens
+    ///
+    /// # Events
+    /// * Emits `bridge_out_initiated` with (destination_chain, recipient, amount)
+    pub fn initiate_bridge_out(
+        env: Env,
+        destination_chain: String,
+        recipient: String,
+        amount: i128,
+    ) -> Result<(), BridgeError> {
+        // TODO: Validate caller is authorized (could be admin or any user with allowance)
+
+        // TODO: Lock/burn tokens held by the contract
+        // let token = env.current_contract_address(); // or separate token address
+        // let token_client = token::Client::new(&env, &token);
+        // if token_client.balance(&env.current_contract_address()) < amount {
+        //     return Err(BridgeError::InsufficientBalance);
+        // }
+
+        // TODO: Call Axelar gateway to initiate cross-chain transfer
+
+        todo!()
+    }
+
+    /// Requests a refund for a failed bridge message.
+    ///
+    /// # Arguments
+    /// * `env` — The Soroban environment
+    /// * `source_chain` — The original source chain
+    /// * `source_address` — The original sender address
+    /// * `nonce` — The nonce from the original bridge message
+    ///
+    /// # Errors
+    /// * `BridgeError::InvalidChain` — If refund request is invalid
+    ///
+    /// # Events
+    /// * Emits `bridge_refund` with (source_chain, source_address, nonce, amount)
+    pub fn request_refund(
+        env: Env,
+        source_chain: String,
+        source_address: String,
+        nonce: u128,
+    ) -> Result<i128, BridgeError> {
+        todo!()
+    }
+
+    /// Sets the authorized Axelar relayer address (admin only).
+    ///
+    /// # Arguments
+    /// * `env` — The Soroban environment
+    /// * `relayer` — The new relayer address
+    ///
+    /// # Events
+    /// * Emits `relayer_updated` with the new relayer address
+    pub fn set_relayer(env: Env, relayer: Address) -> Result<(), BridgeError> {
+        todo!()
+    }
+
+    /// Gets the current authorized relayer address.
+    pub fn get_relayer(env: Env) -> Option<Address> {
+        todo!()
+    }
+
+    /// Checks if an incoming bridge message has already been processed.
+    pub fn is_nonce_used(env: Env, source_chain: String, source_address: String, nonce: u128) -> bool {
+        todo!()
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use soroban_sdk::testutils::Address as _;
+    use soroban_sdk::{Address, Env, String};
+
+    #[test]
+    fn test_bridge_message_structure() {
+        let env = Env::default();
+        let msg = BridgeMessage {
+            source_chain: String::from_str(&env, "Ethereum"),
+            source_address: String::from_str(&env, "0x1234...abcd"),
+            token: Address::generate(&env),
+            amount: 1000,
+            recipient: Address::generate(&env),
+            nonce: 1,
+        };
+        assert_eq!(msg.amount, 1000);
+        assert_eq!(msg.nonce, 1);
+    }
+
+    #[test]
+    fn test_refund_request_structure() {
+        let env = Env::default();
+        let req = RefundRequest {
+            source_chain: String::from_str(&env, "Ethereum"),
+            source_address: String::from_str(&env, "0x1234...abcd"),
+            token: Address::generate(&env),
+            amount: 1000,
+            requested_at: 12345,
+        };
+        assert_eq!(req.amount, 1000);
+        assert_eq!(req.requested_at, 12345);
+    }
+
+    #[test]
+    fn test_bridge_error_values() {
+        assert_eq!(BridgeError::Unauthorized as u32, 1);
+        assert_eq!(BridgeError::ReplayDetected as u32, 2);
+        assert_eq!(BridgeError::InvalidChain as u32, 3);
+        assert_eq!(BridgeError::InsufficientBalance as u32, 4);
+    }
+}