Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cygaar/inkmate
Building block smart contracts written in Rust for Stylus
https://github.com/cygaar/inkmate
Last synced: about 1 month ago
JSON representation
Building block smart contracts written in Rust for Stylus
- Host: GitHub
- URL: https://github.com/cygaar/inkmate
- Owner: cygaar
- License: mit
- Created: 2024-04-03T18:34:56.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-07-14T15:46:53.000Z (4 months ago)
- Last Synced: 2024-08-02T11:22:08.840Z (4 months ago)
- Language: Rust
- Size: 428 KB
- Stars: 39
- Watchers: 3
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-stylus - Inkmate - Gas-efficient smart contracts written in Rust, including ERC20 and ERC721 (Libraries)
README
# 🖊️ inkmate
**Modern**, **opinionated**, and **gas optimized** building blocks for **smart contract development** in Rust for [Stylus](https://docs.arbitrum.io/stylus/stylus-gentle-introduction).
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
```ml
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](https://docs.arbitrum.io/stylus/stylus-quickstart).
Once you've done that, you can start a new Stylus project by running:
```bash
cargo stylus new
```
Install `inkmate` by running:
```bash
cargo add inkmate
```
If you want to only install certain features (ex. erc20), you can run:
```bash
cargo add inkmate --features "erc20"
```
Alternatively, you can add the following to your `Cargo.toml` file (replace `0.0.5` with your preferred version):
```toml
[dependencies]
inkmate = { version = "0.0.5", features = ["erc20"] }
```
Here's an example contract that uses `inkmate`
```rust
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 erc20;
}
}
#[external]
#[inherit(ERC20)]
impl ERC20Mock {
pub fn mint(&mut self, qty: U256) -> Result<(), Vec> {
self.erc20._mint(msg::sender(), qty);
Ok(())
}
pub fn burn(&mut self, qty: U256) -> Result<(), Vec> {
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:
```bash
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:
```bash
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:
```bash
cargo stylus deploy -e https://stylus-testnet.arbitrum.io/rpc --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:
```bash
cargo test -p inkmate-common
```
## Acknowledgements
These contracts were inspired by or directly modified from many sources, primarily:
- [solmate](https://github.com/transmissions11/solmate)
- [renegade](https://github.com/renegade-fi/renegade-contracts)
- [solady](https://github.com/Vectorized/solady)
- [revm](https://github.com/bluealloy/revm)
- [stylus-sdk](https://github.com/OffchainLabs/stylus-sdk-rs)