software-mansion/protostar

Protostar is a toolchain for developing and testing Starknet contracts

⚠️ WARNING ⚠️

This project is now considered legacy!

If you want to use Cairo 2.0 contracts, consider migrating to starknet-foundry developed by Software Mansion in collaboration with Foundry Foundation.
New features will not be added to this project.
https://github.com/foundry-rs/starknet-foundry

---

Starknet smart contract development toolchain

---

Protostar helps with writing, deploying, and testing your smart contracts. It is loosely inspired by Foundry.

Protostar is actively developed 🔨 . We release every two weeks. Our roadmap is public, see what is coming soon!

Install with

curl -L https://raw.githubusercontent.com/software-mansion/protostar/master/install.sh | bash

Documentation 📄

Table of contents

• Additional resources
• Installation
• Development
  • Setting up environment
    • Bumping cairo bindings version
      • Caveats:
    • Submodules development
    • Git hooks
• Updating website/docs

Additional resources

• Testing Starknet contracts made easy with Protostar

Installation

To install Protostar, run:

curl -L https://raw.githubusercontent.com/software-mansion/protostar/master/install.sh | bash

If you want to specify a version, run the following command with the requested version:

curl -L https://raw.githubusercontent.com/software-mansion/protostar/master/install.sh | bash -s -- -v 0.3.2

---

Development

Setting up environment

1. Install Python version management tool: pyenv or asdf
2. Install Python 3.9.14 using the Python version management tool and activate that version
   • To be able to build Protostar, set the following environmental variable before installing Python: PYTHON_CONFIGURE_OPTS="--enable-shared"
3. Clone this repository
4. Verify the active Python version: python -V
5. Install Poetry — a dependency manager
6. Create Python virtual environment in the project directory: poetry env use 3.9
7. Activate environment: poetry shell
8. Upgrade pip: pip install --upgrade pip
9. Install project dependencies: poetry install
   • MacBook M1/M2: CFLAGS=-I/opt/homebrew/opt/gmp/include LDFLAGS=-L/opt/homebrew/opt/gmp/lib poetry install
10. Install bindings for the rust tools used by protostar:
    • install rust
    • poetry run poe install_all_bindings
11. Patch the git's config by always allowing file transport: git config --global protocol.file.allow always (needed for some tests to pass)
12. Verify the setup by running tests: poe test
13. Build Protostar: poe build
    • You can find the newly created binary at dist/protostar/protostar

Bumping cairo bindings version

To bump cairo bindings version to the latest commit on fork (master branch), run:

poetry run poe bump_cairo_bindings

After this, you can pull & rebuild your local version of bindings by running:

poetry run poe install_all_bindings

Caveats:

Remember to have your working tree clean, since it creates a commit on the current branch.

The command will check if the tracking branch is master, so you don't commit/push to master by accident (would be rejected by branch protection).

Submodules development

You can use submodules from a different branch than main. Run commands

git submodule set-branch --branch <your-branch>
poetry run poe install_all_bindings

Remember to not push those changes to the repository.

Git hooks

Run the following script to enable lint checks and automatic formatting before commit/push.

./scripts/apply_hooks.sh

Updating website/docs

Please read website/README.md.

protostar's Issues

Add compilation of the project

Allow configuring and running compilation for the project. We should use the starknet compiler from cairo-lang. We should parse remapping of the repo names to corresponding directories, and modify imports on the fly.

Add configuration class for the tool

It should parse a .toml file (or envs) and accept overwriting updates for it's state.
The order in which we will be accepting for this config will be:

1. Global config (.toml somewhere in home/tool directory)
2. Local .toml file
3. Environment variables (override all else settings)

Add `init` command

Should work something like poetry init.
The function should accept various config parameters to allow for adapting the existing project to be protostar compatible (libraries root etc.)

Document: "Installation" and "Project initialization"

Add command to adjust existing project to protostar

Fix library functions importing in tests

Implement more cheatcodes, based on existing ones and `foundry`

Integration tests setup

We need to set up integration test suite, testing all of the existing commands

Support installing packages under custom name as a way of avoiding conflicts

Add `remove` command

Remove command should remove submodule directory and corresponding files in .git.

Add tool installer

Add missing (test) assertions

Compared to Foundry

Utilize contracts filed from package.toml in compiliation

Add functions for installing cairo contracts from github repo, in specified location

We should provide functions which allow installation of cairo contracts bundles from github repos. We should parametrize it to allow easy definition of dependency desination.
In this phase we should use git submodules to facilitate management of versions.

