# π snekmate
[![π΅οΈββοΈ Test smart contracts](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml/badge.svg)](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml)
[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue)](https://www.gnu.org/licenses/agpl-3.0)
[![npm package](https://img.shields.io/npm/v/snekmate.svg?color=blue)](https://www.npmjs.com/package/snekmate)
[![PyPI package](https://img.shields.io/pypi/v/snekmate?color=blue)](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
```ml
src
βββ snekmate
βββ auth
β βββ Ownable β "Owner-Based Access Control Functions"
β βββ Ownable2Step β "2-Step Ownership Transfer Functions"
β βββ AccessControl β "Multi-Role-Based Access Control Functions"
β βββ interfaces
β βββ IAccessControl β "AccessControl Interface Definition"
βββ 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"
βββ governance
β βββ TimelockController β "Multi-Role-Based Timelock Controller 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"
βββ utils
βββ Base64 β "Base64 Encoding and Decoding Functions"
βββ BatchDistributor β "Batch Sending Both Native and ERC-20 Tokens"
βββ CreateAddress β "`CREATE` EVM Opcode Utility Function for Address Calculation"
βββ Create2Address β "`CREATE2` EVM Opcode Utility Functions for Address Calculations"
βββ ECDSA β "Elliptic Curve Digital Signature Algorithm (ECDSA) Functions"
βββ SignatureChecker β "ECDSA and EIP-1271 Signature Verification Functions"
βββ EIP712DomainSeparator β "EIP-712 Domain Separator"
βββ Math β "Standard Mathematical Utility Functions"
βββ MerkleProofVerification β "Merkle Tree Proof Verification Functions"
βββ Multicall β "Multicall Functions"
βββ interfaces
βββ IERC5267 β "EIP-5267 Interface Definition"
```
## π 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
```
> 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.3.8`](https://github.com/vyperlang/vyper/releases/tag/v0.3.8) the default EVM version is set to `shanghai`.
### 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.
## π©πΌββοΈ Tests
This repository contains [Foundry](https://github.com/foundry-rs/foundry)-based unit tests, property-based tests (i.e. fuzzing), and invariant tests 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` | β
| β
| β
|
| `Ownable2Step` | β
| β
| β
|
| `AccessControl` | β
| β
| β
|
| `ERC2981` | β
| β
| β
|
| `ERC4626` | β
| β
| β
|
| `TimelockController` | β
| β
| β
|
| `ERC20` | β
| β
| β
|
| `ERC721` | β
| β
| β
|
| `ERC1155` | β
| β
| β
|
| `Base64` | β
| β | β |
| `BatchDistributor` | β
| β
| β
|
| `CreateAddress` | β
| β
| β |
| `Create2Address` | β
| β
| β |
| `ECDSA` | β
| β
| β |
| `SignatureChecker` | β
| β
| β |
| `EIP712DomainSeparator` | β
| β
| β |
| `Math` | β
| β
| β |
| `MerkleProofVerification` | β
| β
| β |
| `Multicall` | β
| β | β |
β
Test Type Implemented   β Test Type Not Implemented
## ππΌ 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": "",
"name": "snekmate",
"maintainer": "",
"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": "",
"author_email": "Pascal Marco Caversaccio <pascal.caversaccio@hotmail.ch>",
"download_url": "https://files.pythonhosted.org/packages/e5/81/59e09a00fb1959529368fd334c6c63d23acb8ba498542ff9a0117957fb61/snekmate-0.0.5.tar.gz",
"platform": null,
"description": "# \ud83d\udc0d snekmate\n\n[![\ud83d\udd75\ufe0f\u200d\u2642\ufe0f Test smart contracts](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml/badge.svg)](https://github.com/pcaversaccio/snekmate/actions/workflows/test-contracts.yml)\n[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue)](https://www.gnu.org/licenses/agpl-3.0)\n[![npm package](https://img.shields.io/npm/v/snekmate.svg?color=blue)](https://www.npmjs.com/package/snekmate)\n[![PyPI package](https://img.shields.io/pypi/v/snekmate?color=blue)](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\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 Ownable2Step \u2014 \"2-Step Ownership Transfer Functions\"\n \u2502 \u251c\u2500\u2500 AccessControl \u2014 \"Multi-Role-Based Access Control Functions\"\n \u2502 \u2514\u2500\u2500 interfaces\n \u2502 \u2514\u2500\u2500 IAccessControl \u2014 \"AccessControl Interface Definition\"\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 \u2514\u2500\u2500 interfaces\n \u2502 \u2514\u2500\u2500 IERC2981 \u2014 \"EIP-2981 Interface Definition\"\n \u251c\u2500\u2500 governance\n \u2502 \u2514\u2500\u2500 TimelockController \u2014 \"Multi-Role-Based Timelock Controller 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 \u2514\u2500\u2500 interfaces\n \u2502 \u251c\u2500\u2500 IERC20Permit \u2014 \"EIP-2612 Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC721Enumerable \u2014 \"EIP-721 Optional Enumeration Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC721Metadata \u2014 \"EIP-721 Optional Metadata Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC721Permit \u2014 \"EIP-4494 Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC721Receiver \u2014 \"EIP-721 Token Receiver Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC1155 \u2014 \"EIP-1155 Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC1155MetadataURI \u2014 \"EIP-1155 Optional Metadata Interface Definition\"\n \u2502 \u251c\u2500\u2500 IERC1155Receiver \u2014 \"EIP-1155 Token Receiver Interface Definition\"\n \u2502 \u2514\u2500\u2500 IERC4906 \u2014 \"EIP-4906 Interface Definition\"\n \u2514\u2500\u2500 utils\n \u251c\u2500\u2500 Base64 \u2014 \"Base64 Encoding and Decoding Functions\"\n \u251c\u2500\u2500 BatchDistributor \u2014 \"Batch Sending Both Native and ERC-20 Tokens\"\n \u251c\u2500\u2500 CreateAddress \u2014 \"`CREATE` EVM Opcode Utility Function for Address Calculation\"\n \u251c\u2500\u2500 Create2Address \u2014 \"`CREATE2` EVM Opcode Utility Functions for Address Calculations\"\n \u251c\u2500\u2500 ECDSA \u2014 \"Elliptic Curve Digital Signature Algorithm (ECDSA) Functions\"\n \u251c\u2500\u2500 SignatureChecker \u2014 \"ECDSA and EIP-1271 Signature Verification Functions\"\n \u251c\u2500\u2500 EIP712DomainSeparator \u2014 \"EIP-712 Domain Separator\"\n \u251c\u2500\u2500 Math \u2014 \"Standard Mathematical Utility Functions\"\n \u251c\u2500\u2500 MerkleProofVerification \u2014 \"Merkle Tree Proof Verification Functions\"\n \u251c\u2500\u2500 Multicall \u2014 \"Multicall Functions\"\n \u2514\u2500\u2500 interfaces\n \u2514\u2500\u2500 IERC5267 \u2014 \"EIP-5267 Interface Definition\"\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> If you want to leverage \ud83d\udc0d 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.3.8`](https://github.com/vyperlang/vyper/releases/tag/v0.3.8) the default EVM version is set to `shanghai`.\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\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. fuzzing), and invariant tests 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| `Ownable2Step` | \u2705 | \u2705 | \u2705 |\n| `AccessControl` | \u2705 | \u2705 | \u2705 |\n| `ERC2981` | \u2705 | \u2705 | \u2705 |\n| `ERC4626` | \u2705 | \u2705 | \u2705 |\n| `TimelockController` | \u2705 | \u2705 | \u2705 |\n| `ERC20` | \u2705 | \u2705 | \u2705 |\n| `ERC721` | \u2705 | \u2705 | \u2705 |\n| `ERC1155` | \u2705 | \u2705 | \u2705 |\n| `Base64` | \u2705 | \u274c | \u274c |\n| `BatchDistributor` | \u2705 | \u2705 | \u2705 |\n| `CreateAddress` | \u2705 | \u2705 | \u274c |\n| `Create2Address` | \u2705 | \u2705 | \u274c |\n| `ECDSA` | \u2705 | \u2705 | \u274c |\n| `SignatureChecker` | \u2705 | \u2705 | \u274c |\n| `EIP712DomainSeparator` | \u2705 | \u2705 | \u274c |\n| `Math` | \u2705 | \u2705 | \u274c |\n| `MerkleProofVerification` | \u2705 | \u2705 | \u274c |\n| `Multicall` | \u2705 | \u274c | \u274c |\n\n\u2705 Test Type Implemented   \u274c Test Type Not Implemented\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.0.5",
"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": "05e085f8ea269bccd811eb1256f47b455b7cad74eb7b82503191ba55b3a1a42d",
"md5": "415f594c863e144514617abf91e06b20",
"sha256": "d508fef7bc9effdaf4977bcc067bb29a24013065dfe6b655238a8d41fe0d8a1e"
},
"downloads": -1,
"filename": "snekmate-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "415f594c863e144514617abf91e06b20",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 111544,
"upload_time": "2024-03-07T14:21:28",
"upload_time_iso_8601": "2024-03-07T14:21:28.153831Z",
"url": "https://files.pythonhosted.org/packages/05/e0/85f8ea269bccd811eb1256f47b455b7cad74eb7b82503191ba55b3a1a42d/snekmate-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e58159e09a00fb1959529368fd334c6c63d23acb8ba498542ff9a0117957fb61",
"md5": "051c56c0465c709d0a39d965cb1f1379",
"sha256": "e09eb294124e6d2450923e2f8e2fbd00bbd2c1eec830e0e4c576cef87871fe50"
},
"downloads": -1,
"filename": "snekmate-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "051c56c0465c709d0a39d965cb1f1379",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 92378,
"upload_time": "2024-03-07T14:21:29",
"upload_time_iso_8601": "2024-03-07T14:21:29.243326Z",
"url": "https://files.pythonhosted.org/packages/e5/81/59e09a00fb1959529368fd334c6c63d23acb8ba498542ff9a0117957fb61/snekmate-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-07 14:21:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pcaversaccio",
"github_project": "snekmate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "snekmate"
}