Support BTC refund flow

contracts/satoshi-bridge/src/api/bridge.rs

@@ -426,6 +426,134 @@ impl Contract {
     }
 }
 
+#[cfg(not(feature = "zcash"))]
+#[near]
+impl Contract {
+    // ── Refund API (Bitcoin only) ──
+
+    /// Submit a refund request for a deposit that was never finalized via `verify_deposit` or `safe_verify_deposit`.
+    /// The BTC transaction is verified through the Light Client to prove the deposit exists.
+    /// After the timelock period, anyone can call `execute_refund` to initiate the return.
+    ///
+    /// # Arguments
+    ///
+    /// * `deposit_msg` - The original deposit message. If `deposit_msg.refund_address` is set,
+    ///   it must match the provided `refund_address`.
+    /// * `refund_address` - BTC address to send the refund to. If `deposit_msg.refund_address`
+    ///   is `None`, this value is used directly.
+    /// * `tx_bytes` - BTC transaction bytes proving the deposit.
+    /// * `vout` - Output index of the deposit in the transaction.
+    /// * `tx_block_blockhash` - Block hash containing the transaction.
+    /// * `tx_index` - Transaction index within the block.
+    /// * `merkle_proof` - Merkle proof for Light Client verification.
+    /// * `gas_fee` - Optional custom gas fee. Only DAO or Operator can set this.
+    ///   If `None`, the default `config.max_btc_gas_fee` is used during `execute_refund`.
+    #[allow(clippy::too_many_arguments)]
+    #[pause(except(roles(Role::DAO)))]
+    pub fn request_refund(
+        &mut self,
+        deposit_msg: DepositMsg,
+        refund_address: String,
+        tx_bytes: Vec<u8>,
+        vout: usize,
+        tx_block_blockhash: String,
+        tx_index: u64,
+        merkle_proof: Vec<String>,
+        gas_fee: Option<U128>,
+    ) -> Promise {
+        if gas_fee.is_some() {
+            let caller = env::predecessor_account_id();
+            require!(
+                self.acl_has_role(Role::DAO.into(), caller.clone())
+                    || self.acl_has_role(Role::Operator.into(), caller),
+                "Only DAO or Operator can specify custom gas_fee"
+            );
+        }
+        self.internal_request_refund(
+            deposit_msg,
+            refund_address,
+            tx_bytes,
+            vout,
+            tx_block_blockhash,
+            tx_index,
+            merkle_proof,
+            gas_fee.map(|v| v.0),
+        )
+    }
+
+    /// Reject a pending refund request.
+    /// - DAO or Operator can reject any request.
+    /// - Anyone can reject a request if the UTXO has already been verified via `verify_deposit`.
+    ///
+    /// # Arguments
+    ///
+    /// * `utxo_storage_key` - The UTXO key identifying the refund request (`{tx_id}@{vout}`).
+    pub fn reject_refund(&mut self, utxo_storage_key: String) {
+        let caller = env::predecessor_account_id();
+        let is_privileged = self.acl_has_role(Role::DAO.into(), caller.clone())
+            || self.acl_has_role(Role::Operator.into(), caller);
+        let is_already_deposited = self
+            .data()
+            .verified_deposit_utxo
+            .contains(&utxo_storage_key);
+        require!(
+            is_privileged || is_already_deposited,
+            "Only DAO/Operator can reject, or UTXO must be already verified via deposit"
+        );
+        self.internal_reject_refund(utxo_storage_key);
+    }
+
+    /// Execute a refund after the timelock has passed. Builds a BTC transaction
+    /// that sends the deposit UTXO back to the `refund_address` specified in the original
+    /// `DepositMsg`. Creates a `BTCPendingInfo` entry for the MPC sign pipeline.
+    /// Marks the UTXO in `verified_deposit_utxo` to prevent future `verify_deposit`.
+    ///
+    /// # Arguments
+    ///
+    /// * `utxo_storage_key` - The UTXO key identifying the refund request (`{tx_id}@{vout}`).
+    #[payable]
+    #[pause(except(roles(Role::DAO)))]
+    pub fn execute_refund(&mut self, utxo_storage_key: String) {
+        require!(
+            env::attached_deposit() >= self.required_balance_for_execute_refund(),
+            "Insufficient deposit for storage"
+        );
+        self.internal_execute_refund(utxo_storage_key);
+    }
+
+    /// Verify that the refund BTC transaction has been confirmed on the Bitcoin network.
+    /// Cleans up the `BTCPendingInfo` after successful verification.
+    ///
+    /// # Arguments
+    ///
+    /// * `tx_id` - Transaction ID of the confirmed refund transaction.
+    /// * `tx_block_blockhash` - Block hash containing the transaction.
+    /// * `tx_index` - Transaction index within the block.
+    /// * `merkle_proof` - Merkle proof for Light Client verification.
+    #[pause(except(roles(Role::DAO)))]
+    pub fn verify_refund_finalize(
+        &mut self,
+        tx_id: String,
+        tx_block_blockhash: String,
+        tx_index: u64,
+        merkle_proof: Vec<String>,
+    ) -> Promise {
+        let btc_pending_info = self.internal_unwrap_btc_pending_info(&tx_id);
+        btc_pending_info.assert_refund_pending_verify_tx();
+        require!(
+            btc_pending_info.tx_bytes_with_sign.is_some(),
+            "Missing tx_bytes_with_sign"
+        );
+        self.internal_verify_refund_finalize(
+            tx_id,
+            tx_block_blockhash,
+            tx_index,
+            merkle_proof,
+            btc_pending_info,
+        )
+    }
+}
+
 impl Contract {
     pub fn create_active_utxo_management_pending_info(
         &mut self,

contracts/satoshi-bridge/src/api/management.rs

@@ -459,4 +459,12 @@ impl Contract {
         );
         self.internal_mut_config().unhealthy_utxo_amount = unhealthy_utxo_amount.0;
     }
+
+    #[cfg(not(feature = "zcash"))]
+    #[payable]
+    #[access_control_any(roles(Role::DAO))]
+    pub fn set_refund_timelock_sec(&mut self, refund_timelock_sec: u64) {
+        assert_one_yocto();
+        self.internal_mut_config().refund_timelock_sec = refund_timelock_sec;
+    }
 }

