NoBey/openzeppelin-contracts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Santiago Palladino
2019-07-19 18:46:02 -03:00
committed by GitHub
parent 64cf73d646
commit dee9a2b897
1 changed files with 41 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
README.md
View File

@ -1,24 +1,24 @@
# <img src="logo.png" alt="OpenZeppelin" width="400px"> # <img src="logo.png" alt="OpenZeppelin" width="400px">
# OpenZeppelin EVM Package # OpenZeppelin Contracts Ethereum Package
[![NPM Package](https://img.shields.io/npm/v/openzeppelin-eth.svg?style=flat-square)](https://www.npmjs.org/package/openzeppelin-eth) [![NPM Package](https://img.shields.io/npm/v/openzeppelin-contracts-ethereum-package.svg?style=flat-square)](https://www.npmjs.org/package/@openzeppelin/contracts-ethereum-package)
[![Build Status](https://img.shields.io/travis/OpenZeppelin/openzeppelin-eth.svg?branch=master&style=flat-square)](https://travis-ci.org/OpenZeppelin/openzeppelin-eth) [![Build Status](https://img.shields.io/travis/OpenZeppelin/openzeppelin-contracts-ethereum-package.svg?branch=master&style=flat-square)](https://travis-ci.org/OpenZeppelin/openzeppelin-contracts-ethereum-package)
**OpenZeppelin is a library for secure smart contract development.** It provides implementations of standards like ERC20 and ERC721 which you can deploy as-is or extend to suit your needs, as well as Solidity components to build custom contracts and more complex decentralized systems. **OpenZeppelin Contracts is a library for secure smart contract development.** It provides implementations of standards like ERC20 and ERC721 which you can deploy as-is or extend to suit your needs, as well as Solidity components to build custom contracts and more complex decentralized systems.
This fork of OpenZeppelin is set up as a **reusable EVM Package**. It is deployed to the kovan, rinkeby, and ropsten test networks, as well as to the main Ethereum network. You can reuse any of the pre-deployed on-chain contracts by simply linking to them using [ZeppelinOS](https://github.com/zeppelinos/zos), or reuse their Solidity source code as with the [vanilla version of OpenZeppelin](https://github.com/openZeppelin/Openzeppelin-solidity). This fork of OpenZeppelin is set up as a **reusable Ethereum Package**. It is deployed to the kovan, rinkeby, and ropsten test networks, as well as to the main Ethereum network. You can reuse any of the pre-deployed on-chain contracts by simply linking to them using the [OpenZeppelin SDK](https://github.com/openzeppelin/openzeppelin-sdk), or reuse their Solidity source code as with the [vanilla version of OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts).
## Differences with OpenZeppelin-Solidity ## Differences with openzeppelin-contracts
This package contains the same contracts as the vanilla [OpenZeppelin-Solidity](https://github.com/openZeppelin/Openzeppelin-solidity). The main difference is that _all contracts in this package are potentially upgradeable_: you will notice that no contracts have constructors defined, but use [initializer functions](https://docs.zeppelinos.org/docs/writing_contracts.html#initializers) instead. Also, this package is set up as an EVM package, and provides a small set of pre-deployed logic contracts that can be used directly via ZeppelinOS, without needing to deploy them again. This package contains the same contracts as the vanilla [openzeppelin-contracts](https://github.com/openZeppelin/openzeppelin-contracts). The main difference is that _all contracts in this package are potentially upgradeable_: you will notice that no contracts have constructors defined, but use [initializer functions](https://docs.zeppelinos.org/docs/writing_contracts.html#initializers) instead. Also, this package is set up as an Ethereum package, and provides a small set of pre-deployed logic contracts that can be used directly via the OpenZeppelin SDK, without needing to deploy them again.
All in all, **you should use this package instead of openzeppelin-solidity if you are managing your project via ZeppelinOS**. All in all, **you should use this package instead of openzeppelin-solidity if you are managing your project via the OpenZeppelin CLI**.
## Install ## Install
``` ```
npm install openzeppelin-eth npm install @openzeppelin/contracts-ethereum-package
``` ```
## Deployed logic contracts ## Deployed logic contracts
@ -28,61 +28,53 @@ npm install openzeppelin-eth
- [TokenVesting](contracts/drafts/TokenVesting.sol): tToken holder contract that can release its token balance gradually like a typical vesting scheme, with a cliff and vesting period, optionally revocable. - [TokenVesting](contracts/drafts/TokenVesting.sol): tToken holder contract that can release its token balance gradually like a typical vesting scheme, with a cliff and vesting period, optionally revocable.
- [PaymentSplitter](contracts/payment/PaymentSplitter.sol): Splits payments among a group of addresses proportionately to some number of shares they own. - [PaymentSplitter](contracts/payment/PaymentSplitter.sol): Splits payments among a group of addresses proportionately to some number of shares they own.
## Using via ZeppelinOS ## Using via the OpenZeppelin CLI
You can easily create upgradeable instances of any of the logic contracts listed above using ZeppelinOS. This will rely on the pre-deployed instances in mainnet, kovan, ropsten, or rinkeby, greatly reducing your gas deployment costs. To do this, just [create a new ZeppelinOS project](https://docs.zeppelinos.org/docs/deploying.html) and [link to this package](https://docs.zeppelinos.org/docs/linking.html). You can easily create upgradeable instances of any of the logic contracts listed above using the OpenZeppelin CLI. This will rely on the pre-deployed instances in mainnet, kovan, ropsten, or rinkeby, greatly reducing your gas deployment costs. To do this, just [create a new OpenZeppelin SDK project](https://docs.zeppelinos.org/docs/deploying.html) and [link to this package](https://docs.zeppelinos.org/docs/linking.html).
```bash ```bash
$ npm install -g zos $ npm install -g @openzeppelin/cli
$ zos init YourProject $ openzeppelin init
$ zos link openzeppelin-eth $ openzeppelin link @openzeppelin/contracts-ethereum-package
> Installing openzeppelin-eth > Installing...
$ zos push --network rinkeby $ openzeppelin create @openzeppelin/contracts-ethereum-package/StandaloneERC20
> Connecting to dependency openzeppelin-eth > Creating...
``` ```
> In case you are working in a private or development network where openzeppelin-eth has not been pre-deployed (such as ganache), you need to instruct ZeppelinOS to deploy the package there with an additional flag: `zos push --deploy-dependencies --network local`. To create an instance of a contract, use the `openzeppelin create` command. As an example, you can run the following to create an upgradeable ERC20 named MyToken, with symbol TKN and 8 decimals, and an initial supply of 100 tokens assigned to the address HOLDER, with a MINTER and a PAUSER. Remember to replace $HOLDER, $MINTER, and $PAUSER with actual addresses when you run this command; you can specify more than one (or none at all) minters and pausers.
To create an instance of a contract, use the `zos create` command. As an example, you can run the following to create an upgradeable ERC20 named MyToken, with symbol TKN and 8 decimals, and an initial supply of 100 tokens assigned to the address HOLDER, with a MINTER and a PAUSER. Remember to replace $HOLDER, $MINTER, and $PAUSER with actual addresses when you run this command; you can specify more than one (or none at all) minters and pausers.
``` ```
$ zos create openzeppelin-eth/StandaloneERC20 --init --args="MyToken,TKN,8,10000000000,$HOLDER,[$MINTER],[$PAUSER]" --network rinkeby $ openzeppelin create
> Creating proxy to logic contract and initializing by calling initialize with: ? Pick a contract to instantiate: @openzeppelin/contracts-ethereum-package/StandaloneERC20
- name (string): "MyToken" ? Pick a network: development
- symbol (string): "TKN" ✓ Deploying @openzeppelin/contracts-ethereum-package dependency to network
- decimals (uint8): "8" ? Do you want to call a function on the instance after creating it?: Yes
- initialSupply (uint256): "10000000000" ? Select which function: * initialize(name: string, symbol: string, decimals: uint8, initialSupply: uint256, initialHolder: address, minters: address[], pausers: address[])
- initialHolder (address): "$HOLDER" ? name (string): MyToken
- minters (address[]): ["$MINTER"] ? symbol (string): MYT
- pausers (address[]): ["$PAUSER"] ? decimals (uint8): 18
Instance created at 0x... ? initialSupply (uint256): 100e18
? initialHolder (address): 0x90f8bf6a479f320ead074411a4b0e7944ea8c9c1
? minters (address[]):
? pausers (address[]):
✓ Setting everything up to create contract instances
✓ Instance created at 0x2612Af3A521c2df9EAF28422Ca335b04AdF3ac66
``` ```
ZeppelinOS will create an upgradeable ERC20 instance and keep track of its address in the `zos.rinkeby.json` file. Should you update your version of openzeppelin-eth later down the road, you can simply run `zos update openzeppelin-eth/StandaloneERC20` to upgrade all your ERC20 instances to the latest version. OpenZeppelin will create an upgradeable ERC20 instance and keep track of its address in the `.openzeppelin/rinkeby.json` file. Should you update your version of the openzeppelin contracts ethereum package later down the road, you can simply run `openzeppelin update` to upgrade all your ERC20 instances to the latest version.
If you want to deploy an ERC721 non-fungible token instead, you can use the following command. You can also deploy a ERC721 token by choosing the `StandaloneERC721` contract when running `openzeppelin create`. Refer to the `initialize` function of each of the predeployed logic contracts to see which parameters are required for initialization.
```
$ zos create openzeppelin-eth/StandaloneERC721 --init --args="MyToken,TKN,[$MINTER],[$PAUSER]" --network rinkeby
> Creating proxy to logic contract and initializing by calling initialize with:
- name (string): "MyToken"
- symbol (string): "TKN"
- minters (address[]): ["$MINTER"]
- pausers (address[]): ["$PAUSER"]
Instance created at 0x...
```
Refer to the `initialize` function of each of the predeployed logic contracts to see which parameters are required for initialization.
## Extending contracts ## Extending contracts
If you prefer to write your custom contracts, import the ones from `openzeppelin-eth` and extend them through inheritance. Note that **you must use this package and not `openzeppelin-solidity` if you are [writing upgradeable contracts](https://docs.zeppelinos.org/docs/writing_contracts.html)**. If you prefer to write your custom contracts, import the ones from this package and extend them through inheritance. Note that **you must use this package and not `@openzeppelin/contracts` if you are [writing upgradeable contracts](https://docs.zeppelinos.org/docs/writing_contracts.html)**.
```solidity ```solidity
pragma solidity ^0.5.0; pragma solidity ^0.5.0;
import 'zos-lib/contracts/Initializable.sol'; import '@openzeppelin/upgrades/contracts/Initializable.sol';
import 'openzeppelin-eth/contracts/token/ERC721/ERC721Full.sol'; import '@openzeppelin/contracts-ethereum-package/contracts/token/ERC721/ERC721Full.sol';
import 'openzeppelin-eth/contracts/token/ERC721/ERC721Mintable.sol'; import '@openzeppelin/contracts-ethereum-package/contracts/token/ERC721/ERC721Mintable.sol';
contract MyNFT is Initializable, ERC721Full, ERC721Mintable { contract MyNFT is Initializable, ERC721Full, ERC721Mintable {
function initialize() public initializer { function initialize() public initializer {
@ -94,15 +86,13 @@ contract MyNFT is Initializable, ERC721Full, ERC721Mintable {
} }
``` ```
> You need an ethereum development framework for the above import statements to work! Check out these guides for [Truffle] or [Embark].
On our site you will find a few [guides] to learn about the different parts of OpenZeppelin, as well as [documentation for the API][API docs]. Keep in mind that the API docs are work in progress, and don’t hesitate to ask questions in [our forum][forum]. On our site you will find a few [guides] to learn about the different parts of OpenZeppelin, as well as [documentation for the API][API docs]. Keep in mind that the API docs are work in progress, and don’t hesitate to ask questions in [our forum][forum].
## Security ## Security
OpenZeppelin the project is maintained by [Zeppelin] the company, and developed following our high standards for code quality and security. OpenZeppelin 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. OpenZeppelin Contracts is maintained by [OpenZeppelin](https://openzeppelin.com) the company, 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.
The core development principles and strategies that OpenZeppelin 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 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 latest audit was done on October 2018 on version 2.0.0. The latest audit was done on October 2018 on version 2.0.0.
@ -119,7 +109,4 @@ OpenZeppelin is released under the [MIT License](LICENSE).
[API docs]: https://docs.openzeppelin.org/v2.3.0/api/token/erc20 [API docs]: https://docs.openzeppelin.org/v2.3.0/api/token/erc20
[guides]: https://docs.openzeppelin.org/v2.3.0/get-started [guides]: https://docs.openzeppelin.org/v2.3.0/get-started
[forum]: https://forum.zeppelin.solutions [forum]: https://forum.zeppelin.solutions
[Zeppelin]: https://zeppelin.solutions
[contribution guide]: CONTRIBUTING.md [contribution guide]: CONTRIBUTING.md
[Truffle]: https://truffleframework.com/docs/truffle/quickstart
[Embark]: https://embark.status.im/docs/quick_start.html