We’ve had a lot of requests recently to guide our users in the migration of customer v1 BTC wallet addresses to new addresses for v2 BTC wallets. Here is our suggested procedure for managing this task, and some concerns or tips to be aware of when performing these steps. 

We believe that the best way of achieving this migration is to begin by counting the amount of users that you have that require new addresses. This will allow you to generate the appropriate amount of addresses on the new wallets. We recommend that you continue to use an omnibus (“pooled”) wallet format, and once you have programmatically generated all the necessary addresses, you can then assign them to your users one by one. Once you have assigned the new addresses to the users, you will want to make sure that you move all funds from the v1 Wallet to the v2 Wallet. By doing so, your customer balances will remain intact. There will be a charge for the network fees that are required on all transactions. This will need to be reflected in your overall balance records. In addition, you will want to make sure to maintain the v1 wallets that your users are linked to and then make sure to periodically move the funds to the v2 wallet to ensure compatibility of the next hard fork and any additional features that BitGo may implement. 

Here are the steps required to implement this:

  1. Decide / calculate how many user addresses you will need to generate on the new wallet. 

  2. Create a new v2 BTC wallet to generate addresses from.

  3. Programmatically generate the required number of addresses that you need for your users; this is best accomplished via the API - please refer to the following: https://www.bitgo.com/api/v2/#create-wallet-address 

  4. Assign the new addresses one by one to your customers. These will eventually replace the original addresses given to the user, but for now, keep both v1 and v2 addresses attached to users. (We recommend creating a new column or field in your database file for the new addresses.) 

  5. Sweep the funds from the v1 BTC wallet to the v2 BTC wallet. Info on this process can be found here: https://bitgo.freshdesk.com/support/solutions/articles/27000037418-how-to-transfer-funds-to-a-new-wallet 

  6. Notify users of the new addresses for their accounts. Emphasize that your users will want to use the new address they are provided with. Be sure to make users aware that their balance has not changed; only the wallet that is holding the balance has changed. 

  7. Periodically sweep the funds from the v1 wallet to the v2 wallet. Check regularly to ensure that you do not miss a hard fork. BitGo provides the function of Webhooks to assist you in monitoring the transactions into and out of your v1 and v2 wallets. It's important to know however that these webhooks function differently on v1 and v2 wallets. 

V1 Webhook documentation can be found here: https://bitgo.github.io/bitgo-docs/#webhook-notifications

V2 Webhook documentation can be found here: https://www.bitgo.com/api/v2/#webhook-notifications