merge api docs changes
Squashed commit of the following: commit 06243c3e8e86074ff8e9e3f22b7829a2c315d707 Merge: 991882ec 99373558 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 18:15:37 2019 -0300 Merge branch 'api-docs' into api-docs-merge commit 991882eca5bb8a3391995154bfb9d53d8a69cb4f Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 18:08:02 2019 -0300 manually apply docs changes and renamings commit fa1f6e97dd67a76c3cd828d0a5e19b4ac6c37acb Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 17:36:03 2019 -0300 move functions to new order commit 99373558e3af4905d29bc6f3f542ba93d28a24ab Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 16:23:40 2019 -0300 add missing docs links commit d180d6c36a6f5460e85473ee5a18992d1449a6ff Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 16:14:12 2019 -0300 update solidity-docgen dependency fixes uri encoded links commit faab0e50da91cd2f0a409e3ad32e2db127ad319a Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 16:05:03 2019 -0300 update openzeppelin-docsite and solidity-docgen dependencies add visibility specifiers commit ef305268bb2735e488e35d16819a4b432b3a35e3 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 23 15:36:45 2019 -0300 Fix guide links. commit 339b20dbfa2d5f6ea02e63c2f3fdcba0fe879c3c Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 23 13:37:51 2019 -0300 Fix typos. commit 6c7b97460578b9eea90b53c280454e361f8f0052 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 15:26:29 2019 -0300 fix utilities guide links commit 0e7692a8fd8516a11becc4121d77d792439600b1 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 15:23:19 2019 -0300 update solidity-docgen dependency commit ebb8a8651516ece21736c6c3b2577eb1b3487651 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 15:15:01 2019 -0300 fix utilities guide links commit 5ec47d62785e1d6e5f8e91edca58f2dc7f87d7a3 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 15:14:49 2019 -0300 fix escrow docs ordering commit cdcdc909b16f219a9a3272036b6a8f21e34b48ef Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 13:35:07 2019 -0300 add wip notice commit 987e2951ae93211c8c70c8288e30573555c57830 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 13:09:35 2019 -0300 update openzeppelin-docsite dependency fixes links to old versions commit b00d22c0affac2e2108df8b773dfa1706afcb44e Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 23 13:09:28 2019 -0300 fix guide links commit f112a9400c5e5ad495c8e0fdb972e26987b34244 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 20:42:37 2019 -0300 update docsite commit 68aacdd56a29e35a84f6732f9293612bbcaf7520 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Wed May 22 20:00:39 2019 -0300 ERC20Capped commit 4edce78bab2c6d140f3ea3f33db71e92ca4d8aaf Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Wed May 22 19:52:30 2019 -0300 Unnecessary polish on token docs. commit 2a4c91cf49c2736dc09c1c03cf383911def1a1b2 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 19:20:05 2019 -0300 rename guides commit 61dd818ea76d4c170c4ab175c6be0d6067d21a29 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Wed May 22 17:04:09 2019 -0300 ERC1820 docs. commit 77b5f0353123b76358dc6d86bdc646c86c9b0bea Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Wed May 22 16:17:34 2019 -0300 Introspection and ERC165. commit 76641a253b3b70279802c5134dd107532eea4b2c Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 17:59:53 2019 -0300 update docgen commit 7be98bc3fbd3566231f943f01b9acb58567d755b Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 17:23:50 2019 -0300 update solidity-docgen commit f7268e6e010f8ef9ac83df241a803f91efc08c0c Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 16:58:31 2019 -0300 update docgen commit 2a8c7a378e8962a5baeb334b2492815f05075f98 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Wed May 22 14:36:35 2019 -0300 Util docs. commit 327ae8ff45a1a523c7591bf4996c4a9b52d7ec7a Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 13:08:50 2019 -0300 add missing drafts commit 5e7f71335ac8423c0e363ae8c7ad9b2977f202f8 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 12:47:41 2019 -0300 tweak ierc20 docs commit cd0e86a0b712f74ffd406e072d4b1fbf4dd2c176 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 12:46:45 2019 -0300 add some erc721 docs commit e081184159417f71da14bc0fc110b7b11e29d75d Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 12:41:46 2019 -0300 update docsite commit 0beb75784022419d47123c2a9fe7a5f1eb87f9b2 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 12:22:27 2019 -0300 correct drafts structure commit 2e94b287c7cead7a6c0603205670566461c31abb Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 11:56:25 2019 -0300 fix docsite-start script commit 0fa4160484309d0851584fe57c0d81a3600977db Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 11:47:44 2019 -0300 improve docsite start script (automatically watch docgen) commit 9d571897cc03bee92035964cf7a2cfeda1e2f690 Author: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 22 11:30:37 2019 -0300 update solidity-docgen commit 82980f5aefbdfb8a9815a3b7b0e88e970b65dd5d Author: Francisco Giordano <frangio.1@gmail.com> Date: Tue May 21 19:15:13 2019 -0300 edit docs for Secondary commit 00d7a005b0530bee730b77a1b69a95f1b4ffe315 Author: Francisco Giordano <frangio.1@gmail.com> Date: Tue May 21 19:15:13 2019 -0300 edit docs for ownable commit b0c4c2bdf83eca5d4a71792daac603236733d46e Author: Francisco Giordano <frangio.1@gmail.com> Date: Tue May 21 18:27:13 2019 -0300 change title of Math section commit deb788583f191780e55b7f673520eaf13a5c7e23 Author: Francisco Giordano <frangio.1@gmail.com> Date: Tue May 21 18:26:59 2019 -0300 capitalization commit f2bcf85d343ea4a0739fe22a77b1e22c2296ddea Author: Francisco Giordano <frangio.1@gmail.com> Date: Tue May 21 18:26:06 2019 -0300 edit docs for Pausable commit 73ba0cf43dbb44c39c1bf2ee63ef9fe558faa919 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Sat May 18 19:08:06 2019 -0300 Crypto docs. commit 9d6fc6223f51cf2321b2e3217c512579654c3917 Merge: 7e21f8f7 9f1cec12 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Fri May 17 17:23:15 2019 -0300 Merge branch 'api-docs-777' into api-docs commit 9f1cec12e3351fb1b5fc0b59f5ded39928064a56 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Fri May 17 17:22:54 2019 -0300 ERC777 done. commit 7e21f8f7b6982d2f92df302cdf6ec62522d8ffff Author: Francisco Giordano <frangio.1@gmail.com> Date: Fri May 17 16:39:47 2019 -0300 add math docs commit f18d1f17023b6e5b42ae04fc38aa1170e6863864 Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 16 20:01:46 2019 -0300 First draft of ERC777 docs. commit985c5d3053Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 16 19:14:32 2019 -0300 Final draft for IERC777. commit bf53f133d987b67f938a329e6d659ba3483aab0b Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 16 19:13:37 2019 -0300 more work on ERC20 api docs commitb7c250b7cbAuthor: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 16 17:08:47 2019 -0300 Fix typo. commit197bbfbfc6Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 16 17:05:14 2019 -0300 Initial draft of IERC777. commit 7dc3b55161c860437a8f13a2ce5808b1c3dd70a2 Author: Francisco Giordano <frangio.1@gmail.com> Date: Thu May 16 11:58:32 2019 -0300 add payment docs structure commitda16fc4480Author: Nicolás Venturo <nicolas.venturo@gmail.com> Date: Thu May 16 16:05:33 2019 -0300 Initial ERC777 docstrings. commit9f6a7e35bdAuthor: Francisco Giordano <frangio.1@gmail.com> Date: Wed May 15 22:13:17 2019 -0300 partial pass through ERC20 docs (cherry picked from commit2f9ae975c8)
This commit is contained in:
Francisco Giordano
@ -1,6 +1,6 @@
|
||||
---
|
||||
id: learn-about-access-control
|
||||
title: Learn About Access Control
|
||||
id: access-control
|
||||
title: Access Control
|
||||
---
|
||||
|
||||
Access control—that is, "who is allowed to do this thing"—is incredibly important in the world of smart contracts. The access control of your contract governs who can mint tokens, who can vote on proposals, who can [`selfdestruct()`](https://blog.zeppelin.solutions/on-the-parity-wallet-multisig-hack-405a8c12e8f7) the contract, and more, so it's very important to understand how you implement it.
|
||||
@ -9,7 +9,7 @@ Access control—that is, "who is allowed to do this thing"—is incredibly impo
|
||||
|
||||
The most common and basic form of access control is the concept of _ownership_: there's one account that is the `owner` and can do administrative tasks on contracts. This approach is perfectly reasonable for contracts that only have a single administrative user.
|
||||
|
||||
OpenZeppelin provides [contracts/ownership/Ownable.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ownership/Ownable.sol) for implementing ownership in your contracts.
|
||||
OpenZeppelin provides [`Ownable`](api/ownership#ownable) for implementing ownership in your contracts.
|
||||
|
||||
```solidity
|
||||
import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
|
||||
@ -31,11 +31,11 @@ contract MyContract is Ownable {
|
||||
}
|
||||
```
|
||||
|
||||
By default, the `owner` of an `Ownable` contract is the `msg.sender` of the contract creation transaction, which is usually exactly what you want.
|
||||
By default, the [`owner`](api/ownership#Ownable.owner()) of an `Ownable` contract is the `msg.sender` of the contract creation transaction, which is usually exactly what you want.
|
||||
|
||||
Ownable also lets you:
|
||||
+ `transferOwnership(address newOwner)` to transfer ownership from one account to another
|
||||
+ `renounceOwnership()` to remove the owner altogether, useful for decentralizing control of your contract. **⚠ Warning!** Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
|
||||
+ [`transferOwnership`](api/ownership#Ownable.transferOwnership(address)) to transfer ownership from one account to another
|
||||
+ [`renounceOwnership`](api/ownership#Ownable.renounceOwnership()) to remove the owner altogether, useful for decentralizing control of your contract. **⚠ Warning!** Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
|
||||
|
||||
|
||||
Note that any contract that supports sending transactions can also be the owner of a contract; the only requirement is that the owner has an Ethereum address, so it could be a Gnosis Multisig or Gnosis Safe, an Aragon DAO, an ERC725/uPort identity contract, or a totally custom contract that _you_ create.
|
||||
@ -44,17 +44,17 @@ In this way you can use _composability_ to add additional layers of access contr
|
||||
|
||||
### Examples in OpenZeppelin
|
||||
|
||||
You'll notice that none of the OpenZeppelin contracts use Ownable, though! This is because there are more flexible ways of providing access control that are more in-line with our reusable contract philosophy. For most contracts, We'll use `Roles` to govern who can do what. There are some cases, though—like with `Escrow`—where there's a direct relationship between contracts. In those cases, we'll use [`Secondary`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ownership/Secondary.sol) to create a "secondary" contract that allows a "primary" contract to manage it.
|
||||
You'll notice that none of the OpenZeppelin contracts use `Ownable`, though! This is because there are more flexible ways of providing access control that are more in-line with our reusable contract philosophy. For most contracts, We'll use `Roles` to govern who can do what. There are some cases, though—like with [`Escrow`](localhost:3000/api/payment#escrow)—where there's a direct relationship between contracts. In those cases, we'll use [`Secondary`](api/ownership#secondary) to create a "secondary" contract that allows a "primary" contract to manage it.
|
||||
|
||||
Let's learn about Role-Based Access Control!
|
||||
|
||||
## Role-Based Access Control & Roles.sol
|
||||
## Roles & Role-Based Access Control
|
||||
|
||||
An alternative to single-concern `Ownable` is role based access control (RBAC), which, instead of keeping track of a single entity with "admin" level privileges, keeps track of multiple different entities with a variety of roles that inform the contract about what they can do.
|
||||
|
||||
For example, a `MintableToken` could have a `minter` role that decides who can mint tokens (which could be assigned to a Crowdsale). It could also have a `namer` role that allows changing the name or symbol of the token (for whatever reason). RBAC gives you much more flexibility over who can do what and is generally recommended for applications that need more configurability. If you're experienced with web development, the vast majority of access control systems are role-based: some users are normal users, some are moderators, and some can be company employee admins.
|
||||
For example, a [`MintableToken`](api/token/ERC20#erc20mintable) could have a `minter` role that decides who can mint tokens (which could be assigned to a [`Crowdsale`](api/crowdsale#crowdsale)). It could also have a `namer` role that allows changing the name or symbol of the token (for whatever reason). RBAC gives you much more flexibility over who can do what and is generally recommended for applications that need more configurability. If you're experienced with web development, the vast majority of access control systems are role-based: some users are normal users, some are moderators, and some can be company employee admins.
|
||||
|
||||
OpenZeppelin provides [contracts/access/Roles.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/access/Roles.sol) for implementing role-based access control.
|
||||
OpenZeppelin provides [`Roles`](api/access#roles) for implementing role-based access control.
|
||||
|
||||
Here's an example of using `Roles` in our token example above, we'll use it to implement a token that can be minted by `Minters` and renamed by `Namers`:
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
id: learn-about-crowdsales
|
||||
title: Learn About Crowdsales
|
||||
id: crowdsales
|
||||
title: Crowdsales
|
||||
---
|
||||
|
||||
Crowdsales are a popular use for Ethereum; they let you allocate tokens to network participants in various ways, mostly in exchange for Ether. They come in a variety of shapes and flavors, so let's go over the various types available in OpenZeppelin and how to use them.
|
||||
@ -20,7 +20,7 @@ Crowdsales have a bunch of different properties, but here are some important one
|
||||
- Does distribution of funds happen in real-time or after the crowdsale?
|
||||
- Can participants receive a refund if the goal is not met?
|
||||
|
||||
To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable [`Crowdsale.sol`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/Crowdsale.sol) base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
|
||||
To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable [`Crowdsale`](api/crowdsale#crowdsale) base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
|
||||
|
||||
## Crowdsale Rate
|
||||
|
||||
@ -60,9 +60,9 @@ One more for practice: if I want to issue "1 TKN for every dollar (USD) in Ether
|
||||
|
||||
One of the first decisions you have to make is "how do I get these tokens to users?". This is usually done in one of three ways:
|
||||
|
||||
- (default) — The Crowdsale contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
|
||||
- [MintedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/emission/MintedCrowdsale.sol) — The Crowdsale mints tokens when a purchase is made.
|
||||
- [AllowanceCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/emission/AllowanceCrowdsale.sol) — The Crowdsale is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
|
||||
- (default) — The `Crowdsale` contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
|
||||
- [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale) — The `Crowdsale` mints tokens when a purchase is made.
|
||||
- [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) — The `Crowdsale` is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
|
||||
|
||||
### Default Emission
|
||||
|
||||
@ -84,7 +84,7 @@ new Crowdsale(
|
||||
|
||||
### Minted Crowdsale
|
||||
|
||||
To use a `MintedCrowdsale`, your token must also be a `ERC20Mintable` token that the crowdsale has permission to mint from. This can look like:
|
||||
To use a [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale), your token must also be a [`ERC20Mintable`](api/token/ERC20#erc20mintable) token that the crowdsale has permission to mint from. This can look like:
|
||||
|
||||
```solidity
|
||||
contract MyToken is ERC20, ERC20Mintable {
|
||||
@ -128,7 +128,7 @@ contract MyCrowdsaleDeployer {
|
||||
|
||||
### AllowanceCrowdsale
|
||||
|
||||
Use an `AllowanceCrowdsale` to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 `approve(...)` method.
|
||||
Use an [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 [`approve`](api/token/ERC20#IERC20.approve(address,uint256)) method.
|
||||
|
||||
```solidity
|
||||
contract MyCrowdsale is AllowanceCrowdsale, Crowdsale {
|
||||
@ -157,10 +157,10 @@ IERC20(tokenAddress).approve(CROWDALE_ADDRESS, SOME_TOKEN_AMOUNT);
|
||||
|
||||
There are a bunch of different validation requirements that your crowdsale might be a part of:
|
||||
|
||||
- [CappedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/CappedCrowdsale.sol) — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
|
||||
- [IndividuallyCappedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/IndividuallyCappedCrowdsale.sol) — caps an individual's contributions.
|
||||
- [WhitelistedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/WhitelistedCrowdsale.sol) — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
|
||||
- [TimedCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/validation/TimedCrowdsale.sol) — adds an `openingTime` and `closingTime` to your crowdsale
|
||||
- [`CappedCrowdsale`](api/crowdsale#cappedcrowdsale) — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
|
||||
- [`IndividuallyCappedCrowdsale`](api/crowdsale#individuallycappedcrowdsale) — caps an individual's contributions.
|
||||
- [`WhitelistCrowdsale`](api/crowdsale#whitelistcrowdsale) — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
|
||||
- [`TimedCrowdsale`](api/crowdsale#timedcrowdsale) — adds an [`openingTime`](api/crowdsale#TimedCrowdsale.openingTime()) and [`closingTime`](api/crowdsale#TimedCrowdsale.closingTime()) to your crowdsale
|
||||
|
||||
Simply mix and match these crowdsale flavors to your heart's content:
|
||||
|
||||
@ -197,7 +197,7 @@ OpenZeppelin is here to make that easy!
|
||||
|
||||
### PostDeliveryCrowdsale
|
||||
|
||||
The [PostDeliveryCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/distribution/PostDeliveryCrowdsale.sol), as its name implies, distributes tokens after the crowdsale has finished, letting users call `withdrawTokens()` in order to claim the tokens they've purchased.
|
||||
The [`PostDeliveryCrowdsale`](api/crowdsale#postdeliverycrowdsale), as its name implies, distributes tokens after the crowdsale has finished, letting users call [`withdrawTokens`](api/crowdsale#PostDeliveryCrowdsale.withdrawTokens(address)) in order to claim the tokens they've purchased.
|
||||
|
||||
```solidity
|
||||
contract MyCrowdsale is PostDeliveryCrowdsale, TimedCrowdsale, Crowdsale {
|
||||
@ -222,7 +222,7 @@ contract MyCrowdsale is PostDeliveryCrowdsale, TimedCrowdsale, Crowdsale {
|
||||
|
||||
### RefundableCrowdsale
|
||||
|
||||
The [RefundableCrowdsale](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/crowdsale/distribution/RefundableCrowdsale.sol) offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can `claimRefund()` to get their Ether back.
|
||||
The [`RefundableCrowdsale`](api/crowdsale#refundablecrowdsale) offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can [`claimRefund`](api/crowdsale#RefundableCrowdsale.claimRefund(address%20payable)) to get their Ether back.
|
||||
|
||||
|
||||
```solidity
|
||||
@ -3,7 +3,7 @@ id: get-started
|
||||
title: Get Started
|
||||
---
|
||||
|
||||
OpenZeppelin can be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use [Truffle](https://github.com/ConsenSys/truffle), an Ethereum development environment, to get started.
|
||||
OpenZeppelin can be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use [Truffle](https://github.com/trufflesuite/truffle), an Ethereum development environment, to get started.
|
||||
|
||||
Please install Truffle and initialize your project:
|
||||
|
||||
@ -33,10 +33,10 @@ contract MyContract is Ownable {
|
||||
|
||||
After installing OpenZeppelin, check out the rest of the guides in the sidebar to learn about the different contracts that OpenZeppelin provides and how to use them.
|
||||
|
||||
- [Learn About Access Control](learn-about-access-control)
|
||||
- [Learn About Crowdsales](learn-about-crowdsales)
|
||||
- [Learn About Tokens](learn-about-tokens)
|
||||
- [Learn About Utilities](learn-about-utilities)
|
||||
- [Learn About Access Control](access-control)
|
||||
- [Learn About Crowdsales](crowdsales)
|
||||
- [Learn About Tokens](tokens)
|
||||
- [Learn About Utilities](utilities)
|
||||
|
||||
You may also want to take a look at the guides on our blog, which cover several common use cases and good practices: https://blog.zeppelin.solutions/guides/home.
|
||||
|
||||
|
||||
@ -1,94 +0,0 @@
|
||||
---
|
||||
id: learn-about-utilities
|
||||
title: Learn About Utilities
|
||||
---
|
||||
|
||||
OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
|
||||
|
||||
## Cryptography
|
||||
|
||||
- [ECDSA.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/cryptography/ECDSA.sol) — provides functions for recovering and managing Ethereum account ECDSA signatures:
|
||||
- to use it, declare: `using ECDSA for bytes32;`
|
||||
- signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
|
||||
- this is the default from `web3.eth.sign` so you probably don't need to worry about this format
|
||||
- recover the signer using `myDataHash.recover(signature)`
|
||||
- if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use `toEthSignedMessageHash`
|
||||
|
||||
|
||||
Use these functions in combination to verify that a user has signed some information on-chain:
|
||||
|
||||
```solidity
|
||||
keccack256(
|
||||
abi.encodePacked(
|
||||
someData,
|
||||
moreData
|
||||
)
|
||||
)
|
||||
.toEthSignedMessageHash()
|
||||
.recover(signature)
|
||||
```
|
||||
|
||||
- [MerkleProof.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/cryptography/MerkleProof.sol) — provides `verify(...)` for verifying merkle proofs.
|
||||
|
||||
|
||||
## Introspection
|
||||
|
||||
In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
|
||||
|
||||
- [IERC165](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/IERC165.sol) — this is the ERC165 interface that defines `supportsInterface(...)`. When implementing ERC165, you'll conform to this interface.
|
||||
- [ERC165](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/ERC165.sol) — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using `_registerInterface(bytes4)`: check out example usage as part of the ERC721 implementation.
|
||||
- [ERC165Checker](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/introspection/ERC165Checker.sol) — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
|
||||
- include with `using ERC165Checker for address;`
|
||||
- `myAddress.supportsInterface(bytes4)`
|
||||
- `myAddress.supportsInterfaces(bytes4[])`
|
||||
|
||||
|
||||
```solidity
|
||||
contract MyContract {
|
||||
using ERC165Checker for address;
|
||||
|
||||
bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
|
||||
|
||||
/**
|
||||
* @dev transfer an ERC721 token from this contract to someone else
|
||||
*/
|
||||
function transferERC721(
|
||||
address token,
|
||||
address to,
|
||||
uint256 tokenId
|
||||
)
|
||||
public
|
||||
{
|
||||
require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
|
||||
IERC721(token).transferFrom(address(this), to, tokenId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Math
|
||||
|
||||
The most popular math related library OpenZeppelin provides is [SafeMath](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol), which provides mathematical functions that protect your contract from overflows and underflows.
|
||||
|
||||
Include the contract with `using SafeMath for uint256;` and then call the functions:
|
||||
|
||||
- `myNumber.add(otherNumber)`
|
||||
- `myNumber.sub(otherNumber)`
|
||||
- `myNumber.div(otherNumber)`
|
||||
- `myNumber.mul(otherNumber)`
|
||||
- `myNumber.mod(otherNumber)`
|
||||
|
||||
Easy!
|
||||
|
||||
## Payment
|
||||
|
||||
Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with [`PaymentSplitter`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/PaymentSplitter.sol)!.
|
||||
|
||||
In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the [Ethereum Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use [`PullPayment`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/PullPayment.sol), which offers an `asyncSend` function for sending money to something and requesting that they `withdraw()` it later.
|
||||
|
||||
If you want to Escrow some funds, check out [`Escrow`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/escrow/Escrow.sol) and [`ConditionalEscrow`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/payment/escrow/ConditionalEscrow.sol) for governing the release of some escrowed Ether.
|
||||
|
||||
### Misc
|
||||
|
||||
Want to check if an address is a contract? Use [`Address`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/utils/Address.sol) and `Address#isContract()`.
|
||||
|
||||
Want to keep track of some numbers that increment by 1 every time you want another one? Check out [`Counter`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/drafts/Counter.sol). This is especially useful for creating incremental ERC721 tokenIds like we did in the last section.
|
||||
@ -3,10 +3,10 @@
|
||||
"get-started"
|
||||
],
|
||||
"Guides": [
|
||||
"learn-about-access-control",
|
||||
"learn-about-crowdsales",
|
||||
"learn-about-tokens",
|
||||
"learn-about-utilities"
|
||||
"access-control",
|
||||
"crowdsales",
|
||||
"tokens",
|
||||
"utilities"
|
||||
],
|
||||
"API Reference": [
|
||||
{
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
id: learn-about-tokens
|
||||
title: Learn About Tokens
|
||||
id: tokens
|
||||
title: Tokens
|
||||
---
|
||||
|
||||
Ah, the "token": the world's most powerful and most misused tool. In this section we'll learn to harness the power of native units of account for good and world peace!
|
||||
@ -21,22 +21,22 @@ An ERC20 token is a contract that keeps track of a `mapping(address => uint256)`
|
||||
|
||||
OpenZeppelin provides a few different ERC20-related contracts. Here are the core contracts you'll almost definitely be using:
|
||||
|
||||
- [IERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/IERC20.sol) — defines the interface that all ERC20 token implementations should conform to
|
||||
- [ERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20.sol) — the base implementation of the ERC20 interface
|
||||
- [ERC20Detailed](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Detailed.sol) — the `name()`, `symbol()`, and `decimals()` getters are optional in the original standard, so `ERC20Detailed` adds that information to your token.
|
||||
- [`IERC20`](api/token/ERC20#ierc20) — defines the interface that all ERC20 token implementations should conform to
|
||||
- [`ERC20`](api/token/ERC20#erc20) — the base implementation of the ERC20 interface
|
||||
- [`ERC20Detailed`](api/token/ERC20#erc20detailed) — the [`name()`](api/token/ERC20#ERC20Detailed.name()), [`symbol()`](api/token/ERC20#ERC20Detailed.symbol()), and [`decimals()`](api/token/ERC20#ERC20Detailed.decimals()) getters are optional in the original standard, so `ERC20Detailed` adds that information to your token.
|
||||
|
||||
|
||||
After that, OpenZeppelin provides a few extra properties that you may want depending on your use-case:
|
||||
|
||||
- [ERC20Mintable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Mintable.sol) — `ERC20Mintable` allows users with the [`MinterRole`](/api/docs/learn-about-access-control.html) to call the `mint()` function and mint tokens to users. Minting can also be finished, locking the `mint()` function's behavior.
|
||||
- [ERC20Burnable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Burnable.sol) — if your token can be burned (aka, it can be destroyed), include this one
|
||||
- [ERC20Capped](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Capped.sol) — `ERC20Capped` is a type of `ERC20Mintable` that enforces a maximum cap on tokens; this is really useful if you want to ensure network participants that there will always be a maximum number of tokens, and is useful for making sure that multiple different minting methods don't accidentally create more tokens than you expected.
|
||||
- [ERC20Pausable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/ERC20Pausable.sol) — `ERC20Pausable` allows anyone with the Pauser role to pause the token, freezing transfers to and from users. This is useful if you want to stop trades until the end of a crowdsale, or if you want to have an emergency switch for freezing your tokens in the event of a large bug. Note that there are inherent decentralization tradeoffs when using a pausable token; users may not expect that their unstoppable money can be frozen by a single address!
|
||||
- [`ERC20Mintable`](api/token/ERC20#erc20mintable) — `ERC20Mintable` allows users with the [`MinterRole`](access-control) to call the [`mint()`](api/token/ERC20#ERC20Mintable.mint(address,uint256)) function and mint tokens to users.
|
||||
- [`ERC20Burnable`](api/token/ERC20#erc20burnable) — if your token can be burned (aka, it can be destroyed), include this one.
|
||||
- [`ERC20Capped`](api/token/ERC20#erc20capped) — `ERC20Capped` is a type of `ERC20Mintable` that enforces a maximum cap on tokens; this is really useful if you want to ensure network participants that there will always be a maximum number of tokens, and is useful for making sure that multiple different minting methods don't accidentally create more tokens than you expected.
|
||||
- [`ERC20Pausable`](api/token/ERC20#erc20pausable) — `ERC20Pausable` allows anyone with the Pauser role to pause the token, freezing transfers to and from users. This is useful if you want to stop trades until the end of a crowdsale, or if you want to have an emergency switch for freezing your tokens in the event of a large bug. Note that there are inherent decentralization tradeoffs when using a pausable token; users may not expect that their unstoppable money can be frozen by a single address!
|
||||
|
||||
Finally, if you're working with ERC20 tokens, OpenZeppelin provides some utility contracts:
|
||||
|
||||
- [SafeERC20](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/SafeERC20.sol) — provides `safeTransfer`, `safeTransferFrom`, and `safeApprove` that are helpful wrappers around the normal ERC20 functions. Using `SafeERC20` forces transfers and approvals to succeed, or the entire transaction is reverted.
|
||||
- [TokenTimelock](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC20/TokenTimelock.sol) — is an escrow contract for ERC20 tokens that will release some tokens after a specified timeout. This is useful for simple vesting schedules like "advisors get all of their tokens after 1 year". For a better vesting schedule, though, see [`TokenVesting`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/drafts/TokenVesting.sol)
|
||||
- [`SafeERC20`](api/token/ERC20#safeerc20) — provides [`safeTransfer`](api/token/ERC20#SafeERC20.safeTransfer(contract%20IERC20,address,uint256)), [`safeTransferFrom`](api/token/ERC20#SafeERC20.safeTransferFrom(contract%20IERC20,address,address,uint256)), and [`safeApprove`](api/token/ERC20#SafeERC20.safeApprove(contract%20IERC20,address,uint256)) that are helpful wrappers around the normal ERC20 functions. Using `SafeERC20` forces transfers and approvals to succeed, or the entire transaction is reverted.
|
||||
- [`TokenTimelock`](api/token/ERC20#tokentimelock) — is an escrow contract for ERC20 tokens that will release some tokens after a specified timeout. This is useful for simple vesting schedules like "advisors get all of their tokens after 1 year". For a better vesting schedule, though, see [`TokenVesting`](api/drafts#tokenvesting)
|
||||
|
||||
### Constructing a Nice ERC20 Token
|
||||
|
||||
@ -79,11 +79,11 @@ We've discussed how you can make a _fungible_ token using ERC20, but what if not
|
||||
|
||||
Let's see what contracts OpenZeppelin provides for helping us work with ERC721:
|
||||
|
||||
- The `IERC721`, `IERC721Metadata`, `IERC721Enumerable` interfaces are part of the [IERC721.sol](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/IERC721.sol) file, which document the interfaces.
|
||||
- [ERC721](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721.sol) — is the full implementation of ERC721, and the contract you'll most likely be inheriting from.
|
||||
- [IERC721Receiver](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/IERC721Receiver.sol) — in some cases, it's beneficial to be 100% certain that a contract knows how to handle ERC721 tokens (imagine sending an in-game item to an exchange address that can't send it back!). When using `safeTransferFrom()`, the contract checks to see that the receiver is an `IERC721Receiver`, which implies that it knows how to handle ERC721 tokens. If you're writing a contract that accepts 721 tokens, you'll want to implement this interface.
|
||||
- [ERC721Mintable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721Mintable.sol) — like the ERC20 version, ERC721Mintable allows addresses with the `Minter` role to mint tokens.
|
||||
- [ERC721Pausable](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/token/ERC721/ERC721Pausable.sol) — like the ERC20 version, ERC721Pausable allows addresses with the `Pauser` role to freeze transfers of tokens.
|
||||
- The [`IERC721`](api/token/ERC721#ierc721), [`IERC721Metadata`](api/token/ERC721#ierc721metadata), [`IERC721Enumerable`](api/token/ERC721#ierc721enumerable) contracts document the interfaces.
|
||||
- [`ERC721`](api/token/ERC721#erc721) — is the full implementation of ERC721, and the contract you'll most likely be inheriting from.
|
||||
- [`IERC721Receiver`](api/token/ERC721#ierc721receiver) — in some cases, it's beneficial to be 100% certain that a contract knows how to handle ERC721 tokens (imagine sending an in-game item to an exchange address that can't send it back!). When using [`safeTransferFrom()`](api/token/ERC721#ERC721.safeTransferFrom(address,address,uint256)), the contract checks to see that the receiver is an `IERC721Receiver`, which implies that it knows how to handle ERC721 tokens. If you're writing a contract that accepts ERC721 tokens, you'll want to implement this interface.
|
||||
- [`ERC721Mintable`](api/token/ERC721#erc721mintable) — like the ERC20 version, `ERC721Mintable` allows addresses with the `Minter` role to mint tokens.
|
||||
- [`ERC721Pausable`](api/token/ERC721#erc721pausable) — like the ERC20 version, `ERC721Pausable` allows addresses with the `Pauser` role to freeze transfers of tokens.
|
||||
|
||||
|
||||
We'll use these contracts to tokenize the time of our dogsitters: when a dogsitter wants to sell an hour of their time to watch a dog, they can mint an ERC721 token that represents that hour slot and then sell this token on an exchange. Then they'll go to the owner's house at the right time to watch their doggos.
|
||||
94
docs/utilities.md
Normal file
94
docs/utilities.md
Normal file
@ -0,0 +1,94 @@
|
||||
---
|
||||
id: utilities
|
||||
title: Utilities
|
||||
---
|
||||
|
||||
OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
|
||||
|
||||
## Cryptography
|
||||
|
||||
- [`ECDSA`](api/cryptography#ecdsa) — provides functions for recovering and managing Ethereum account ECDSA signatures:
|
||||
- to use it, declare: `using ECDSA for bytes32;`
|
||||
- signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
|
||||
- this is the default from `web3.eth.sign` so you probably don't need to worry about this format
|
||||
- recover the signer using [`myDataHash.recover(signature)`](api/cryptography#ECDSA.recover(bytes32,bytes))
|
||||
- if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use [`toEthSignedMessageHash`](api/cryptography#ECDSA.toEthSignedMessageHash(bytes32))
|
||||
|
||||
|
||||
Use these functions in combination to verify that a user has signed some information on-chain:
|
||||
|
||||
```solidity
|
||||
keccack256(
|
||||
abi.encodePacked(
|
||||
someData,
|
||||
moreData
|
||||
)
|
||||
)
|
||||
.toEthSignedMessageHash()
|
||||
.recover(signature)
|
||||
```
|
||||
|
||||
- [`MerkleProof`](api/cryptography#merkleproof) — provides [`verify`](api/cryptography#MerkleProof.verify(bytes32[],bytes32,bytes32)) for verifying merkle proofs.
|
||||
|
||||
|
||||
## Introspection
|
||||
|
||||
In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
|
||||
|
||||
- [`IERC165`](api/introspection#ierc165) — this is the ERC165 interface that defines [`supportsInterface`](api/introspection#IERC165.supportsInterface(bytes4)). When implementing ERC165, you'll conform to this interface.
|
||||
- [`ERC165`](api/introspection#erc165) — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using [`_registerInterface(bytes4)`](api/introspection#ERC165._registerInterface(bytes4)): check out example usage as part of the ERC721 implementation.
|
||||
- [`ERC165Checker`](api/introspection#erc165checker) — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
|
||||
- include with `using ERC165Checker for address;`
|
||||
- [`myAddress._supportsInterface(bytes4)`](api/introspection#ERC165Checker._supportsInterface(address,bytes4))
|
||||
- [`myAddress._supportsAllInterfaces(bytes4[])`](api/introspection#ERC165Checker._supportsAllInterfaces(address,bytes4[]))
|
||||
|
||||
|
||||
```solidity
|
||||
contract MyContract {
|
||||
using ERC165Checker for address;
|
||||
|
||||
bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
|
||||
|
||||
/**
|
||||
* @dev transfer an ERC721 token from this contract to someone else
|
||||
*/
|
||||
function transferERC721(
|
||||
address token,
|
||||
address to,
|
||||
uint256 tokenId
|
||||
)
|
||||
public
|
||||
{
|
||||
require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
|
||||
IERC721(token).transferFrom(address(this), to, tokenId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Math
|
||||
|
||||
The most popular math related library OpenZeppelin provides is [`SafeMath`](api/math#safemath), which provides mathematical functions that protect your contract from overflows and underflows.
|
||||
|
||||
Include the contract with `using SafeMath for uint256;` and then call the functions:
|
||||
|
||||
- `myNumber.add(otherNumber)`
|
||||
- `myNumber.sub(otherNumber)`
|
||||
- `myNumber.div(otherNumber)`
|
||||
- `myNumber.mul(otherNumber)`
|
||||
- `myNumber.mod(otherNumber)`
|
||||
|
||||
Easy!
|
||||
|
||||
## Payment
|
||||
|
||||
Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with [`PaymentSplitter`](api/payment#paymentsplitter)!
|
||||
|
||||
In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the [Ethereum Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use [`PullPayment`](api/payment#pullpayment), which offers an [`_asyncTransfer`](api/payment#PullPayment._asyncTransfer(address,uint256)) function for sending money to something and requesting that they [`withdrawPayments()`](api/payment#PullPayment.withdrawPayments(address%20payable)) it later.
|
||||
|
||||
If you want to Escrow some funds, check out [`Escrow`](api/payment#escrow) and [`ConditionalEscrow`](api/payment#conditionalescrow) for governing the release of some escrowed Ether.
|
||||
|
||||
### Misc
|
||||
|
||||
Want to check if an address is a contract? Use [`Address`](api/utils#address) and [`Address#isContract()`](api/utils#Address.isContract(address)).
|
||||
|
||||
Want to keep track of some numbers that increment by 1 every time you want another one? Check out [`Counter`](api/drafts#counter). This is especially useful for creating incremental ERC721 `tokenId`s like we did in the last section.
|
||||
Reference in New Issue
Block a user