🖊️ inkmate

Modern, opinionated, and gas optimized building blocks for smart contract development in Rust for Stylus.

Stylus allows smart contracts to be written in any language that compiles down to web assembly. Stylus contracts are fully compatible with existing EVM smart contracts. Stylus contracts can lead to large gas savings, especially when it comes to memory and compute. Stylus is only supported on Orbit chains based on Arbitrum's Nitro tech stack.

inkmate currently only supports Rust smart contracts, but further support for other languages may be added in the future.

Safety

This is experimental software and is provided on an "as is" and "as available" basis. This code has not been audited!

We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

Contracts

tokens
├─ ERC20 — "Minimalist and gas efficient ERC20 + EIP-2612 implementation"
├─ ERC721 — "Minimalist and gas efficient ERC721 implementation"
├─ ERC721A (coming soon) — "Gas efficient ERC721 implementation with cheap minting costs"
utils
├─ ECRECOVER — "Library for calling ecrecover in Rust smart contracts"

Installation

You'll first need to install the necessary tooling to support Rust Stylus contracts by following the official installation guide.

Once you've done that, you can start a new Stylus project by running:

cargo stylus new <YOUR_PROJECT_NAME>

Install inkmate by running:

cargo add inkmate

If you want to only install certain features (ex. erc20), you can run:

cargo add inkmate --features "erc20"

Alternatively, you can add the following to your Cargo.toml file (replace 0.0.5 with your preferred version):

[dependencies]
inkmate = { version = "0.0.5", features = ["erc20"] }

Here's an example contract that uses inkmate

extern crate alloc;

use alloc::vec::Vec;
use inkmate::tokens::erc20::{ERC20Params, ERC20};
use stylus_sdk::{alloy_primitives::U256, msg, prelude::*};

struct ERC20MockParams;

/// Immutable definitions
impl ERC20Params for ERC20MockParams {
    const NAME: &'static str = "ERC20 Stylus Example";
    const SYMBOL: &'static str = "MOCK";
    const DECIMALS: u8 = 18;
}

sol_storage! {
    #[entrypoint] // Makes ERC20Mock the entrypoint
    struct ERC20Mock {
        #[borrow] // Allows erc20 to access ERC20Mock's storage
        ERC20<ERC20MockParams> erc20;
    }
}

#[external]
#[inherit(ERC20<ERC20MockParams>)]
impl ERC20Mock {
    pub fn mint(&mut self, qty: U256) -> Result<(), Vec<u8>> {
        self.erc20._mint(msg::sender(), qty);
        Ok(())
    }

    pub fn burn(&mut self, qty: U256) -> Result<(), Vec<u8>> {
        self.erc20._burn(msg::sender(), qty)?;
        Ok(())
    }
}

Contributing

This repo is setup as a single Rust workspace with several crates:

common which contains common utility functions
contracts which contains the primary contract logic
samples which contains sample implementations of various contracts

The contracts crate consists of multiple features to allow for conditional compilation and optional dependencies. This helps reduce binary sizes for Stylus contracts.

Because the contracts crate is feature gated, you cannot run cargo stylus check directly as you normally would. To test the validity of our code (ex. erc20), we need to build a specific sample and verify the compiled wasm explicitly.

To build the binary for your selected feature (ex. erc20), you can run:

cargo +nightly build --target wasm32-unknown-unknown --lib --release --features=erc20 -p samples -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort

Then to run check the validity of the contract you can run:

cargo stylus check --wasm-file-path target/wasm32-unknown-unknown/release/samples.wasm

Finally, you can deploy the contract to the Stylus testnet by running:

cargo stylus deploy -e https://stylus-testnet.arbitrum.io/rpc --private-key=<PRIVATE_KEY> --wasm-file-path target/wasm32-unknown-unknown/release/deps/samples.wasm

Testing

Currently, only unit tests for specific pieces of logic are supported. A full set of integration tests will be added soon to test contract interaction logic.

To run unit tests, you can run:

cargo test -p inkmate-common

Acknowledgements

These contracts were inspired by or directly modified from many sources, primarily:

cygaar / inkmate