🐍 snekmate

State-of-the-art, highly opinionated, hyper-optimised, and secure 🐍Vyper smart contract building blocks.

• 📜 Contracts
• 🎛 Installation
  • 1️⃣ PyPI
  • 2️⃣ Foundry
  • 3️⃣ npm
• 🔧 Usage
• 👩🏼‍⚖️ Tests
• 👮‍♀️ Audits
• 🙏🏼 Acknowledgements
• 🫡 Contributing
• 💸 Donation
• 📄 Licence
  • ⚖️ Dual-Licensing Option
  • 📩 Requesting an MIT License
• 💢 Disclaimer

📜 Contracts

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"
        ├── block_hash — "Utility Functions to Access Historical Block Hashes"
        ├── create — "`CREATE` EVM Opcode Utility Functions"
        ├── create2 — "`CREATE2` EVM Opcode Utility Functions"
        ├── create3 — "`CREATE3`-Based Utility Functions"
        ├── 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"
        ├── pausable — "Pausable 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"
            ├── block_hash_mock — "`block_hash` Module Reference Implementation"
            ├── create_mock — "`create` Module Reference Implementation"
            ├── create2_mock — "`create2` Module Reference Implementation"
            ├── create3_mock — "`create3` 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"
            └── pausable_mock — "`pausable` Module Reference Implementation"

🎛 Installation

We offer three convenient ways to install the 🐍 snekmate contracts:

1️⃣ PyPI

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.

2️⃣ Foundry

You can install 🐍 snekmate via submodules using Foundry with:

forge install pcaversaccio/snekmate

3️⃣ npm

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

🔧 Usage

🐍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.

Please read here to learn more about using 🐍Vyper modules.

👩🏼‍⚖️ Tests

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.

✅ 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:

# 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

👮‍♀️ Audits

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.

🙏🏼 Acknowledgements

This repository is inspired by or directly modified from many sources, primarily:

• ApeAcademy
• Batch Distributor
• CREATE Factory
• Disperse Research
• Multicall
• OpenZeppelin Contracts
• Solady
• Solmate

🫡 Contributing

🐍 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!

💸 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. I can pledge that I will use this money to help fix more existing challenges in the Ethereum ecosystem 🤝.

📄 Licence

This software is released under the GNU Affero General Public License v3.0 only (AGPL-3.0-only) by default.

We believe in fostering a collaborative and open ecosystem. The AGPL-3.0-only licence keeps the code free, the knowledge shared, and the doors open. It stands as a quiet rebellion against control, a promise that what is built in the open will remain in the open, owned by no one and available to all.

⚖️ Dual-Licensing Option

We understand that AGPL-3.0-only-licensed software may not be suitable for all use cases, particularly in cases involving:

• Proprietary or closed-source projects,
• Licence incompatibilities, or
• Commercial applications with conflicting requirements.

For such scenarios, we offer an alternative licence under the MIT License, granted at our sole discretion.

📩 Requesting an MIT License

If you have substantial reasons for requiring a more permissive licence, such as those outlined above, feel free to contact us via email to request access to the software under the MIT License.

Each request is evaluated on a case-by-case basis, and we will provide the MIT License if deemed appropriate.

💢 Disclaimer