@rsksmart/btc-transaction-solidity-helper 0.0.3 → 0.2.1

package/Readme.md

@@ -1,14 +1,16 @@
 # Bitcoin Transaction Solidity Helper
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/rsksmart/btc-transaction-solidity-helper/badge)](https://scorecard.dev/viewer/?uri=github.com/rsksmart/btc-transaction-solidity-helper)
 
 The intention of this library is to make easier to work with Bitcoin transactions in Solidity smart contracts. Since Rootstock extends Bitcoin's capabilities by enabling smart contracts it is important to be able to work with Bitcoin transactions in them.
 
 ## Features
 
 The features of this library include:
-* Bitcoin transaction output parsing: is able to receive a raw tx and return an array of structs with the tx outputs
+* Bitcoin transaction output parsing: is able to receive a raw tx and return an array of structures with the tx outputs
 * Bitcoin transaction hashing: is able to receive a raw tx and return its hash
-* Bitcoin transaction output script validation: is able to receive a raw output script, validate that is from a specific type and return a result. E.g. receive a raw null-data script and return the embeded data in it
+* Bitcoin transaction output script validation: is able to receive a raw output script, validate that is from a specific type and return a result. E.g. receive a raw null-data script and return the embedded data in it
 * Bitcoin address generation: is able to generate Bitcoin the address from a specific script and also to validate if a given address was generated from a script or not.
+* Bitcoin address validation: is able to validate if a Bitcoin address is of a given type or not.
 
 ### Future features
 These are some features that can increase the library capabilities in the future:
@@ -28,4 +30,4 @@ These are some features that can increase the library capabilities in the future
  ```solidity
     BtcUtils.TxRawOutput[] memory outputs = BtcUtils.getOutputs(btcTx);
     bytes memory btcTxDestination = BtcUtils.parseNullDataScript(outputs[0].pkScript, false);
- ```  
+ ```

package/contracts/BtcUtils.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.18;
 
+import "./OpCodes.sol";
+
 /**
  * @title BtcUtils
  * @notice This library contains functionality to make easier to work with Bitcoin transactions in Solidity.
@@ -10,11 +12,27 @@ pragma solidity ^0.8.18;
 library BtcUtils {
     uint8 private constant MAX_COMPACT_SIZE_LENGTH = 252;
     uint8 private constant MAX_BYTES_USED_FOR_COMPACT_SIZE = 8;
+
+    uint private constant HASH160_SIZE = 20;
+    uint private constant SHA256_SIZE = 32;
+    uint private constant TAPROOT_PUBKEY_SIZE = 32;
+
     uint8 private constant OUTPOINT_SIZE = 36;
     uint8 private constant OUTPUT_VALUE_SIZE = 8;
-    uint8 private constant PUBKEY_HASH_SIZE = 20;
+
     uint8 private constant PUBKEY_HASH_START = 3;
-    uint8 private constant CHECK_BYTES_FROM_HASH = 4;
+    bytes1 private constant PUBKEY_HASH_MAINNET_BYTE = 0x00;
+    bytes1 private constant PUBKEY_HASH_TESTNET_BYTE = 0x6f;
+
+    uint8 private constant SCRIPT_HASH_START = 2;
+    bytes1 private constant SCRIPT_HASH_MAINNET_BYTE = 0x05;
+    bytes1 private constant SCRIPT_HASH_TESTNET_BYTE = 0xc4;
+
+    uint private constant BECH32_WORD_SIZE = 5;
+    uint private constant BYTE_SIZE = 8;
+
+    bytes1 private constant WITNESS_VERSION_0 = 0x00;
+    bytes1 private constant WITNESS_VERSION_1 = 0x01;
 
 
     /**
@@ -28,6 +46,10 @@ library BtcUtils {
         uint256 totalSize;
     }
 
+    function version() external pure returns (string memory) {
+        return "0.2.1";
+    }
+
     /// @notice Parse a raw transaction to get an array of its outputs in a structured representation
     /// @param rawTx the raw transaction
     /// @return An array of `TxRawOutput` with the outputs of the transaction
@@ -61,7 +83,7 @@ library BtcUtils {
     }
 
     function extractRawOutput(uint position, bytes memory rawTx) private pure returns (TxRawOutput memory) {
-        TxRawOutput memory result;
+        TxRawOutput memory result = TxRawOutput(0, "", 0, 0);
         result.value = uint64(calculateLittleEndianFragment(position, position + OUTPUT_VALUE_SIZE, rawTx));
         position += OUTPUT_VALUE_SIZE;
 
@@ -78,42 +100,164 @@ library BtcUtils {
         return result;
     }
 
-    /// @notice Parse a raw pay-to-public-key-hash output script to get the corresponding address
+    /// @notice Parse a raw output script whose type is not known by the consumer. The function will
+    /// return the corresponding address if the type of the script is supported or an error if not.
+    /// For the addresses that are encoded with base58check the checksum bytes are not included in
+    /// the resulting byte array
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
+    /// @param mainnet if the address to generate is from mainnet or testnet
+    /// @return The address bytes regarless of the output script type
+    function outputScriptToAddress(bytes calldata outputScript, bool mainnet) public pure returns (bytes memory) {
+        if (isP2PKHOutput(outputScript)) {
+            return parsePayToPubKeyHash(outputScript, mainnet);
+        }
+        if (isP2SHOutput(outputScript)) {
+            return parsePayToScriptHash(outputScript, mainnet);
+        }
+        if (isP2WPKHOutput(outputScript)) {
+            return parsePayToWitnessPubKeyHash(outputScript);
+        }
+        if (isP2WSHOutput(outputScript)) {
+            return parsePayToWitnessScriptHash(outputScript);
+        }
+        if (isP2TROutput(outputScript)) {
+            return parsePayToTaproot(outputScript);
+        }
+        revert("Unsupported script type");
+    }
+
+    /// @notice Check if a raw output script is a pay-to-public-key-hash output
+    /// @param pkScript the fragment of the raw transaction containing the raw output script
+    /// @return Whether the script has a pay-to-public-key-hash output structure or not
+    function isP2PKHOutput(bytes memory pkScript) public pure returns (bool) {
+        return pkScript.length == 5 + HASH160_SIZE &&
+            pkScript[0] == OpCodes.OP_DUP &&
+            pkScript[1] == OpCodes.OP_HASH160 &&
+            uint8(pkScript[2]) == HASH160_SIZE &&
+            pkScript[23] == OpCodes.OP_EQUALVERIFY &&
+            pkScript[24] ==  OpCodes.OP_CHECKSIG;
+    }
+
+    /// @notice Check if a raw output script is a pay-to-script-hash output
+    /// @param pkScript the fragment of the raw transaction containing the raw output script
+    /// @return Whether the script has a pay-to-script-hash output structure or not
+    function isP2SHOutput(bytes memory pkScript) public pure returns (bool) {
+        return pkScript.length == 3 + HASH160_SIZE &&
+            pkScript[0] == OpCodes.OP_HASH160 &&
+            uint8(pkScript[1]) == HASH160_SIZE &&
+            pkScript[22] == OpCodes.OP_EQUAL;
+    }
+
+    /// @notice Check if a raw output script is a pay-to-witness-pubkey-hash output
+    /// @param pkScript the fragment of the raw transaction containing the raw output script
+    /// @return Whether the script has a pay-to-witness-pubkey-hash output structure or not
+    function isP2WPKHOutput(bytes memory pkScript) public pure returns (bool) {
+        return pkScript.length == 2 + HASH160_SIZE &&
+            pkScript[0] == OpCodes.OP_0 &&
+            uint8(pkScript[1]) == HASH160_SIZE;
+    }
+
+    /// @notice Check if a raw output script is a pay-to-witness-script-hash output
+    /// @param pkScript the fragment of the raw transaction containing the raw output script
+    /// @return Whether the script has a pay-to-witness-script-hash output structure or not
+    function isP2WSHOutput(bytes memory pkScript) public pure returns (bool) {
+        return pkScript.length == 2 + SHA256_SIZE &&
+            pkScript[0] == OpCodes.OP_0 &&
+            uint8(pkScript[1]) == SHA256_SIZE;
+    }
+
+    /// @notice Check if a raw output script is a pay-to-taproot output
+    /// @notice Reference for implementation: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki 
+    /// @param pkScript the fragment of the raw transaction containing the raw output script
+    /// @return Whether the script has a pay-to-taproot output structure or not
+    function isP2TROutput(bytes memory pkScript) public pure returns (bool) {
+        return pkScript.length == 2 + TAPROOT_PUBKEY_SIZE &&
+            pkScript[0] == OpCodes.OP_1 &&
+            uint8(pkScript[1]) == TAPROOT_PUBKEY_SIZE;
+    }
+
+    /// @notice Parse a raw pay-to-public-key-hash output script to get the corresponding address,
+    /// the resulting byte array doesn't include the checksum bytes of the base58check encoding at
+    /// the end
     /// @param outputScript the fragment of the raw transaction containing the raw output script
     /// @param mainnet if the address to generate is from mainnet or testnet 
     /// @return The address generated using the receiver's public key hash
     function parsePayToPubKeyHash(bytes calldata outputScript, bool mainnet) public pure returns (bytes memory) {
-        require(outputScript.length == 25, "Script has not the required length");
-        require(
-            outputScript[0] == 0x76 && // OP_DUP
-            outputScript[1] == 0xa9 && // OP_HASH160
-            outputScript[2] == 0x14 && // pubKeyHashSize, should be always 14 (20B)
-            outputScript[23] == 0x88 && // OP_EQUALVERIFY
-            outputScript[24] == 0xac, // OP_CHECKSIG
-            "Script has not the required structure"
-        );
+        require(isP2PKHOutput(outputScript), "Script hasn't the required structure");
 
-        bytes memory destinationAddress = new bytes(PUBKEY_HASH_SIZE);
-        for(uint8 i = PUBKEY_HASH_START; i < PUBKEY_HASH_SIZE + PUBKEY_HASH_START; i++) {
-            destinationAddress[i - PUBKEY_HASH_START] = outputScript[i];
+        bytes memory destinationAddress = new bytes(HASH160_SIZE + 1);
+        for(uint8 i = PUBKEY_HASH_START; i < HASH160_SIZE + PUBKEY_HASH_START; i++) {
+            destinationAddress[i - PUBKEY_HASH_START + 1] = outputScript[i];
         }
 
-        uint8 versionByte = mainnet? 0x00 : 0x6f;
-        bytes memory result = addVersionByte(bytes1(versionByte), destinationAddress);
+        destinationAddress[0] = mainnet? PUBKEY_HASH_MAINNET_BYTE : PUBKEY_HASH_TESTNET_BYTE;
+        return destinationAddress;
+    }
 
-        return result;
+    /// @notice Parse a raw pay-to-script-hash output script to get the corresponding address,
+    /// the resulting byte array doesn't include the checksum bytes of the base58check encoding at
+    /// the end
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
+    /// @param mainnet if the address to generate is from mainnet or testnet
+    /// @return The address generated using the script hash
+    function parsePayToScriptHash(bytes calldata outputScript, bool mainnet) public pure returns (bytes memory) {
+        require(isP2SHOutput(outputScript), "Script hasn't the required structure");
+
+        bytes memory destinationAddress = new bytes(HASH160_SIZE + 1);
+        for(uint8 i = SCRIPT_HASH_START; i < HASH160_SIZE + SCRIPT_HASH_START; i++) {
+            destinationAddress[i - SCRIPT_HASH_START + 1] = outputScript[i];
+        }
+
+        destinationAddress[0] = mainnet? SCRIPT_HASH_MAINNET_BYTE : SCRIPT_HASH_TESTNET_BYTE;
+        return destinationAddress;
     }
 
-    function addVersionByte(bytes1 versionByte, bytes memory source) private pure returns (bytes memory) {
-        bytes memory dataWithVersion = new bytes(source.length + 1);
-        dataWithVersion[0] = versionByte;
+    /// @notice Parse a raw pay-to-witness-pubkey-hash output script to get the corresponding address words,
+    /// the resulting words are only the data part of the bech32 encoding and doesn't include the HRP
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
+    /// @return The address bech32 words generated using the pubkey hash
+    function parsePayToWitnessPubKeyHash(bytes calldata outputScript) public pure returns (bytes memory) {
+        require(isP2WPKHOutput(outputScript), "Script hasn't the required structure"); 
+        uint length = 1 + total5BitWords(HASH160_SIZE);
+        bytes memory result = new bytes(length);
+        result[0] = WITNESS_VERSION_0;
+        bytes memory words = to5BitWords(outputScript[2:]);
+        for (uint i = 1; i < length; i++) {
+            result[i] = words[i - 1];
+        }
+        return result;
+    }
 
-        uint8 i;
-        for (i = 0; i < source.length; i++) {
-            dataWithVersion[i + 1] = source[i];
+    /// @notice Parse a raw pay-to-witness-script-hash output script to get the corresponding address words,
+    /// the resulting words are only the data part of the bech32 encoding and doesn't include the HRP
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
+    /// @return The address bech32 words generated using the script hash
+    function parsePayToWitnessScriptHash(bytes calldata outputScript) public pure returns (bytes memory) {
+        require(isP2WSHOutput(outputScript), "Script hasn't the required structure");
+        uint length = 1 + total5BitWords(SHA256_SIZE);
+        bytes memory result = new bytes(length);
+        result[0] = WITNESS_VERSION_0;
+        bytes memory words = to5BitWords(outputScript[2:]);
+        for (uint i = 1; i < length; i++) {
+            result[i] = words[i - 1];
         }
+        return result;
+    }
 
-        return dataWithVersion;
+    /// @notice Parse a raw pay-to-taproot output script to get the corresponding address words,
+    /// the resulting words are only the data part of the bech32m encoding and doesn't include the HRP
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
+    /// @return The address bech32m words generated using the taproot pubkey hash
+    function parsePayToTaproot(bytes calldata outputScript) public pure returns (bytes memory) {
+        require(isP2TROutput(outputScript), "Script hasn't the required structure");
+        uint length = 1 + total5BitWords(TAPROOT_PUBKEY_SIZE);
+        bytes memory result = new bytes(length);
+        result[0] = WITNESS_VERSION_1;
+        bytes memory words = to5BitWords(outputScript[2:]);
+        for (uint i = 1; i < length; i++) {
+            result[i] = words[i - 1];
+        }
+        return result;
     }
 
     /// @notice Parse a raw null-data output script to get its content
@@ -121,7 +265,7 @@ library BtcUtils {
     /// @return The content embedded inside the script
     function parseNullDataScript(bytes calldata outputScript) public pure returns (bytes memory) {
         require(outputScript.length > 1,"Invalid size");
-        require(outputScript[0] == 0x6a, "Not OP_RETURN");
+        require(outputScript[0] == OpCodes.OP_RETURN, "Not OP_RETURN");
         return outputScript[1:];
     }
 
@@ -165,7 +309,8 @@ library BtcUtils {
         (uint32(uint8(bs[offset + 3])) << 24);
     }
 
-    /// @notice Check if a pay-to-script-hash address belogs to a specific script
+    /// @notice Check if a pay-to-script-hash address belogs to a specific script, expects the address
+    /// bytes to include the 4 checksum bytes at the end
     /// @param p2sh the pay-to-script-hash address
     /// @param script the script to check
     /// @param mainnet flag to specify if its a mainnet address
@@ -174,14 +319,15 @@ library BtcUtils {
         return p2sh.length == 25 && keccak256(p2sh) ==  keccak256(getP2SHAddressFromScript(script, mainnet));
     }
 
-    /// @notice Generate a pay-to-script-hash address from a script
+    /// @notice Generate a pay-to-script-hash address from a script, the resulting byte array already contains
+    /// the 4 checksum bytes at the end of it
     /// @param script the script to generate the address from
     /// @param mainnet flag to specify if the output should be a mainnet address
     /// @return The address generate from the script
     function getP2SHAddressFromScript(bytes calldata script, bool mainnet) public pure returns (bytes memory) {
         bytes20 scriptHash = ripemd160(abi.encodePacked(sha256(script)));
-        uint8 versionByte = mainnet ? 0x5 : 0xc4;
-        bytes memory versionAndHash = bytes.concat(bytes1(versionByte), scriptHash);
+        bytes1 versionByte = mainnet ? SCRIPT_HASH_MAINNET_BYTE : SCRIPT_HASH_TESTNET_BYTE;
+        bytes memory versionAndHash = bytes.concat(versionByte, scriptHash);
         bytes4 checksum = bytes4(sha256(abi.encodePacked(sha256(versionAndHash))));
         return bytes.concat(versionAndHash, checksum);
     }
@@ -220,4 +366,36 @@ library BtcUtils {
         }
         return result;
     }
+
+    /// @notice Referece for implementation: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
+    function to5BitWords(bytes memory byteArray) private pure returns(bytes memory) {
+        uint8 MAX_VALUE = 31;
+
+        uint currentValue = 0;
+        uint bitCount = 0;
+        uint8 resultIndex = 0;
+        bytes memory result = new bytes(total5BitWords(byteArray.length));
+
+        for (uint i = 0; i < byteArray.length; ++i) {
+            currentValue = (currentValue << BYTE_SIZE) | uint8(byteArray[i]);
+            bitCount += BYTE_SIZE;
+            while (bitCount >= BECH32_WORD_SIZE) {
+                bitCount -= BECH32_WORD_SIZE;
+                // this mask ensures that the result will always have 5 bits
+                result[resultIndex] = bytes1(uint8((currentValue >> bitCount) & MAX_VALUE));
+                resultIndex++;
+            }
+        }
+
+        if (bitCount > 0) {
+            result[resultIndex] = bytes1(uint8((currentValue << (BECH32_WORD_SIZE - bitCount)) & MAX_VALUE));
+        }
+        return result;
+    }
+
+    function total5BitWords(uint numberOfBytes) private pure returns(uint) {
+        uint total = (numberOfBytes * BYTE_SIZE) / BECH32_WORD_SIZE;
+        bool extraWord = (numberOfBytes * BYTE_SIZE) % BECH32_WORD_SIZE == 0;
+        return total + (extraWord? 0 : 1);
+    }
 }

package/contracts/OpCodes.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.18;
+
+
+library OpCodes {
+    bytes1 public constant OP_DUP = 0x76;
+    bytes1 public constant OP_HASH160 = 0xa9;
+    bytes1 public constant OP_EQUALVERIFY = 0x88;
+    bytes1 public constant OP_CHECKSIG = 0xac;
+    bytes1 public constant OP_RETURN = 0x6a;
+    bytes1 public constant OP_EQUAL = 0x87;
+
+    bytes1 public constant OP_0 = 0x00;
+    bytes1 public constant OP_1 = 0x51;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsksmart/btc-transaction-solidity-helper",
-  "version": "0.0.3",
+  "version": "0.2.1",
   "description": "Solidity library with functions to work with Bitcoin transactions inside smart contracts",
   "main": "contracts",
   "files": [
@@ -11,7 +11,7 @@
     "test:coverage": "npx hardhat coverage",
     "lint": "npx hardhat check",
     "compile": "npx hardhat compile",
-    "prepare": "husky install"
+    "prepare": "pip3 install pre-commit && pre-commit install"
   },
   "repository": {
     "type": "git",
@@ -37,7 +37,9 @@
   "devDependencies": {
     "@nomicfoundation/hardhat-toolbox": "^3.0.0",
     "@nomiclabs/hardhat-solhint": "^3.0.1",
+    "bech32": "^2.0.0",
+    "bs58check": "^3.0.1",
     "hardhat": "^2.17.0",
-    "husky": "^8.0.3"
+    "solidity-coverage": "^0.8.12"
   }
 }