From 9fa09338e53d50c6cb873498143baa289d1d6d11 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:39:14 +0100 Subject: [PATCH 01/12] feat: Initialize btc-bridge-contract with constants and traits - Added `bridgeable-token-trait` defining transfer and get-balance functions. - Defined error codes for various bridge-related errors. - Set constants for contract deployer, deposit limits, and required confirmations. - Initialized data variables for bridge status, total bridged amount, and last processed height. --- Clarinet.toml | 22 ++++++++++++---------- contracts/btc-bridge.clar | 0 tests/btc-bridge_test.ts | 26 ++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 10 deletions(-) create mode 100644 contracts/btc-bridge.clar create mode 100644 tests/btc-bridge_test.ts diff --git a/Clarinet.toml b/Clarinet.toml index 4d223e1..e97c367 100644 --- a/Clarinet.toml +++ b/Clarinet.toml @@ -1,20 +1,22 @@ - [project] name = "btc-bridge" authors = [] +description = "" telemetry = true +requirements = [] +[contracts.btc-bridge] +path = "contracts/btc-bridge.clar" +depends_on = [] + +[repl] +costs_version = 2 +parser_version = 2 + [repl.analysis] passes = ["check_checker"] + [repl.analysis.check_checker] -# If true, inputs are trusted after tx_sender has been checked. +strict = false trusted_sender = false -# If true, inputs are trusted after contract-caller has been checked. trusted_caller = false -# If true, untrusted data may be passed into a private function without a -# warning, if it gets checked inside. This check will also propagate up to the -# caller. callee_filter = false - -# [contracts.counter] -# path = "contracts/counter.clar" -# depends_on = [] diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar new file mode 100644 index 0000000..e69de29 diff --git a/tests/btc-bridge_test.ts b/tests/btc-bridge_test.ts new file mode 100644 index 0000000..9a18ae0 --- /dev/null +++ b/tests/btc-bridge_test.ts @@ -0,0 +1,26 @@ + +import { Clarinet, Tx, Chain, Account, types } from 'https://deno.land/x/clarinet@v0.14.0/index.ts'; +import { assertEquals } from 'https://deno.land/std@0.90.0/testing/asserts.ts'; + +Clarinet.test({ + name: "Ensure that <...>", + async fn(chain: Chain, accounts: Map) { + let block = chain.mineBlock([ + /* + * Add transactions with: + * Tx.contractCall(...) + */ + ]); + assertEquals(block.receipts.length, 0); + assertEquals(block.height, 2); + + block = chain.mineBlock([ + /* + * Add transactions with: + * Tx.contractCall(...) + */ + ]); + assertEquals(block.receipts.length, 0); + assertEquals(block.height, 3); + }, +}); From 247701c866aac5862e5b4ebc492c1e09329c69a5 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:41:43 +0100 Subject: [PATCH 02/12] feat: Initialize btc-bridge-contract with constants and traits - Added `bridgeable-token-trait` defining transfer and get-balance functions. - Defined error codes for various bridge-related errors. - Set constants for contract deployer, deposit limits, and required confirmations. - Initialized data variables for bridge status, total bridged amount, and last processed height. --- contracts/btc-bridge.clar | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index e69de29..eb6ca9f 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -0,0 +1,29 @@ +;; title: btc-bridge-contract +;; summary: Enables secure cross-chain transfers between Bitcoin and Stacks networks +;; description: Facilitates secure asset transfers between Bitcoin and Stacks blockchains, +;; handling deposits, withdrawals, and validator management with robust security checks. + + +;; traits +(define-trait bridgeable-token-trait + ( + (transfer (uint principal principal) (response bool uint)) + (get-balance (principal) (response uint uint)) + ) +) + + +;; constants +;; Error codes +(define-constant ERROR-NOT-AUTHORIZED u1000) +(define-constant ERROR-INVALID-AMOUNT u1001) +(define-constant ERROR-INSUFFICIENT-BALANCE u1002) +(define-constant ERROR-INVALID-BRIDGE-STATUS u1003) +(define-constant ERROR-INVALID-SIGNATURE u1004) +(define-constant ERROR-ALREADY-PROCESSED u1005) +(define-constant ERROR-BRIDGE-PAUSED u1006) +(define-constant ERROR-INVALID-VALIDATOR-ADDRESS u1007) +(define-constant ERROR-INVALID-RECIPIENT-ADDRESS u1008) +(define-constant ERROR-INVALID-BTC-ADDRESS u1009) +(define-constant ERROR-INVALID-TX-HASH u1010) +(define-constant ERROR-INVALID-SIGNATURE-FORMAT u1011) \ No newline at end of file From 097337dc49cf13279b0727f5671165635134e3ff Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:42:23 +0100 Subject: [PATCH 03/12] feat: Define constants, data variables, and maps for btc-bridge-contract - Set constants for contract deployer, deposit limits, and required confirmations. - Initialized data variables for bridge status, total bridged amount, and last processed height. - Defined data maps for deposits, validators, validator signatures, and bridge balances. --- contracts/btc-bridge.clar | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index eb6ca9f..41ac8fe 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -26,4 +26,36 @@ (define-constant ERROR-INVALID-RECIPIENT-ADDRESS u1008) (define-constant ERROR-INVALID-BTC-ADDRESS u1009) (define-constant ERROR-INVALID-TX-HASH u1010) -(define-constant ERROR-INVALID-SIGNATURE-FORMAT u1011) \ No newline at end of file +(define-constant ERROR-INVALID-SIGNATURE-FORMAT u1011) + +;; Constants +(define-constant CONTRACT-DEPLOYER tx-sender) +(define-constant MIN-DEPOSIT-AMOUNT u100000) +(define-constant MAX-DEPOSIT-AMOUNT u1000000000) +(define-constant REQUIRED-CONFIRMATIONS u6) + +;; data vars +(define-data-var bridge-paused bool false) +(define-data-var total-bridged-amount uint u0) +(define-data-var last-processed-height uint u0) + +;; data maps +(define-map deposits + { tx-hash: (buff 32) } + { + amount: uint, + recipient: principal, + processed: bool, + confirmations: uint, + timestamp: uint, + btc-sender: (buff 33) + } +) + +(define-map validators principal bool) +(define-map validator-signatures + { tx-hash: (buff 32), validator: principal } + { signature: (buff 65), timestamp: uint } +) + +(define-map bridge-balances principal uint) \ No newline at end of file From 927e968017f539fd57c552ea6021df38f9d0ede3 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:43:14 +0100 Subject: [PATCH 04/12] feat: Add public functions to initialize and pause the bridge - Added `initialize-bridge` function to set the bridge paused state to false, callable only by the contract deployer. - Added `pause-bridge` function to set the bridge paused state to true, callable only by the contract deployer. --- contracts/btc-bridge.clar | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 41ac8fe..05a575f 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -58,4 +58,23 @@ { signature: (buff 65), timestamp: uint } ) -(define-map bridge-balances principal uint) \ No newline at end of file +(define-map bridge-balances principal uint) + +;; public functions +;; Initializes the bridge by setting the paused state to false. Only the contract deployer can call this function. +(define-public (initialize-bridge) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (var-set bridge-paused false) + (ok true) + ) +) + +;; Pauses the bridge. Only the contract deployer can call this function. +(define-public (pause-bridge) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (var-set bridge-paused true) + (ok true) + ) +) \ No newline at end of file From acc431c453838e1cb43cc1982107008fc7db980b Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:44:01 +0100 Subject: [PATCH 05/12] feat: Add public functions to resume the bridge and add validators - Added `resume-bridge` function to resume the bridge if paused, callable only by the contract deployer. - Added `add-validator` function to add a validator to the bridge, callable only by the contract deployer. --- contracts/btc-bridge.clar | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 05a575f..aa7d47a 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -77,4 +77,24 @@ (var-set bridge-paused true) (ok true) ) -) \ No newline at end of file +) + +;; Resumes the bridge if it is paused. Only the contract deployer can call this function. +(define-public (resume-bridge) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (asserts! (var-get bridge-paused) (err ERROR-INVALID-BRIDGE-STATUS)) + (var-set bridge-paused false) + (ok true) + ) +) + +;; Adds a validator to the bridge. Only the contract deployer can call this function. +(define-public (add-validator (validator principal)) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (asserts! (is-valid-principal validator) (err ERROR-INVALID-VALIDATOR-ADDRESS)) + (map-set validators validator true) + (ok true) + ) +) From 35e9c277adfb96e76a47bef36269e089cae0a843 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:45:26 +0100 Subject: [PATCH 06/12] feat: Add public functions to remove validators and initiate deposits - Added `remove-validator` function to remove a validator from the bridge, callable only by the contract deployer. - Added `initiate-deposit` function for validators to initiate a deposit into the bridge with necessary validations. --- contracts/btc-bridge.clar | 45 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index aa7d47a..e9a969a 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -98,3 +98,48 @@ (ok true) ) ) + +;; Removes a validator from the bridge. Only the contract deployer can call this function. +(define-public (remove-validator (validator principal)) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (asserts! (is-valid-principal validator) (err ERROR-INVALID-VALIDATOR-ADDRESS)) + (map-set validators validator false) + (ok true) + ) +) + +;; Initiates a deposit into the bridge. Validators must call this function. +(define-public (initiate-deposit + (tx-hash (buff 32)) + (amount uint) + (recipient principal) + (btc-sender (buff 33)) +) + (begin + (asserts! (not (var-get bridge-paused)) (err ERROR-BRIDGE-PAUSED)) + (asserts! (validate-deposit-amount amount) (err ERROR-INVALID-AMOUNT)) + (asserts! (get-validator-status tx-sender) (err ERROR-NOT-AUTHORIZED)) + (asserts! (is-valid-tx-hash tx-hash) (err ERROR-INVALID-TX-HASH)) + (asserts! (is-none (map-get? deposits {tx-hash: tx-hash})) (err ERROR-ALREADY-PROCESSED)) + (asserts! (is-valid-principal recipient) (err ERROR-INVALID-RECIPIENT-ADDRESS)) + (asserts! (is-valid-btc-address btc-sender) (err ERROR-INVALID-BTC-ADDRESS)) + + (let + ((validated-deposit { + amount: amount, + recipient: recipient, + processed: false, + confirmations: u0, + timestamp: block-height, + btc-sender: btc-sender + })) + + (map-set deposits + {tx-hash: tx-hash} + validated-deposit + ) + (ok true) + ) + ) +) From 0d787724b1308bdcff684aa992920e562b57f63a Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:46:26 +0100 Subject: [PATCH 07/12] feat: Add public functions to confirm deposits and withdraw from the bridge - Added `confirm-deposit` function for validators to confirm a deposit into the bridge with necessary validations. - Added `withdraw` function to withdraw an amount from the bridge to a Bitcoin recipient address with necessary validations. --- contracts/btc-bridge.clar | 80 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index e9a969a..71f346d 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -143,3 +143,83 @@ ) ) ) + +;; Confirms a deposit into the bridge. Validators must call this function. +(define-public (confirm-deposit + (tx-hash (buff 32)) + (signature (buff 65)) +) + (let ( + (deposit (unwrap! (map-get? deposits {tx-hash: tx-hash}) (err ERROR-INVALID-BRIDGE-STATUS))) + (is-validator (get-validator-status tx-sender)) + ) + (asserts! (not (var-get bridge-paused)) (err ERROR-BRIDGE-PAUSED)) + (asserts! (is-valid-tx-hash tx-hash) (err ERROR-INVALID-TX-HASH)) + (asserts! (is-valid-signature signature) (err ERROR-INVALID-SIGNATURE-FORMAT)) + (asserts! (not (get processed deposit)) (err ERROR-ALREADY-PROCESSED)) + (asserts! (>= (get confirmations deposit) REQUIRED-CONFIRMATIONS) (err ERROR-INVALID-BRIDGE-STATUS)) + + (asserts! + (is-none (map-get? validator-signatures {tx-hash: tx-hash, validator: tx-sender})) + (err ERROR-ALREADY-PROCESSED) + ) + + (let + ((validated-signature { + signature: signature, + timestamp: block-height + })) + + (map-set validator-signatures + {tx-hash: tx-hash, validator: tx-sender} + validated-signature + ) + + (map-set deposits + {tx-hash: tx-hash} + (merge deposit {processed: true}) + ) + + (map-set bridge-balances + (get recipient deposit) + (+ (default-to u0 (map-get? bridge-balances (get recipient deposit))) + (get amount deposit)) + ) + + (var-set total-bridged-amount + (+ (var-get total-bridged-amount) (get amount deposit)) + ) + (ok true) + ) + ) +) + +;; Withdraws an amount from the bridge to a Bitcoin recipient address. +(define-public (withdraw + (amount uint) + (btc-recipient (buff 34)) +) + (let ( + (current-balance (get-bridge-balance tx-sender)) + ) + (asserts! (not (var-get bridge-paused)) (err ERROR-BRIDGE-PAUSED)) + (asserts! (>= current-balance amount) (err ERROR-INSUFFICIENT-BALANCE)) + (asserts! (validate-deposit-amount amount) (err ERROR-INVALID-AMOUNT)) + + (map-set bridge-balances + tx-sender + (- current-balance amount) + ) + + (print { + type: "withdraw", + sender: tx-sender, + amount: amount, + btc-recipient: btc-recipient, + timestamp: block-height + }) + + (var-set total-bridged-amount (- (var-get total-bridged-amount) amount)) + (ok true) + ) +) \ No newline at end of file From 3399ccb8908c69f03a1a08f6e1817cd46c4bdc21 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:47:00 +0100 Subject: [PATCH 08/12] feat: Add emergency withdrawal function for contract deployer - Added `emergency-withdraw` function to allow the contract deployer to perform an emergency withdrawal with necessary validations. --- contracts/btc-bridge.clar | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 71f346d..7ef1f1e 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -222,4 +222,22 @@ (var-set total-bridged-amount (- (var-get total-bridged-amount) amount)) (ok true) ) +) + +;; Allows the contract deployer to perform an emergency withdrawal. +(define-public (emergency-withdraw (amount uint) (recipient principal)) + (begin + (asserts! (is-eq tx-sender CONTRACT-DEPLOYER) (err ERROR-NOT-AUTHORIZED)) + (asserts! (>= (var-get total-bridged-amount) amount) (err ERROR-INSUFFICIENT-BALANCE)) + (asserts! (is-valid-principal recipient) (err ERROR-INVALID-RECIPIENT-ADDRESS)) + + (let ( + (current-balance (default-to u0 (map-get? bridge-balances recipient))) + (new-balance (+ current-balance amount)) + ) + (asserts! (> new-balance current-balance) (err ERROR-INVALID-AMOUNT)) + (map-set bridge-balances recipient new-balance) + (ok true) + ) + ) ) \ No newline at end of file From 10644022c6c3fbfdc8d2c23873a16378461b8696 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:47:50 +0100 Subject: [PATCH 09/12] feat: Add read-only functions for btc-bridge-contract - Added `get-deposit` to retrieve deposit details using the transaction hash. - Added `get-bridge-status` to check if the bridge is paused. - Added `get-validator-status` to check if a given principal is a validator. - Added `get-bridge-balance` to retrieve the bridge balance of a user. - Added `is-valid-principal` to validate if a given principal address is valid. --- contracts/btc-bridge.clar | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 7ef1f1e..6d0ff70 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -240,4 +240,34 @@ (ok true) ) ) +) + +;; read only functions +;; Retrieves the details of a deposit using the transaction hash. +(define-read-only (get-deposit (tx-hash (buff 32))) + (map-get? deposits {tx-hash: tx-hash}) +) + +;; Retrieves the current status of the bridge (paused or not). +(define-read-only (get-bridge-status) + (var-get bridge-paused) +) + +;; Checks if a given principal is a validator. +(define-read-only (get-validator-status (validator principal)) + (default-to false (map-get? validators validator)) +) + +;; Retrieves the bridge balance of a user. +(define-read-only (get-bridge-balance (user principal)) + (default-to u0 (map-get? bridge-balances user)) +) + +;; Validates if a given principal address is valid. +(define-read-only (is-valid-principal (address principal)) + (and + (is-ok (principal-destruct? address)) + (not (is-eq address CONTRACT-DEPLOYER)) + (not (is-eq address (as-contract tx-sender))) + ) ) \ No newline at end of file From ce6f0a3286aa57bbf1f3f353b797bb4ceaa7367a Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:48:24 +0100 Subject: [PATCH 10/12] feat: Add read-only validation functions for btc-bridge-contract - Added `is-valid-btc-address` to validate Bitcoin addresses. - Added `is-valid-tx-hash` to validate transaction hashes. - Added `is-valid-signature` to validate signatures. - Added `validate-deposit-amount` to check if a deposit amount is within the allowed range. --- contracts/btc-bridge.clar | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 6d0ff70..588f6b9 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -270,4 +270,39 @@ (not (is-eq address CONTRACT-DEPLOYER)) (not (is-eq address (as-contract tx-sender))) ) +) + +;; Validates if a given Bitcoin address is valid. +(define-read-only (is-valid-btc-address (btc-addr (buff 33))) + (and + (is-eq (len btc-addr) u33) + (not (is-eq btc-addr 0x000000000000000000000000000000000000000000000000000000000000000000)) + true + ) +) + +;; Validates if a given transaction hash is valid. +(define-read-only (is-valid-tx-hash (tx-hash (buff 32))) + (and + (is-eq (len tx-hash) u32) + (not (is-eq tx-hash 0x0000000000000000000000000000000000000000000000000000000000000000)) + true + ) +) + +;; Validates if a given signature is valid. +(define-read-only (is-valid-signature (signature (buff 65))) + (and + (is-eq (len signature) u65) + (not (is-eq signature 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000)) + true + ) +) + +;; Validates if a given deposit amount is within the allowed range. +(define-read-only (validate-deposit-amount (amount uint)) + (and + (>= amount MIN-DEPOSIT-AMOUNT) + (<= amount MAX-DEPOSIT-AMOUNT) + ) ) \ No newline at end of file From 5788c9c6238cdcf7e627cd774401c5b25257efa3 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 19:50:00 +0100 Subject: [PATCH 11/12] feat: Remove redundant check for principal validity in is-valid-principal function --- contracts/btc-bridge.clar | 1 - 1 file changed, 1 deletion(-) diff --git a/contracts/btc-bridge.clar b/contracts/btc-bridge.clar index 588f6b9..95d08cc 100644 --- a/contracts/btc-bridge.clar +++ b/contracts/btc-bridge.clar @@ -266,7 +266,6 @@ ;; Validates if a given principal address is valid. (define-read-only (is-valid-principal (address principal)) (and - (is-ok (principal-destruct? address)) (not (is-eq address CONTRACT-DEPLOYER)) (not (is-eq address (as-contract tx-sender))) ) From 71a605e2768ec60a97563b78468ca8562f5860a9 Mon Sep 17 00:00:00 2001 From: adeshola-code Date: Fri, 27 Dec 2024 20:59:47 +0100 Subject: [PATCH 12/12] feat: Add comprehensive README for Bitcoin-Stacks Bridge Smart Contract --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f789344 --- /dev/null +++ b/README.md @@ -0,0 +1,185 @@ +# Bitcoin-Stacks Bridge Smart Contract + +A secure and robust cross-chain bridge enabling asset transfers between Bitcoin and Stacks blockchains. + +## Overview + +The BTC-Stacks Bridge facilitates trustless asset transfers between Bitcoin and Stacks networks through a validator-based system with multiple security checks and balances. + +## Features + +- **Secure Cross-Chain Transfers**: Enable safe asset movement between Bitcoin and Stacks +- **Validator Management**: Multi-validator system for enhanced security +- **Deposit Management**: Structured handling of deposits with confirmations +- **Emergency Controls**: Safety mechanisms including pause functionality and emergency withdrawals +- **Balance Tracking**: Accurate tracking of user balances and total bridged amounts + +## Technical Architecture + +### Core Components + +1. **Token Interface** + +```clarity +(define-trait bridgeable-token-trait + ((transfer (uint principal principal) (response bool uint)) + (get-balance (principal) (response uint uint))) +) +``` + +2. **Data Storage** + +- Deposits tracking +- Validator registry +- Bridge balances +- Validator signatures + +### Security Parameters + +- Minimum deposit: 100,000 units +- Maximum deposit: 1,000,000,000 units +- Required confirmations: 6 + +## Functions + +### Administrative Functions + +1. **initialize-bridge** + + - Initializes the bridge in active state + - Restricted to contract deployer + +2. **pause-bridge / resume-bridge** + + - Emergency controls for bridge operations + - Restricted to contract deployer + +3. **add-validator / remove-validator** + - Validator management functions + - Restricted to contract deployer + +### Core Operations + +1. **initiate-deposit** + + ```clarity + (tx-hash (buff 32)) + (amount uint) + (recipient principal) + (btc-sender (buff 33)) + ``` + + - Initiates cross-chain deposit + - Requires validator authorization + - Validates transaction parameters + +2. **confirm-deposit** + + ```clarity + (tx-hash (buff 32)) + (signature (buff 65)) + ``` + + - Confirms deposit with validator signature + - Updates user balances + - Requires minimum confirmations + +3. **withdraw** + ```clarity + (amount uint) + (btc-recipient (buff 34)) + ``` + - Processes withdrawals to Bitcoin + - Validates balance and amount + - Updates bridge state + +### Query Functions + +1. **get-deposit**: Retrieves deposit details +2. **get-bridge-status**: Checks bridge operational status +3. **get-validator-status**: Verifies validator status +4. **get-bridge-balance**: Checks user balance + +### Validation Functions + +1. **is-valid-principal**: Validates Stacks addresses +2. **is-valid-btc-address**: Validates Bitcoin addresses +3. **is-valid-tx-hash**: Validates transaction hashes +4. **is-valid-signature**: Validates validator signatures +5. **validate-deposit-amount**: Validates deposit amounts + +## Error Handling + +The contract includes comprehensive error handling with specific error codes: + +| Code | Description | +| ---- | ------------------------ | +| 1000 | Unauthorized access | +| 1001 | Invalid amount | +| 1002 | Insufficient balance | +| 1003 | Invalid bridge status | +| 1004 | Invalid signature | +| 1005 | Already processed | +| 1006 | Bridge paused | +| 1007 | Invalid validator | +| 1008 | Invalid recipient | +| 1009 | Invalid BTC address | +| 1010 | Invalid transaction hash | +| 1011 | Invalid signature format | + +## Security Considerations + +1. **Access Control** + + - Strict validator management + - Administrative function restrictions + - Multi-signature requirements + +2. **Transaction Validation** + + - Comprehensive parameter validation + - Double-processing prevention + - Balance checks + +3. **Emergency Measures** + - Bridge pause mechanism + - Emergency withdrawal function + - Invalid transaction protection + +## Usage Examples + +### Initiating a Deposit + +```clarity +(contract-call? .btc-bridge initiate-deposit + 0x1234567890abcdef... ;; tx-hash + u500000 ;; amount + 'ST1234567890ABCDEF ;; recipient + 0x9876543210... ;; btc-sender +) +``` + +### Processing a Withdrawal + +```clarity +(contract-call? .btc-bridge withdraw + u500000 ;; amount + 0x9876543210... ;; btc-recipient +) +``` + +## Best Practices + +1. Always verify transaction status before confirmation +2. Maintain secure validator key management +3. Monitor bridge status before operations +4. Verify recipient addresses carefully +5. Check balance availability before withdrawals + +## Error Resolution + +1. **ERR-UNAUTHORIZED**: Verify caller has appropriate permissions +2. **ERR-INVALID-AMOUNT**: Ensure amount within valid range +3. **ERR-BRIDGE-PAUSED**: Check bridge operational status +4. **ERR-ALREADY-PROCESSED**: Verify transaction uniqueness +5. **ERR-INSUFFICIENT-BALANCE**: Confirm adequate balance