mirror
/
openzeppelin-contracts
mirror of https://github.com/OpenZeppelin/openzeppelin-contracts
2
1
Fork 1
Code Issues Releases Wiki Activity

Update guidelines and project documentation (#3966)

Browse Source 
Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>
pull/3961/head^2
Francisco 2 years ago committed by GitHub
parent 18691d1a6f
commit 88a64a802e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 151 additions and 140 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 2
      .github/workflows/checks.yml
  2. 2
      CODE_OF_CONDUCT.md
  3. 66
      CONTRIBUTING.md
  4. 114
      GUIDELINES.md
  5. 2
      LICENSE
  6. 24
      README.md
  7. 44
      SECURITY.md
  8. 2
      audits/2017-03.md
  9. 0
      audits/2018-10.pdf
  10. BIN
      audits/2022-10-Checkpoints.pdf
  11. BIN
      audits/2022-10-ERC4626.pdf
  12. 15
      audits/README.md
  13. BIN
      certora/reports/2021-10.pdf
  14. BIN
      certora/reports/2022-03.pdf
  15. BIN
      certora/reports/2022-05.pdf
  16. 0
      docs/README.md

2
.github/workflows/checks.yml
Unescape View File

@ -87,4 +87,4 @@ jobs:
uses: codespell-project/actions-codespell@v1.0
with:
check_filenames: true
skip: package-lock.json
skip: package-lock.json,*.pdf

2
CODE_OF_CONDUCT.md
Unescape View File

@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at maintainers@openzeppelin.org. All
reported by contacting the project team at contact@openzeppelin.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.

66
CONTRIBUTING.md
Unescape View File

@ -1,64 +1,34 @@
Contributing to OpenZeppelin Contracts
=======
# Contributing Guidelines
We really appreciate and value contributions to OpenZeppelin Contracts. Please take 5' to review the items listed below to make sure that your contributions are merged as soon as possible.
There are many ways to contribute to OpenZeppelin Contracts.
## Contribution guidelines
## Troubleshooting
Smart contracts manage value and are highly vulnerable to errors and attacks. We have very strict [guidelines], please make sure to review them!
You can help other users in the community to solve their smart contract issues in the [OpenZeppelin Forum].
## Creating Pull Requests (PRs)
[OpenZeppelin Forum]: https://forum.openzeppelin.com/
As a contributor, you are expected to fork this repository, work on your own fork and then submit pull requests. The pull requests will be reviewed and eventually merged into the main repo. See ["Fork-a-Repo"](https://help.github.com/articles/fork-a-repo/) for how this works.
## Opening an issue
## A typical workflow
You can [open an issue] to suggest a feature or report a minor bug. For serious bugs please do not open an issue, instead refer to our [security policy] for appropriate steps.
1) Make sure your fork is up to date with the main repository:
If you believe your issue may be due to user error and not a problem in the library, consider instead posting a question on the [OpenZeppelin Forum].
```
cd openzeppelin-contracts
git remote add upstream https://github.com/OpenZeppelin/openzeppelin-contracts.git
git fetch upstream
git pull --rebase upstream master
```
NOTE: The directory `openzeppelin-contracts` represents your fork's local copy.
Before opening an issue, be sure to search through the existing open and closed issues, and consider posting a comment in one of those instead.
2) Branch out from `master` into `fix/some-bug-#123`:
(Postfixing #123 will associate your PR with the issue #123 and make everyone's life easier =D)
```
git checkout -b fix/some-bug-#123
```
When requesting a new feature, include as many details as you can, especially around the use cases that motivate it. Features are prioritized according to the impact they may have on the ecosystem, so we appreciate information showing that the impact could be high.
3) Make your changes, add your files, commit, and push to your fork.
[security policy]: https://github.com/OpenZeppelin/openzeppelin-contracts/security
[open an issue]: https://github.com/OpenZeppelin/openzeppelin-contracts/issues/new/choose
```
git add SomeFile.js
git commit "Fix some bug #123"
git push origin fix/some-bug-#123
```
## Submitting a pull request
4) Run tests, linter, etc. This can be done by running local continuous integration and make sure it passes.
If you would like to contribute code or documentation you may do so by forking the repository and submitting a pull request.
```bash
npm test
npm run lint
```
Any non-trivial code contribution must be first discussed with the maintainers in an issue (see [Opening an issue](#opening-an-issue)). Only very minor changes are accepted without prior discussion.
5) Go to [github.com/OpenZeppelin/openzeppelin-contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) in your web browser and issue a new pull request.
Make sure to read and follow the [engineering guidelines](./GUIDELINES.md). Run linter and tests to make sure your pull request is good before submitting it.
*IMPORTANT* Read the PR template very carefully and make sure to follow all the instructions. These instructions
refer to some very important conditions that your PR must meet in order to be accepted, such as making sure that all tests pass, JS linting tests pass, Solidity linting tests pass, etc.
When opening the pull request you will be presented with a template and a series of instructions. Read through it carefully and follow all the steps. Expect a review and feedback from the maintainers afterwards.
6) Maintainers will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of OpenZeppelin Contracts.
*IMPORTANT* Please pay attention to the maintainer's feedback, since it's a necessary step to keep up with the standards OpenZeppelin Contracts attains to.
## All set!
If you have any questions, feel free to post them to github.com/OpenZeppelin/openzeppelin-contracts/issues.
Finally, if you're looking to collaborate and want to find easy tasks to start, look at the issues we marked as ["Good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue).
Thanks for your time and code!
[guidelines]: GUIDELINES.md
If you're looking for a good place to start, look for issues labelled ["good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue)!

