@alexbosworth/blockchain 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Versions
 
+## 1.7.0
+
+- `idForTransactionComponents`: Add method to get transaction id for components
+- `queryTransactions`: Add method to find transaction outputs matching a query
+
 ## 1.6.0
 
 - `previousBlockId`: Add method to get the previous block id from a block

package/README.md

@@ -72,6 +72,33 @@ Get an id for a block: the double sha256 hash of the block header
       id: <Block Id Hex Encoded String>
     }
 
+### idForTransactionComponents
+
+Determine a transaction id from transaction components
+
+    {
+      inputs: [{
+        hash: <Spending Internal Byte Order Transaction Id Buffer Object>
+        script: <Script Buffer Object>
+        sequence: <Sequence Number>
+        vout: <Spending Transaction Output Index Number>
+      }]
+      locktime: <Timelock nLockTime Number>
+      outputs: [{
+        script: <Output Script Buffer Object>
+        tokens: <Tokens Count Number>
+      }]
+      version: <Version Number>
+    }
+
+    @throws
+    <Error>
+
+    @returns
+    {
+      id: <Transaction Id Hex String>
+    }
+
 ### noLocktimeIdForTransaction
 
 Get an id for a transaction with witness data and mlocktime not included
@@ -121,6 +148,28 @@ Given a raw block, return the previous block id
       previous: <Previous Block Id Hex String>
     }
 
+### queryTransactions
+
+Find matching transactions within a block
+
+    {
+      block: <Hex Encoded Raw Block String>
+      outputs: [<Output Script Hex String>]
+    }
+
+    @throws
+    <Error>
+
+    @returns
+    {
+      outputs: [{
+        script: <Output Script Hex String>
+        tokens: <Output Value Number>
+        transaction_id: <Transaction Id Hex String>
+        transaction_vout: <Transaction Output Index Number>
+      }]
+    }
+
 ### scriptAsScriptElements
 
 Map a serialized script into an array of script elements

package/hashes/id_for_transaction_components.js

@@ -0,0 +1,99 @@
+const {createHash} = require('crypto');
+
+const {numberAsCompactInt} = require('./../numbers');
+
+const {alloc} = Buffer;
+const bufferAsHex = buffer => buffer.toString('hex');
+const byteCountHash = 32;
+const byteCountInt32 = 4;
+const byteCountInt64 = 8;
+const {concat} = Buffer;
+const sha256 = preimage => createHash('sha256').update(preimage).digest();
+
+/** Determine a transaction id from transaction components
+
+  {
+    inputs: [{
+      hash: <Spending Internal Byte Order Transaction Id Buffer Object>
+      script: <Script Buffer Object>
+      sequence: <Sequence Number>
+      vout: <Spending Transaction Output Index Number>
+    }]
+    locktime: <Timelock nLockTime Number>
+    outputs: [{
+      script: <Output Script Buffer Object>
+      tokens: <Tokens Count Number>
+    }]
+    version: <Version Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    id: <Transaction Id Hex String>
+  }
+*/
+module.exports = ({inputs, locktime, outputs, version}) => {
+  const elements = [];
+
+  // Write the signed transaction version number
+  const ver = alloc(byteCountInt32);
+
+  ver.writeInt32LE(version);
+
+  elements.push(ver);
+
+  // Write how many inputs there are
+  elements.push(numberAsCompactInt({number: inputs.length}).encoded);
+
+  // Write the inputs
+  elements.push(concat(inputs.map(input => {
+    // Encode the sequence number
+    const sequence = alloc(byteCountInt32);
+
+    sequence.writeUInt32LE(input.sequence);
+
+    // Encode the spend output index
+    const vout = alloc(byteCountInt32);
+
+    vout.writeUInt32LE(input.vout);
+
+    // Write the spend outpoint, script sig, sequence number
+    return concat([
+      input.hash,
+      vout,
+      numberAsCompactInt({number: input.script.length}).encoded,
+      input.script,
+      sequence,
+    ]);
+  })));
+
+  // Write the outputs count
+  elements.push(numberAsCompactInt({number: outputs.length}).encoded);
+
+  elements.push(concat(outputs.map(output => {
+    // Encode the output value
+    const value = alloc(byteCountInt64);
+
+    value.writeBigUInt64LE(BigInt(output.tokens));
+
+    // Write the output value and output script
+    return concat([
+      value,
+      numberAsCompactInt({number: output.script.length}).encoded,
+      output.script,
+    ]);
+  })));
+
+  // Write the locktime
+  const timelock = alloc(byteCountInt32);
+
+  timelock.writeUInt32LE(locktime);
+
+  elements.push(timelock);
+
+  // The id is the double sha256 hash of the elements, reversed
+  return {id: bufferAsHex(sha256(sha256(concat(elements))).reverse())};
+};

