List unspent transaction outputs by address on Bitcoin with Amazon Managed Blockchain Query

With the intention to construct an utility that interacts with the Bitcoin blockchain, whether or not it’s a pockets, an Ordinals market, or a BTC trade, you will need to be capable to reliably entry the Bitcoin community. For instance, you’ll need to learn essential information from the blockchain that acts as enter for correctly constructed Bitcoin transactions. Probably the most foundational of those information wants is retrieving information pertaining to transaction outputs for a given pockets from the Bitcoin community, which serves a wide range of use instances. For instance, retrieving unspent transaction outputs (UTXOs) to be consumed as inputs for outgoing transactions of BTC, retrieving all UTXOs for a given pockets to calculate a stability in BTC, gathering spent outputs to render an inventory of previous Bitcoin transactions, and extra. There are a number of choices for retrieving this information, together with third-party information suppliers and node operators or operating your personal Bitcoin Core node.

Working your personal Bitcoin Core node prioritizes independence and verifiability, and means that you can observe transaction output information for a restricted set of wallets (comprising n variety of addresses). Nevertheless, utilizing self-managed Bitcoin Core nodes as is limits the size at which you’ll be able to retrieve transaction output information. In distinction, Amazon Managed Blockchain (AMB) makes use of cloud scale indexing and storage to supply a low-latency API for information pertaining to a vast set of wallets. AMB Query affords comfort, ease of scale, and pricing effectivity for Bitcoin workloads, serving to you shed the undifferentiated heavy lifting of managing Bitcoin nodes and performing information extractions from the community at scale.

On this publish, we deal with methods to use the blockchain information APIs out there in AMB Question to supply dependable, cost-effective entry to Bitcoin information at scale, together with transaction output information. Moreover, AMB Access supplies serverless entry to a fleet of Bitcoin nodes that you should use to broadcast your Bitcoin transactions after you could have retrieved UTXOs able to spend from AMB Question.

AMB Question and the ListFilteredTransactionEvents API

AMB Question supplies a set of developer-friendly APIs that serve present and historic blockchain information from a number of public blockchains, together with Bitcoin. With AMB Question, builders can shed the undifferentiated heavy lifting of node operations, blockchain information indexing, and ETL (extract, remodel, and cargo), and focus their efforts on differentiated options for his or her utility. With AMB Question, now you can use the ListFilteredTransactionEvents API to question for spent or unspent transaction outputs for an tackle or set of addresses on the Bitcoin community and its testnet, offering a substitute for the built-in listunspent JSON-RPC API within the Bitcoin Core node implementation.

The ListFilteredTransactionEvents API permits builders to do the next:

• Retrieve unspent transaction outputs for a given tackle or set of addresses to ease the method of establishing Bitcoin transactions
• Retrieve spent transaction output info to populate dashboards or pockets interfaces
• Filter transaction occasions pertaining to unspent outputs by timestamp and finality standing

Earlier than demonstrating ListFilteredTransactionEvents performance in a code pattern, it’s vital to disambiguate the basics of the unspent transaction output (UTXO) mannequin employed by Bitcoin and why you’ll inevitably require an API like ListFilteredTransactionEvents when constructing a Bitcoin utility.

Understanding the unspent transaction output (UTXO) mannequin

The Bitcoin blockchain makes use of the UTXO accounting methodology, so duties akin to calculating a spendable stability of BTC or populating a transaction to spend BTC start with compiling the unspent transaction outputs for a given pockets. In Bitcoin, every new transaction of BTC consumes unspent outputs from earlier transactions, and in flip leads to new unspent outputs to be consumed by future transactions. This idea is finest illustrated by analyzing the anatomy of a Bitcoin transaction:

{
    "txid" : "c80b343d2ce2b5d829c2de9854c7c8d423c0e33bda264c4013
              8d834aab4c0638",
    "hash" : "c80b343d2ce2b5d829c2de9854c7c8d423c0e33bda264c40138d834aab4c0638",
    "dimension" : 85,
    "vsize" : 85,
    "model" : 1,
    "locktime" : 0,
    "vin" : [
        {
            "txid" : "3f4fa19803dec4d6a84fae3821da7ac7577080ef75
                      451294e71f9b20e0ab1e7b",
            "vout" : 0,
            "scriptSig" : {
                "asm" : "",
                "hex" : ""
            },
            "sequence" : 4294967295
        }
    ],
    "vout" : [
        {
            "value" : 49.99990000,
            "n" : 0,
            "scriptPubKey" : {
                "asm" : "OP_DUP OP_HASH160 cbc20a7664f2f69e5355a
                         a427045bc15e7c6c772 OP_EQUALVERIFY OP_CHECKSIG",
                "hex" : "76a914cbc20a7664f2f69e5355aa427045bc15e
                         7c6c77288ac",
                "reqSigs" : 1,
                "type" : "pubkeyhash",
                "addresses" : [
                    "mz6KvC4aoUeo6wSxtiVQTo7FDwPnkp6URG"
                ]
            }
        }
    ]
}