Rename command "compile" to "build"

The CLI should be as similar as possible to the Foundry's CLI.

Allow hints in tests

We need to allow hints in tests. InternalDeploy has to be used for this.

Handle errors in a user-friendly way

`libs_path` tweaks

When libs_path is unfilled at init, it will point to the root of the project as the library directory.
Also we should take that path into account when installing dependencies - we should install it in that directory

Improve default template

• Add working cairo files

Integrate compilation with the .toml `contracts` config

Research and implement some simple cheatcodes

Command upgrading protostar

It should include
protostar upgrade - upgrades cli to newest version
protostar --version - prints current cli version

Make package_root and lib_root easier to maintain

Support ARM processors

zsh: bad CPU type in executable: protostar

Deploy protostar on pip

Fix `syscall_ptr` in `mock_call`

Fix testing environment

We probably shouldn't cd inside tests

protostar/src/commands/install/pull_package_submodules_test.py

Line 122 in afb0e3a

os.chdir(repo_clone_dir)

Reaserch & POC - integration testing in cairo

Remove chdir from integration tests

Leaving it as open question because I am actually not sure we should or shouldn't do it. It is not a priority thought.

Improve initial loading time

Add `expectEmit` cheatcode

• consider using with_attr

function expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData) external;

This cheat code is used to assert that certain logs are emitted on the next call.

1. Call the cheat code, specifying whether we should check the first, second or third topic, and the log data.
2. Emit the event we are supposed to see after the next call.
3. Perform the call.

If the event is not available in the current scope (e.g because we are using an interface, or an external smart contract), we can define the event ourselves with an identical event signature.

The cheatcode does not check the origin of the event, but simply that it was emitted during that call.

event Transfer(address indexed from, address indexed to, uint256 amount);

function testERC20EmitsTransfer() public {
  // Only `src` and `dst` are indexed in ERC20's `Transfer` event,
  // so we only check topic 0 and 1, as well as the data (`amount`).
  cheats.expectEmit(true, true, false, true);

  // We emit the event we expect to see.
  emit MyToken.Transfer(address(this), address(1), 10);

  // We perform the call.
  myToken.transfer(address(1), 10);
}

Calls to other cheat codes before the final call are ignored, meaning we can also do something like this:

function testERC20EmitsTransfer() public {
  // The first two lines are the same as above.
  cheats.expectEmit(true, true, false, true);
  emit MyToken.Transfer(address(alice), address(1), 10);

  // Use the `prank` cheat code to impersonate a user.
  cheats.prank(address(alice));

  // We perform the call.
  myToken.transfer(address(1), 10);
}

We can also assert that multiple events are emitted in a single call. For example:

function testERC20EmitsBatchTransfer() public {
  // We declare multiple expected transfer events
  for (uint256 i = 0; i < users.length; i++) {
    cheats.expectEmit(true, true, true, true);
    emit Transfer(address(this), users[i], 10);
  }

  // We also expect a custom `BatchTransfer(uint256 numberOfTransfers)` event.
  cheats.expectEmit(false, false, false, false);
  emit BatchTransfer(users.length);

  // We perform the call.
  myToken.batchTransfer(users, 10);
}

Add test runner

It should accept test functions/contracts and run each one of them in isolation

Add custom protostar path and source repo for upgrade command

Add `new` command

Init new repo inside of the init script

Preprocessor errors should be caught and expected (i.e. `build` procedure)

Those should be treated as user error, not a protostar one:

starkware.cairo.lang.compiler.preprocessor.preprocessor_error.PreprocessorError: src/main.cairo:5:5: Hint is not whitelisted.
This may indicate that this library function cannot be used in StarkNet contracts.
    %{ val = 123 %}
    ^*************^
Unexpected Protostar error. Report it here:
https://github.com/software-mansion/protostar/issues

Improve cheatcodes injections

Reaserch & POC - cheatcodes

Bootstrap the documentation and it's hosting

Write proper readme

Setup GH Actions

Like in starknet.py - on each PR

Replace existing cheats implementation to be usable from hints

Add `--version` command

Add functions for collecting cairo tests

Some test function definition patterns would be nice as well.

Setup logging

Logger should be configurable by verboseness and should allow disabling or enabling colorizing.

Add `update` command

Support installing packages by `author_name`/`repo_name`@`version`

Support different CPU architectures (ARM most importantly)

We need to support running this took natively on apple silicon which is becoming more common, so supporting other archs should not be that difficult

Fetch submodules if no argument is provided to `install` command

Make a package referencing consistent across commands