package/hashes/index.js

@@ -1,5 +1,9 @@
 const idForBlock = require('./id_for_block');
-const noLocktimeIdForTransaction = require('./no_locktime_id_for_transaction');
+const idForTransactionComponents = require('./id_for_transaction_components');
 const previousBlockId = require('./previous_block_id');
 
-module.exports = {idForBlock, noLocktimeIdForTransaction, previousBlockId};
+module.exports = {
+  idForBlock,
+  idForTransactionComponents,
+  previousBlockId,
+};

package/index.js

@@ -1,9 +1,11 @@
 const {compactIntAsNumber} = require('./numbers');
 const {componentsOfTransaction} = require('./transactions');
 const {idForBlock} = require('./hashes');
-const {noLocktimeIdForTransaction} = require('./hashes');
+const {idForTransactionComponents} = require('./hashes');
+const {noLocktimeIdForTransaction} = require('./transactions');
 const {numberAsCompactInt} = require('./numbers');
 const {previousBlockId} = require('./hashes');
+const {queryTransactions} = require('./transactions');
 const {scriptAsScriptElements} = require('./script');
 const {scriptElementsAsScript} = require('./script');
 
@@ -11,9 +13,11 @@ module.exports = {
   compactIntAsNumber,
   componentsOfTransaction,
   idForBlock,
+  idForTransactionComponents,
   noLocktimeIdForTransaction,
   numberAsCompactInt,
   previousBlockId,
+  queryTransactions,
   scriptAsScriptElements,
   scriptElementsAsScript,
 };

package/package.json

@@ -17,7 +17,7 @@
     "url": "https://github.com/alexbosworth/blockchain.git"
   },
   "scripts": {
-    "test": "npx nyc@latest node --experimental-test-coverage --test test/hashes/*.js test/numbers/*.js test/script/*.js test/transactions/*.js"
+    "test": "npx nyc@15.1.0 node --experimental-test-coverage --test test/hashes/*.js test/numbers/*.js test/script/*.js test/transactions/*.js"
   },
-  "version": "1.6.0"
+  "version": "1.7.0"
 }

package/test/hashes/test_id_for_block.js

@@ -1,4 +1,4 @@
-const {deepStrictEqual} = require('node:assert').strict;
+const {deepEqual} = require('node:assert').strict;
 const test = require('node:test');
 const {throws} = require('node:assert').strict;
 
