@alexbosworth/blockchain 1.7.0 → 3.0.0

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Versions
 
-## 1.7.0
+## 3.0.0
+
+- `decodeBase58Address`: Add method to convert b58 address to hash and version
+
+### Breaking Changes
+
+- End support for Node.js v18, require v20+
+
+## 2.0.0
 
 - `idForTransactionComponents`: Add method to get transaction id for components
 - `queryTransactions`: Add method to find transaction outputs matching a query
 
+### Breaking Changes
+
+- End support for Node.js v16, require v18+
+
 ## 1.6.0
 
 - `previousBlockId`: Add method to get the previous block id from a block

package/README.md

@@ -56,6 +56,23 @@ Get the components of a hex-encoded transaction
       version: <Version Number>
     }
 
+### decodeBase58Address
+
+Derive output hash and version data from a base58 address string
+
+    {
+      address: <Base58 Encoded Address String>
+    }
+
+    @throws
+    <Error>
+
+    @returns
+    {
+      hash: <Output Hash Buffer Object>
+      version: <Script Version Byte Number>
+    }
+
 ### idForBlock
 
 Get an id for a block: the double sha256 hash of the block header

package/addresses/decode_base58_address.js

@@ -0,0 +1,129 @@
+const {createHash} = require('crypto');
+
+const base58Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const byteMask = 0xff;
+const {ceil} = Math;
+const countChecksumBytes = 4;
+const countHashBytes = 20;
+const countVersionBytes = 1;
+const leadingZeroCharCode = 0x31;
+const notFoundIndex = -1;
+const sha256 = preimage => createHash('sha256').update(preimage).digest();
+
+/** Derive output hash and version data from a base58 address string
+
+  {
+    address: <Base58 Encoded Address String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    hash: <Output Hash Buffer Object>
+    version: <Script Version Byte Number>
+  }
+*/
+module.exports = ({address}) => {
+  if (typeof address !== 'string') {
+    throw new Error('ExpectedBase58AddressStringToDecode');
+  }
+
+  // Ignore address string whitespace
+  const str = address.trim();
+
+  // Exit early with error on empty address, since it's not an address
+  if (!str.length) {
+    throw new Error('ExpectedNonEmptyBase58AddressToDecode');
+  }
+
+  let bytesLength = 0;
+  let countLeadingZeros = 0;
+  let index = 0;
+
+  // Iterate to determine the number of leading zeros to preserve
+  while (index < str.length && str.charCodeAt(index) === leadingZeroCharCode) {
+    countLeadingZeros++;
+    index++;
+  }
+
+  // Total bytes needed are log(58) / log(256) (256 values in a byte) = 0.732..
+  const workingSize = ceil((str.length - index) * 733 / 1000);
+
+  // Working buffer for the base256 (byte) representation, right-aligned
+  const working = new Uint8Array(workingSize);
+
+  // Iterate through the address characters and grab the decoded bytes
+  while (index < str.length) {
+    const value = base58Alphabet.indexOf(str[index]);
+
+    if (value === notFoundIndex) {
+      throw new Error('ExpectedAllBase58CharactersInBase58Address');
+    }
+
+    let carry = value;
+    let i = 0;
+
+    for (
+      let position = workingSize - 1;
+      (carry !== 0 || i < bytesLength) && position >= 0;
+      --position, ++i
+    ) {
+      carry += base58Alphabet.length * working[position];
+
+      // Take the least-significant byte
+      working[position] = carry & byteMask;
+
+      // Carry forward the remaining bytes
+      carry = (carry / 256) | 0;
+    }
+
+    // Track the number of bytes being used
+    bytesLength = i;
+
+    // Move to the next character in the address
+    index++;
+  }
+
+  // Meaningful bytes are right-aligned in working
+  const bytesStart = workingSize - bytesLength;
+  const meaningfulCount = workingSize - bytesStart;
+
+  // Final buffer: leading zeros plus meaningful bytes
+  const decoded = Buffer.alloc(countLeadingZeros + meaningfulCount);
+
+  // Make a view into the meaningful bytes
+  const dataBytes = working.subarray(bytesStart, bytesStart + meaningfulCount);
+
+  // Copy the meaningful bytes into the final decoded data
+  decoded.set(dataBytes, countLeadingZeros);
+
+  // Exit early with error when we don't have both a payload and checksum
+  if (decoded.length <= countChecksumBytes) {
+    throw new Error('ExpectedPayloadAndChecksumInBase58Address');
+  }
+
+  // The last bytes of a base58 address are a double sha256 checksum
+  const checksum = decoded.subarray(decoded.length - countChecksumBytes);
+
+  // Aside from the checksum there is a version byte and then a hash
+  const payload = decoded.subarray(0, decoded.length - countChecksumBytes);
+
+  // Make sure that we have a base58 payload that has the version and hash
+  if (payload.length !== countVersionBytes + countHashBytes) {
+    throw new Error('ExpectedVersionAnd20ByteHashInBase58AddressPayload');
+  }
+
+  // Calculate the checksum for the given payload
+  const payloadCheck = sha256(sha256(payload)).subarray(0, countChecksumBytes);
+
+  // Exit early with error when the double SHA256 of payload doesn't match
+  if (!checksum.equals(payloadCheck)) {
+    throw new Error('ExpectedValidPayloadChecksumInBase58Address');
+  }
+
+  const [version] = payload;
+
+  return {version, hash: payload.subarray(countVersionBytes)};
+};

