#1023

contributing.md

@@ -0,0 +1,153 @@
+# Contributing
+
+You can contribute to Warp by raising issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
+
+## DOs and DON'Ts
+
+Please do:
+
+- **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
+- **DO** include tests for both, new features and bug fixes
+- **DO** keep the discussions focused on the initial topic
+
+Please do not:
+
+- **DON'T** raise PRs with style changes
+- **DON'T** surprise us with big pull requests. It's better to first raise it as an issue and have it discussed
+- **DON'T** commit code that you didn't author. This may breach IP
+- **DON'T** submit PRs that alter licensing, contributing guide lines or code of conduct
+
+## Installation
+
+First, please make sure you have all the required external [dependencies](dependencies.md) installed.
+
+Then, with a Python3.9 virtual environment activated, perform the following instructions:
+
+1. Clone this repo and change directory into the `warp` folder.
+
+2. Install the JavaScript dependencies:
+
+```bash
+yarn
+```
+
+3. Install the Python dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+If you are using a M1 chipped Mac and getting a `'gmp.h' file not found` error when installing Cairo run the following:
+
+```bash
+CFLAGS=-I`brew --prefix gmp`/include LDFLAGS=-L`brew --prefix gmp`/lib pip install ecdsa fastecdsa sympy
+```
+
+Then run the pip command above again.
+
+4. Compile the project:
+
+```bash
+yarn build
+```
+
+5. Compile Warp libraries
+
+```bash
+yarn warplib
+```
+
+6. Test the installation worked by transpiling an example ERC20 contract:
+
+```bash
+bin/warp transpile exampleContracts/ERC20.sol
+```
+
+## First steps :feet:
+
+To look what features we are currently working on or tasks that are pending to do, please checkout the [project on github](https://github.com/orgs/NethermindEth/projects/30/views/3).
+
+## Developing tips :honey_pot:
+
+It can be tedious to manually recompile the project after every minor change. You can automate the process of recompiling by executing the following command in a separate terminal:
+
+```bash
+yarn dev
+```
+
+Alternatively to `yarn dev` you can run typescript in interpreted mode to achieve the same. This is an example using `transpile` command:
+
+```bash
+npx ts-node src transpile example_contracts/ERC20.sol
+```
+
+### Testing for contributors :stethoscope:
+
+Warp includes three sets of tests:
+
+- Compilation Tests: These tests ensure that transpiled contracts are valid Cairo code.
+
+- Behaviour Tests: These tests verify the correct functionality of transpiled contracts.
+
+- Semantic Tests: These tests involve transpiling Solidity's semantic tests and checking that the runtime behaviour remains consistent.
+
+#### Compilation Tests
+
+Start by running the compilation tests to verify that your contribution doesn't break any fundamental features. These tests are also the quickest to execute.
+
+```bash
+yarn test:examples
+```
+
+#### Behaviour Tests
+
+Behaviour tests involve transpiling a set of Solidity contracts and deploying them to a testnet. Each deployed contract undergoes testing for all of its runtime functionality.
+
+1. Run the setup script (Required only once):
+
+```bash
+tests/behaviour/setup.sh
+```
+
+2. In a separate terminal, start a StarkNet testnet server (make sure cairo-lang is installed in the environment):
+
+```bash
+yarn testnet
+```
+
+3. Run the tests:
+
+```bash
+yarn test
+```
+
+<br>
+
+To generate benchmarks locally during development:
+
+```bash
+yarn testnet:benchmark
+yarn test
+```
+
+```python
+python starknet-testnet/generateMarkdown.py
+```
+
+This saves the benchmarks at `benchmark/stats/data.md`
+
+#### Semantic Tests
+
+Semantic tests involve transpiling each of Solidity's behaviour tests and deploying them. Each test is executed, and its result is compared to the output of its Solidity counterpart.
+
+Execute instructions _1_ and _2_ from [Behaviour Tests](#behaviour-tests) if you haven't already. Then:
+
+3. Run semantic tests:
+
+```bash
+yarn test:semantic
+```
+
+## PR - CI Process
+
+The project uses GitHub Actions to build its artifacts and run tests. We do our best to keep the suite fast and stable. For incoming PRs, builds and test runs must be clean.

dependencies.md

@@ -0,0 +1,52 @@
+# Dependencies
+
+1. You will need [z3](https://github.com/Z3Prover/z3) and [gmp](https://gmplib.org/#DOWNLOAD)
+   installed to use Warp.
+
+- Install command on macOS:
+
+```bash
+brew install z3 gmp
+```
+
+If you're on an arm based Apple machine (m1/m2 mac) you'll need to install `gmp` and export some
+environment variables
+
+```
+export CFLAGS=-I`brew --prefix gmp`/include
+export LDFLAGS=-L`brew --prefix gmp`/lib
+```
+
+- Install command on Ubuntu:
+
+```bash
+sudo apt install libz3-dev libgmp3-dev
+```
+
+2. Install Python3.9 with dev dependencies (`python3.9 python3.9-venv python3.9-dev`) into your base env.
+   If you do not have the dev dependencies installed the installation will fail.
+   <br>
+
+- Install commands on MacOS:
+
+```bash
+brew install [email protected]
+```
+
+With python3.9 already installed you have venv covered:
+
+> If you are using Python 3.3 or newer (...) venv is included in the Python standard library and requires no additional installation.
+
+Then you can install dev package using pip:
+
+```bash
+pip install python-dev-tools
+```
+
+- Install commands on Ubuntu:
+
+```bash
+sudo apt install python3.9 python3.9-venv python3.9-dev
+```
+
+Or you can just install python3.9 and then install python-dev-tools using pip.

docs/yarn.lock

@@ -2266,11 +2266,16 @@ acorn@^6.1.1:
   resolved "https://registry.yarnpkg.com/acorn/-/acorn-6.4.2.tgz#35866fd710528e92de10cf06016498e47e39e1e6"
   integrity sha512-XtGIhXwF8YM8bJhGxG5kXgjkEuNGLTkoYqVE+KMR+aspr4KGYmKYg7yUe3KghyQ9yheNwLnjmzh/7+gfDBmHCQ==
 
-acorn@^8.0.4, acorn@^8.4.1, acorn@^8.5.0:
+acorn@^8.0.4, acorn@^8.5.0:
   version "8.8.0"
   resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.8.0.tgz#88c0187620435c7f6015803f5539dae05a9dbea8"
   integrity sha512-QOxyigPVrpZ2GXT+PFyZTl6TtOFc5egxHIP9IlQ+RbupQuX4RkT/Bee4/kQuC02Xkzg84JcT7oLYtDIQxp+v7w==
 
+acorn@^8.7.1:
+  version "8.8.2"
+  resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.8.2.tgz#1b2f25db02af965399b9776b0c2c391276d37c4a"
+  integrity sha512-xjIYgE8HBrkpd/sJqOGNspf8uHG+NOHGOw6a/Urj8taM2EXfdNAH2oFcPeIFfsv3+kz/mJrS5VuMqbNLjCa2vw==
+
 address@^1.0.1, address@^1.1.2:
   version "1.2.0"
   resolved "https://registry.yarnpkg.com/address/-/address-1.2.0.tgz#d352a62c92fee90f89a693eccd2a8b2139ab02d9"
@@ -3501,10 +3506,10 @@ end-of-stream@^1.1.0:
   dependencies:
     once "^1.4.0"
 
-enhanced-resolve@^5.9.3:
-  version "5.10.0"
-  resolved "https://registry.yarnpkg.com/enhanced-resolve/-/enhanced-resolve-5.10.0.tgz#0dc579c3bb2a1032e357ac45b8f3a6f3ad4fb1e6"
-  integrity sha512-T0yTFjdpldGY8PmuXXR0PyQ1ufZpEGiHVrp7zHKB7jdR4qlmZHhONVM5AQOAWXuF/w3dnHbEQVrNptJgt7F+cQ==
+enhanced-resolve@^5.10.0:
+  version "5.12.0"
+  resolved "https://registry.yarnpkg.com/enhanced-resolve/-/enhanced-resolve-5.12.0.tgz#300e1c90228f5b570c4d35babf263f6da7155634"
+  integrity sha512-QHTXI/sZQmko1cbDoNAa3mJ5qhWUUNAq3vR0/YiD379fWQrcfuoX1+HW2S0MTt7XmoPLapdaDKUtelUSPic7hQ==
   dependencies:
     graceful-fs "^4.2.4"
     tapable "^2.2.0"
@@ -7392,7 +7397,7 @@ wait-on@^6.0.0:
     minimist "^1.2.5"
     rxjs "^7.5.4"
 
-watchpack@^2.3.1:
+watchpack@^2.4.0:
   version "2.4.0"
   resolved "https://registry.yarnpkg.com/watchpack/-/watchpack-2.4.0.tgz#fa33032374962c78113f93c7f2fb4c54c9862a5d"
   integrity sha512-Lcvm7MGST/4fup+ifyKi2hjyIAwcdI4HRgtvTpIUxBRhB+RFtUh8XtDOxUfctVCnhVi+QQj49i91OyvzkJl6cg==
@@ -7500,20 +7505,20 @@ webpack-sources@^3.2.2, webpack-sources@^3.2.3:
   integrity sha512-/DyMEOrDgLKKIG0fmvtz+4dUX/3Ghozwgm6iPp8KRhvn+eQf9+Q7GWxVNMk3+uCPWfdXYC4ExGBckIXdFEfH1w==
 
 webpack@^5.61.0:
-  version "5.73.0"
-  resolved "https://registry.yarnpkg.com/webpack/-/webpack-5.73.0.tgz#bbd17738f8a53ee5760ea2f59dce7f3431d35d38"
-  integrity sha512-svjudQRPPa0YiOYa2lM/Gacw0r6PvxptHj4FuEKQ2kX05ZLkjbVc5MnPs6its5j7IZljnIqSVo/OsY2X0IpHGA==
+  version "5.76.1"
+  resolved "https://registry.yarnpkg.com/webpack/-/webpack-5.76.1.tgz#7773de017e988bccb0f13c7d75ec245f377d295c"
+  integrity sha512-4+YIK4Abzv8172/SGqObnUjaIHjLEuUasz9EwQj/9xmPPkYJy2Mh03Q/lJfSD3YLzbxy5FeTq5Uw0323Oh6SJQ==
   dependencies:
     "@types/eslint-scope" "^3.7.3"
     "@types/estree" "^0.0.51"
     "@webassemblyjs/ast" "1.11.1"
     "@webassemblyjs/wasm-edit" "1.11.1"
     "@webassemblyjs/wasm-parser" "1.11.1"
-    acorn "^8.4.1"
+    acorn "^8.7.1"
     acorn-import-assertions "^1.7.6"
     browserslist "^4.14.5"
     chrome-trace-event "^1.0.2"
-    enhanced-resolve "^5.9.3"
+    enhanced-resolve "^5.10.0"
     es-module-lexer "^0.9.0"
     eslint-scope "5.1.1"
     events "^3.2.0"
@@ -7526,7 +7531,7 @@ webpack@^5.61.0:
     schema-utils "^3.1.0"
     tapable "^2.1.1"
     terser-webpack-plugin "^5.1.3"
-    watchpack "^2.3.1"
+    watchpack "^2.4.0"
     webpack-sources "^3.2.3"
 
 webpackbar@^5.0.2:

installation.md

@@ -0,0 +1,35 @@
+# Installation
+
+The first step is to make sure you have all required external [dependencies](dependencies.md) installed.
+
+Then perform the following instructions in order:
+
+1. Add the warp package from npm.
+
+```bash
+yarn global add @nethermindeth/warp
+```
+
+2. Ensure the package was added by checking the version number:
+
+```bash
+warp version
+```
+
+3. Install the dependencies:
+
+```bash
+warp install --verbose
+```
+
+Use the `--python` flag to pass the path to `python3.9` binary, if the above command complains.
+
+```bash
+warp install --python <path/to/python3.9> --verbose
+```
+
+4. Test the installation worked by transpiling an example ERC20 contract:
+
+```bash
+warp transpile <contract-path>
+```