contracts/satoshi-bridge/src/api/mod.rs

@@ -1,3 +1,4 @@
+#[allow(clippy::too_many_arguments)]
 mod bridge;
 mod chain_signatures;
 mod management;

contracts/satoshi-bridge/src/api/view.rs

@@ -284,4 +284,11 @@ impl Contract {
     pub fn required_balance_for_safe_deposit(&self) -> NearToken {
         REQUIRED_BALANCE_FOR_DEPOSIT
     }
+
+    #[cfg(not(feature = "zcash"))]
+    pub fn required_balance_for_execute_refund(&self) -> NearToken {
+        // execute_refund uses ~700 bytes of storage (BTCPendingInfo + Account + verified_deposit_utxo)
+        // At 0.00001 NEAR/byte, that's ~0.007 NEAR. We use 0.01 NEAR as a safe margin.
+        NearToken::from_millinear(10)
+    }
 }

contracts/satoshi-bridge/src/btc_pending_info.rs

@@ -73,6 +73,7 @@ pub enum PendingInfoState {
     ActiveUtxoManagementOriginal(OriginalState),
     ActiveUtxoManagementRbf(RbfState),
     ActiveUtxoManagementCancelRbf(RbfState),
+    Refund(OriginalState),
 }
 
 impl PendingInfoState {
@@ -84,6 +85,7 @@ impl PendingInfoState {
             PendingInfoState::ActiveUtxoManagementOriginal(state) => state.assert_pending_sign(),
             PendingInfoState::ActiveUtxoManagementRbf(state) => state.assert_pending_sign(),
             PendingInfoState::ActiveUtxoManagementCancelRbf(state) => state.assert_pending_sign(),
+            PendingInfoState::Refund(state) => state.assert_pending_sign(),
         }
     }
     pub fn assert_pending_verify(&self) {
@@ -94,6 +96,7 @@ impl PendingInfoState {
             PendingInfoState::ActiveUtxoManagementOriginal(state) => state.assert_pending_verify(),
             PendingInfoState::ActiveUtxoManagementRbf(state) => state.assert_pending_verify(),
             PendingInfoState::ActiveUtxoManagementCancelRbf(state) => state.assert_pending_verify(),
+            PendingInfoState::Refund(state) => state.assert_pending_verify(),
         }
     }
 }