package/addresses/index.js

@@ -0,0 +1,3 @@
+const decodeBase58Address = require('./decode_base58_address');
+
+module.exports = {decodeBase58Address};

package/index.js

@@ -1,5 +1,6 @@
 const {compactIntAsNumber} = require('./numbers');
 const {componentsOfTransaction} = require('./transactions');
+const {decodeBase58Address} = require('./addresses');
 const {idForBlock} = require('./hashes');
 const {idForTransactionComponents} = require('./hashes');
 const {noLocktimeIdForTransaction} = require('./transactions');
@@ -12,6 +13,7 @@ const {scriptElementsAsScript} = require('./script');
 module.exports = {
   compactIntAsNumber,
   componentsOfTransaction,
+  decodeBase58Address,
   idForBlock,
   idForTransactionComponents,
   noLocktimeIdForTransaction,

package/package.json

@@ -8,7 +8,7 @@
   },
   "description": "Blockchain data utility methods",
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
   },
   "license": "MIT",
   "name": "@alexbosworth/blockchain",
@@ -17,7 +17,7 @@
     "url": "https://github.com/alexbosworth/blockchain.git"
   },
   "scripts": {
-    "test": "npx nyc@15.1.0 node --experimental-test-coverage --test test/hashes/*.js test/numbers/*.js test/script/*.js test/transactions/*.js"
+    "test": "npx nyc@17.1.0 node --experimental-test-coverage --test test/addresses/*.js test/hashes/*.js test/numbers/*.js test/script/*.js test/transactions/*.js"
   },
-  "version": "1.7.0"
+  "version": "3.0.0"
 }

package/test/addresses/decode_base58_address.js

@@ -0,0 +1,70 @@
+const {deepEqual} = require('node:assert').strict;
+const test = require('node:test');
+const {throws} = require('node:assert').strict;
+
+const {decodeBase58Address} = require('./../../');
+
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+
+const tests = [
+  {
+    args: {},
+    description: 'An address is expected',
+    error: 'ExpectedBase58AddressStringToDecode',
+  },
+  {
+    args: {address: ' '},
+    description: 'A non-empty address is expected',
+    error: 'ExpectedNonEmptyBase58AddressToDecode',
+  },
+  {
+    args: {address: '16ro3Jptwo4asSevZnsRX6vfRS24TGE6uP'},
+    description: 'Address checksum must match',
+    error: 'ExpectedValidPayloadChecksumInBase58Address',
+  },
+  {
+    args: {address: '16ro3Jptwo4asSevZnsRX6vfRS24TGE6'},
+    description: 'Address checksum must be present',
+    error: 'ExpectedVersionAnd20ByteHashInBase58AddressPayload',
+  },
+  {
+    args: {address: '1'},
+    description: 'Address payload and checksum must be present',
+    error: 'ExpectedPayloadAndChecksumInBase58Address',
+  },
+  {
+    args: {address: '16ro3Jptwo4asSevZnsRX6vfRS24TGE6u!'},
+    description: 'Characters must be base58 set',
+    error: 'ExpectedAllBase58CharactersInBase58Address',
+  },
+  {
+    args: {address: '16ro3Jptwo4asSevZnsRX6vfRS24TGE6uK'},
+    description: 'A hash and version are returned for a p2pkh address',
+    expected: {
+      hash: hexAsBuffer('404371705fa9bd789a2fcd52d2c580b65d35549d'),
+      version: 0,
+    },
+  },
+  {
+    args: {address: '3P14159f73E4gFr7JterCCQh9QjiTjiZrG'},
+    description: 'A hash and version are returned for a p2sh address',
+    expected: {
+      hash: hexAsBuffer('e9c3dd0c07aac76179ebc76a6c78d4d67c6c160a'),
+      version: 5,
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, (t, end) => {
+    if (!!error) {
+      throws(() => decodeBase58Address(args), new Error(error), 'Err');
+    } else {
+      const res = decodeBase58Address(args);
+
+      deepEqual(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});