Bitcoin Overview
Introduction
Bitcoin has a specific model for handling balances and keeping track of the value at each address. This is called the UTXO (Unspent Transaction Output) model. There are many explainers on the internet if you wish to know more.
Sending Transactions with the API and the UTXO model
TrustVault keeps track of the UTXOs you have in your wallet. When attempting to send a transaction TrustVault will select the most appropriate UTXOs for you to spend.
In order to allow multiple transactions to be pending at once, TrustVault will lock the UTXOs. In this instance, “pending” means when they are in the TrustVault system waiting for further signatures or waiting to be confirmed on the network.
Example
Ignoring fees, to keep the maths easy, let’s say you have the following UTXOs:
| Address | Value | Status |
|---|---|---|
| A | 1 BTC | Unspent |
| B | 10 BTC | Unspent |
| C | 15 BTC | Unspent |
- Wallet Balance: 26 BTC
- Spendable Balance: 26 BTC
Let’s say you want to send 12 BTC. You submit a transaction for 5 BTC to an address you don’t own. Using the API and setting sendToDevicesForSigning = true, this creates a transaction that is ready for signing.
Any devices connected to the wallet will get an alert to sign and you may wish to sign via the API too (depending on your wallet multi-sig rules).
TrustVault Under the hood
TrustVault selects the 15 BTC UTXO at address C to use as the transaction input. Remember, inputs are the UTXOs you wish to spend in a transaction.
Whilst this transaction is pending (waiting for confirmation or for signatures) the following is the state of play:
| Address | Value | Status |
|---|---|---|
| A | 1 BTC | Unspent |
| B | 10 BTC | Unspent |
| C | 15 BTC | Locked |
| D | 3 BTC | Pending |
- Wallet Balance: 14 BTC (1 + 10 + 3 (Change))
- Spendable Balance: 11 BTC
The 15 BTC is now locked and cannot be used as has been locked for the transaction that has yet to be confirmed on the network. The change UTXO shows in your balance but again, is unspendable.
An attempt to send 12 BTC or more, will fail. Even though your balance is 14. This is because of the UTXO model and the way the UTXOs have been allocated (locked) to this transaction.
The API will return the max you can spend in a transaction. This is shown in the response from the createBitcoinTransaction as maxAllowedToSend and feeForMax
An attempt to send 11 BTC or fewer will succeed and will put those UTXOs into a Locked status as well.
Once the transaction is mined on the network the UTXO set is as follows:
| Address | Value | Status |
|---|---|---|
| A | 1 BTC | Unspent |
| B | 10 BTC | Unspent |
| C | 15 BTC | Spent |
| D | 3 BTC | Unspent |
- Wallet Balance: 14 BTC
- Spendable Balance: 14 BTC
You can now create a new transaction.