Bitcoin Deposit Handling

1. Purpose

The purpose of this document is to outline functional specifications for monitoring bitcoin network and handling deposits. Result of a deposit is conversion of Bitcoin (BTC) to Peerplays assets (pBTC).

2. Scope

Sidechain operating node will monitor Bitcoin network for events of interest, namely transfer of assets to a Peerplays address. When transfer happens, sidechain will process it, in order to pick up information needed to handle it. Handling deposits will create certain amount of tokens on a Peerplays network. This amount will match the amount of assets on target sidechain by predefined exchange rate.

Specific functions covered include:

  • monitor transactions to a designated sidechain user address

  • handle deposit via creation of sidechain event data

  • create & confirm object proposals

  • conversion of BTC to pBTC based on defined exchange rate, with applicable fees

  • sign transactions

  • withdraw bitcoin for conversion into Peerplays tokens

3. Background

NOTE: Deposit handling requirements are not final.

Deposit handling will consist of two parts, a BTC Event Listener and a BTC Event Handler. Listener can identify and report new block, a transaction, or filtered single event (like specific operation involving specific address). We have identified three (3) distinct scenarios describing how deposits and withdrawals may be implemented. Scenarios are outlined in this article:

Comparison between scenarios for handling deposits and withdrawals

Requirements below are describing functional specifications based on Scenario 1 - Multi-signature primary wallet controlled by SON network, holding all the funds. All transfers are made to and from this multi-signature wallet.

4. Process Overview

Described here is the process of monitoring deposit address and processing transactions that occur in relation to target address.

pBTC token issue is initiated by Sidechain Listener identifying a Bitcoin deposit, passing information to Sidechain Handler .

Note that steps 2 through 14 are described in detail in BTC Transaction Signing functional specification.

Steps involved:

  1. User initiates deposit to convert BTC to pBTC

  2. Listener identifies that a BTC transaction is initiated

  3. Listener passes event data to handler

  4. Handler receives event data and creates an object (normally SON Wallet Object, SON Wallet Deposit Object or SON Wallet Withdraw Object)

  5. Object is checked by by all active SONs to compare object data from the chain against data generated by each SON.

    1. If data does not match, transaction is terminated

    2. If data matches, object is deemed ‘Confirmed'. Proceed to next step

  6. Handler checks the number of active SONs

    1. If active SONs are > 5, proceed to next step

    2. If active SONs are < 5, store transaction for processing until required number of active SONs is available (this step will be repeated until SON availability requirement is met)

  7. Issue proposal for for sidechain transaction create operation

  8. Active SONs create local copies of transaction data to be verified against proposal

  9. Proposal is verified by active sons by comparing local copies of transaction data to proposal

    1. If data does not match, proposal is not approved and will eventually expire thus terminating the transaction

    2. If data matches, proposal is approved. Proceed to next step

  10. Transaction object containing a list of SONs expected to sign is created and published to the sidechain. List of SONs will be created based on list of active SONs

  11. Expected SON signers initiate parallel processing of transaction. Offline SONs will not participate in signing and only the online SONs (regardless of status) will sign the transaction

  12. Sign transaction

    1. Each signing SON adds its signature

    2. Each signing SON is added to list or received signatures

    3. Operation evaluator checks signatures to determine if latest signature is the last signature required to complete transaction signing

      1. If no, repeat this step after each SON’s signature

      2. If yes, mark transaction object as ‘Completed’ (helper field complete = true)

  13. Scheduled SON detects completed transaction object

  14. Transaction is converted to a readable format and sent to Bitcoin network

  15. User receives pBTC amount

  16. Deposit is marked as processed

5. Context

To facilitate conversion of bitcoin in to peerplays tokens, SON must include an event listener and an event handler mechanism to identify specific types of transactions and handle them accordingly. Proposed approach uses multi-signature Primary Wallet controlled by SON network, holding all the funds. All transfers are made to and from this multi-signature wallet.

6. Flow Diagram

7. Requirements

7.1 Wallet information

Current deposit address implementation is Timelocked-one-or-weighted-multisig

SON must be able to create/update Peerplays multisig account, and create/re-create Bitcoin multisig address controlled by active SONs.

The SONs may change at any maintenance interval when the votes are tallied and the existing SONs are voted out. Since, the bitcoin public keys of the SONs will be used to create the multisig bitcoin wallet, their public keys will have to be changed in order to operate the multisig bitcoin wallet. System must transfer the funds from the old wallet to the new wallet every time an SON changes and incur associated bitcoin transaction fees.

To reduce this additional cost, an m-of-n multisig bitcoin wallet will be created with signatures of 2/3rd SONs required for a bitcoin transaction. Change of public key for the SON in the multisig bitcoin wallet is not needed until 1/3rd of the SONs changes. Once, 1/3rd of the initial SONs changes, we must create a new multisig bitcoin wallet with the public keys of the current SONs and transfer the funds from the previous wallet to the newly created multisig bitcoin wallet.

