@alexbosworth/blockchain 1.0.0

package/.gitattributes

@@ -0,0 +1 @@
+package-lock.json binary

package/.tm_properties

@@ -0,0 +1 @@
+exclude = '{$exclude,node_modules,*~}'

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 1.0
+
+- Add `compactIntAsNumber` to convert a Bitcoin variable byte size int
+- Add `numberAsCompactInt` to convert a number to a Bitcoin variable byte int

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Alex Bosworth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Blockchain
+
+Utility methods for working with Blockchain data

package/index.js

@@ -0,0 +1,4 @@
+const {compactIntAsNumber} = require('./numbers');
+const {numberAsCompactInt} = require('./numbers');
+
+module.exports = {compactIntAsNumber, numberAsCompactInt};

package/numbers/compact_int_as_number.js

@@ -0,0 +1,53 @@
+const byteLength = n => n < 253 ? 1 : n < 254 ? 3 : n < 255 ? 5 : 9;
+const defaultOffset = 0;
+const {isBuffer} = Buffer;
+const isSafeNumber = n => n <= BigInt(Number.MAX_SAFE_INTEGER);
+const lengthMarkerOffset = 1;
+const limitBytes1 = 253;
+
+/** Convert a compact integer to a regular number
+
+  {
+    encoded: <Compact Integer Encoded Number Buffer Object>
+    [start]: <Buffer Offset Start Index Number>
+  }
+
+  @returns
+  {
+    bytes: <Byte Count Number>
+    number: <Integer Number>
+  }
+*/
+module.exports = ({encoded, start}) => {
+  if (!isBuffer(encoded)) {
+    throw new Error('ExpectedBufferToConvertCompactIntegerToNumber');
+  }
+
+  const offset = start || defaultOffset;
+
+  // The total byte count of the compact integer is given by the first byte
+  const size = encoded.readUInt8(offset);
+
+  // Convert the first byte into the byte length of the encoding
+  const bytes = byteLength(size);
+
+  switch (bytes) {
+  case 1:
+    return {bytes, number: size};
+
+  case 3:
+    return {bytes, number: encoded.readUInt16LE(offset + lengthMarkerOffset)};
+
+  case 5:
+    return {bytes, number: encoded.readUInt32LE(offset + lengthMarkerOffset)};
+
+  default:
+    const number = encoded.readBigUInt64LE(offset + lengthMarkerOffset);
+
+    if (!isSafeNumber(number)) {
+      throw new Error('ExpectedSafeSizeEncodedCompactInteger');
+    }
+
+    return {bytes, number: Number(number)};
+  }
+};

package/numbers/index.js

@@ -0,0 +1,4 @@
+const compactIntAsNumber = require('./compact_int_as_number');
+const numberAsCompactInt = require('./number_as_compact_int');
+
+module.exports = {compactIntAsNumber, numberAsCompactInt};

package/numbers/number_as_compact_int.js

@@ -0,0 +1,55 @@
+const isSafeNumber = n => Number.isInteger(n) && n <= Number.MAX_SAFE_INTEGER;
+const byteLength = n => n < 253 ? 1 : n <= 65535 ? 3 : n <= 4294967295 ? 5 : 9;
+const byteLengthMarkerOffset = 1;
+const limitBytes1 = 253;
+const limitBytes2 = 65535;
+const limitBytes4 = 4294967295;
+const markerBytes2 = 253;
+const markerBytes4 = 254;
+const markerBytes8 = 255;
+const rightShift = 0;
+
+/** Convert a number to compact size integer serialization
+
+  {
+    number: <Amount to Convert to Compact Integer Serialization Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    encoded: <Serialized Compact Integer Buffer Object>
+  }
+*/
+module.exports = ({number}) => {
+  if (!isSafeNumber(number)) {
+    throw new Error('ExpectedEncodeSafeNumberToEncodeAsCompactInteger');
+  }
+
+  const encoded = Buffer.alloc(byteLength(number));
+
+  switch (encoded.length) {
+  case 1:
+    encoded.writeUInt8(number);
+    break;
+
+  case 3:
+    encoded.writeUInt8(markerBytes2);
+    encoded.writeUInt16LE(number, byteLengthMarkerOffset);
+    break;
+
+  case 5:
+    encoded.writeUInt8(markerBytes4);
+    encoded.writeUInt32LE(number, byteLengthMarkerOffset);
+    break;
+
+  default:
+    encoded.writeUInt8(markerBytes8);
+    encoded.writeBigUInt64LE(BigInt(number), byteLengthMarkerOffset);
+    break;
+  }
+
+  return {encoded};
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "author": {
+    "name": "Alex Bosworth",
+    "url": "https://twitter.com/alexbosworth"
+  },
+  "bugs": {
+    "url": "https://github.com/alexbosworth/blockchain/issues"
+  },
+  "description": "Blockchain data utility methods",
+  "devDependencies": {
+    "@alexbosworth/tap": "15.0.12"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "name": "@alexbosworth/blockchain",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexbosworth/blockchain.git"
+  },
+  "scripts": {
+    "test": "tap -j 2 --branches=1 --functions=1 --lines=1 --statements=1 -t 200 test/numbers/*.js"
+  },
+  "version": "1.0.0"
+}

