Analysis tools documentation

tools/README.md

@@ -36,3 +36,18 @@ Development tools are usually making a lot of requests to certain endpoints, esp
 
 Note:
 Enable [`development mode`](../docs/dev-mode.md) to correctly assert revert messages of contract calls with `hardhat-chai-matchers`.
+
+# EVM Analysis tools study General Information: 
+This report aims to analyze potential tools that will aid in the development, porting, and security assessment
+of Smart Contracts deployed on the Hedera network. Key aspects evaluated during this research include:
+- Ease of use and compatibility with Hedera.
+- Ability to identify optimizations and potential errors or bugs specific to Smart Contracts on the Hedera.
+- Issues with compatibility for contracts ported from Ethereum or other networks to the Hedera.
+### Prerequisites
+Tools were tested in the MacOS and Kubuntu Linux environments as well as on Docker containers. Test setup involves:
+- Installing the Solidity compiler package.
+- Cloning the Hedera JSON RPC repository: `git clone -b main --single-branch  https://github.com/hashgraph/hedera-json-rpc-relay.git`.
+- Installing dependencies, and building the project: `npm install`, `npm run setup`, from the project directory.
+- Starting the project: `npm start`.
+- Launching the analytical tools discussed in this report: `docker-compose up -d`, using
+  [docker-compose](slither-analysis/docker-compose.yaml) file placed in the tool analysis directory ([Dockerfile](slither-analysis/Dockerfile) for the Slither will be required).

tools/maian-analysis/analysis.md