114
GUIDELINES.md
Unescape View File

@ -1,81 +1,88 @@
Design Guidelines
=======
# Engineering Guidelines
These are some global design goals in OpenZeppelin Contracts.
## Testing
#### D0 - Security in Depth
We strive to provide secure, tested, audited code. To achieve this, we need to match intention with function. Thus, documentation, code clarity, community review and security discussions are fundamental.
Code must be thoroughly tested with quality unit tests.
#### D1 - Simple and Modular
Simpler code means easier audits, and better understanding of what each component does. We look for small files, small contracts, and small functions. If you can separate a contract into two independent functionalities you should probably do it.
We defer to the [Moloch Testing Guide](https://github.com/MolochVentures/moloch/tree/master/test#readme) for specific recommendations, though not all of it is relevant here. Note the introduction:
#### D2 - Naming Matters
> Tests should be written, not only to verify correctness of the target code, but to be comprehensively reviewed by other programmers. Therefore, for mission critical Solidity code, the quality of the tests are just as important (if not more so) than the code itself, and should be written with the highest standards of clarity and elegance.
We take our time with picking names. Code is going to be written once, and read hundreds of times. Renaming for clarity is encouraged.
Every addition or change to the code must come with relevant and comprehensive tests.
#### D3 - Tests
Refactors should avoid simultaneous changes to tests.
Write tests for all your code. We encourage Test Driven Development so we know when our code is right. Even though not all code in the repository is tested at the moment, we aim to test every line of code in the future.
Flaky tests are not acceptable.
#### D4 - Check preconditions and post-conditions
The test suite should run automatically for every change in the repository, and in pull requests tests must pass before merging.
A very important way to prevent vulnerabilities is to catch a contract’s inconsistent state as early as possible. This is why we want functions to check pre- and post-conditions for executing its logic. When writing code, ask yourself what you are expecting to be true before and after the function runs, and express it in code.
The test suite coverage must be kept as close to 100% as possible, enforced in pull requests.
#### D5 - Code Consistency
In some cases unit tests may be insufficient and complementary techniques should be used:
Consistency on the way classes are used is paramount to an easier understanding of the library. The codebase should be as unified as possible. Read existing code and get inspired before you write your own. Follow the style guidelines. Don’t hesitate to ask for help on how to best write a specific piece of code.
1. Property-based tests (aka. fuzzing) for math-heavy code.
2. Formal verification for state machines.
#### D6 - Regular Audits
Following good programming practices is a way to reduce the risk of vulnerabilities, but professional code audits are still needed. We will perform regular code audits on major releases, and hire security professionals to provide independent review.
## Code style
# Style Guidelines
Solidity code should be written in a consistent format enforced by a linter, following the official [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html). See below for further [Solidity Conventions](#solidity-conventions).
The design guidelines have quite a high abstraction level. These style guidelines are more concrete and easier to apply, and also more opinionated. We value clean code and consistency, and those are prerequisites for us to include new code in the repository. Before proposing a change, please read these guidelines and take some time to familiarize yourself with the style of the existing codebase.
The code should be simple and straightforward, prioritizing readability and understandability. Consistency and predictability should be maintained across the codebase. In particular, this applies to naming, which should be systematic, clear, and concise.
## Solidity code
Sometimes these guidelines may be broken if doing so brings significant efficiency gains, but explanatory comments should be added.
In order to be consistent with all the other Solidity projects, we follow the
[official recommendations documented in the Solidity style guide](http://solidity.readthedocs.io/en/latest/style-guide.html).
Modularity should be pursued, but not at the cost of the above priorities.
Any exception or additions specific to our project are documented below.
## Documentation
* Try to avoid acronyms and abbreviations.
For contributors, project guidelines and processes must be documented publicly.
* All state variables should be private.
For users, features must be abundantly documented. Documentation should include answers to common questions, solutions to common problems, and recommendations for critical decisions that the user may face.
* Private state variables should have an underscore prefix.
All changes to the core codebase (excluding tests, auxiliary scripts, etc.) must be documented in a changelog, except for purely cosmetic or documentation changes.
```
contract TestContract {
uint256 private _privateVar;
uint256 internal _internalVar;
}
```
## Peer review
* Parameters must not be prefixed with an underscore.
All changes must be submitted through pull requests and go through peer code review.
```
function test(uint256 testParameter1, uint256 testParameter2) {
...
}
```
The review must be approached by the reviewer in a similar way as if it was an audit of the code in question (but importantly it is not a substitute for and should not be considered an audit).
* Internal and private functions should have an underscore prefix.
Reviewers should enforce code and project guidelines.
```
function _testInternal() internal {
...
}
```
External contributions must be reviewed separately by multiple maintainers.
## Automation
Automation should be used as much as possible to reduce the possibility of human error and forgetfulness.
Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions worklows](https://github.com/nikitastupin/pwnhub).
Some other examples of automation are:
- Looking for common security vulnerabilities or errors in our code (eg. reentrancy analysis).
- Keeping dependencies up to date and monitoring for vulnerable dependencies.
# Solidity Conventions
In addition to the official Solidity Style Guide we have a number of other conventions that must be followed.
* All state variables should be private.
Changes to state should be accompanied by events, and in some cases it is not correct to arbitrarily set state. Encapsulating variables as private and only allowing modification via setters enables us to ensure that events and other rules are followed reliably and prevents this kind of user error.
* Internal or private state variables or functions should have an underscore prefix.
```
function _testPrivate() private {
...
contract TestContract {
uint256 private _privateVar;
uint256 internal _internalVar;
function _testInternal() internal { ... }
function _testPrivate() private { ... }
}
```
* Events should be emitted immediately after the state change that they
represent, and consequently they should be named in past tense.
represent, and should be named in the past tense.
```
function _burn(address who, uint256 value) internal {
@ -85,7 +92,7 @@ Any exception or additions specific to our project are documented below.
```
Some standards (e.g. ERC20) use present tense, and in those cases the
standard specification prevails.
standard specification is used.
* Interface names should have a capital I prefix.
@ -93,13 +100,4 @@ Any exception or additions specific to our project are documented below.
interface IERC777 {
```
## Tests
* Tests Must be Written Elegantly
Tests are a good way to show how to use the library, and maintaining them is extremely necessary. Don't write long tests, write helper functions to make them be as short and concise as possible (they should take just a few lines each), and use good variable names.
* Tests Must not be Random
Inputs for tests should not be generated randomly. Accounts used to create test contracts are an exception, those can be random. Also, the type and structure of outputs should be checked.
* Unchecked arithmetic blocks should contain comments explaining why overflow is guaranteed not to happen. If the reason is immediately apparent from the line above the unchecked block, the comment may be omitted.

2
LICENSE
Unescape View File

@ -1,6 +1,6 @@
The MIT License (MIT)
Copyright (c) 2016-2022 zOS Global Limited and contributors
Copyright (c) 2016-2023 zOS Global Limited and contributors
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the

24
README.md
Unescape View File

@ -1,9 +1,10 @@
# <img src="logo.svg" alt="OpenZeppelin" height="40px">
[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-blue)](https://docs.openzeppelin.com/contracts)
[![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts.svg)](https://www.npmjs.org/package/@openzeppelin/contracts)
[![Coverage Status](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts/graph/badge.svg)](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts)
[![gitpoap badge](https://public-api.gitpoap.io/v1/repo/OpenZeppelin/openzeppelin-contracts/badge)](https://www.gitpoap.io/gh/OpenZeppelin/openzeppelin-contracts)
[![GitPOAPs](https://public-api.gitpoap.io/v1/repo/OpenZeppelin/openzeppelin-contracts/badge)](https://www.gitpoap.io/gh/OpenZeppelin/openzeppelin-contracts)
[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-yellow)](https://docs.openzeppelin.com/contracts)
[![Forum](https://img.shields.io/badge/forum-%F0%9F%92%AC-yellow)](https://docs.openzeppelin.com/contracts)
**A library for secure smart contract development.** Build on a solid foundation of community-vetted code.
@ -19,7 +20,7 @@
### Installation
```console
```
$ npm install @openzeppelin/contracts
```
@ -52,7 +53,6 @@ The guides in the [documentation site](https://docs.openzeppelin.com/contracts)
* [Access Control](https://docs.openzeppelin.com/contracts/access-control): decide who can perform each of the actions on your system.
* [Tokens](https://docs.openzeppelin.com/contracts/tokens): create tradeable assets or collectives, and distribute them via [Crowdsales](https://docs.openzeppelin.com/contracts/crowdsales).
* [Gas Station Network](https://docs.openzeppelin.com/contracts/gsn): let your users interact with your contracts without having to pay for gas themselves.
* [Utilities](https://docs.openzeppelin.com/contracts/utilities): generic useful tools including non-overflowing math, signature verification, and trustless paying systems.
The [full API](https://docs.openzeppelin.com/contracts/api/token/ERC20) is also thoroughly documented, and serves as a great reference when developing your smart contract application. You can also ask for help or follow Contracts's development in the [community forum](https://forum.openzeppelin.com).
@ -65,15 +65,17 @@ Finally, you may want to take a look at the [guides on our blog](https://blog.op
## Security
This project is maintained by [OpenZeppelin](https://openzeppelin.com), and developed following our high standards for code quality and security. OpenZeppelin Contracts is meant to provide tested and community-audited code, but please use common sense when doing anything that deals with real money! We take no responsibility for your implementation decisions and any security problems you might experience.
This project is maintained by [OpenZeppelin](https://openzeppelin.com) with the goal of providing a secure and reliable library of smart contract components for the ecosystem. We address security through risk management in various areas such as engineering and open source best practices, scoping and API design, multi-layered review processes, and incident response preparedness.
The security policy is detailed in [`SECURITY.md`](./SECURITY.md), and specifies how you can report security vulnerabilities, which versions will receive security patches, and how to stay informed about them. We run a [bug bounty program on Immunefi](https://immunefi.com/bounty/openzeppelin) to reward the responsible disclosure of vulnerabilities.
The core development principles and strategies that OpenZeppelin Contracts is based on include: security in depth, simple and modular code, clarity-driven naming conventions, comprehensive unit testing, pre-and-post-condition sanity checks, code consistency, and regular audits.
The engineering guidelines we follow to promote project quality can be found in [`GUIDELINES.md`](./GUIDELINES.md).
The latest audit was done on October 2018 on version 2.0.0.
Past audits can be found in [`audits/`](./audits).
We have a [**bug bounty program** on Immunefi](https://www.immunefi.com/bounty/openzeppelin). Please report any security issues you find through the Immunefi dashboard, or reach out to security@openzeppelin.com.
Smart contracts are a nascent techology and carry a high level of technical risk and uncertainty. Although OpenZeppelin is well known for its security audits, using OpenZeppelin Contracts is not a substitute for a security audit.
Critical bug fixes will be backported to past major releases.
OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. As set out further in the Terms, you acknowledge that you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use.
## Contribute
@ -82,3 +84,7 @@ OpenZeppelin Contracts exists thanks to its contributors. There are many ways yo
## License
OpenZeppelin Contracts is released under the [MIT License](LICENSE).
## Legal
Your use of this Project is governed by the terms found at www.openzeppelin.com/tos (the "Terms").

44
SECURITY.md
Unescape View File

@ -1,20 +1,42 @@
# Security Policy
Security vulnerabilities should be disclosed to the project maintainers through [Immunefi], or alternatively by email to security@openzeppelin.com.
[Immunefi]: https://immunefi.com/bounty/openzeppelin
## Bug Bounty
We have a [**bug bounty program** on Immunefi](https://www.immunefi.com/bounty/openzeppelin). Please report any security issues you find through the Immunefi dashboard, or reach out to security@openzeppelin.com.
Responsible disclosure of security vulnerabilities is rewarded through a bug bounty program on [Immunefi].
There is a bonus reward for issues introduced in release candidates that are reported before making it into a stable release.
## Security Patches
Security vulnerabilities will be patched as soon as responsibly possible, and published as an advisory on this repository (see [advisories]) and on the affected npm packages.
[advisories]: https://github.com/OpenZeppelin/openzeppelin-contracts/security/advisories
Projects that build on OpenZeppelin Contracts are encouraged to clearly state, in their source code and websites, how to be contacted about security issues in the event that a direct notification is considered necessary. We recommend including it in the NatSpec for the contract as `/// @custom:security-contact security@example.com`.
Additionally, we recommend installing the library through npm and setting up vulnerability alerts such as [Dependabot].
[Dependabot]: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security#what-is-dependabot
### Supported Versions
Security patches will be released for the latest minor of a given major release. For example, if an issue is found in versions >=4.6.0 and the latest is 4.8.0, the patch will be released only in version 4.8.1.
Critical bug fixes will be backported to past major releases.
Only critical severity bug fixes will be backported to past major releases.
## Supported Versions
| Version | Critical security fixes | Other security fixes |
| ------- | ----------------------- | -------------------- |
| 4.x | :white_check_mark: | :white_check_mark: |
| 3.4 | :white_check_mark: | :x: |
| 2.5 | :white_check_mark: | :x: |
| < 2.0 | :x: | :x: |
The recommendation is to use the latest version available.
Note as well that the Solidity language itself only guarantees security updates for the latest release.
| Version | Supported |
| ------- | ------------------------------------ |
| 4.x | :white_check_mark::white_check_mark: |
| 3.4 | :white_check_mark: |
| 2.5 | :white_check_mark: |
| < 2.0 | :x: |
## Legal
Note that the Solidity language itself only guarantees security updates for the latest release.
Smart contracts are a nascent techology and carry a high level of technical risk and uncertainty. OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project.

2
audit/2017-03.md → audits/2017-03.md
Unescape View File

@ -1,6 +1,6 @@
# OpenZeppelin Audit
NOTE ON 2021-07-19: This report makes reference to Zeppelin, OpenZeppelin, OpenZeppelin [C]ontracts, the OpenZeppelin team, and OpenZeppelin library. Many of these things have since been renamed and know that this audit applies to what is currently called the OpenZeppelin Contracts which are maintained by the OpenZeppelin Conracts Community.
NOTE ON 2021-07-19: This report makes reference to Zeppelin, OpenZeppelin, OpenZeppelin Contracts, the OpenZeppelin team, and OpenZeppelin library. Many of these things have since been renamed and know that this audit applies to what is currently called the OpenZeppelin Contracts which are maintained by the OpenZeppelin Contracts Community.
March, 2017
Authored by Dennis Peterson and Peter Vessenes

0
audit/2018-10.pdf → audits/2018-10.pdf
Unescape View File

BIN
audits/2022-10-Checkpoints.pdf
View File

Binary file not shown.

BIN
audits/2022-10-ERC4626.pdf
View File

Binary file not shown.

15
audits/README.md
Unescape View File

@ -0,0 +1,15 @@
# Audits
| Date | Version | Commit | Auditor | Scope | Links |
| ------------ | ------- | --------- | ------------ | -------------------- | ----------------------------------------------------------- |
| October 2022 | v4.8.0 | `14f98db` | OpenZeppelin | ERC4626, Checkpoints | [🔗](./2022-10-ERC4626.pdf) [🔗](./2022-10-Checkpoints.pdf) |
| October 2018 | v2.0.0 | `dac5bcc` | LevelK | Everything | [🔗](./2018-10.pdf) |
| March 2017 | v1.0.4 | `9c5975a` | New Alchemy | Everything | [🔗](./2017-03.md) |
# Formal Verification
| Date | Version | Commit | Tool | Scope | Links |
| ------------ | ------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| May 2022 | v4.7.0 | `109778c` | Certora | Initializable, GovernorPreventLateQuorum, ERC1155Burnable, ERC1155Pausable, ERC1155Supply, ERC1155Holder, ERC1155Receiver | [🔗](../certora/reports/2022-05.pdf) |
| March 2022 | v4.4.0 | `4088540` | Certora | ERC20Votes, ERC20FlashMint, ERC20Wrapper, TimelockController, ERC721Votes, Votes, AccessControl, ERC1155 | [🔗](../certora/reports/2022-03.pdf) |
| October 2021 | v4.4.0 | `4088540` | Certora | Governor, GovernorCountingSimple, GovernorProposalThreshold, GovernorTimelockControl, GovernorVotes, GovernorVotesQuorumFraction | [🔗](../certora/reports/2021-10.pdf) |

BIN
certora/reports/2021-10.pdf
View File

Binary file not shown.

BIN
certora/reports/2022-03.pdf
View File

Binary file not shown.

BIN
certora/reports/2022-05.pdf
View File

Binary file not shown.

0
DOCUMENTATION.md → docs/README.md
Unescape View File

Write Preview
Loading…
Cancel
Save