The vin object defines the worth (BTC) going into the transaction, which refers to a number of of the earlier vout objects. These vout objects are the unspent worth out from earlier Bitcoin transactions. Every new Bitcoin transaction will take unspent transaction outputs from earlier transactions within the vin object, after which outline new vout entries to spend (ship) them to different wallets.

Related articles

Meter Is The First Multi-Asset Validation PoS Blockchain

June 13, 2024

Exploring Interoperability And AI For Africa’s Digital Leap

June 13, 2024

The vout array defines the record of outputs for the transaction, together with the recipient, worth (in BTC), and extra. The overall worth of the vout entries will usually be equal to the sum of the worth of vin, and can usually outline change as a vout to return to the sender of the transaction. This leads to new unspent outputs (vout) for the sender to spend in one other transaction. Though the previous transaction instance makes use of a single vin and vout, it is not uncommon for every transaction to have a number of vin and vout entries outlined.

As you may infer from the development of a Bitcoin transaction, calculating the whole spendable stability of a given pockets requires calculating the sum of the whole unspent transaction outputs (vout) for a given pockets. Within the absence of an API to supply this perception, you would need to make a big amount of requests to a Bitcoin node to retrieve all vin and vout inside transactions pertaining to your pockets and carry out calculations to find out that are spent or unspent outputs. This info can be a prerequisite to establishing a sound Bitcoin transaction. With AMB Question, it’s easy to retrieve an inventory of spent and unspent transaction outputs for a given set of addresses, which is illustrated within the subsequent part.

The best way to use AMB Question to get an inventory of unspent transaction outputs

The ListFilteredTransactionEvents API takes an inventory of addresses and returns any relevant Bitcoin transaction VOUT occasions, each spent and unspent, pertaining to these addresses. Information is returned within the following format, which supplies the important thing properties that you could be use to populate a Bitcoin transaction with any variety of these unspent outputs:

HTTP/1.1 200
Content material-type: utility/json

{
   "occasions": [ 
      { 
         "blockchainInstant": { 
            "time": number
         },
         "confirmationStatus": "string",
         "contractAddress": "string",
         "eventType": "string",
         "from": "string",
         "network": "string",
         "spentVoutIndex": number,
         "spentVoutTransactionHash": "string",
         "spentVoutTransactionId": "string",
         "to": "string",
         "tokenId": "string",
         "transactionHash": "string",
         "transactionId": "string",
         "value": "string",
         "voutIndex": number,
         "voutSpent": boolean
      }
   ],
   "nextToken": "string"
}

Within the previous response format doc, you will discover a number of properties pertaining to spent and unspent transaction outputs. When retrieving spent transaction outputs, spentVoutTransactionHash, spentVoutTransactionId, and spentVoutIndex outline the transaction identifiers and the array place of the spent output (vout) so you may simply decide the origin of that output. For unspent transaction outputs, the properties transactionHash, transactionId, and voutIndex outline the transaction identifiers and the array place of the unspent output within the father or mother transaction. Moreover, the flag confirmationStatus defines whether or not the transaction containing the output is taken into account closing on the Bitcoin blockchain. In AMB Question, a transaction’s finality is outlined as equal to or higher than six confirmations, or blocks mined after the block by which the transaction is contained. Transactions thought of closing in keeping with this criterion might be marked FINAL, whereas unconfirmed transactions might be marked NONFINAL.

To raised illustrate the response from the API, the JavaScript code pattern defines a easy script to retrieve an inventory of unspent transaction outputs for a single Bitcoin tackle on the Bitcoin testnet. To run these Node.js examples, the next conditions apply:

• You will need to have node model supervisor (nvm) and Node.js put in in your machine. You will discover set up directions to your OS within the nvm GitHub repo.
• Use the node –model command and make sure that you’re utilizing Node version v18.12.0 (LTS) or increased. If required, you should use the nvm set up 18.12.0 command, adopted by the nvm use 18.12.0 command to put in.
• The setting variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY should comprise the credentials which might be related to the account. Export these variables as strings in your consumer through the use of the next instructions. Change the values within the following code with acceptable values from the AWS Identity and Access Management (IAM) person account.

Copy the next two code snippets to your native working listing, containing the code pattern (index.js) and package deal.json, which incorporates one dependency, the official AWS SDK module for AMB Question:

The next is the package deal.json code:

{
  "title": "query-bitcoin",
  "model": "1.0.0",
  "description": "",
  "major": "index.js",
  "scripts": {
    "take a look at": "echo "Error: no take a look at specified" && exit 1"
  },
  "creator": "",
  "license": "ISC",
  "dependencies": {
    "@aws-sdk/client-managedblockchain-query": "^3.538.0"
  }
}

The next is the index.js code:

const { ManagedBlockchainQueryClient, ListFilteredTransactionEventsCommand } = require("@aws-sdk/client-managedblockchain-query");