Requirements below assume use of multi-signature primary wallet controlled by SON network, holding all the funds. All transfers are made to and from this multi-signature wallet.

SON must be able to keep the history records of active primary wallets, duration of activity period, and the SONs who control the wall at the time of creation.

7.2 Listener

SON must include a Bitcoin event listener which monitors a designated Bitcoin address registered as a sidechain user address for deposits. Specifically, listener uses Bitcoin node interface for monitoring changes in the blockchain

Listener must be able to recognize a change that signifies a deposit event and capture the following data associated with each transaction of this type:

  • Transaction unique identifier

  • Transfer operation’s source address

  • Transfer operation’s target address

  • Transfer amount

  • Transaction fee (for transfer operation)

Following identifying a deposit transaction, Listener must check the number of active SONs to verify that a minimum of 5 SONs are active. If minimum is not met, deposit transaction must be stored for processing until minimum number of active SONs becomes available.

7.3 Handler

Detailed end-to-end functional specifications for handling and signing BTC transactions are posted in the Functional Specifications - BTC Transaction Processing & Signing spec. In summary, this occurs as follows:

SON must include a Bitcoin event handler which uses information supplied by the Listener to perform a specific operation that’s based on transaction type submitted by listener. When handler receives notification of Deposit transaction from the Listener, sidechain_event_data must be received and passed to sidechain_event_data_received.

System must then create a SON Wallet Deposit Object, which upon creation will be processed by all available SONs to verify its data. To verify object, system must check local data of each SON against object data on the side chain. Object must be deemed valid when its data is confirmed, and rejected when its data cannot be confirmed. Transaction terminates if object data is not confirmed during this check.

Successful object verification results in issuance of transaction create proposal that is based on confirmed object and includes some of its data (specifically, a reference to the object). Created sidechain transaction object must contain reference to the sidechain where it should be processed, reference to the object it is created for, sidechain transaction body, list of expected signers, list of received signatures, and the helper fields for calculating signature weights.

This proposal must be verified by SONs, which is performed by verifying referred object against locally re-created transaction data. If data does not match, proposal will be deleted from proposal list and transaction won’t be completed. If data matches, system must approve the proposal. Approved proposals must result in object being published on the chain.

When the object is published on the chain, SONs specified on the list of expected signers must begin processing it in parallel. Note that SONs specified as signers must sign the transaction as long as they are online, disregarding their status (thus SON in any status must sign the transaction). Once enough signatures hve been collected, transaction is marked as ‘Completed’.

When scheduled SON detects that a sidechain transaction object has been completed, it must collect all data from the sidechain transaction object, compile it, convert to a format that is ready for transmission to Bitcoin network, and send this transaction to the Bitcoin network.

SON must start conversion of deposit amount from bitcoin into peerplay tokens following deposit confirmation. Conversion operation must calculate btc to ppy conversion using 1:1 rate. Conversion is completed by sending funds from bitcoin address (sidechain user address for deposits) to primary wallet (bitcoin multisig address).

User will receive peerplays core assets matching the amount of deposited bitcoin.

7.4 Refund Scenario

In some cases a transaction will not be processed by SONs (such as when active SONs threshold is not met), which will cause funds to wait until required number of active SONs become available. System must allow users to initiate refunds of their transactions.

Refund scenario must adhere to same rules as regular bitcoin transaction:

  1. User needs transaction id for the transaction they wish to refund

  2. User creates another transaction using transaction id of transaction they want to refund to move funds to their own address

  3. User signs the transaction using a private key that matches the public key he provided in sidechain address mapping

  4. Transaction is pushed to bitcoin network and user is refunded once transaction is processed

7.5 Current Deposit Address Implementation - One-or-weighted-multisig

This deposit address implementation type allows to send funds from this address with 2/3 weights of SON votes (like in Primary Wallet) or with single user signature. To create such address we need:

1) user public key

2) all SONs public keys

3) every SON weight

Note: This is the current implementation of the Deposit address.

This address type is implemented by btc_one_or_weighted_multisig_address class.

8. Glossary

pBTC​ is a peerplay Blockchain Asset, which represents users’ balances in Bitcoin on Peerplays blockchain. Having a balance of 1 pBTC would mean having it backed by the same amount of Bitcoin on a Witness-controlled Multisig Wallet. New pBTC are NOT ISSUED by OWNER with ​issue ​operation. New pBTC are issued strictly in relation with ​Deposit​ operations.

PW (Primary Wallet) ​is the main Multisig Bitcoin Wallet.

Multi-signature (multisig) refers to requiring more than one key to authorize a Bitcoin transaction. It is generally used to divide up responsibility for possession of bitcoins.

SON status overview 2020-03-11

Comparison between scenarios for handling deposits and withdrawals

Functional Specifications - BTC Transaction Processing & Signing

Last updated