Yona BTC Canonical Bridge flow

This section describes the workflow of Yona BTC Bridge in the direction of Deposit and Withdrawal

When a user interacts with the Yona BTC Bridge, they can perform 2 way transactions: transfer from the Bitcoin network (currently testing) to the Yona Network (in this context this counts as a deposit) and vice versa (in this context this counts as a withdrawal). Interaction takes place through the Yona BTC Bridge interface: link

At the High level, the process looks simple: the user performs I/O transactions and the bridge manages the minting or burning of BTC on the Yona Network side. These diagrams show both of these processes with a consistent description of all the actions on the user side and the internal actions that are performed by the relays and smart contracts.

Bridge deposit flow to the Yona Network

Provide Yona address: The user initiates the bridging process by providing their Yona address to the Bridge UI. This is the address where they want to receive the bridged BTC on the Yona network.
Generate BTC deposit address: The Bridge UI generates a unique Bitcoin deposit address, which is linked to the user's Yona address in the bridge's system. Importantly, the generated address is of the P2WSH (Pay-to-Witness-Script-Hash) type, which is supported by the majority of Bitcoin wallets out of the box. This ensures broad compatibility and ease of use for most users without requiring special wallet configurations.
Display BTC deposit address: The Bridge UI shows the generated Bitcoin address to the user. This is the address where the user needs to send their Bitcoin for bridging.
Send BTC to deposit address: The user transfers the desired amount of Bitcoin from their wallet to the provided deposit address on the Bitcoin network.
Submit Transaction ID: After sending the Bitcoin, the user submits the Bitcoin transaction ID to the Bridge UI. This allows the bridge to track and verify the transaction.
Send BTC transaction info: The Bridge UI forwards the Bitcoin transaction information to the TX relayer for processing and verification.
Generate Merkle Proof: The TX relayer (which works as part of the Relayer off-chain client) creates a cryptographic Merkle proof that demonstrates the transaction's inclusion in the Bitcoin blockchain. This proof is crucial for verifying the transaction on the Yona side.
Submit transaction with proof: The TX relayer (which works as part of the Relayer off-chain client) sends the transaction details along with the Merkle proof to the Relay on-chain Program. This program is responsible for verifying and processing the bridged transaction on the Yona network.
Mint BTC on Yona to user's address: Once the Yona Relay on-chain Program verifies the transaction and proof, it mints an equivalent amount of BTC on the Yona network and sends it to the user's specified Yona address.
Watch over relayed transactions: Bridge Nodes continuously monitor transactions relayed to the Yona Relay on-chain Program. Once a new bridging transaction is finalized, Bridge Nodes add corresponding UTXO(s) to their spendable set, which means that they are available for withdrawal.
Watch over new blocks: The Block relayer (which works as part of the Relayer off-chain client) continuously monitor the Bitcoin network for newly mined blocks. This ensures that the bridge stays up-to-date with the latest state of the Bitcoin blockchain.
Submit block headers: The Block relayer submits new Bitcoin block headers to the Relay on-chain program. This allows the Yona network to track and verify the state of the Bitcoin blockchain, which is essential for the bridging process.

Bridge deposit flow from the Yona Network

The user submits a Bitcoin address and burn amount to the Bridge UI: initiates withdrawal by providing the Bitcoin address to which the user wishes to receive funds and specifying the amount of Yona BTC they wish to ‘burn’.
The Bridge UI broadcasts a burn transaction to the Yona Relay on-chain Program: Upon receiving the user's input, the Bridge UI generates and signs a burn transaction. This transaction burn the specified amount of Yona BTC, removing them from circulation in Yona Network. The signed transaction is then sent to the Yona Relay on-chain Program.
Bridge Nodes monitor the burn transaction: The Bridge Nodes, which are responsible for maintaining the integrity and security of the cross-chain bridge, actively monitor the on-chain state for the burn transaction. They verify the transaction's validity and wait for it to be finalized on the Yona blockchain.
Once the burn transaction is finalized, Bridge Nodes broadcast a withdrawal transaction to the Bitcoin Network: After the burn transaction is finalized, the Bridge Nodes construct a new transaction on the Bitcoin network, using the bridge's pool of Bitcoin UTXOs (Unspent Transaction Outputs). This transaction is designed to send the equivalent amount of Bitcoin to the user's specified address. The Bridge Nodes sign this transaction and broadcast it to the Bitcoin network.
The Bridge UI helps to monitor the withdrawal transaction status: Once the withdrawal transaction is broadcast to the Bitcoin network, the Bridge UI begins monitoring its status. This involves checking for confirmations on the Bitcoin blockchain and tracking the transaction's progress.
At the end, the Bridge UI notifies the user once the withdrawal transaction is sent: After the withdrawal transaction has been successfully broadcast to the Bitcoin network and has received an initial confirmation, the Bridge UI sends a notification to the user. This notification typically includes details such as the transaction ID, the amount transferred, and any relevant fees. It informs the user that the cross-chain transfer process is complete from the bridge's perspective, though the user may need to wait for additional confirmations on the Bitcoin network before considering the transaction fully settled.

