Guides
Quant Connect LoginTalk to us

Unspent Transaction Output (UTXO)

UTXO state model

Suggest Edits

What is an unspent transaction output (UTXO)?

Distributed Ledger Technologies have two main ways to format the current state information:

  1. Accounts-based: Tokens are assigned to a specific blockchain account, controlled by either a private key or smart contract code.

  2. UTXO-based: Tokens are assigned to a particular unspent transaction output (UTXO). Each UTXO includes details regarding how these tokens can be unlocked and moved.

    The unlock rules regarding a UTXO can include things like:

  3. A signature by a particular blockchain account

  4. Multiple signatures by multiple blockchain accounts

  5. Revealing a particular secret value to prove ownership, and so on.


If you want to inspect the state of an Accounts-based blockchain, the current state primary key is a blockchain account identifier (usually an address). The information assigned to each blockchain account will include: (a) balance; (b) sequence; (c) smart contract code (if any).

Whereas if you want to inspect the state of a UTXO-based blockchain, the current state primary key is a UTXO identifier. The information assigned to each UTXO will include: (a) locked tokens; (b) rules to unlock the tokens (sometimes referred to as a UTXO smart contract).

Examples of distributed ledger technologies that use the UTXO model are Bitcoin and Corda.

This guide is designed to walk you through the steps needed to do a search on a UTXO and inspect its status.

Prerequisites

Call the endpoint

Replace <utxoId> with the UTXO you would like to perform a search for:

/v2/autoexecution/search/utxo/<utxoId>

For example, to get details on the UTXO 74f513dae1a7c238eda6e2b3e667a4b0e75f422882512466dd2d5ea702c43465:0.

In the request body, pass the technology and network for which the UTXO search is to be performed and the utxoId as a path parameter, then send the request.

curl --request POST \
     --url https://api.sandbox.overledger.io/v2/autoexecution/search/utxo/74f513dae1a7c238eda6e2b3e667a4b0e75f422882512466dd2d5ea702c43465%3A0 \
     --header 'Authorization: Bearer token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "location": {
    "technology": "Bitcoin",
    "network": "Testnet"
  }
}
'

If the request is successful, you will receive a response with the UTXO details as below:

{
    "preparationUtxoSearchResponse": {
        "requestId": "497e7ab3-7083-4270-b93b-0cb918a4fc52",
        "gatewayFee": {
            "amount": "0",
            "unit": "QNT"
        }
    },
    "executionUtxoSearchResponse": {
        "location": {
            "technology": "Bitcoin",
            "network": "testnet"
        },
        "timestamp": "1615478974",
        "status": {
            "value": "UTX1000",
            "code": "UNSPENT_SUCCESSFUL",
            "description": "The UTXO has been created in a transaction that is in successful status and can be spent.",
            "message": "UTXO can be spent.",
            "timestamp": "1615483678"
        },
        "destination": [
            {
                "destinationId": "mtHsSjGeVhSQVqcM3fv5A79qoSJ5TgEjtj",
                "payment": {
                    "amount": "0.0001",
                    "unit": "BTC"
                },
                "smartContract": {
                    "type": "pubkeyhash"
                }
            }
        ],
        "utxoId": "74f513dae1a7c238eda6e2b3e667a4b0e75f422882512466dd2d5ea702c43465:0",
        "nativeData": {
            "vout": [
                {
                    "value": 1.0E-4,
                    "n": 0,
                    "scriptPubKey": {
                        "asm": "OP_DUP OP_HASH160 8c202dc31b453e900cc7c14c17dd852ac517a504 OP_EQUALVERIFY OP_CHECKSIG",
                        "desc": "addr(mtHsSjGeVhSQVqcM3fv5A79qoSJ5TgEjtj)#69gmx6mk",
                        "hex": "76a9148c202dc31b453e900cc7c14c17dd852ac517a50488ac",
                        "address": "mtHsSjGeVhSQVqcM3fv5A79qoSJ5TgEjtj",
                        "type": "pubkeyhash"
                    }
                }
            ]
        },
    }
}

For full information on all of the parameters please refer to the API documentation.

UTXO Statuses

Information regarding Overledger's standardised UTXO status codes is as follows:

  • UNSPENT_PENDING: This transaction output has been created in a transaction that Overledger currently deems not yet successful (hence the PENDING suffix). This transaction has not yet been spent in any other transaction (hence the UNSPENT prefix).
  • UNSPENT_SUCCESSFUL: This transaction output has been created in a transaction that Overledger deems successful (hence the SUCCESSFUL suffix). This transaction has not yet been spent in any other transaction (hence the UNSPENT prefix).
  • SPENT: This transaction has been spent in another transaction.
  • UNSPENDABLE_PENDING: This transaction output has been created in a transaction that Overledger currently deems not yet successful (hence the PENDING suffix). But this transaction output can never be spent, because it has no unlocking condition (hence the UNSPENDABLE prefix).
  • UNSPENDABLE_SUCCESSFUL: This transaction output has been created in a transaction that Overledger deems successful (hence the SUCCESSFUL suffix). But this transaction output can never be spent, because it has no unlocking condition (hence the UNSPENDABLE prefix).

Updated 6 months ago