package/test/numbers/test_compact_int_as_number.js

@@ -0,0 +1,77 @@
+const {test} = require('@alexbosworth/tap');
+
+const {compactIntAsNumber} = require('./../../');
+
+const tests = [
+  {
+    args: {encoded: ''},
+    description: 'Encoded bytes are expected',
+    error: 'ExpectedBufferToConvertCompactIntegerToNumber',
+  },
+  {
+    args: {encoded: 'ffffffffffffffffff'},
+    description: 'Too large numbers are not supported',
+    error: 'ExpectedSafeSizeEncodedCompactInteger',
+  },
+  {
+    args: {encoded: '00'},
+    description: 'Smallest possible one byte number decoded',
+    expected: {bytes: 1, number: 0},
+  },
+  {
+    args: {encoded: 'fc'},
+    description: 'Largest possible one byte number decoded',
+    expected: {bytes: 1, number: 252},
+  },
+  {
+    args: {encoded: '00fcffffff', start: 1},
+    description: 'Largest possible one byte number decoded with offset',
+    expected: {bytes: 1, number: 252},
+  },
+  {
+    args: {encoded: 'fdfd00'},
+    description: 'Smallest possible two byte number decoded',
+    expected: {bytes: 3, number: 253},
+  },
+  {
+    args: {encoded: 'fdffff'},
+    description: 'Largest possible two byte number decoded',
+    expected: {bytes: 3, number: 65535}
+  },
+  {
+    args: {encoded: 'fe00000100'},
+    description: 'Smallest possible four byte number decoded',
+    expected: {bytes: 5, number: 65536},
+  },
+  {
+    args: {encoded: 'feffffffff'},
+    description: 'Largest possible four byte number decoded',
+    expected: {bytes: 5, number: 4294967295},
+  },
+  {
+    args: {encoded: 'ff0000000001000000'},
+    description: 'Smallest possible eight byte number decoded',
+    expected: {bytes: 9, number: 4294967296},
+  },
+  {
+    args: {encoded: 'ffffffffffffff1f00'},
+    description: 'Max safe integer decoded',
+    expected: {bytes: 9, number: 9007199254740991},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    args.encoded = !!args.encoded ? Buffer.from(args.encoded, 'hex') : null;
+
+    if (!!error) {
+      throws(() => compactIntAsNumber(args), new Error(error), 'Error');
+    } else {
+      const res = compactIntAsNumber(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/test/numbers/test_number_as_compact_int.js

@@ -0,0 +1,70 @@
+const {test} = require('@alexbosworth/tap');
+
+const {numberAsCompactInt} = require('./../../');
+
+const tests = [
+  {
+    args: {number: 0.1},
+    description: 'Fractional numbers are not allowed',
+    error: 'ExpectedEncodeSafeNumberToEncodeAsCompactInteger',
+  },
+  {
+    args: {number: Number.MAX_SAFE_INTEGER + 1},
+    description: 'Large numbers are not allowed',
+    error: 'ExpectedEncodeSafeNumberToEncodeAsCompactInteger',
+  },
+  {
+    args: {number: 0},
+    description: 'Smallest possible one byte number encoded',
+    expected: '00',
+  },
+  {
+    args: {number: 252},
+    description: 'Largest possible one byte number encoded',
+    expected: 'fc',
+  },
+  {
+    args: {number: 253},
+    description: 'Smallest possible two byte number encoded',
+    expected: 'fdfd00',
+  },
+  {
+    args: {number: 65535},
+    description: 'Largest possible two byte number encoded',
+    expected: 'fdffff',
+  },
+  {
+    args: {number: 65536},
+    description: 'Smallest possible four byte number encoded',
+    expected: 'fe00000100',
+  },
+  {
+    args: {number: 4294967295},
+    description: 'Largest possible four byte number encoded',
+    expected: 'feffffffff',
+  },
+  {
+    args: {number: 4294967296},
+    description: 'Smallest possible eight byte number encoded',
+    expected: 'ff0000000001000000',
+  },
+  {
+    args: {number: 9007199254740991},
+    description: 'Max safe integer encoded',
+    expected: 'ffffffffffffff1f00',
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    if (!!error) {
+      throws(() => numberAsCompactInt(args), new Error(error), 'Error');
+    } else {
+      const res = numberAsCompactInt(args);
+
+      strictSame(res.encoded.toString('hex'), expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});