Support BTC refund flow

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

@@ -426,6 +426,72 @@ impl Contract {
     }
 }
 
+#[cfg(not(feature = "zcash"))]
+#[near]
+impl Contract {
+    // ── Refund API (Bitcoin only) ──
+
+    #[pause(except(roles(Role::DAO)))]
+    pub fn request_refund(
+        &mut self,
+        deposit_msg: DepositMsg,
+        tx_bytes: Vec<u8>,
+        vout: usize,
+        tx_block_blockhash: String,
+        tx_index: u64,
+        merkle_proof: Vec<String>,
+    ) -> Promise {
+        self.internal_request_refund(
+            deposit_msg,
+            tx_bytes,
+            vout,
+            tx_block_blockhash,
+            tx_index,
+            merkle_proof,
+        )
+    }
+
+    #[payable]
+    #[access_control_any(roles(Role::DAO, Role::Operator))]
+    pub fn reject_refund(&mut self, utxo_storage_key: String) {
+        assert_one_yocto();
+        self.internal_reject_refund(utxo_storage_key);
+    }
+
+    #[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);
+    }
+
+    #[pause(except(roles(Role::DAO)))]
+    pub fn verify_refund(
+        &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(
+            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,11 @@ impl Contract {
         );
         self.internal_mut_config().unhealthy_utxo_amount = unhealthy_utxo_amount.0;
     }
+
+    #[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/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.1 NEAR as a safe margin.
+        NearToken::from_millinear(100)
+    }
 }

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,11 +409,12 @@ 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()
-            .collect::<Vec<u8>>(),
+            .collect::<Vec<u8>>()
+            .as_slice(),
     );
     hex::encode(hash_bytes)
 }
@@ -457,6 +474,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.
+    #[serde(default)]
+    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,20 @@ pub enum Event<'a> {
         index: Option<usize>,
         err_msg: String,
     },
+    RefundRequested {
+        deposit_msg: DepositMsg,
+        utxo_storage_key: String,
+        amount: U128,
+        refund_address: String,
+    },
+    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,7 @@ impl From<ConfigV0> for Config {
             unhealthy_utxo_amount: 1000,
             #[cfg(feature = "zcash")]
             expiry_height_gap: 1000,
+            refund_timelock_sec: 0,
         }
     }
 }
@@ -330,6 +333,7 @@ impl From<ConfigV1> for Config {
             unhealthy_utxo_amount,
             #[cfg(feature = "zcash")]
             expiry_height_gap,
+            refund_timelock_sec: 0,
         }
     }
 }
@@ -393,6 +397,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 +473,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,