@@ -30,7 +30,7 @@ tests.forEach(({args, description, error, expected}) => {
     } else {
       const res = idForBlock(args);
 
-      deepStrictEqual(res, expected, 'Got expected result');
+      deepEqual(res, expected, 'Got expected result');
     }
 
     return end();

package/test/hashes/test_no_locktime_id_for_transaction.js

@@ -1,4 +1,4 @@
-const {deepStrictEqual} = require('node:assert').strict;
+const {deepEqual} = require('node:assert').strict;
 const {throws} = require('node:assert').strict;
 const test = require('node:test');
 
@@ -48,7 +48,7 @@ tests.forEach(({args, description, error, expected}) => {
     } else {
       const res = noLocktimeIdForTransaction(args);
 
-      deepStrictEqual(res, expected, 'Got expected result');
+      deepEqual(res, expected, 'Got expected result');
     }
 
     return end();

package/test/transactions/test_query_transactions.js

@@ -0,0 +1,51 @@
+const {deepStrictEqual} = require('node:assert').strict;
+const {throws} = require('node:assert').strict;
+const test = require('node:test');
+
+const {queryTransactions} = require('./../../');
+
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+
+const tests = [
+  {
+    args: {},
+    description: 'A block is required',
+    error: 'ExpectedHexEncodedBlockToQueryTransactions',
+  },
+  {
+    args: {
+      block: '00008020b43ebc848b8a78430f745b58dd0cfecb5a41fda1f9a0793833a98dad00000000cbbb00aa6ab7ea52d99e87088d2d80e7ca27f217f4cb8bc7ac635f17a1ff336900ccd364f4422e1906713cdb07010000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff1a03bcb725012013090909200909200904686700c4ee5902000000ffffffff022162250000000000160014820d4a343a44e915c36494995c2899abe37418930000000000000000266a24aa21a9ed78afc412c2c7c1b3135c2a2473a6837068c5ea891e5068d396041057114a749501200000000000000000000000000000000000000000000000000000000000000000000000000100000001ce99c6498760022c4a268bb2bd553b71c5dd7e705ad47704ca2b8cdf72b2d755030000006b483045022100ca65bd58a725c83c3420874e4e0017562ef451f1df17eb42cfd35ee9dd28f98902204a6aafb47a2e1492e50cb0c7038000741d952e3770f9a1f9c9a6229c124e5e790121037435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1dfdffffff040000000000000000536a4c5054325bb3a276c4f8c7ecdccd704cf9a0e691db1364e66648672e23871de8b005816f3ec0ecda15e15dbec4e7f2be15f1e4e52e72c187deb36bd3b89d9793ea0e7c71e00025b7b9000f0025b12400114a10270000000000001976a914000000000000000000000000000000000000000088ac10270000000000001976a914000000000000000000000000000000000000000088acb2e8ae08000000001976a914ba27f99e007c7f605a8305e318c1abde3cd220ac88ac00000000010000000001014d4f50b9002361be3b82382e628e41ec29ffb5a28abec8a59ebbf4f28ba4675401000000171600142642be55762762143195a7eb3b965fcc47df9000ffffffff013b0d0000000000001600146ad03f5c84f201cbcbae045ffb9a8b9d769f83d40247304402205993d5c216bcb968c8ed1a99d67a3e4bcf54434c29ffc1bd72c49769d4814f6302200a40821effc9c1fb00d6de454b35244cb70f294b7f3971fee796b9a302f7efa1012103eadead8e5b3a54e36ad936096bd4ca8960ef753b2d81db9afb4ce7a458155e2e0000000002000000000101a4a1f7f07d0d95cd22e7039646133cb29d7b3c5ec55f86720f9cfbd0aa5d155001000000000000000002102700000000000017a91423269e856a01136288e09d8ea5049f5e64d56399872ca218000000000016001456ddc1cec4c3cf468646d6cc2d531d232d43dd4502473044022069f7f79e6c8cfe3ad43e9a5e3da0d77f93169bd4d98a9ef1f5d521340510d688022053b18b1914a40b2b60cb453d8421fa8f2d1c05c9f084b90f38092379276281c701210216243ae4738f200518bf8f0204f6b95e408aadd65f553bad98f0f8a9fd7472eb0000000002000000000102c9f48fe21843a24377835106e94e3ecee80e128027a4fa84d9371df56464b0190000000000fdffffffc9f48fe21843a24377835106e94e3ecee80e128027a4fa84d9371df56464b0190100000000fdffffff01e7170000000000001976a91459cada50314c829e19f5a7786f8ee0d4987f429d88ac0247304402204d578466dad41a451ac42a58bfb15b4ede988181ca384d3d7dfc158289dc369402205b35dd90b83ed4b02ccd300b370d57d3f919d4a100280ba9b2b68feef6f75e720121039757fd1ca6e33c3433cd8de13178dfd50f5688b688301a932cc4eba38e85e80c02473044022052dbdb28b87d8bed9edb8abc664452ad4bd85dd0c068f61a4bffa92a66748d090220674e642420b027c00dc3a0fcec74f53fdd31b9bcd76d20397ef9c8f61a45788c01210251db63b01e13ff7656cb606d732970b4760466162c83e041e018846c627760a1bab7250002000000011e43091d1b554f7e3ce175241aba175bf797996dda991bfdc34fc5cb8298ee5e010000006a473044022027af54aec1a603c1260312241f6cc27d49db4d79cb946a3fb56aff6c8e5e4132022022d3954e49699d369480624c3e8397fd361d9baffdd700d1e9882b465e523b670121021bc2b79284dca29127ed41021571fd3026157c01b4fef8824e94976592b165b3fdffffff0280d725000000000016001475f1d3e5088db87f9a336287cb55142d2062ada3ab72000000000000160014f5e5e9b3af38635bf6992f9732206d0ccb421e9ebbb7250001000000017c1194e8b17d9d26aaba8a78c2cd84490d96d5405619da3b2a9f454860b18911010000006b483045022100e1a219e719575a51e70ccfb06a1968dfd6d2055a3c46664ede399b8a3aab7f8902204b7994dec9e0a6f74e4db0d5a0a06738bd608476160c530392f8f220ad3cb4c6012103ef3f06ff6ea92d1b0a4693ed3f83ad45740b02259739e6427209cb88581416a0ffffffff0278350000000000001976a914e830afe90f87e5c561df7e66ef530d4dd8ea182088ac55d61300000000001976a914fe0f6279060ba6bc6a8b4375d7de8cf8b35a683788ac00000000',
+    },
+    description: 'An outputs array is required',
+    error: 'ExpectedArrayOfOutputsToQueryTransactionsInBlock',
+  },
+  {
+    args: {
+      block: '00008020b43ebc848b8a78430f745b58dd0cfecb5a41fda1f9a0793833a98dad00000000cbbb00aa6ab7ea52d99e87088d2d80e7ca27f217f4cb8bc7ac635f17a1ff336900ccd364f4422e1906713cdb07010000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff1a03bcb725012013090909200909200904686700c4ee5902000000ffffffff022162250000000000160014820d4a343a44e915c36494995c2899abe37418930000000000000000266a24aa21a9ed78afc412c2c7c1b3135c2a2473a6837068c5ea891e5068d396041057114a749501200000000000000000000000000000000000000000000000000000000000000000000000000100000001ce99c6498760022c4a268bb2bd553b71c5dd7e705ad47704ca2b8cdf72b2d755030000006b483045022100ca65bd58a725c83c3420874e4e0017562ef451f1df17eb42cfd35ee9dd28f98902204a6aafb47a2e1492e50cb0c7038000741d952e3770f9a1f9c9a6229c124e5e790121037435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1dfdffffff040000000000000000536a4c5054325bb3a276c4f8c7ecdccd704cf9a0e691db1364e66648672e23871de8b005816f3ec0ecda15e15dbec4e7f2be15f1e4e52e72c187deb36bd3b89d9793ea0e7c71e00025b7b9000f0025b12400114a10270000000000001976a914000000000000000000000000000000000000000088ac10270000000000001976a914000000000000000000000000000000000000000088acb2e8ae08000000001976a914ba27f99e007c7f605a8305e318c1abde3cd220ac88ac00000000010000000001014d4f50b9002361be3b82382e628e41ec29ffb5a28abec8a59ebbf4f28ba4675401000000171600142642be55762762143195a7eb3b965fcc47df9000ffffffff013b0d0000000000001600146ad03f5c84f201cbcbae045ffb9a8b9d769f83d40247304402205993d5c216bcb968c8ed1a99d67a3e4bcf54434c29ffc1bd72c49769d4814f6302200a40821effc9c1fb00d6de454b35244cb70f294b7f3971fee796b9a302f7efa1012103eadead8e5b3a54e36ad936096bd4ca8960ef753b2d81db9afb4ce7a458155e2e0000000002000000000101a4a1f7f07d0d95cd22e7039646133cb29d7b3c5ec55f86720f9cfbd0aa5d155001000000000000000002102700000000000017a91423269e856a01136288e09d8ea5049f5e64d56399872ca218000000000016001456ddc1cec4c3cf468646d6cc2d531d232d43dd4502473044022069f7f79e6c8cfe3ad43e9a5e3da0d77f93169bd4d98a9ef1f5d521340510d688022053b18b1914a40b2b60cb453d8421fa8f2d1c05c9f084b90f38092379276281c701210216243ae4738f200518bf8f0204f6b95e408aadd65f553bad98f0f8a9fd7472eb0000000002000000000102c9f48fe21843a24377835106e94e3ecee80e128027a4fa84d9371df56464b0190000000000fdffffffc9f48fe21843a24377835106e94e3ecee80e128027a4fa84d9371df56464b0190100000000fdffffff01e7170000000000001976a91459cada50314c829e19f5a7786f8ee0d4987f429d88ac0247304402204d578466dad41a451ac42a58bfb15b4ede988181ca384d3d7dfc158289dc369402205b35dd90b83ed4b02ccd300b370d57d3f919d4a100280ba9b2b68feef6f75e720121039757fd1ca6e33c3433cd8de13178dfd50f5688b688301a932cc4eba38e85e80c02473044022052dbdb28b87d8bed9edb8abc664452ad4bd85dd0c068f61a4bffa92a66748d090220674e642420b027c00dc3a0fcec74f53fdd31b9bcd76d20397ef9c8f61a45788c01210251db63b01e13ff7656cb606d732970b4760466162c83e041e018846c627760a1bab7250002000000011e43091d1b554f7e3ce175241aba175bf797996dda991bfdc34fc5cb8298ee5e010000006a473044022027af54aec1a603c1260312241f6cc27d49db4d79cb946a3fb56aff6c8e5e4132022022d3954e49699d369480624c3e8397fd361d9baffdd700d1e9882b465e523b670121021bc2b79284dca29127ed41021571fd3026157c01b4fef8824e94976592b165b3fdffffff0280d725000000000016001475f1d3e5088db87f9a336287cb55142d2062ada3ab72000000000000160014f5e5e9b3af38635bf6992f9732206d0ccb421e9ebbb7250001000000017c1194e8b17d9d26aaba8a78c2cd84490d96d5405619da3b2a9f454860b18911010000006b483045022100e1a219e719575a51e70ccfb06a1968dfd6d2055a3c46664ede399b8a3aab7f8902204b7994dec9e0a6f74e4db0d5a0a06738bd608476160c530392f8f220ad3cb4c6012103ef3f06ff6ea92d1b0a4693ed3f83ad45740b02259739e6427209cb88581416a0ffffffff0278350000000000001976a914e830afe90f87e5c561df7e66ef530d4dd8ea182088ac55d61300000000001976a914fe0f6279060ba6bc6a8b4375d7de8cf8b35a683788ac00000000',
+      outputs: ['00146ad03f5c84f201cbcbae045ffb9a8b9d769f83d4'],
+    },
+    description: 'A block is queried for transaction outputs',
+    expected: {
+      outputs: [{
+        script: '00146ad03f5c84f201cbcbae045ffb9a8b9d769f83d4',
+        tokens: 3387,
+        transaction_id: 'e3a79c31b81c2852ff7eaf170900842e8060dba9afc1613f09a4b387793d56e0',
+        transaction_vout: 0,
+      }],
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, (t, end) => {
+    if (!!error) {
+      throws(() => queryTransactions(args), new Error(error), 'Got err');
+    } else {
+      const res = queryTransactions(args);
+
+      deepStrictEqual(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/transactions/index.js

@@ -1,4 +1,11 @@
 const componentsOfTransaction = require('./components_of_transaction');
+const noLocktimeIdForTransaction = require('./no_locktime_id_for_transaction');
 const parseTransaction = require('./parse_transaction');
+const queryTransactions = require('./query_transactions');
 
-module.exports = {componentsOfTransaction, parseTransaction};
+module.exports = {
+  componentsOfTransaction,
+  noLocktimeIdForTransaction,
+  parseTransaction,
+  queryTransactions,
+};

package/{hashes → transactions}/no_locktime_id_for_transaction.js

@@ -1,6 +1,6 @@
 const {createHash} = require('crypto');
 
-const {parseTransaction} = require('./../transactions');
+const parseTransaction = require('./parse_transaction');
 
 const bufferAsHex = buffer => buffer.toString('hex');
 const sha256 = preimage => createHash('sha256').update(preimage).digest();

package/transactions/parse_transaction.js

@@ -19,7 +19,7 @@ const times = n => [...Array(n).keys()];
 
   {
     buffer: <Data Buffer Object>
-    is_terminating_after_outputs: <Ignore Data After Outputs Bool>
+    [is_terminating_after_outputs]: <Ignore Data After Outputs Bool>
     [start]: <Starting Offset Index Number>
   }
 

package/transactions/query_transactions.js

@@ -0,0 +1,76 @@
+const {createHash} = require('crypto');
+
+const {idForTransactionComponents} = require('./../hashes');
+const parseTransaction = require('./parse_transaction');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const transactionsStartIndex = 81;
+
+/** Find matching transactions within a block
+
+  {
+    block: <Hex Encoded Raw Block String>
+    outputs: [<Output Script Hex String>]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    outputs: [{
+      script: <Output Script Hex String>
+      tokens: <Output Value Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+  }
+*/
+module.exports = ({block, outputs}) => {
+  if (!block) {
+    throw new Error('ExpectedHexEncodedBlockToQueryTransactions');
+  }
+
+  if (!isArray(outputs)) {
+    throw new Error('ExpectedArrayOfOutputsToQueryTransactionsInBlock');
+  }
+
+  const buffer = hexAsBuffer(block);
+  let cursor = transactionsStartIndex;
+  const hits = [];
+
+  // Iterate forward through the block, parsing txs and looking for hits
+  while (cursor < buffer.length) {
+    const tx = parseTransaction({buffer, start: cursor});
+
+    // Look at the transaction outputs to see if there is a match
+    const matches = tx.outputs.forEach((output, vout) => {
+      // Exit early when the script isn't included in the outputs
+      if (!outputs.includes(bufferAsHex(output.script))) {
+        return;
+      }
+
+      // Calculate the transaction id
+      const {id} = idForTransactionComponents({
+        inputs: tx.inputs,
+        locktime: tx.locktime,
+        outputs: tx.outputs,
+        version: tx.version,
+      });
+
+      // Add the output to found hits
+      return hits.push({
+        script: bufferAsHex(output.script),
+        tokens: output.tokens,
+        transaction_id: id,
+        transaction_vout: vout,
+      });
+    });
+
+    cursor += tx.bytes.length;
+  }
+
+  return {outputs: hits};
+};