Awesome
<img align="right" width="150" height="150" top="100" src="./assets/huff.png">huff-rs •
![Discord](https://img.shields.io/discord/980519274600882306)
huff-rs
is a Huff compiler built in rust.
What is a Huff?
Huff is a low-level programming language designed for developing highly optimized smart contracts that run on the Ethereum Virtual Machine (EVM). Huff does not hide the inner workings of the EVM. Instead, Huff exposes its programming stack to the developer for manual manipulation.
Rather than having functions, Huff has macros - individual blocks of bytecode that can be rigorously tested and evaluated using the Huff runtime testing suite.
Huff was originally developed by the Aztec Protocol team to write Weierstrudel. Weierstrudel is an on-chain elliptical curve arithmetic library that requires incredibly optimized code that neither Solidity nor Yul could provide.
While EVM experts can use Huff to write highly-efficient smart contracts for use in production, it can also serve as a way for beginners to learn more about the EVM.
To dive deeper into Huff, visit the Official Huff Docs(also available on github).
Installation
Something not working? Send a message in discord.
First run the command below to get huffup
, the Huff installer:
curl -L get.huff.sh | bash
To avoid redirecting the script directly into bash, download and run the huffup installation script.
To install the Huff compiler, simply run huffup
.
If you have the old huffc (TypeScript version) npm package installed globally, you can remove it with:
sudo yarn global remove huffc
To make sure you are running the rust version, you can run huffc --version
and it should respond with huff_cli <version>
. If it responds with 2.0.0
that means you are running the Typescript version.
$ huffc --version
huff_cli 0.3.2
Alternatively
Install from source by running:
git clone https://raw.githubusercontent.com/huff-language/huff-rs
cd huff-rs
cargo install --path ./huff_cli --bins --locked --force
OR
cargo install --git https://raw.githubusercontent.com/huff-language/huff-rs --locked huff_cli
How Fast?
Compilation Benchmarks
Compiler | Cold (No Cache) | Light Cache | Deep Cache | Full Cache |
---|---|---|---|---|
[huff-language/huff-rs][huff-rs] | XXXms | XXXms | XXXms | XXXms |
[huff-language/huffc][huffc] | XXXms | XXXms | XXXms | XXXms |
Note: Compilation benchmarks were performed on huff-examples erc20.
Architecture
Modules
- huff_core: The core module to huff-rs. Resolves source file paths, executes compilation, and exports artifacts.
- huff_cli: The command line interface for the Huff compiler.
- huff_js: A wasm compatible interface to the Huff compiler for JavaScript bindings.
- huff_lexer: Takes in the source of a
.huff
file and generates a vector ofToken
s. - huff_parser: Crafts a
Contract
AST from the vector ofToken
s generated by huff_lexer. - huff_codegen: EVM Bytecode generation module that accepts an AST generated by huff_parser.
- huff_utils: Various utilities and types used by all modules.
- huffup: Update or revert to a specific huff-rs branch with ease. (Forked from foundry)
Contributing
All contributions are welcome! We want to make contributing to this project as easy and transparent as possible, whether it's:
- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Becoming a maintainer
We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!
To run examples, make sure you update git submodules to pull down the huff-examples submodule by running git submodule update
.
The branching convention used by huff-rs is a stage
branch that is meant to be merged off of and is periodically merged into main
. So, when creating a feature, branch off of the stage
branch and create a pr from your branch into the stage
branch!
i.e:
To pass github actions, please run:
cargo check --all
cargo test --all --all-features
cargo +nightly fmt -- --check
cargo +nightly clippy --all --all-features -- -D warnings
In order to fix any formatting issues, run:
cargo +nightly fmt --all
Recommended PR Template
Here is an example PR template - not strictly required, but will greatly improve the speed at which your PR is reviewed & merged!
## Overview
<Provide a general overview of what your pr accomplishes, why, and how (including links)>
## Checklist
- [x] <Ex: Added a `new` method to the Huff Lexer [here](./huff_lexer/src/lib.rs#50)>
- [x] <Ex: Fully tested the `new` method [here](./huff_lexer/tests/new.rs)>
- [ ] <Ex: Wrote documentation for the `new` method [here](./huff_lexer/README.md#20)>
When the PR checklist isn't complete, it is highly recommended to make it a draft PR. NOTE: if your PR is not complete, it will likely be changed to a draft by one of the repository admins.
For breaking changes: make sure to edit the excalidraw asset and export the file to ./assets/huffc.excalidraw along with an image to ./assets/huffc.png.
Safety
Warning
This is experimental software and is provided on an "as is" and "as available" basis. Expect rapid iteration and use at your own risk.
This code is not designed for safety.
- There are untested invariants in the code that may break.
- You can easily shoot yourself in the foot if you're not careful.
- You should thoroughly read the documentation and examples.
We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.
Acknowledgements
The original Huff Language compiler: huffc
.
An exemplary, minimal rust compiler: ripc.
Foundry, for the many scripts, documentation, devops, and code on which huff-rs is based on.
All huff-rs contributors, users, advocates, and enthusiasts!