@@ -0,0 +1,70 @@
+# MAIAN
+
+[MAIAN](https://github.com/ivicanikolicsg/MAIAN) is a tool specifically designed to find security vulnerabilities
+in Smart Contracts that operate on Ethereum and other blockchain platforms. MAIAN main aim is to detect three
+types of problematic contracts:
+- **suicidal contract**: one that can be forced to self-destruct by any external user, not just their owner.
+- **prodigal contract**: one that can inadvertently leak funds to arbitrary addresses due to improper handling of
+  Ether transfers.
+- **greedy contract**: one that locks funds indefinitely, making them irretrievable.
+  Its key features are:
+- Capability of analyzing both Solidity source code and bytecode.
+- Automated analysis with detailed reporting of vulnerabilities.
+- Graphical representations of control flow to aid in the understanding of contract behavior.
+- Integrated support for deployment analysis.
+- Easily integrates with continuous integration pipelines for ongoing security assessment.
+  The tool is especially effective at finding specific types of security flaws that involve the misuse of funds within contracts
+
+## Installation:
+Due to changes in web3.py library introduced in version 3.5.5V (including), an attempt to start MAIAN, using instructions from
+[github repo](https://github.com/ivicanikolicsg/MAIAN), ends with an error prompt that may be found [here](example_build_execution_error.md)
+Further discussion regarding this error may be found [here](https://github.com/ethereum/web3.py/issues/879)
+Alternative ways to run MAIAN are:
+1) Running with manual downgrade od Python to v2 and web3.py to 3.5.4V
+2) Running inside the Docker container:
+```Shell
+docker pull cryptomental/maian-augur-ci
+docker run -it cryptomental/maian-augur-ci
+cd MAIAN/tool && python2 maian.py -s example_contracts/example_suicidal.sol KAI -c 0
+```
+> **NOTE**: There is no `solc-select preinstalled` in the docker image. In order to change the version run:
+> ```shell
+> wget https://github.com/ethereum/solidity/releases/download/{your_version}/solc-static-linux && mv solc-static-linux /usr/bin/solc
+> ```
+> where `{your_version}` is desired solidity compiler version, ie. v0.8.24.
+## Examples of executions:
+* [Suicidal contract detection](execution_examples/suicidal_detection.md)
+* [Leak detection](execution_examples/leak_detection.md)
+* [AtomicHTS.sol check](execution_examples/AtomicHTS.md)
+* [HederaTokenService.sol check](execution_examples/HederaTokenService.md)
+
+## Tool analysis:
+### Attempt of replacing Ethereum's JSON RPC to Hedera's JSON RPC relay:
+As of April 2024, MAIAN across the last six years was not in active development. This state leads the tool to be
+out of date and lacks support for newer features. This leads to multiple challenges, most impactful ones
+are the following:
+- **Differences in RPC Methods Ethereum's JSON RPC API**: Hedera does not support `eth_sendTransaction`.
+  The available alternative is: `eth_sendRawTransaction` which requires transactions to be signed before being submitted,
+  this additional step would have to be implemented in the MAIAN code.
+- **Lack of Transaction Signing functionality**: In Ethereum, the unlocked account can automatically sign transactions,
+  whereas, in Hedera, the transaction needs to be pre-signed. MAIAN lack of support for modern cryptographic libraries such as:
+  `eth_account`, a newer version of `web3.py`, `pycryptodome`, will substantially impede alignment for the network in this
+  field.
+- **Library and language limitations**: due to out-of-date dependencies and environment, MAIAN lacks built-in support
+  for SHA-3 (KECCAK-256), which is essential for Ethereum-style transactions and required for compatibility with
+  Hedera's API, support for integrated account management, and transaction signing functionalities are also missing
+- **Security and Maintenance Concerns**: using outdated software causes both Security risks and increases maintenance
+  efforts
+
+### Recommendations and possible investments in the tool:
+- **Upgrade Python and web3.py**: Moving to at least Python 3.6+ and the latest version of web3.py would provide
+  support for modern cryptographic functions, easier management of dependencies, and improve security.
+- **Client-side Transaction Signing**: Implement client-side transaction signing to adapt to Hedera’s
+  `eth_sendRawTransaction`.
+- **Review and Adapt to Hedera’s API**: Thoroughly review Hedera’s API capabilities to understand the adjustments
+  needed in the application to accommodate Hedera's specific methods and operational paradigms.
+
+> **Support**:
+> Even though MAIAN is not officially marked as abandoned, the last changes were introduced to the code base 6 years ago.
+> Further work with this tool should be preceded by migrating it to a supported Python version and dropping
+> archival dependencies from its codebase.

tools/maian-analysis/docker-compose.yaml

@@ -0,0 +1,6 @@
+services:
+  maian:
+    image: cryptomental/maian-augur-ci
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    entrypoint: ["sleep", "infinity"]

tools/maian-analysis/example_build_execution_error.md

@@ -0,0 +1,14 @@
+```Shell
+Traceback (most recent call last):
+File "/Users/jasuwienas/Projects/blockchain/evm/MAIAN/tool/maian.py", line 24, in <module>
+from web3 import Web3, KeepAliveRPCProvider, IPCProvider
+File "/opt/homebrew/lib/python3.11/site-packages/web3/__init__.py", line 7, in <module>
+from eth_account import Account  # noqa: E402
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+File "/opt/homebrew/lib/python3.11/site-packages/eth_account/__init__.py", line 1, in <module>
+from eth_account.account import Account  # noqa: F401
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+File "/opt/homebrew/lib/python3.11/site-packages/eth_account/account.py", line 1, in <module>
+from collections import (
+ImportError: cannot import name 'Mapping' from 'collections' (/opt/homebrew/Cellar/python@3.11/3.11.7_1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/collections/__init__.py)
+```

tools/maian-analysis/execution_examples/AtomicHTS.md

@@ -0,0 +1,71 @@
+```shell
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/hts-precompile/AtomicHTS.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Deploying contract ........... confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/AtomicHTS.address 
+[ ] Check if contract is SUICIDAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Blockchain contract: True
+[ ] Debug              : False
+
+[-] The code does not contain SUICIDE instructions, hence it is not vulnerable
+```
+
+```shell
+root@194c8c7535a2:/MAIAN/tool# python2 maian.py -s /examples/hts-precompile/AtomicHTS.sol AtomicHTS -c 1
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/hts-precompile/AtomicHTS.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Sending Ether to contract 0x9e536236abf2288a7864c6a1afaa4cb98d464306  ... tx[0] mined  Sent! 
+[ ] Deploying contract .......................... confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/AtomicHTS.address 
+[ ] The contract balance: 44   Positive balance
+[ ] Check if contract is PRODIGAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Blockchain contract: True
+[ ] Debug              : False
+[+] The code does not have CALL/SUICIDE, hence it is not prodigal
+```
+
+```shell
+root@194c8c7535a2:/MAIAN/tool# python2 maian.py -s /examples/hts-precompile/AtomicHTS.sol AtomicHTS -c 2
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/hts-precompile/AtomicHTS.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Deploying contract ............. confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/AtomicHTS.address 
+[ ] Check if contract is GREEDY
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Debug              : False
+[-] Contract can receive Ether
+
+[-] No lock vulnerability found because the contract cannot receive Ether 
+```

tools/maian-analysis/execution_examples/HederaTokenService.md

@@ -0,0 +1,72 @@
+```shell
+root@194c8c7535a2:/MAIAN/tool# python2 maian.py -s /examples/example_hbar_to_and_from_contract.sol hbarToAndFromContract -c 0
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/example_hbar_to_and_from_contract.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Deploying contract ........... confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/hbarToAndFromContract.address 
+[ ] Check if contract is SUICIDAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Blockchain contract: True
+[ ] Debug              : False
+
+[-] The code does not contain SUICIDE instructions, hence it is not vulnerable
+```
+
+```shell
+root@194c8c7535a2:/MAIAN/tool# python2 maian.py -s /examples/example_hbar_to_and_from_contract.sol hbarToAndFromContract -c 1
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/example_hbar_to_and_from_contract.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Sending Ether to contract 0x9e536236abf2288a7864c6a1afaa4cb98d464306  . tx[0] mined  Sent! 
+[ ] Deploying contract ........... confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/hbarToAndFromContract.address 
+[ ] The contract balance: 44   Positive balance
+[ ] Check if contract is PRODIGAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Blockchain contract: True
+[ ] Debug              : False
+[+] The code does not have CALL/SUICIDE, hence it is not prodigal
+```
+
+```shell
+root@194c8c7535a2:/MAIAN/tool# python2 maian.py -s /examples/example_hbar_to_and_from_contract.sol hbarToAndFromContract -c 2
+
+====================================================================================================
+[ ] Compiling Solidity contract from the file /examples/example_hbar_to_and_from_contract.sol ...  Done 
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+/usr/local/lib/python2.7/dist-packages/web3/main.py:130: DeprecationWarning: Python 2 support is ending! Please upgrade to Python 3 promptly. Support will end at the beginning of 2018.
+  category=DeprecationWarning,
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED 
+[ ] Deploying contract ...... confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306 
+[ ] Contract code length on the blockchain :    2  : 0x... 
+[ ] Contract address saved in file: ./out/hbarToAndFromContract.address 
+[ ] Check if contract is GREEDY
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : ...
+[ ] Bytecode length    : 0
+[ ] Debug              : False
+[-] Contract can receive Ether
+
+[-] No lock vulnerability found because the contract cannot receive Ether 
+```

tools/maian-analysis/execution_examples/leak_detection.md

@@ -0,0 +1,32 @@
+```shell
+[ ] Compiling Solidity contract from the file example_contracts/example_prodigal.sol ...  Done
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED
+[ ] Sending Ether to contract 0x9e536236abf2288a7864c6a1afaa4cb98d464306  ... tx[0] mined  Sent!
+[ ] Deploying contract ............ confirmed at address: 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract code length on the blockchain :    7754  : 0x6060604052600436106100d05760...
+[ ] Contract address saved in file: ./out/KAI.address
+[ ] The contract balance: 44   Positive balance
+[ ] Check if contract is PRODIGAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : 6060604052600436106100d0576000357c0100000000000000...
+[ ] Bytecode length    : 7752
+[ ] Blockchain contract: True
+[ ] Debug              : False
+
+[ ] Search with call depth: 1   : 1111111
+[ ] Search with call depth: 2   : 11222222211122222212222
+
+[-] Leak vulnerability found!
+
+    The following 2 transaction(s) will trigger the contract to leak:
+    -Tx[1] :0bb5e62b
+    -Tx[2] :41c0e1b5
+
+    The transactions correspond to the functions:
+    -EGC()
+    -kill()
+
+[ ] Confirming leak vulnerability on private chain ... ......................... tx[0] mined ....................... tx[1] mined
+    Confirmed ! The contract is prodigal !
+```

tools/maian-analysis/execution_examples/suicidal_detection.md

@@ -0,0 +1,32 @@
+```shell
+====================================================================================================
+[ ] Compiling Solidity contract from the file example_contracts/example_suicidal.sol ...  Done
+[ ] Connecting to PRIVATE blockchain emptychain  ... ESTABLISHED
+
+[ ] Deploying contract .............................................................................
+[ ] Contract code length on the blockchain :    7754  : 0x6060604052600436106100d05760...
+[ ] Contract address saved in file: ./out/KAI.address
+[ ] Check if contract is SUICIDAL
+
+[ ] Contract address   : 0x9E536236ABF2288a7864C6A1AfaA4Cb98D464306
+[ ] Contract bytecode  : 6060604052600436106100d0576000357c0100000000000000...
+[ ] Bytecode length    : 7752
+[ ] Blockchain contract: True
+[ ] Debug              : False
+
+[ ] Search with call depth: 1   : 1111111
+[ ] Search with call depth: 2   : 11222222211122222212222
+
+[-] Suicidal vulnerability found!
+
+    The following 2 transaction(s) will trigger the contract to be killed:
+    -Tx[1] :0bb5e62b
+    -Tx[2] :41c0e1b5
+
+    The transactions correspond to the functions:
+    -EGC()
+    -kill()
+
+[ ] Confirming suicide vulnerability on private chain ... .................. tx[0] mined .................. tx[1] mined
+    Confirmed ! The contract is suicidal !
+```