PreviousYona BTC Canonical Bridge explained NextBridge Nodes

Last updated 2 months ago

Bridge deposit flow to the Yona Network

Provide Yona address: The user initiates the bridging process by providing their Yona address to the Bridge UI. This is the address where they want to receive the bridged BTC on the Yona network.

Generate BTC deposit address: The Bridge UI generates a unique Bitcoin deposit address, which is linked to the user's Yona address in the bridge's system. Importantly, the generated address is of the P2WSH (Pay-to-Witness-Script-Hash) type, which is supported by the majority of Bitcoin wallets out of the box. This ensures broad compatibility and ease of use for most users without requiring special wallet configurations.

Display BTC deposit address: The Bridge UI shows the generated Bitcoin address to the user. This is the address where the user needs to send their Bitcoin for bridging.

Send BTC to deposit address: The user transfers the desired amount of Bitcoin from their wallet to the provided deposit address on the Bitcoin network.

Submit Transaction ID: After sending the Bitcoin, the user submits the Bitcoin transaction ID to the Bridge UI. This allows the bridge to track and verify the transaction.

Send BTC transaction info: The Bridge UI forwards the Bitcoin transaction information to the TX relayer for processing and verification.

Generate Merkle Proof: The TX relayer (which works as part of the Relayer off-chain client) creates a cryptographic Merkle proof that demonstrates the transaction's inclusion in the Bitcoin blockchain. This proof is crucial for verifying the transaction on the Yona side.

Submit transaction with proof: The TX relayer (which works as part of the Relayer off-chain client) sends the transaction details along with the Merkle proof to the Relay on-chain Program. This program is responsible for verifying and processing the bridged transaction on the Yona network.

Mint BTC on Yona to user's address: Once the Yona Relay on-chain Program verifies the transaction and proof, it mints an equivalent amount of BTC on the Yona network and sends it to the user's specified Yona address.

Watch over relayed transactions: Bridge Nodes continuously monitor transactions relayed to the Yona Relay on-chain Program. Once a new bridging transaction is finalized, Bridge Nodes add corresponding UTXO(s) to their spendable set, which means that they are available for withdrawal.

Watch over new blocks: The Block relayer (which works as part of the Relayer off-chain client) continuously monitor the Bitcoin network for newly mined blocks. This ensures that the bridge stays up-to-date with the latest state of the Bitcoin blockchain.

Submit block headers: The Block relayer submits new Bitcoin block headers to the Relay on-chain program. This allows the Yona network to track and verify the state of the Bitcoin blockchain, which is essential for the bridging process.

Bridge deposit flow from the Yona Network

The user submits a Bitcoin address and burn amount to the Bridge UI: initiates withdrawal by providing the Bitcoin address to which the user wishes to receive funds and specifying the amount of Yona BTC they wish to ‘burn’.

The Bridge UI broadcasts a burn transaction to the Yona Relay on-chain Program: Upon receiving the user's input, the Bridge UI generates and signs a burn transaction. This transaction burn the specified amount of Yona BTC, removing them from circulation in Yona Network. The signed transaction is then sent to the Yona Relay on-chain Program.

Bridge Nodes monitor the burn transaction: The Bridge Nodes, which are responsible for maintaining the integrity and security of the cross-chain bridge, actively monitor the on-chain state for the burn transaction. They verify the transaction's validity and wait for it to be finalized on the Yona blockchain.

Once the burn transaction is finalized, Bridge Nodes broadcast a withdrawal transaction to the Bitcoin Network: After the burn transaction is finalized, the Bridge Nodes construct a new transaction on the Bitcoin network, using the bridge's pool of Bitcoin UTXOs (Unspent Transaction Outputs). This transaction is designed to send the equivalent amount of Bitcoin to the user's specified address. The Bridge Nodes sign this transaction and broadcast it to the Bitcoin network.

The Bridge UI helps to monitor the withdrawal transaction status: Once the withdrawal transaction is broadcast to the Bitcoin network, the Bridge UI begins monitoring its status. This involves checking for confirmations on the Bitcoin blockchain and tracking the transaction's progress.

At the end, the Bridge UI notifies the user once the withdrawal transaction is sent: After the withdrawal transaction has been successfully broadcast to the Bitcoin network and has received an initial confirmation, the Bridge UI sends a notification to the user. This notification typically includes details such as the transaction ID, the amount transferred, and any relevant fees. It informs the user that the cross-chain transfer process is complete from the bridge's perspective, though the user may need to wait for additional confirmations on the Bitcoin network before considering the transaction fully settled.