@@ -157,6 +160,13 @@ impl BTCPendingInfo {
         }
     }
 
+    pub fn assert_refund_pending_verify_tx(&self) {
+        match self.state.borrow() {
+            PendingInfoState::Refund(state) => state.assert_pending_verify(),
+            _ => env::panic_str("Not refund related tx"),
+        }
+    }
+
     pub fn assert_active_utxo_management_related_pending_verify_tx(&self) {
         match self.state.borrow() {
             PendingInfoState::ActiveUtxoManagementOriginal(state) => state.assert_pending_verify(),
@@ -222,6 +232,9 @@ impl BTCPendingInfo {
             PendingInfoState::ActiveUtxoManagementCancelRbf(state) => {
                 state.stage = PendingInfoStage::PendingVerify;
             }
+            PendingInfoState::Refund(state) => {
+                state.stage = PendingInfoStage::PendingVerify;
+            }
         }
     }
 
@@ -243,6 +256,9 @@ impl BTCPendingInfo {
             PendingInfoState::ActiveUtxoManagementCancelRbf(state) => {
                 state.stage = PendingInfoStage::PendingBurn;
             }
+            PendingInfoState::Refund(state) => {
+                state.stage = PendingInfoStage::PendingBurn;
+            }
         }
     }
 
@@ -393,7 +409,7 @@ impl Contract {
 
 pub fn generate_btc_pending_sign_id(payload_preimages: &[Vec<u8>]) -> String {
     let hash_bytes = env::sha256_array(
-        &payload_preimages
+        payload_preimages
             .iter()
             .flatten()
             .copied()
@@ -457,6 +473,7 @@ mod tests {
             post_actions: None,
             extra_msg: None,
             safe_deposit: None,
+            refund_address: None,
         };
 
         let path = get_deposit_path(&deposit_msg);

contracts/satoshi-bridge/src/config.rs

@@ -110,6 +110,9 @@ pub struct Config {
     pub unhealthy_utxo_amount: u64,
     #[cfg(feature = "zcash")]
     pub expiry_height_gap: u32,
+    // Timelock in seconds before a refund request can be executed.
+    #[cfg(not(feature = "zcash"))]
+    pub refund_timelock_sec: u64,
 }
 
 impl Config {

contracts/satoshi-bridge/src/deposit_msg.rs

@@ -22,6 +22,9 @@ pub struct DepositMsg {
     // If this field is present, the legacy post_actions field must be None
     #[serde(skip_serializing_if = "Option::is_none")]
     pub safe_deposit: Option<SafeDepositMsg>,
+    // BTC address for refund if deposit is never finalized.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub refund_address: Option<String>,
 }
 
 #[near(serializers = [json])]

contracts/satoshi-bridge/src/event.rs

@@ -92,6 +92,21 @@ pub enum Event<'a> {
         index: Option<usize>,
         err_msg: String,
     },
+    RefundRequested {
+        deposit_msg: DepositMsg,
+        utxo_storage_key: String,
+        amount: U128,
+        refund_address: String,
+        gas_fee: U128,
+    },
+    RefundRejected {
+        utxo_storage_key: String,
+    },
+    RefundExecuted {
+        utxo_storage_key: String,
+        amount: U128,
+        refund_address: String,
+    },
 }
 
 impl Event<'_> {

contracts/satoshi-bridge/src/legacy.rs

@@ -60,6 +60,8 @@ impl From<ContractDataV0> for ContractData {
             acc_claimed_protocol_fee,
             cur_reserved_protocol_fee,
             acc_protocol_fee_for_gas,
+            #[cfg(not(feature = "zcash"))]
+            refund_requests: IterableMap::new(StorageKey::RefundRequests),
         }
     }
 }