const listUnspentOutputs = async (addresses) => { 
  const consumer = new ManagedBlockchainQueryClient({ area: "us-east-1" });
  
  const enter = { // ListFilteredTransactionEventsInput
    addressIdentifierFilter: { 
      "transactionEventToAddress": [ ...addresses ]
    }, // record addresses to get occasions for 
    community: "BITCOIN_TESTNET", // outline the community, testnet or mainnet
    kind: { // kind order
      sortOrder: "ASCENDING",
    },
    maxResults: Quantity("250"),
    "voutFilter": { 
      "voutSpent": false // retrieve solely unspent outputs
   }
  };

  const command = new ListFilteredTransactionEventsCommand(enter);

  attempt {
    const information = await consumer.ship(command);
    console.log(information);
  } catch (error) {
    console.error(error);
  } 
}

listUnspentOutputs(['tb1qfrpw8av77mrmcf03epn5evfhv59z0t793jdh6t']) // enter the Bitcoin addresses of your alternative right here

To make use of this code, run the next command out of your working listing, changing the tackle outlined within the index.js with the addresses of your alternative, if desired:

npm i && node index.js

With the filter set for unspent transactions solely within the previous code pattern, the end result might be much like the next:

occasions: [
    {
      blockchainInstant: [Object],
      confirmationStatus: 'FINAL',
      eventType: 'BITCOIN_VOUT',
      community: 'BITCOIN_TESTNET',
      to: 'tb1qfrpw8av77mrmcf03epn5evfhv59z0t793jdh6t',
      tokenId: 'btc',
      transactionHash: '195d8c08bda48315b4ba3690264dcee36a7862f98c15d3dde9cf57bbbdf6c6ad',
      transactionId: '438961c65220ca0c9427614f9dcd2a7ca8a1e638e7702debae6aa28417045ce7',
      worth: '0.00001',
      voutIndex: 0,
      voutSpent: false
    },
    {
      blockchainInstant: [Object],
      confirmationStatus: 'FINAL',
      eventType: 'BITCOIN_VOUT',
      community: 'BITCOIN_TESTNET',
      to: 'tb1qfrpw8av77mrmcf03epn5evfhv59z0t793jdh6t',
      tokenId: 'btc',
      transactionHash: 'c1f2b279e50142fbbf62282e51c3e0a2f04247173f3b9dceef15345e12aa5db2',
      transactionId: '0ec51620a146b9d3e61b35fd68c7fa3e124a1b4bd2d582177fe9529a8c59158b',
      worth: '0.00001',
      voutIndex: 0,
      voutSpent: false
    },
    {
      blockchainInstant: [Object],
      confirmationStatus: 'FINAL',
      eventType: 'BITCOIN_VOUT',
      community: 'BITCOIN_TESTNET',
      to: 'tb1qfrpw8av77mrmcf03epn5evfhv59z0t793jdh6t',
      tokenId: 'btc',
      transactionHash: '347994d54743989fb65e8845d6d10b8cea87b0d4aa6c98dfcdd063735711be8a',
      transactionId: '8ce1bbf94989cc23a13d5bf2d44dbba51b2f50a4ab759cf1309e97a3eb7d5b76',
      worth: '0.00001',
      voutIndex: 0,
      voutSpent: false
    },
    {
      blockchainInstant: [Object],
      confirmationStatus: 'FINAL',
      eventType: 'BITCOIN_VOUT',
      community: 'BITCOIN_TESTNET',
      to: 'tb1qfrpw8av77mrmcf03epn5evfhv59z0t793jdh6t',
      tokenId: 'btc',
      transactionHash: 'd307359bbc4d68542f2c9c2bce73094280ad304b7240715305fcb3f80323308d',
      transactionId: '17ae7be33a27ab9bee81b91428abca423824e68be8e944399809a5f0fe197c90',
      worth: '0.00001545',
      voutIndex: 0,
      voutSpent: false
    }
  ]
}

Within the response, you may see that the transaction identifiers (transactionHash and transactionId), worth, and voutIndex are outlined for every unspent output, which might function inputs for establishing future Bitcoin transactions.

You’ll be able to modify the filters in your question to retrieve totally different information, akin to retrieving each unspent and spent outputs, or limiting the timespan for which to retrieve information. For extra details about these filters, seek advice from Request Body. Requests to AMB Question APIs are billed per request based mostly on pricing buckets per million requests. You’ll be able to view the newest pricing information for every API to calculate the price of requests to AMB Question.

Conclusion

On this publish, we outlined the basics of the UTXO mannequin made prevalent by Bitcoin, how UTXOs are central to transactions in Bitcoin, and methods to retrieve UTXO information utilizing AMB Question. To be taught extra about AMB Question, see What is Amazon Managed Blockchain (AMB) Query? To be taught extra about different Managed Blockchain choices, see Amazon Managed Blockchain.

Concerning the creator

Forrest Colyer manages the Web3/Blockchain Specialist Options Structure crew that helps the Amazon Managed Blockchain (AMB) service. Forrest and his crew assist clients at each stage of their adoption journey, from proof of idea to manufacturing, offering deep technical experience and strategic steerage to assist convey blockchain workloads to life. By means of his expertise with personal blockchain options led by consortia and public blockchain use instances like NFTs and DeFi, Forrest helps allow clients to establish and implement high-impact blockchain options.