Understanding Bitcoin

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.

Introduction#

Sending Transactions with the API and the UTXO model#

Example#

TrustVault Under the hood#

Introduction

Sending Transactions with the API and the UTXO model

Example

TrustVault Under the hood