State-of-the-art, highly opinionated, hyper-optimised, and secure ๐Vyper smart contract building blocks.
Warning
This is experimental software and is provided on an "as is" and "as available" basis. We do not give any warranties and will not be liable for any losses incurred through any use of this code base.
- ๐ Contracts
- ๐ Installation
- ๐ง Usage
- ๐ฉ๐ผโโ๏ธ Tests
- ๐ฎโโ๏ธ Audits
- ๐๐ผ Acknowledgements
- ๐ซก Contributing
- ๐ธ Donation
- ๐ข Disclaimer
src
โโโ snekmate
โโโ auth
โ โโโ ownable โ "Owner-Based Access Control Functions"
โ โโโ ownable_2step โ "2-Step Ownership Transfer Functions"
โ โโโ access_control โ "Multi-Role-Based Access Control Functions"
โ โโโ interfaces
โ โ โโโ IAccessControl โ "AccessControl Interface Definition"
โ โโโ mocks
โ โโโ ownable_mock โ "`ownable` Module Reference Implementation"
โ โโโ ownable_2step_mock โ "`ownable_2step` Module Reference Implementation"
โ โโโ access_control_mock โ "`access_control` Module Reference Implementation"
โโโ extensions
โ โโโ erc2981 โ "ERC-721 and ERC-1155 Compatible ERC-2981 Reference Implementation"
โ โโโ erc4626 โ "Modern and Gas-Efficient ERC-4626 Tokenised Vault Implementation"
โ โโโ interfaces
โ โ โโโ IERC2981 โ "EIP-2981 Interface Definition"
โ โโโ mocks
โ โโโ erc2981_mock โ "`erc2981` Module Reference Implementation"
โ โโโ erc4626_mock โ "`erc4626` Module Reference Implementation"
โโโ governance
โ โโโ timelock_controller โ "Multi-Role-Based Timelock Controller Reference Implementation"
โ โโโ mocks
โ โโโ timelock_controller_mock โ "`timelock_controller` Module Reference Implementation"
โโโ tokens
โ โโโ erc20 โ "Modern and Gas-Efficient ERC-20 + EIP-2612 Implementation"
โ โโโ erc721 โ "Modern and Gas-Efficient ERC-721 + EIP-4494 Implementation"
โ โโโ erc1155 โ "Modern and Gas-Efficient ERC-1155 Implementation"
โ โโโ interfaces
โ โ โโโ IERC20Permit โ "EIP-2612 Interface Definition"
โ โ โโโ IERC721Enumerable โ "EIP-721 Optional Enumeration Interface Definition"
โ โ โโโ IERC721Metadata โ "EIP-721 Optional Metadata Interface Definition"
โ โ โโโ IERC721Permit โ "EIP-4494 Interface Definition"
โ โ โโโ IERC721Receiver โ "EIP-721 Token Receiver Interface Definition"
โ โ โโโ IERC1155 โ "EIP-1155 Interface Definition"
โ โ โโโ IERC1155MetadataURI โ "EIP-1155 Optional Metadata Interface Definition"
โ โ โโโ IERC1155Receiver โ "EIP-1155 Token Receiver Interface Definition"
โ โ โโโ IERC4906 โ "EIP-4906 Interface Definition"
โ โโโ mocks
โ โโโ erc20_mock โ "`erc20` Module Reference Implementation"
โ โโโ erc721_mock โ "`erc721` Module Reference Implementation"
โ โโโ erc1155_mock โ "`erc1155` Module Reference Implementation"
โโโ utils
โโโ base64 โ "Base64 Encoding and Decoding Functions"
โโโ batch_distributor โ "Batch Sending Both Native and ERC-20 Tokens"
โโโ create_address โ "`CREATE` EVM Opcode Utility Function for Address Calculation"
โโโ create2_address โ "`CREATE2` EVM Opcode Utility Functions for Address Calculations"
โโโ ecdsa โ "Elliptic Curve Digital Signature Algorithm (ECDSA) Secp256k1-Based Functions"
โโโ p256 โ "Elliptic Curve Digital Signature Algorithm (ECDSA) Secp256r1-Based Functions"
โโโ message_hash_utils โ "Signature Message Hash Utility Functions"
โโโ signature_checker โ "ECDSA and EIP-1271 Signature Verification Functions"
โโโ eip712_domain_separator โ "EIP-712 Domain Separator"
โโโ math โ "Standard Mathematical Utility Functions"
โโโ merkle_proof_verification โ "Merkle Tree Proof Verification Functions"
โโโ multicall โ "Multicall Functions"
โโโ interfaces
โ โโโ IERC1271 โ "EIP-1271 Interface Definition"
โ โโโ IERC5267 โ "EIP-5267 Interface Definition"
โโโ mocks
โโโ base64_mock โ "`base64` Module Reference Implementation"
โโโ batch_distributor_mock โ "`batch_distributor` Module Reference Implementation"
โโโ create_address_mock โ "`create_address` Module Reference Implementation"
โโโ create2_address_mock โ "`create2_address` Module Reference Implementation"
โโโ ecdsa_mock โ "`ecdsa` Module Reference Implementation"
โโโ p256_mock โ "`p256` Module Reference Implementation"
โโโ message_hash_utils_mock โ "`message_hash_utils` Module Reference Implementation"
โโโ signature_checker_mock โ "`signature_checker` Module Reference Implementation"
โโโ eip712_domain_separator_mock โ "`eip712_domain_separator` Module Reference Implementation"
โโโ math_mock โ "`math` Module Reference Implementation"
โโโ merkle_proof_verification_mock โ "`merkle_proof_verification` Module Reference Implementation"
โโโ multicall_mock โ "`multicall` Module Reference Implementation"
Important
๐ snekmate uses a ZeroVer-based versioning scheme. This means ๐ snekmate's major version will never exceed the first and most important number in computing: zero.
We offer three convenient ways to install the ๐ snekmate contracts:
You can install ๐ snekmate from PyPI with:
pip install snekmate
When using the ๐Vyper CLI, the search path defaults to the current working directory and the Python
sys.path
. As a result, all imported ๐ snekmate contracts (e.g.from snekmate.tokens import erc20
) are seamlessly located during compilation.
You can install ๐ snekmate via submodules using Foundry with:
forge install pcaversaccio/snekmate
Note
If you want to leverage ๐ snekmate's VyperDeployer
contract for your own testing, ensure that you compile the ๐Vyper contracts with the same EVM version as configured in your foundry.toml
file. The VyperDeployer
contract offers two overloaded deployContract
functions that allow the configuration of the target EVM version. Please note that since ๐Vyper version 0.4.0
the default EVM version is set to cancun
. Furthermore, the VyperDeployer
contract relies on the Python script compile.py
for successful compilation and deployment. Always use the VyperDeployer
contract alongside with the aforementioned script.
You can install ๐ snekmate from npm with:
npm install --save-dev snekmate
Or if you are using Yarn:
yarn add --dev snekmate
In case you are using pnpm, invoke:
pnpm add --save-dev snekmate
Caution
It is possible to install the latest versions of main
or any other branch locally via pip install git+https://github.com/pcaversaccio/snekmate.git@<branch>
or forge install pcaversaccio/snekmate && forge update
. Each branch, including the main
branch, must be understood as a development branch that should be avoided in favour of tagged releases. The release process includes security measures that the repository branches do not guarantee.
๐Vyper favours code reuse through composition rather than inheritance (Solidity inheritance makes it easy to break the Liskov Substitution Principle). A ๐Vyper module encapsulates everything required for code reuse, from type and function declarations to state. All ๐ snekmate contracts are ๐Vyper modules. Thus, many of the ๐ snekmate contracts do not compile independently, but you must import
and initializes
them. Please note that if a module is stateless, it does not require the keyword initializes
(or uses
) for initialisation (or usage). Each module contract has an associated mock contract in the mock/
directory, which is part of the associated contract subdirectory. These mock contracts are very illustrative of how ๐ snekmate contracts can be used as ๐Vyper modules.
Important
All ๐ snekmate contracts are very well documented in the form of general code and NatSpec comments. There are no shortcuts โ if you are importing specific logic, read the documentation!
Please read here to learn more about using ๐Vyper modules.
This repository contains Foundry-based unit tests, property-based tests (i.e. stateless fuzzing), and invariant tests (i.e. stateful fuzzing) for all contracts, if applicable. All tests are run as part of the CI pipeline test-contracts
.
Note
An invariant is a property of a program that should always hold true. Fuzzing is a way of checking whether the invariant is falsifiable.
Contract | Unit Tests | Property-Based Tests | Invariant Tests |
---|---|---|---|
ownable |
โ | โ | โ |
ownable_2step |
โ | โ | โ |
access_control |
โ | โ | โ |
erc2981 |
โ | โ | โ |
erc4626 |
โ | โ | โ |
timelock_controller |
โ | โ | โ |
erc20 |
โ | โ | โ |
erc721 |
โ | โ | โ |
erc1155 |
โ | โ | โ |
base64 |
โ | โ | โ |
batch_distributor |
โ | โ | โ |
create_address |
โ | โ | โ |
create2_address |
โ | โ | โ |
ecdsa |
โ | โ | โ |
p256 |
โ | โ | โ |
message_hash_utils |
โ | โ | โ |
signature_checker |
โ | โ | โ |
eip712_domain_separator |
โ | โ | โ |
math |
โ | โ | โ |
merkle_proof_verification |
โ | โ | โ |
multicall |
โ | โ | โ |
โ Test Type Implemented โ โ Test Type Not Implemented
Furthermore, the echidna
-based property tests for the erc20
and erc721
contracts are available in the test/tokens/echidna/
directory. You can run the tests by invoking:
# Run Echidna ERC-20 property tests.
~$ FOUNDRY_PROFILE=echidna echidna test/tokens/echidna/ERC20Properties.sol --contract CryticERC20ExternalHarness --config test/echidna.yaml
# Run Echidna ERC-721 property tests.
~$ FOUNDRY_PROFILE=echidna echidna test/tokens/echidna/ERC721Properties.sol --contract CryticERC721ExternalHarness --config test/echidna.yaml
Eventually, the halmos
-based symbolic tests for the erc20
, erc721
, erc1155
, and math
contracts are available in the test/tokens/halmos/
and test/utils/halmos/
directories. You can run the tests by invoking:
Important
You must install the Yices 2 SMT solver before invoking the halmos
-based symbolic tests.
# Run Halmos ERC-20 symbolic tests.
~$ FOUNDRY_PROFILE=halmos halmos --contract ERC20TestHalmos --config test/halmos.toml
# Run Halmos ERC-721 symbolic tests. Be careful, this is a (very!) time-consuming operation.
~$ FOUNDRY_PROFILE=halmos halmos --contract ERC721TestHalmos --config test/halmos.toml
# Run Halmos ERC-1155 symbolic tests. Be careful, this is a (very!) time-consuming operation.
~$ FOUNDRY_PROFILE=halmos halmos --contract ERC1155TestHalmos --config test/halmos.toml
# Run Halmos math symbolic tests.
~$ FOUNDRY_PROFILE=halmos halmos --contract MathTestHalmos --config test/halmos.toml
Tip
If you encounter any issues, please ensure that you have the latest ๐Vyper version installed locally.
Although the ๐ snekmate contracts have not (yet) undergone a full comprehensive audit, selected library modules integrated into specific protocols (such as Curve) have been thoroughly reviewed within the scope of prior audits. The corresponding audit reports are available here.
This repository is inspired by or directly modified from many sources, primarily:
- ApeAcademy
- Batch Distributor
CREATE
Factory- Disperse Research
- Multicall
- OpenZeppelin Contracts
- Solady
- Solmate
๐ snekmate only exists thanks to its contributors. There are many ways to get involved and contribute to our high-quality and secure smart contracts. Check out our Contribution Guidelines!
I am a strong advocate of the open-source and free software paradigm. However, if you feel my work deserves a donation, you can send it to this address: 0xe9Fa0c8B5d7F79DeC36D3F448B1Ac4cEdedE4e69
. I can pledge that I will use this money to help fix more existing challenges in the Ethereum ecosystem ๐ค.