# 🐍 snekmate <!-- omit from toc -->
[](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.npmjs.com/package/snekmate)
[](https://pypi.org/project/snekmate)
<img src=https://github.com/pcaversaccio/snekmate/assets/25297591/a899251b-d22b-4cb3-8109-88facba53d6a width="1050"/>
**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](#-contracts)
- [🎛 Installation](#-installation)
- [1️⃣ Foundry](#1️⃣-foundry)
- [2️⃣ PyPI](#2️⃣-pypi)
- [3️⃣ npm](#3️⃣-npm)
- [🔧 Usage](#-usage)
- [👩🏼⚖️ Tests](#️-tests)
- [🙏🏼 Acknowledgements](#-acknowledgements)
- [🫡 Contributing](#-contributing)
- [💸 Donation](#-donation)
- [💢 Disclaimer](#-disclaimer)
## 📜 Contracts
```ml
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"
```
## 🎛 Installation
> [!IMPORTANT]
> 🐍 snekmate uses a [ZeroVer](https://0ver.org)-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:
### 1️⃣ Foundry
You can install 🐍 snekmate via submodules using [Foundry](https://github.com/foundry-rs/foundry) with:
```console
forge install pcaversaccio/snekmate
```
> [!NOTE]
> If you want to leverage 🐍 snekmate's [`VyperDeployer`](./lib/utils/VyperDeployer.sol) 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`](./lib/utils/VyperDeployer.sol) contract offers two overloaded `deployContract` functions that allow the configuration of the target EVM version. Please note that since 🐍Vyper version [`0.4.0`](https://github.com/vyperlang/vyper/releases/tag/v0.4.0) the default EVM version is set to `cancun`. Furthermore, the [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract relies on the Python script [`compile.py`](./lib/utils/compile.py) for successful compilation and deployment. Always use the [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract alongside with the aforementioned script.
### 2️⃣ PyPI
You can install 🐍 snekmate from [PyPI](https://pypi.org/project/snekmate) with:
```console
pip install snekmate
```
> You can use `pip install snekmate -t .` to install the contracts directly into the current working directory!
### 3️⃣ npm
You can install 🐍 snekmate from [npm](https://www.npmjs.com/package/snekmate) with:
```console
npm install --save-dev snekmate
```
Or if you are using [Yarn](https://yarnpkg.com):
```console
yarn add --dev snekmate
```
In case you are using [pnpm](https://pnpm.io), invoke:
```console
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.
## 🔧 Usage
🐍Vyper favours code reuse through composition rather than inheritance (Solidity inheritance makes it easy to break the [Liskov Substitution Principle](https://en.wikipedia.org/wiki/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](https://docs.vyperlang.org/en/latest/natspec.html) comments. There are no shortcuts – if you are importing specific logic, read the documentation!
Please read [here](https://docs.vyperlang.org/en/latest/using-modules.html) to learn more about using 🐍Vyper modules.
## 👩🏼⚖️ Tests
This repository contains [Foundry](https://github.com/foundry-rs/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`](./.github/workflows/test-contracts.yml).
> [!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`](https://github.com/crytic/echidna)-based [property](https://github.com/crytic/properties) tests for the [`erc20`](./src/snekmate/tokens/ERC20.vy) and [`erc721`](./src/snekmate/tokens/ERC721.vy) contracts are available in the [`test/tokens/echidna/`](./test/tokens/echidna) directory. You can run the tests by invoking:
```console
# 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`](https://github.com/a16z/halmos)-based symbolic tests for the [`erc20`](./src/snekmate/tokens/erc20.vy), [`erc721`](./src/snekmate/tokens/erc721.vy), [`erc1155`](./src/snekmate/tokens/erc1155.vy), and [`math`](./src/snekmate/utils/math.vy) contracts are available in the [`test/tokens/halmos/`](./test/tokens/halmos) and [`test/utils/halmos/`](./test/utils/halmos) directories. You can run the tests by invoking:
> [!IMPORTANT]
> You must install the [Yices 2 SMT solver](https://github.com/SRI-CSL/yices2) before invoking the [`halmos`](https://github.com/a16z/halmos)-based symbolic tests.
```console
# 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 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](https://github.com/vyperlang/vyper/releases) 🐍Vyper version installed locally.
## 🙏🏼 Acknowledgements
This repository is inspired by or directly modified from many sources, primarily:
- [ApeAcademy](https://github.com/ApeAcademy)
- [Batch Distributor](https://github.com/pcaversaccio/batch-distributor)
- [`CREATE` Factory](https://github.com/pcaversaccio/create-util)
- [Disperse Research](https://github.com/banteg/disperse-research)
- [Multicall](https://github.com/mds1/multicall)
- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts)
- [Solady](https://github.com/Vectorized/solady)
- [Solmate](https://github.com/transmissions11/solmate)
## 🫡 Contributing
🐍 snekmate only exists thanks to its [contributors](https://github.com/pcaversaccio/snekmate/graphs/contributors). There are many ways to get involved and contribute to our high-quality and secure smart contracts. Check out our [Contribution Guidelines](./CONTRIBUTING.md)!
## 💸 Donation
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`](https://etherscan.io/address/0xe9Fa0c8B5d7F79DeC36D3F448B1Ac4cEdedE4e69). I can pledge that I will use this money to help fix more existing challenges in the Ethereum ecosystem 🤝.
## 💢 Disclaimer
<img src=https://user-images.githubusercontent.com/25297591/167394075-1813e258-3b03-4bc8-9305-69126a07d57e.png width="1050"/>
Raw data
{
"_id": null,
"home_page": null,
"name": "snekmate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Pascal Marco Caversaccio <pascal.caversaccio@hotmail.ch>",
"keywords": "security, library, ethereum, smart-contracts, evm, vyper, vyper-contracts",
"author": null,
"author_email": "Pascal Marco Caversaccio <pascal.caversaccio@hotmail.ch>",
"download_url": "https://files.pythonhosted.org/packages/a5/47/33f865f94c8892e3be93eaa103289709dd373442a02dc689452b18527f62/snekmate-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83d\udc0d snekmate <!-- omit from toc -->\n\n[](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml)\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://www.npmjs.com/package/snekmate)\n[](https://pypi.org/project/snekmate)\n\n<img src=https://github.com/pcaversaccio/snekmate/assets/25297591/a899251b-d22b-4cb3-8109-88facba53d6a width=\"1050\"/>\n\n**State-of-the-art**, **highly opinionated**, **hyper-optimised**, and **secure** \ud83d\udc0dVyper smart contract building blocks.\n\n> [!WARNING]\n> 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.\n\n- [\ud83d\udcdc Contracts](#-contracts)\n- [\ud83c\udf9b Installation](#-installation)\n - [1\ufe0f\u20e3 Foundry](#1\ufe0f\u20e3-foundry)\n - [2\ufe0f\u20e3 PyPI](#2\ufe0f\u20e3-pypi)\n - [3\ufe0f\u20e3 npm](#3\ufe0f\u20e3-npm)\n- [\ud83d\udd27 Usage](#-usage)\n- [\ud83d\udc69\ud83c\udffc\u200d\u2696\ufe0f Tests](#\ufe0f-tests)\n- [\ud83d\ude4f\ud83c\udffc Acknowledgements](#-acknowledgements)\n- [\ud83e\udee1 Contributing](#-contributing)\n- [\ud83d\udcb8 Donation](#-donation)\n- [\ud83d\udca2 Disclaimer](#-disclaimer)\n\n## \ud83d\udcdc Contracts\n\n```ml\nsrc\n\u2514\u2500\u2500 snekmate\n \u251c\u2500\u2500 auth\n \u2502 \u251c\u2500\u2500 ownable \u2014 \"Owner-Based Access Control Functions\"\n \u2502 \u251c\u2500\u2500 ownable_2step \u2014 \"2-Step Ownership Transfer Functions\"\n \u2502 \u251c\u2500\u2500 access_control \u2014 \"Multi-Role-Based Access Control Functions\"\n \u2502 \u251c\u2500\u2500 interfaces\n \u2502 \u2502 \u2514\u2500\u2500 IAccessControl \u2014 \"AccessControl Interface Definition\"\n \u2502 \u2514\u2500\u2500 mocks\n \u2502 \u251c\u2500\u2500 ownable_mock \u2014 \"`ownable` Module Reference Implementation\"\n \u2502 \u251c\u2500\u2500 ownable_2step_mock \u2014 \"`ownable_2step` Module Reference Implementation\"\n \u2502 \u2514\u2500\u2500 access_control_mock \u2014 \"`access_control` Module Reference Implementation\"\n \u251c\u2500\u2500 extensions\n \u2502 \u251c\u2500\u2500 erc2981 \u2014 \"ERC-721 and ERC-1155 Compatible ERC-2981 Reference Implementation\"\n \u2502 \u251c\u2500\u2500 erc4626 \u2014 \"Modern and Gas-Efficient ERC-4626 Tokenised Vault Implementation\"\n \u2502 \u251c\u2500\u2500 interfaces\n \u2502 \u2502 \u2514\u2500\u2500 IERC2981 \u2014 \"EIP-2981 Interface Definition\"\n \u2502 \u2514\u2500\u2500 mocks\n \u2502 \u251c\u2500\u2500 erc2981_mock \u2014 \"`erc2981` Module Reference Implementation\"\n \u2502 \u2514\u2500\u2500 erc4626_mock \u2014 \"`erc4626` Module Reference Implementation\"\n \u251c\u2500\u2500 governance\n \u2502 \u251c\u2500\u2500 timelock_controller \u2014 \"Multi-Role-Based Timelock Controller Reference Implementation\"\n \u2502 \u2514\u2500\u2500 mocks\n \u2502 \u2514\u2500\u2500 timelock_controller_mock \u2014 \"`timelock_controller` Module Reference Implementation\"\n \u251c\u2500\u2500 tokens\n \u2502 \u251c\u2500\u2500 erc20 \u2014 \"Modern and Gas-Efficient ERC-20 + EIP-2612 Implementation\"\n \u2502 \u251c\u2500\u2500 erc721 \u2014 \"Modern and Gas-Efficient ERC-721 + EIP-4494 Implementation\"\n \u2502 \u251c\u2500\u2500 erc1155 \u2014 \"Modern and Gas-Efficient ERC-1155 Implementation\"\n \u2502 \u251c\u2500\u2500 interfaces\n \u2502 \u2502 \u251c\u2500\u2500 IERC20Permit \u2014 \"EIP-2612 Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC721Enumerable \u2014 \"EIP-721 Optional Enumeration Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC721Metadata \u2014 \"EIP-721 Optional Metadata Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC721Permit \u2014 \"EIP-4494 Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC721Receiver \u2014 \"EIP-721 Token Receiver Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC1155 \u2014 \"EIP-1155 Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC1155MetadataURI \u2014 \"EIP-1155 Optional Metadata Interface Definition\"\n \u2502 \u2502 \u251c\u2500\u2500 IERC1155Receiver \u2014 \"EIP-1155 Token Receiver Interface Definition\"\n \u2502 \u2502 \u2514\u2500\u2500 IERC4906 \u2014 \"EIP-4906 Interface Definition\"\n \u2502 \u2514\u2500\u2500 mocks\n \u2502 \u251c\u2500\u2500 erc20_mock \u2014 \"`erc20` Module Reference Implementation\"\n \u2502 \u251c\u2500\u2500 erc721_mock \u2014 \"`erc721` Module Reference Implementation\"\n \u2502 \u2514\u2500\u2500 erc1155_mock \u2014 \"`erc1155` Module Reference Implementation\"\n \u2514\u2500\u2500 utils\n \u251c\u2500\u2500 base64 \u2014 \"Base64 Encoding and Decoding Functions\"\n \u251c\u2500\u2500 batch_distributor \u2014 \"Batch Sending Both Native and ERC-20 Tokens\"\n \u251c\u2500\u2500 create_address \u2014 \"`CREATE` EVM Opcode Utility Function for Address Calculation\"\n \u251c\u2500\u2500 create2_address \u2014 \"`CREATE2` EVM Opcode Utility Functions for Address Calculations\"\n \u251c\u2500\u2500 ecdsa \u2014 \"Elliptic Curve Digital Signature Algorithm (ECDSA) Secp256k1-Based Functions\"\n \u251c\u2500\u2500 p256 \u2014 \"Elliptic Curve Digital Signature Algorithm (ECDSA) Secp256r1-Based Functions\"\n \u251c\u2500\u2500 message_hash_utils \u2014 \"Signature Message Hash Utility Functions\"\n \u251c\u2500\u2500 signature_checker \u2014 \"ECDSA and EIP-1271 Signature Verification Functions\"\n \u251c\u2500\u2500 eip712_domain_separator \u2014 \"EIP-712 Domain Separator\"\n \u251c\u2500\u2500 math \u2014 \"Standard Mathematical Utility Functions\"\n \u251c\u2500\u2500 merkle_proof_verification \u2014 \"Merkle Tree Proof Verification Functions\"\n \u251c\u2500\u2500 multicall \u2014 \"Multicall Functions\"\n \u251c\u2500\u2500 interfaces\n \u2502 \u251c\u2500\u2500 IERC1271 \u2014 \"EIP-1271 Interface Definition\"\n \u2502 \u2514\u2500\u2500 IERC5267 \u2014 \"EIP-5267 Interface Definition\"\n \u2514\u2500\u2500 mocks\n \u251c\u2500\u2500 base64_mock \u2014 \"`base64` Module Reference Implementation\"\n \u251c\u2500\u2500 batch_distributor_mock \u2014 \"`batch_distributor` Module Reference Implementation\"\n \u251c\u2500\u2500 create_address_mock \u2014 \"`create_address` Module Reference Implementation\"\n \u251c\u2500\u2500 create2_address_mock \u2014 \"`create2_address` Module Reference Implementation\"\n \u251c\u2500\u2500 ecdsa_mock \u2014 \"`ecdsa` Module Reference Implementation\"\n \u251c\u2500\u2500 p256_mock \u2014 \"`p256` Module Reference Implementation\"\n \u251c\u2500\u2500 message_hash_utils_mock \u2014 \"`message_hash_utils` Module Reference Implementation\"\n \u251c\u2500\u2500 signature_checker_mock \u2014 \"`signature_checker` Module Reference Implementation\"\n \u251c\u2500\u2500 eip712_domain_separator_mock \u2014 \"`eip712_domain_separator` Module Reference Implementation\"\n \u251c\u2500\u2500 math_mock \u2014 \"`math` Module Reference Implementation\"\n \u251c\u2500\u2500 merkle_proof_verification_mock \u2014 \"`merkle_proof_verification` Module Reference Implementation\"\n \u2514\u2500\u2500 multicall_mock \u2014 \"`multicall` Module Reference Implementation\"\n```\n\n## \ud83c\udf9b Installation\n\n> [!IMPORTANT] \n> \ud83d\udc0d snekmate uses a [ZeroVer](https://0ver.org)-based versioning scheme. This means \ud83d\udc0d snekmate's major version will never exceed the first and most important number in computing: zero.\n\nWe offer three convenient ways to install the \ud83d\udc0d snekmate contracts:\n\n### 1\ufe0f\u20e3 Foundry\n\nYou can install \ud83d\udc0d snekmate via submodules using [Foundry](https://github.com/foundry-rs/foundry) with:\n\n```console\nforge install pcaversaccio/snekmate\n```\n\n> [!NOTE]\n> If you want to leverage \ud83d\udc0d snekmate's [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract for your own testing, ensure that you compile the \ud83d\udc0dVyper contracts with the same EVM version as configured in your `foundry.toml` file. The [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract offers two overloaded `deployContract` functions that allow the configuration of the target EVM version. Please note that since \ud83d\udc0dVyper version [`0.4.0`](https://github.com/vyperlang/vyper/releases/tag/v0.4.0) the default EVM version is set to `cancun`. Furthermore, the [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract relies on the Python script [`compile.py`](./lib/utils/compile.py) for successful compilation and deployment. Always use the [`VyperDeployer`](./lib/utils/VyperDeployer.sol) contract alongside with the aforementioned script.\n\n### 2\ufe0f\u20e3 PyPI\n\nYou can install \ud83d\udc0d snekmate from [PyPI](https://pypi.org/project/snekmate) with:\n\n```console\npip install snekmate\n```\n\n> You can use `pip install snekmate -t .` to install the contracts directly into the current working directory!\n\n### 3\ufe0f\u20e3 npm\n\nYou can install \ud83d\udc0d snekmate from [npm](https://www.npmjs.com/package/snekmate) with:\n\n```console\nnpm install --save-dev snekmate\n```\n\nOr if you are using [Yarn](https://yarnpkg.com):\n\n```console\nyarn add --dev snekmate\n```\n\nIn case you are using [pnpm](https://pnpm.io), invoke:\n\n```console\npnpm add --save-dev snekmate\n```\n\n> [!CAUTION]\n> 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.\n\n## \ud83d\udd27 Usage\n\n\ud83d\udc0dVyper favours code reuse through composition rather than inheritance (Solidity inheritance makes it easy to break the [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)). A \ud83d\udc0dVyper module encapsulates everything required for code reuse, from type and function declarations to state. **All \ud83d\udc0d snekmate contracts are \ud83d\udc0dVyper modules.** Thus, many of the \ud83d\udc0d 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 \ud83d\udc0d snekmate contracts can be used as \ud83d\udc0dVyper modules.\n\n> [!IMPORTANT]\n> All \ud83d\udc0d snekmate contracts are very well documented in the form of general code and [NatSpec](https://docs.vyperlang.org/en/latest/natspec.html) comments. There are no shortcuts \u2013 if you are importing specific logic, read the documentation!\n\nPlease read [here](https://docs.vyperlang.org/en/latest/using-modules.html) to learn more about using \ud83d\udc0dVyper modules.\n\n## \ud83d\udc69\ud83c\udffc\u200d\u2696\ufe0f Tests\n\nThis repository contains [Foundry](https://github.com/foundry-rs/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`](./.github/workflows/test-contracts.yml).\n\n> [!NOTE]\n> An _invariant_ is a property of a program that should always hold true. Fuzzing is a way of checking whether the invariant is falsifiable.\n\n| **Contract** | **Unit Tests** | **Property-Based Tests** | **Invariant Tests** |\n| :-------------------------- | :------------: | :----------------------: | :-----------------: |\n| `ownable` | \u2705 | \u2705 | \u2705 |\n| `ownable_2step` | \u2705 | \u2705 | \u2705 |\n| `access_control` | \u2705 | \u2705 | \u2705 |\n| `erc2981` | \u2705 | \u2705 | \u2705 |\n| `erc4626` | \u2705 | \u2705 | \u2705 |\n| `timelock_controller` | \u2705 | \u2705 | \u2705 |\n| `erc20` | \u2705 | \u2705 | \u2705 |\n| `erc721` | \u2705 | \u2705 | \u2705 |\n| `erc1155` | \u2705 | \u2705 | \u2705 |\n| `base64` | \u2705 | \u274c | \u274c |\n| `batch_distributor` | \u2705 | \u2705 | \u2705 |\n| `create_address` | \u2705 | \u2705 | \u274c |\n| `create2_address` | \u2705 | \u2705 | \u274c |\n| `ecdsa` | \u2705 | \u2705 | \u274c |\n| `p256` | \u2705 | \u2705 | \u274c |\n| `message_hash_utils` | \u2705 | \u2705 | \u274c |\n| `signature_checker` | \u2705 | \u2705 | \u274c |\n| `eip712_domain_separator` | \u2705 | \u2705 | \u274c |\n| `math` | \u2705 | \u2705 | \u274c |\n| `merkle_proof_verification` | \u2705 | \u2705 | \u274c |\n| `multicall` | \u2705 | \u274c | \u274c |\n\n\u2705 Test Type Implemented   \u274c Test Type Not Implemented\n\nFurthermore, the [`echidna`](https://github.com/crytic/echidna)-based [property](https://github.com/crytic/properties) tests for the [`erc20`](./src/snekmate/tokens/ERC20.vy) and [`erc721`](./src/snekmate/tokens/ERC721.vy) contracts are available in the [`test/tokens/echidna/`](./test/tokens/echidna) directory. You can run the tests by invoking:\n\n```console\n# Run Echidna ERC-20 property tests.\n~$ FOUNDRY_PROFILE=echidna echidna test/tokens/echidna/ERC20Properties.sol --contract CryticERC20ExternalHarness --config test/echidna.yaml\n\n# Run Echidna ERC-721 property tests.\n~$ FOUNDRY_PROFILE=echidna echidna test/tokens/echidna/ERC721Properties.sol --contract CryticERC721ExternalHarness --config test/echidna.yaml\n```\n\nEventually, the [`halmos`](https://github.com/a16z/halmos)-based symbolic tests for the [`erc20`](./src/snekmate/tokens/erc20.vy), [`erc721`](./src/snekmate/tokens/erc721.vy), [`erc1155`](./src/snekmate/tokens/erc1155.vy), and [`math`](./src/snekmate/utils/math.vy) contracts are available in the [`test/tokens/halmos/`](./test/tokens/halmos) and [`test/utils/halmos/`](./test/utils/halmos) directories. You can run the tests by invoking:\n\n> [!IMPORTANT]\n> You must install the [Yices 2 SMT solver](https://github.com/SRI-CSL/yices2) before invoking the [`halmos`](https://github.com/a16z/halmos)-based symbolic tests.\n\n```console\n# Run Halmos ERC-20 symbolic tests.\n~$ FOUNDRY_PROFILE=halmos halmos --contract ERC20TestHalmos --config test/halmos.toml\n\n# Run Halmos ERC-721 symbolic tests. Be careful, this is a (very!) time-consuming operation.\n~$ FOUNDRY_PROFILE=halmos halmos --contract ERC721TestHalmos --config test/halmos.toml\n\n# Run Halmos ERC-1155 symbolic tests. Be careful, this is a time-consuming operation.\n~$ FOUNDRY_PROFILE=halmos halmos --contract ERC1155TestHalmos --config test/halmos.toml\n\n# Run Halmos math symbolic tests.\n~$ FOUNDRY_PROFILE=halmos halmos --contract MathTestHalmos --config test/halmos.toml\n```\n\n> [!TIP]\n> If you encounter any issues, please ensure that you have the [latest](https://github.com/vyperlang/vyper/releases) \ud83d\udc0dVyper version installed locally.\n\n## \ud83d\ude4f\ud83c\udffc Acknowledgements\n\nThis repository is inspired by or directly modified from many sources, primarily:\n\n- [ApeAcademy](https://github.com/ApeAcademy)\n- [Batch Distributor](https://github.com/pcaversaccio/batch-distributor)\n- [`CREATE` Factory](https://github.com/pcaversaccio/create-util)\n- [Disperse Research](https://github.com/banteg/disperse-research)\n- [Multicall](https://github.com/mds1/multicall)\n- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts)\n- [Solady](https://github.com/Vectorized/solady)\n- [Solmate](https://github.com/transmissions11/solmate)\n\n## \ud83e\udee1 Contributing\n\n\ud83d\udc0d snekmate only exists thanks to its [contributors](https://github.com/pcaversaccio/snekmate/graphs/contributors). There are many ways to get involved and contribute to our high-quality and secure smart contracts. Check out our [Contribution Guidelines](./CONTRIBUTING.md)!\n\n## \ud83d\udcb8 Donation\n\nI 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`](https://etherscan.io/address/0xe9Fa0c8B5d7F79DeC36D3F448B1Ac4cEdedE4e69). I can pledge that I will use this money to help fix more existing challenges in the Ethereum ecosystem \ud83e\udd1d.\n\n## \ud83d\udca2 Disclaimer\n\n<img src=https://user-images.githubusercontent.com/25297591/167394075-1813e258-3b03-4bc8-9305-69126a07d57e.png width=\"1050\"/>\n",
"bugtrack_url": null,
"license": "AGPL-3.0-only License",
"summary": "State-of-the-art, highly opinionated, hyper-optimised, and secure \ud83d\udc0dVyper smart contract building blocks.",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/pcaversaccio/snekmate/blob/main/CHANGELOG.md",
"GitHub": "https://github.com/pcaversaccio/snekmate",
"Homepage": "https://github.com/pcaversaccio/snekmate#readme"
},
"split_keywords": [
"security",
" library",
" ethereum",
" smart-contracts",
" evm",
" vyper",
" vyper-contracts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "141c8d5285626ee40f297cc4bf944ffcb1c4bf02c966fb34ee8c452ab9b232d7",
"md5": "4c59bda6c7e9e291dbe2ee8d10e0476b",
"sha256": "0f56078c4237f2f57704ec6c974378751c5f30fb2c19f406aec2f173c002ab85"
},
"downloads": -1,
"filename": "snekmate-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c59bda6c7e9e291dbe2ee8d10e0476b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 112946,
"upload_time": "2024-06-26T14:26:08",
"upload_time_iso_8601": "2024-06-26T14:26:08.117352Z",
"url": "https://files.pythonhosted.org/packages/14/1c/8d5285626ee40f297cc4bf944ffcb1c4bf02c966fb34ee8c452ab9b232d7/snekmate-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a54733f865f94c8892e3be93eaa103289709dd373442a02dc689452b18527f62",
"md5": "36a06b0c6ef8e630635db90b98b7b0aa",
"sha256": "8446b4c1aac8bf80b5e6a7e4fe7e9b2547200fabd9577bf6e22a2e79ba88d5de"
},
"downloads": -1,
"filename": "snekmate-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "36a06b0c6ef8e630635db90b98b7b0aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 94723,
"upload_time": "2024-06-26T14:26:09",
"upload_time_iso_8601": "2024-06-26T14:26:09.912549Z",
"url": "https://files.pythonhosted.org/packages/a5/47/33f865f94c8892e3be93eaa103289709dd373442a02dc689452b18527f62/snekmate-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-26 14:26:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pcaversaccio",
"github_project": "snekmate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "snekmate"
}
JSON
