justrightnow / warp

Warp - Bringing Solidity to StarkNet at warp speed. Warp is a Solidity to Cairo Transpiler, this allows teams to write/migrate Solidity to Cairo for easy onboarding into the StarkNet ecosystem.

Warp

Warp brings Solidity to StarkNet, making it possible to transpile Ethereum smart contracts to StarkNet Cairo Contracts.

Quickstart

Docker compose provides a ready to use environment featuring warp and devnet.

Build and run containers

docker-compose up

Transpile

docker-compose exec warp warp transpile example_contracts/ERC20.sol

Alternatively for warp developers:

docker-compose exec warp npx ts-node src transpile example_contracts/ERC20.sol

It's best to copy the contract/repo to the warp directory so it is available in container via volume. Use contract's paths relative to warp root. For example, assuming you've copied your project to warp/projects/myproject you can replace example_contracts/ERC20.sol with projects/myproject/mycontract.sol in the above commands.

Deploy to devnet

docker-compose exec warp warp compile warp_output/example__contracts/ERC20__WC__WARP.cairo
docker-compose exec warp starknet deploy --no_wallet --contract warp_output/example__contracts/ERC20__WC__WARP_compiled.json --gateway_url http://devnet:5050

Documentation 📖

You can read the documentation here.

Installation ⚙️

Dependencies

---

1. You will need z3 and gmp installed to use Warp.

• Install command on macOS:

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:

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.
   

Warp Installation Method 1:

---

Without any virtual environment activated perform the following in order:

1. Add the warp package from npm.

yarn global add @nethermindeth/warp

2. Ensure the package was added by checking the version number:

warp version

3. Install the dependencies:

warp install --verbose

Use the --python flag to pass the path to python3.9 binary, if the above command complains.

warp install --python <path/to/python3.9> --verbose

4. Test the installation worked by transpiling an example ERC20 contract:

warp transpile example_contracts/ERC20.sol

Warp Installation Method 2 (from source/for devs):

---

Make sure you have the dependencies installed first.

With a virtual environment (recommended Python3.9) activated:

1. Clone this repo and change directory into the warp folder.

2. Install the JavaScript dependencies:

yarn

3. Install the Python dependencies:

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:

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:

yarn warplib

5. Test the installation worked by transpiling an example ERC20 contract:

bin/warp transpile example_contracts/ERC20.sol

Usage 💻

If you have used installation method 1 you can use the warp command in any folder. If you have used installation method 2, you will have to specify the path to the warp directory followed by bin/warp e.g path_to_warp_repo/bin/warp ...

StarkNet setup

Select your network and wallet types. It's recommended to set these as environment variables but they can also be passed as explicit arguments to the Warp CLI and the StarkNet CLI.

export STARKNET_WALLET=starkware.starknet.wallets.open_zeppelin.OpenZeppelinAccount
export STARKNET_NETWORK=alpha-goerli

Make sure you have a StarkNet account set up, if you have not done so yet please:

warp deploy_account

CLI Commands

---

To transpile a Solidity contract:

warp transpile <path to Solidity contract>

To declare a StarkNet contract:

warp declare <path to StarkNet contract>

Please note to deploy a contract you will first have to declare it.

To deploy a StarkNet contract:

warp deploy <path to StarkNet contract>

The deploy command will generate the compiled json file as well as the abi json file. Use warp deploy --help command to see more deployment options.

Libraries

---

Libraries are bundled into the point of use, therefore if you try transpile a standalone library it will result in no output. If you would like to transpile and deploy a standalone library please alter its declaration to `contract`.

Unsupported Solidity Features

---

Several features of Solidity are not supported/do not have analogs in Starknet yet. We will try our best to add these features as StarkNet supports them, but some may not be possible due to fundamental differences in the platforms.

Please see the list below:

Support Status	Symbol
Will likely never be supported	❌
Being developed/investigated	⚒️
Currently Unknown/If added in Cairo	❓

Solidity	Support Status
fallback functions with args	⚒️
delegate calls	⚒️
low level calls	❌
indexed parameters	❓
nested tuple expressions	❓
typeName expressions	❓
gasleft()	❓
msg.value	❓
msg.sig	❓
msg.data	❓
tx.gasprice	❓
tx.origin	❓
try/catch	❓
block.coinbase	❓
block.gaslimit	❓
block.basefee	❓
block.chainid	❓
block.difficulty	❌
precompiles (apart from ecrecover)	❓
selfdestruct	❓
blockhash	❓
functions pointers in storage	❓
sha256 (use keccak256 instead)	❌
ternary operator	⚒️
receive	❓
Inline Yul Assembly - arithmetic (add, sub ...)	⚒️
Inline Yul Assembly - (memory, calldata, storage)	❓
user defined errors	❓
function call options e.g x.f{gas: 10000}(arg1)	❓
member access of address object e.g address.balance	❓
nested tuple assignments	❓

Note: We have changed the return of ecrecover to be uint160 because we use the address type for StarkNet addresses.

Docker 🐳

Build the image from source:

docker build -t warp .

Run the container with the same options and arguments as the Warp binary:

docker run --rm -v $PWD:/dapp --user $(id -u):$(id -g) warp transpile example_contracts/ERC20.sol

Contributing

Please checkout our database of open tickets here

Testing for contributors 🩺

To test that your contribution doesn't break any features you can test that all previous example contracts transpile and then cairo compile by running the following:

warp test

For this to work, you must have the cairo-lang package installed. To test try:

starknet-compile -v

Instructions to set this up can be found at https://www.cairo-lang.org/docs/quickstart.html

Then to see that your contribution doesn't break the behaviour tests follow these steps:

1. Run the setup script:

tests/behaviour/setup.sh

2. In a separate terminal, start a StarkNet testnet server (in an environment with cairo-lang installed):

yarn testnet

3. Run the tests:

yarn test

To generate benchmarks locally during development:

yarn testnet:benchmark
yarn test

python starknet-testnet/generateMarkdown.py

This saves the benchmarks at benchmark/stats/data.md

Contact Us ☎️

If you run into any problems please raise an issue or contact us on our Nethermind discord server: https://discord.com/invite/PaCMRFdvWT