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

package/README.md

@@ -0,0 +1,179 @@
+[![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)
+<img src="img/rootstock-docs.png" alt="RSK Logo" style="width:100%; height: auto;" />
+
+# BTC Transaction Solidity Helper
+
+Bitcoin, a decentralized digital currency, serves as both a store of value and a means of transferring wealth. Its security is rooted in the blockchain, a distributed ledger maintained by a network of miners. These miners expend significant computational power and energy to create new blocks, which are added to the blockchain every 10 minutes. The more hashing power contributed by miners, the more secure the network becomes. [Learn more about Bitcoin](https://developer.bitcoin.org/index.html).
+
+Rootstock, the pioneering open-source smart contract platform built on Bitcoin, aims to enhance the Bitcoin ecosystem by introducing smart contract functionality, near-instant payments, and improved scalability. Its comprehensive technology stack, encompassing Rootstock smart contracts and the Rootstock Infrastructure Framework, is designed to foster a more equitable and inclusive financial system. Read more about the [Rootstock Stack](/concepts/fundamentals/stack/).
+
+The [Bitcoin Solidity helper library](https://github.com/rsksmart/btc-transaction-solidity-helper) facilitates seamless interaction between Bitcoin transactions and Solidity smart contracts on the Rootstock platform. In this guide, we will learn how to handle Bitcoin transactions in a Solidity Smart contract, we will also learn how to parse transactions, hash transactions and validate scripts for bitcoin transactions. You can find the public repository for the [bitcoin transaction solidity helper library](https://github.com/rsksmart/btc-transaction-solidity-helper).
+
+## Features of the Library
+
+The features of the Bitcoin Solidity Helper library include:
+1. Bitcoin transaction output parsing: This accurately extracts and organizes transaction outputs from raw Bitcoin transactions. It is able to receive a raw tx and return an array of structures with the tx outputs.
+2. Bitcoin transaction hashing: This calculates the cryptographic hash of a Bitcoin transaction, ensuring its authenticity and integrity. It receives a raw tx and returns its hash.
+3. Bitcoin transaction output script validation: This verifies the validity and type of output scripts within a Bitcoin transaction, allowing for specific data extraction. It receives a raw output script, validates that it is from a specific type and returns a result. E.g. receive a raw null-data script and return the embedded data in it.
+4. 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.
+5. Bitcoin address validation: This checks if a Bitcoin address conforms to a particular type or format. It validates if a Bitcoin address is of a given type or not.
+
+## Versioning
+Current version is ![npm version](https://img.shields.io/npm/v/@rsksmart/btc-transaction-solidity-helper.svg)
+
+To check the NPM package, please check [Bitcoin Solidity Helper NPM Package.](https://www.npmjs.com/.package/@rsksmart/btc-transaction-solidity-helper)
+
+## Prerequisites
+* Knowledge of Solidity and how to write smart contracts.
+* [Bitcoin Solidity Helper Package.](https://github.com/rsksmart/btc-transaction-solidity-helper/pkgs/npm/btc-transaction-solidity-helper)
+
+## Setup
+To setup the Solidity helper library in your project, run the following npm command:
+
+```bash
+   npm install @rsksmart/btc-transaction-solidity-helper
+```
+
+## Usage
+
+### Import the library:
+
+```bash
+import "@rsksmart/btc-transaction-solidity-helper/contracts/BtcUtils.sol";
+```
+
+### Using the library:
+
+```bash
+BtcUtils.TxRawOutput[] memory outputs = BtcUtils.getOutputs(btcTx);
+bytes memory scriptData = BtcUtils.parseNullDataScript(outputs[0].pkScript);
+```
+
+_This fragment parses a raw Bitcoin transaction to extract its outputs and then parses the first output to get the data of the null data script._
+
+## Parsing a Bitcoin Transaction Output
+All the bitcoin transactions have a specific format when they are serialized. By having knowledge of this format, we can process a raw transaction in order to extract the information about its outputs.
+
+A raw transaction has the following top-level format:
+
+| Bytes | Name | Data Type | Description |
+| --- | --- | --- | --- |
+| 4 | Version | `int32_t` | [Transaction version number](https://developer.bitcoin.org/terms.html#term-transaction-version-number) (note, this is signed); currently version 1 or 2. Programs creating transactions using newer consensus rules may use higher version numbers. Version 2 means that [BIP68](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki#specification) applies. |
+| Varies | tx_in count | compactSize uint | Number of inputs in this transaction. |
+| Varies | tx_in | txIn | Transaction inputs. See description of txIn below. |
+| Varies | tx_out count | compactSize uint | Number of outputs in this transaction. |
+| Varies | tx_out | txOut | Transaction outputs. See description of txOut below. |
+| 4 | lock_time | `uint32_t` | A time ([Unix epoch time](https://en.wikipedia.org/wiki/Unix_time)) or block number. See the [locktime parsing rules](https://developer.bitcoin.org/devguide/transactions.html#locktime_parsing_rules). |
+
+
+> See the [Reference Implementation](https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format)
+
+The approach that the library takes is to calculate, based on the length of each section, where does the output part start. After this, it starts parsing each output separately and adding its script and value into a solidity data structure.
+
+| Bytes | Name | Data Type | Description |
+| --- | --- | --- | --- |
+| 8 | Value | `int64_t` | Number of satoshis to spend. May be zero; the sum of all outputs may not exceed the sum of satoshis previously spent to the outpoints provided in the input section. (Exception: coinbase transactions spend the block subsidy and collect transaction fees.) |
+| 1+ | pk_script bytes | compactSize uint | Number of bytes in the pubkey script. Maximum is 10,000 bytes. |
+| 1+ | pk_script | `char[]` | Defines the conditions which must be satisfied to spend this output. |
+
+> See the [Reference Implementation](https://developer.bitcoin.org/reference/transactions.html#txout-a-transaction-output)
+
+```solidity
+struct TxRawOutput {
+        uint64 value;
+        bytes pkScript;
+        uint256 scriptSize;
+        uint256 totalSize;
+    }
+```
+
+After finishing the processing of each output, the library returns an ordered output array, so the user can take advantage of this information in its solidity contract.  
+
+In order to show the benefits of this library, we’ll use the example of the [Flyover Protocol](/developers/integrate/flyover/). In this protocol, there is a smart contract that one party uses to claim a refund, in order to claim this refund, they need to prove that there was a payment with a specific amount done to a specific address in the Bitcoin Network, in order to do this, the smart contract receives the Bitcoin raw transaction. Since making this validation is not a trivial process, as it requires to parse the whole transaction, here is where we can see the utility of the library.
+
+The usage of the output parsing functionality is the following:
+```solidity
+BtcUtils.TxRawOutput[] memory outputs = BtcUtils.getOutputs(btcTx);
+```
+
+Then the user is able to perform any validation:
+```solidity
+require(expectedValue <= outputs[0].value, "incorrect amount");
+```
+
+:::info[Info]
+The value field of the output structure is in satoshis.
+:::
+
+
+## Hashing Transactions
+The hash algorithm used in the Bitcoin Network is just the `SHA256(SHA256())` of the serialized transaction. The library exposes one function that will apply this hash algorithm to any byte array passed to it, making it easy to calculate the transaction id of any raw transaction present in the contract.
+
+This function is specifically useful to interact with the [rootstock native bridge](/concepts/powpeg/), as many of its functions have a transaction id as parameter. For example, by using the transaction hash function, it is easy to know how many confirmations a Bitcoin block has inside a smart contract function.
+
+### Example code with explanation
+Based on the example stated in the previous section, after validating that a specific transaction has an output paying a certain amount to an address. We need to know if that transaction has enough confirmations:
+
+Here's an example:
+
+```solidity
+BtcUtils.TxRawOutput[] memory outputs = BtcUtils.getOutputs(btcTx);
+require(expectedValue <= outputs[0].value, "incorrect amount");
+bytes32 txId = BtcUtils.hashBtcTx(btcTx)
+// assuming btcBlockHeaderHash,partialMerkleTree, merkleBranchHashes
+// were provided in the function parameters
+uint confirmations = bridge.getBtcTransactionConfirmations(
+              txId,
+               btcBlockHeaderHash,
+               partialMerkleTree,
+               merkleBranchHashes
+           )
+require(confirmations > expectedConfirmations, "not enough confirmations");
+```
+
+Read more about the [bridge functionality.](https://github.com/rsksmart/rskj/blob/master/rskj-core/src/main/java/co/rsk/peg/BridgeSupport.java)
+
+## Script Validation for Bitcoin Transaction Output
+In the Bitcoin network, when a user wants to send funds to another, the user creates a transaction and adds an output with the value that it wants to send. The other user doesn’t “receive” this amount directly, instead, we call receiving to the ability of providing the proper input to the output script so it returns `true`:
+
+<Quote caption="Bitcoin Script Documentation">
+
+  A transaction is valid if nothing in the combined script triggers failure and the top stack item is True (non-zero) when the script exits. Read more info in [Bitcoin Script](https://en.bitcoin.it/wiki/Script)
+</Quote>
+
+> By having knowledge of the structure of the outputs that each type of address has, we can process and validate any arbitrary output extracted with the functions explained in the previous sections. In the same way, we can parse those outputs to obtain the specific value that later is encoded (in base58check, bech32 or bech32m) and presented as the “destination address”. 
+
+The output that the library supports and is able to parse to an address are:
+* P2PKH (Pay to public key hash)
+* P2SH (Pay to script hash)
+* P2WPKH (Pay to witness public key hash)
+* P2WSH (Pay to witness script hash)
+* P2TR (Pay to taproot)
+
+**Some use cases for script validation:**
+
+As seen in the previous example, we validated inside our smart contract that a Bitcoin transaction has the correct amount and enough confirmations, now we need to validate that it was performed on the correct address. To do this, the library has the capability of parsing an arbitrary output and converting it into an address.
+
+Here's an example:
+
+```solidity
+bytes memory btcTxDestination = BtcUtils.outputScriptToAddress(
+           outputs[0].pkScript,
+           mainnetFlag
+       );
+       require(keccak256(expectedAddress) == keccak256(btcTxDestination), "incorrect address");
+```
+
+## Conclusion
+Congratulations, we have successfully learnt how to use the Solidity Helper library to parse, hash, and validate scripts within Bitcoin transactions. By using this library, developers can gain valuable insights into Bitcoin transaction data and build more sophisticated smart contract dApps on Rootstock.
+
+### Future features
+**Some future enhancements to the library includes:**
+* Transaction Input Parsing: The ability to extract and analyze transaction input data to receive a raw tx and return an array of structs with the tx inputs.
+* Transaction Creation: Utilities to facilitate the creation of raw Bitcoin transactions within smart contracts.
+
+## Contribution Guidelines
+* Please refer to the Rootstock Contribution Guidelines for more information on how to contribute to this project.
+
+## License:
+MIT License - Copyright (c) 2023 Rootstock.

package/contracts/BtcUtils.sol

@@ -59,7 +59,7 @@ library BtcUtils {
         if (rawTx[4] == 0x00 && rawTx[5] == 0x01) { // if its segwit, skip marker and flag
             currentPosition = 6;
         }
-        
+
         (uint64 inputCount, uint16 inputCountSize) = parseCompactSizeInt(currentPosition, rawTx);
         currentPosition += inputCountSize;
 
@@ -167,7 +167,7 @@ library BtcUtils {
     }
 
     /// @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 
+    /// @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) {
@@ -180,7 +180,7 @@ library BtcUtils {
     /// 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 
+    /// @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(isP2PKHOutput(outputScript), "Script hasn't the required structure");
@@ -217,13 +217,12 @@ library BtcUtils {
     /// @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);
+        require(isP2WPKHOutput(outputScript), "Script hasn't the required structure");
+        uint length = 1 + 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];
+            result[i] = outputScript[i + 1];
         }
         return result;
     }
@@ -234,12 +233,11 @@ library BtcUtils {
     /// @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);
+        uint length = 1 + 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];
+            result[i] = outputScript[i + 1];
         }
         return result;
     }
@@ -250,18 +248,17 @@ library BtcUtils {
     /// @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);
+        uint length = 1 + 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];
+            result[i] = outputScript[i + 1];
         }
         return result;
     }
 
     /// @notice Parse a raw null-data output script to get its content
-    /// @param outputScript the fragment of the raw transaction containing the raw output script 
+    /// @param outputScript the fragment of the raw transaction containing the raw output script
     /// @return The content embedded inside the script
     function parseNullDataScript(bytes calldata outputScript) public pure returns (bytes memory) {
         require(outputScript.length > 1,"Invalid size");
@@ -271,7 +268,7 @@ library BtcUtils {
 
     /// @notice Hash a bitcoin raw transaction to get its id (reversed double sha256)
     /// @param btcTx the transaction to hash
-    /// @return The transaction id 
+    /// @return The transaction id
     function hashBtcTx(bytes calldata btcTx) public pure returns (bytes32) {
         bytes memory doubleSha256 = abi.encodePacked(sha256(abi.encodePacked(sha256(btcTx))));
         bytes1 aux;
@@ -340,7 +337,7 @@ library BtcUtils {
         } else if (maxSize <= MAX_COMPACT_SIZE_LENGTH) {
             return (maxSize, 1);
         }
-        
+
         uint compactSizeBytes = 2 ** (maxSize - MAX_COMPACT_SIZE_LENGTH);
         require(compactSizeBytes <= MAX_BYTES_USED_FOR_COMPACT_SIZE, "unsupported compact size length");
 
@@ -357,7 +354,7 @@ library BtcUtils {
         bytes memory array
     ) private pure returns (uint) {
         require(
-            fragmentStart < array.length && fragmentEnd < array.length, 
+            fragmentStart < array.length && fragmentEnd < array.length,
             "Range can't be bigger than array"
         );
         uint result = 0;
@@ -366,36 +363,4 @@ 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

@@ -3,6 +3,7 @@ pragma solidity ^0.8.18;
 
 
 library OpCodes {
+    bytes1 public constant OP_DROP = 0x75;
     bytes1 public constant OP_DUP = 0x76;
     bytes1 public constant OP_HASH160 = 0xa9;
     bytes1 public constant OP_EQUALVERIFY = 0x88;
@@ -10,6 +11,8 @@ library OpCodes {
     bytes1 public constant OP_RETURN = 0x6a;
     bytes1 public constant OP_EQUAL = 0x87;
 
+    bytes1 public constant OP_PUSHBYTES_32 = 0x20;
+
     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.2.1",
+  "version": "0.3.0",
   "description": "Solidity library with functions to work with Bitcoin transactions inside smart contracts",
   "main": "contracts",
   "files": [

package/Readme.md

@@ -1,33 +0,0 @@
-# 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 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 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:
-* Bitcoin transaction input parsing: should be able to receive a raw tx and return an array of structs with the tx inputs
-* Bitcoin transaction creation: utilities for building a raw transaction inside a contract
-
-## Usage
-1. Run this command to install the contracts
- ```console
-    npm install @rsksmart/btc-transaction-solidity-helper
- ```
-2. Import the library in your contract
- ```solidity
-    import "@rsksmart/btc-transaction-solidity-helper/contracts/BtcUtils.sol";
- ```
-3. Use the library. E.g.:
- ```solidity
-    BtcUtils.TxRawOutput[] memory outputs = BtcUtils.getOutputs(btcTx);
-    bytes memory btcTxDestination = BtcUtils.parseNullDataScript(outputs[0].pkScript, false);
- ```