Skip to content

Latest commit

 

History

History
107 lines (82 loc) · 5.31 KB

CONTRIBUTING.md

File metadata and controls

107 lines (82 loc) · 5.31 KB
Raw

Contributing

This document exists as a brief introduction to how you can contribute to the storage layout extractor project. It includes a guide to getting started and contributing to main, as well as a code tour that briefly goes over the major components of the library.

This repository is written in Rust, a high-performance and low-level language with a smart compiler that helps to write reliable and fast software. If you haven't worked with Rust before, take a look at the "New to Rust?" section below!

Setting Up for Development

Getting set up with this project is pretty simple.

  1. Clone the repository. If you don't want to contribute directly you can use HTTPS clones:

    git clone https://github.com/smlxlio/storage-layout-extractor

    If you do want to contribute directly to the tree, we recommend cloning over SSH:

    git clone [email protected]:smlxlio/storage-layout-extractor.git

  2. Building the project is then as simple as entering the project directory and using cargo.

    cargo build

  3. You can also test using cargo.

    cargo test

Getting Your Work on main

For contributions this repository works on a Pull Request and subsequent review model, supported by CI to check that things avoid being broken. The process works as follows:

  1. If necessary, you fork the repository, but if you have access please create a branch.
  2. You make your changes on that branch.
  3. Pull-request that branch against main.
  4. The pull request will be reviewed, and CI will run on it.
  5. Once reviewers accept the code, and CI has passed, it will be merged to main!

Code Tour

The code in this repository is primarily structured around each of the phases described in the readme.

  • data: This contains useful data structures necessary for the implementation of the library.
  • disassembly: This contains the implementation of the disassembler and the instruction stream used during execution.
  • error: This contains the strongly-typed error representation for the library. The library uses a unified error representation at its interface, but also has individual error representations for each "phase" of the analysis. This portion of the library also implements conversions between the various error types, and mechanisms for locating errors in bytecode.
  • extractor: This contains the driver for the library itself, as well as the implementation of the analysis state machine that makes it harder to get into broken states while analysing a contract.
  • inference: This contains the type checker, as well as the type language used by the library. It also contains the lifting passes and the inference rules used by the inference process, and the implementation of the unifier.
  • opcode: This contains the opcode definition, and the implementations of each individual EVM opcode and their symbolic semantics.
  • vm: This contains the implementation of the symbolic virtual machine and the state it needs to execute.

This project is a library and hence does not come with a driver to enable its use directly as a product. It can easily be wrapped in a CLI or server to enable working with it in a more user-facing fashion.

A good demonstration of how to use the library in both simple and complex scenarios can be found in the integration tests. Reading the common test utilities will likely be a good introduction to the various modes of usage, as well as an explanation of the kind of functionality a driver program will require.

New to Rust?

If you are new to working with Rust, a great place to start is the official Rust Book. It gives a great overview of the language and general style. It's also worth getting familiar with the following tools:

  • Rustup, the Rust toolchain installer.
  • Cargo, the Rust build tool and package manager.
  • docs.rs, a site providing up-to-date crate (package) documentation for all packages published to crates.io, the official package registry.
  • Rustdoc, the ecosystem's official documentation tool.

In terms of development tooling, there are two major options in this space.