Earn Contracts Overview

This documentation covers the main functions of BTCz that are essential for depositing Bitcoin, staking, unstaking, and withdrawing funds.

Function: deposit

Description:

Allows users to deposit Bitcoin into the protocol. The function verifies the provided Bitcoin transaction, mints the equivalent amount of wrapped Bitcoin tokens (btcz) on the Stacks blockchain, and credits them to the user's account.

Arguments:

1. tx (buff 4096)

   • Type: Buffer of up to 4096 bytes.

   • Description: The raw serialized Bitcoin transaction where the user has sent Bitcoin to the protocol's peg-in address.

2. block { header: (buff 80), height: uint }

   • Type: Tuple containing block header and block height.

     • header (buff 80): The raw 80-byte Bitcoin block header containing metadata about the block.

     • height (uint): The height (number) of the block in the Bitcoin blockchain.

   • Description: The Bitcoin block that includes the transaction, used to verify that the transaction is mined.

3. proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }

   • Type: Tuple containing Merkle proof data.

     • tx-index (uint): The index of the transaction within the block's list of transactions.

     • hashes (list 14 (buff 32)): A list of up to 14 sibling hashes (each 32 bytes) needed to reconstruct the Merkle path.

     • tree-depth (uint): The depth of the Merkle tree.

   • Description: The Merkle proof that the transaction is included in the specified block.

4. output-idx (uint)

   • Type: Unsigned integer.

   • Description: The index of the output in the transaction that corresponds to the deposit amount sent to the protocol's peg-in address.

5. order-idx (uint)

   • Type: Unsigned integer.

   • Description: The index of the output in the transaction containing the user's order script, which encodes the recipient's Stacks address for crediting btcz tokens.

---

Function: init-withdraw

Description:

Enables users to initiate the withdrawal process of their btcz tokens back into Bitcoin. The user specifies the Bitcoin address for receiving the funds, and the protocol burns the specified amount of btcz tokens and creates a withdrawal request.

Arguments:

1. peg-out-address (buff 128)

   • Type: Buffer of up to 128 bytes.

   • Description: The Bitcoin address where the user wants to receive the withdrawn Bitcoin.

2. btcz-amount (uint)

   • Type: Unsigned integer.

   • Description: The amount of btcz tokens the user wishes to withdraw, which will be burned from their balance.

---

Function: finalize-withdraw

Description:

Allows the protocol (contract owner) to finalize a user's withdrawal request. After the Bitcoin transfer is processed, this function marks the withdrawal as completed.

Arguments:

1. withdrawal-id (uint)

   • Type: Unsigned integer.

   • Description: The unique identifier (nonce) of the withdrawal request to be finalized.

---

Function: add-rewards

Description:

Enables the contract owner to add Bitcoin rewards to the protocol's total BTC balance. This function is typically used to distribute yield generated from staking or other activities to btcz holders.

Arguments:

1. btc-amount (uint)

   • Type: Unsigned integer.

   • Description: The amount of Bitcoin (in satoshis) to add to the protocol's total BTC balance as rewards.

---

Fees and Ratios

The protocol calculates fees and token amounts based on current BTC to btcz ratios, which can change over time due to rewards and staking activities.

Audit Report

Here you can find the audit report conducted by Clarity Alliance.