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.
commit 985c5d3053
Author: 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
commit b7c250b7cb
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date: Thu May 16 17:08:47 2019 -0300
Fix typo.
commit 197bbfbfc6
Author: 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
commit da16fc4480
Author: Nicolás Venturo <nicolas.venturo@gmail.com>
Date: Thu May 16 16:05:33 2019 -0300
Initial ERC777 docstrings.
commit 9f6a7e35bd
Author: Francisco Giordano <frangio.1@gmail.com>
Date: Wed May 15 22:13:17 2019 -0300
partial pass through ERC20 docs
(cherry picked from commit 2f9ae975c8)
release-v2.3.0
Francisco Giordano
6 years ago
parent
96fbe823ff
commit
e41daba7b4
@ -0,0 +1,9 @@ |
||||
--- |
||||
sections: |
||||
- title: Libraries |
||||
contracts: |
||||
- ECDSA |
||||
- MerkleProof |
||||
--- |
||||
|
||||
This collection of libraries provides simple and safe ways to use different cryptographic primitives. |
||||
@ -0,0 +1,16 @@ |
||||
--- |
||||
sections: |
||||
- title: ERC 20 |
||||
contracts: |
||||
- ERC20Migrator |
||||
- ERC20Snapshot |
||||
- TokenVesting |
||||
- title: Miscellenous |
||||
contracts: |
||||
- Counters |
||||
- SignatureBouncer |
||||
- SignedSafeMath |
||||
- subdirectory: ERC1046 |
||||
--- |
||||
|
||||
> This page is incomplete. We're working to improve it for the next release. Stay tuned! |
||||
@ -1,15 +1,22 @@ |
||||
pragma solidity ^0.5.0; |
||||
|
||||
/** |
||||
* @title IERC165 |
||||
* @dev https://eips.ethereum.org/EIPS/eip-165 |
||||
* @dev Interface of the ERC165 standard, as defined in the |
||||
* [EIP](https://eips.ethereum.org/EIPS/eip-165). |
||||
* |
||||
* Implementers can declare support of contract interfaces, which can then be |
||||
* queried by others (`ERC165Checker`). |
||||
* |
||||
* For an implementation, see `ERC165`. |
||||
*/ |
||||
interface IERC165 { |
||||
/** |
||||
* @notice Query if a contract implements an interface |
||||
* @param interfaceId The interface identifier, as specified in ERC-165 |
||||
* @dev Interface identification is specified in ERC-165. This function |
||||
* uses less than 30,000 gas. |
||||
* @dev Returns true if this contract implements the interface defined by |
||||
* `interfaceId`. See the corresponding |
||||
* [EIP section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified) |
||||
* to learn more about how these ids are created. |
||||
* |
||||
* This function call must use less than 30 000 gas. |
||||
*/ |
||||
function supportsInterface(bytes4 interfaceId) external view returns (bool); |
||||
} |
||||
|
||||
@ -1,17 +1,17 @@ |
||||
pragma solidity ^0.5.0; |
||||
|
||||
/** |
||||
* @title IERC1820Implementer |
||||
* Interface for contracts that will be registered as implementers in the ERC1820 registry. |
||||
* @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820 |
||||
* @dev Interface for an ERC1820 implementer, as defined in the |
||||
* [EIP](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface). |
||||
* Used by contracts that will be registered as implementers in the |
||||
* `IERC1820Registry`. |
||||
*/ |
||||
interface IERC1820Implementer { |
||||
/** |
||||
* @notice Indicates whether the contract implements the interface `interfaceHash` for the address `account` or |
||||
* not. |
||||
* @param interfaceHash keccak256 hash of the name of the interface |
||||
* @param account Address for which the contract will implement the interface |
||||
* @return ERC1820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `account`. |
||||
* @dev Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract |
||||
* implements `interfaceHash` for `account`. |
||||
* |
||||
* See `IERC1820Registry.setInterfaceImplementer`. |
||||
*/ |
||||
function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32); |
||||
} |
||||
|
||||
@ -0,0 +1,23 @@ |
||||
--- |
||||
sections: |
||||
- title: Local |
||||
contracts: |
||||
- IERC165 |
||||
- ERC165 |
||||
- ERC165Checker |
||||
- title: Global |
||||
contracts: |
||||
- IERC1820Registry |
||||
- IERC1820Implementer |
||||
- ERC1820Implementer |
||||
--- |
||||
|
||||
This set of interfaces and contracts deal with [type introspection](https://en.wikipedia.org/wiki/Type_introspection) of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_. |
||||
|
||||
Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors. |
||||
|
||||
There are two main ways to approach this. |
||||
- Locally, where a contract implements `IERC165` and declares an interface, and a second one queries it directly via `ERC165Checker`. |
||||
- Globally, where a global and unique registry (`IERC1820Registry`) is used to register implementers of a certain interface (`IERC1820Implementer`). It is then the registry that is queried, which allows for more complex setups, like contracts implementing interfaces for externally-owned accounts. |
||||
|
||||
Note that, in all cases, accounts simply _declare_ their interfaces, but they are not required to actually implement them. This mechanism can therefore be used to both prevent errors and allow for complex interactions (see `ERC777`), but it must not be relied on for security. |
||||
@ -0,0 +1,10 @@ |
||||
--- |
||||
title: Math |
||||
sections: |
||||
- title: Libraries |
||||
contracts: |
||||
- SafeMath |
||||
- Math |
||||
--- |
||||
|
||||
These are math-related utilities. |
||||
@ -0,0 +1,3 @@ |
||||
Contract modules for simple authorization and access control mechanisms. |
||||
|
||||
For more complex needs see [Access](access). |
||||
@ -0,0 +1,10 @@ |
||||
--- |
||||
sections: |
||||
- title: Payment Utilities |
||||
contracts: |
||||
- PaymentSplitter |
||||
- PullPayment |
||||
- subdirectory: escrow |
||||
--- |
||||
|
||||
> This page is incomplete. We're working to improve it for the next release. Stay tuned! |
||||
@ -0,0 +1,8 @@ |
||||
--- |
||||
title: Escrows |
||||
sections: |
||||
- contracts: |
||||
- Escrow |
||||
- ConditionalEscrow |
||||
- RefundEscrow |
||||
--- |
||||
@ -1,23 +1,76 @@ |
||||
pragma solidity ^0.5.0; |
||||
|
||||
/** |
||||
* @title ERC20 interface |
||||
* @dev see https://eips.ethereum.org/EIPS/eip-20 |
||||
* @dev Interface of the ERC20 standard as defined in the EIP. Does not include |
||||
* the optional functions; to access them see `ERC20Detailed`. |
||||
*/ |
||||
interface IERC20 { |
||||
function transfer(address to, uint256 value) external returns (bool); |
||||
/** |
||||
* @dev Returns the amount of tokens in existence. |
||||
*/ |
||||
function totalSupply() external view returns (uint256); |
||||
|
||||
function approve(address spender, uint256 value) external returns (bool); |
||||
/** |
||||
* @dev Returns the amount of tokens owned by `account`. |
||||
*/ |
||||
function balanceOf(address account) external view returns (uint256); |
||||
|
||||
function transferFrom(address from, address to, uint256 value) external returns (bool); |
||||
/** |
||||
* @dev Moves `amount` tokens from the caller's account to `recipient`. |
||||
* |
||||
* Returns a boolean value indicating whether the operation succeeded. |
||||
* |
||||
* Emits a `Transfer` event. |
||||
*/ |
||||
function transfer(address recipient, uint256 amount) external returns (bool); |
||||
|
||||
function totalSupply() external view returns (uint256); |
||||
/** |
||||
* @dev Returns the remaining number of tokens that `spender` will be |
||||
* allowed to spend on behalf of `owner` through `transferFrom`. This is |
||||
* zero by default. |
||||
* |
||||
* This value changes when `approve` or `transferFrom` are called. |
||||
*/ |
||||
function allowance(address owner, address spender) external view returns (uint256); |
||||
|
||||
function balanceOf(address who) external view returns (uint256); |
||||
/** |
||||
* @dev Sets `amount` as the allowance of `spender` over the caller's tokens. |
||||
* |
||||
* Returns a boolean value indicating whether the operation succeeded. |
||||
* |
||||
* > Beware that changing an allowance with this method brings the risk |
||||
* that someone may use both the old and the new allowance by unfortunate |
||||
* transaction ordering. One possible solution to mitigate this race |
||||
* condition is to first reduce the spender's allowance to 0 and set the |
||||
* desired value afterwards: |
||||
* https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 |
||||
* |
||||
* Emits an `Approval` event. |
||||
*/ |
||||
function approve(address spender, uint256 amount) external returns (bool); |
||||
|
||||
function allowance(address owner, address spender) external view returns (uint256); |
||||
/** |
||||
* @dev Moves `amount` tokens from `sender` to `recipient` using the |
||||
* allowance mechanism. `amount` is then deducted from the caller's |
||||
* allowance. |
||||
* |
||||
* Returns a boolean value indicating whether the operation succeeded. |
||||
* |
||||
* Emits a `Transfer` event. |
||||
*/ |
||||
function transferFrom(address sender, address recipient, uint256 amount) external returns (bool); |
||||
|
||||
/** |
||||
* @dev Emitted when `value` tokens are moved from one account (`from`) to |
||||
* another (`to`). |
||||
* |
||||
* Note that `value` may be zero. |
||||
*/ |
||||
event Transfer(address indexed from, address indexed to, uint256 value); |
||||
|
||||
/** |
||||
* @dev Emitted when the allowance of a `spender` for an `owner` is set by |
||||
* a call to `approve`. `value` is the new allowance. |
||||
*/ |
||||
event Approval(address indexed owner, address indexed spender, uint256 value); |
||||
} |
||||
|
||||
@ -1,18 +1,35 @@ |
||||
--- |
||||
sections: |
||||
- title: Interfaces |
||||
- title: Core |
||||
contracts: |
||||
- IERC20 |
||||
- title: Contracts |
||||
contracts: |
||||
- ERC20 |
||||
- ERC20Detailed |
||||
- title: Extensions |
||||
contracts: |
||||
- ERC20Mintable |
||||
- ERC20Burnable |
||||
- ERC20Capped |
||||
- ERC20Pausable |
||||
- ERC20Capped |
||||
- title: Utilities |
||||
contracts: |
||||
- SafeERC20 |
||||
- TokenTimelock |
||||
--- |
||||
|
||||
This set of interfaces, contracts, and utilities are all related to the [ERC20 Token Standard](https://eips.ethereum.org/EIPS/eip-20). |
||||
|
||||
*For a walkthrough on how to create an ERC20 token read our [ERC20 guide](../../tokens.md#constructing-a-nice-erc20-token).* |
||||
|
||||
There a few core contracts that implement the behavior specified in the EIP: `IERC20`, `ERC20`, `ERC20Detailed`. |
||||
|
||||
Additionally there are multiple extensions, including: |
||||
- designation of addresses that can create token supply (`ERC20Mintable`), with an optional maximum cap (`ERC20Capped`), |
||||
- destruction of own tokens (`ERC20Burnable`), |
||||
- designation of addresses that can pause token operations for all users (`ERC20Pausable`). |
||||
|
||||
Finally, there are some utilities to interact with ERC20 contracts in various ways. |
||||
- `SafeERC20` is a wrapper around the interface that eliminates the need to handle boolean return values. |
||||
- `TokenTimelock` can hold tokens for a beneficiary until a specified time. |
||||
|
||||
> This page is incomplete. We're working to improve it for the next release. Stay tuned! |
||||
|
||||
@ -0,0 +1,37 @@ |
||||
--- |
||||
sections: |
||||
- title: Core |
||||
contracts: |
||||
- IERC721 |
||||
- ERC721 |
||||
- IERC721Metadata |
||||
- ERC721Metadata |
||||
- ERC721Enumerable |
||||
- IERC721Enumerable |
||||
- IERC721Full |
||||
- ERC721Full |
||||
- IERC721Receiver |
||||
- title: Extensions |
||||
contracts: |
||||
- ERC721Mintable |
||||
- ERC721MetadataMintable |
||||
- ERC721Burnable |
||||
- ERC721Pausable |
||||
- title: Convenience |
||||
contracts: |
||||
- ERC721Holder |
||||
--- |
||||
|
||||
This set of interfaces, contracts, and utilities are all related to the [ERC721 Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721). |
||||
|
||||
*For a walkthrough on how to create an ERC721 token read our [ERC721 guide](../../tokens.md#erc721).* |
||||
|
||||
The EIP consists of three interfaces, found here as `IERC721`, |
||||
`IERC721Metadata`, and `IERC721Enumerable`. Only the first one is required in a |
||||
contract to be ERC721 compliant. Each interface is implemented separately in |
||||
`ERC721`, `ERC721Metadata`, and `ERC721Enumerable`. You can choose the subset |
||||
of functionality you would like to support in your token by combining the |
||||
desired subset through inheritance. The fully featured token implementing all |
||||
three interfaces is prepackaged as `ERC721Full`. |
||||
|
||||
> This page is incomplete. We're working to improve it for the next release. Stay tuned! |
||||
@ -0,0 +1,17 @@ |
||||
--- |
||||
sections: |
||||
- title: Core |
||||
contracts: |
||||
- IERC777 |
||||
- ERC777 |
||||
- title: Hooks |
||||
contracts: |
||||
- IERC777Sender |
||||
- IERC777Recipient |
||||
--- |
||||
|
||||
This set of interfaces and contracts are all related to the [ERC777 token standard](https://eips.ethereum.org/EIPS/eip-777). |
||||
|
||||
The token behavior itself is implemented in the core contracts: `IERC777`, `ERC777`. |
||||
|
||||
Additionally there are interfaces used to develop contracts that react to token movements: `IERC777Sender`, `IERC777Recipient`. |
||||
@ -0,0 +1,11 @@ |
||||
--- |
||||
title: Utilities |
||||
sections: |
||||
- title: Contracts |
||||
contracts: |
||||
- Address |
||||
- Arrays |
||||
- ReentrancyGuard |
||||
--- |
||||
|
||||
Miscellaneous contracts containing utility functions, often related to working with different data types. |
||||
@ -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. |
||||
@ -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. |
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in new issue