@@ -190,6 +192,8 @@ impl From<ConfigV0> for Config {
             unhealthy_utxo_amount: 1000,
             #[cfg(feature = "zcash")]
             expiry_height_gap: 1000,
+            #[cfg(not(feature = "zcash"))]
+            refund_timelock_sec: 14 * 24 * 3600, // 2 weeks
         }
     }
 }
@@ -330,6 +334,8 @@ impl From<ConfigV1> for Config {
             unhealthy_utxo_amount,
             #[cfg(feature = "zcash")]
             expiry_height_gap,
+            #[cfg(not(feature = "zcash"))]
+            refund_timelock_sec: 14 * 24 * 3600, // 2 weeks
         }
     }
 }
@@ -393,6 +399,8 @@ impl From<ContractDataV1> for ContractData {
             acc_claimed_protocol_fee,
             cur_reserved_protocol_fee,
             acc_protocol_fee_for_gas,
+            #[cfg(not(feature = "zcash"))]
+            refund_requests: IterableMap::new(StorageKey::RefundRequests),
         }
     }
 }
@@ -467,6 +475,8 @@ impl From<ContractDataV2> for ContractData {
             acc_claimed_protocol_fee,
             cur_reserved_protocol_fee,
             acc_protocol_fee_for_gas,
+            #[cfg(not(feature = "zcash"))]
+            refund_requests: IterableMap::new(StorageKey::RefundRequests),
         }
     }
 }

contracts/satoshi-bridge/src/lib.rs

@@ -36,6 +36,8 @@ pub mod nbtc;
 pub mod network;
 pub mod psbt;
 pub mod rbf;
+#[cfg(not(feature = "zcash"))]
+pub mod refund;
 pub mod token_transfer;
 #[cfg(test)]
 mod unit;
@@ -54,6 +56,8 @@ pub use crate::json_utils::*;
 pub use crate::legacy::*;
 pub use crate::nbtc::*;
 pub use crate::rbf::*;
+#[cfg(not(feature = "zcash"))]
+pub use crate::refund::*;
 pub use crate::token_transfer::*;
 pub use crate::utils::*;
 pub use crate::utxo::*;
@@ -92,6 +96,8 @@ enum StorageKey {
     LostFound,
     PostActionMsgTemplates,
     ExtraMsgRelayerWhiteList,
+    #[cfg(not(feature = "zcash"))]
+    RefundRequests,
 }
 
 #[derive(AccessControlRole, Deserialize, Serialize, Copy, Clone)]
@@ -125,6 +131,8 @@ pub struct ContractData {
     pub acc_claimed_protocol_fee: u128,
     pub cur_reserved_protocol_fee: u128,
     pub acc_protocol_fee_for_gas: u128,
+    #[cfg(not(feature = "zcash"))]
+    pub refund_requests: IterableMap<String, VRefundRequest>,
 }
 
 #[near(serializers = [borsh])]
@@ -186,6 +194,8 @@ impl Contract {
                 ),
                 post_action_msg_templates: IterableMap::new(StorageKey::PostActionMsgTemplates),
                 lost_found: IterableMap::new(StorageKey::LostFound),
+                #[cfg(not(feature = "zcash"))]
+                refund_requests: IterableMap::new(StorageKey::RefundRequests),
                 acc_collected_protocol_fee: 0,
                 cur_available_protocol_fee: 0,
                 acc_claimed_protocol_fee: 0,