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

Merge pull request #48 from OpenZeppelin/docs/update-readme

Browse Source 
Add more usage instructions to README
This commit is contained in:
Francisco Giordano
2019-02-13 12:22:16 -03:00
committed by GitHub
parent 6bf2ae8229 3dbf651b8e
commit f18fd17355
1 changed files with 62 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
README.md
View File

@ -7,7 +7,13 @@
**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.
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.
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).
## Differences with OpenZeppelin-Solidity
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.
All in all, **you should use this package instead of openzeppelin-solidity if you are managing your project via ZeppelinOS**.
## Install
@ -15,9 +21,61 @@ This fork of OpenZeppelin is set up as a **reusable EVM Package**. It is deploye
npm install openzeppelin-eth
```
## Usage
## Deployed logic contracts
To write your custom contracts, import ours and extend them through inheritance.
- [StandaloneERC20](contracts/token/ERC20/StandaloneERC20.sol): ERC20 token implementation, optionally mintable and pausable.
- [StandaloneERC721](contracts/token/ERC721/StandaloneERC721.sol): ERC721 non-fungible token implementation with metadata and enumerable extensions, optionally mintable and pausable.
- [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.
## Using via ZeppelinOS
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).
```bash
$ npm install -g zos
$ zos init YourProject
$ zos link openzeppelin-eth
> Installing openzeppelin-eth
$ zos push --network rinkeby
> Connecting to dependency openzeppelin-eth
```
> 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 `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
> Creating proxy to logic contract and initializing by calling initialize with:
- name (string): "MyToken"
- symbol (string): "TKN"
- decimals (uint8): "8"
- initialSupply (uint256): "10000000000"
- initialHolder (address): "$HOLDER"
- minters (address[]): ["$MINTER"]
- pausers (address[]): ["$PAUSER"]
Instance created at 0x...
```
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.
If you want to deploy an ERC721 non-fungible token instead, you can use the following command.
```
$ 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
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)**.
```solidity
pragma solidity ^0.5.0;
@ -36,16 +94,6 @@ contract MyNFT is Initializable, ERC721Full, ERC721Mintable {
}
```
## Pre-deployed contracts
- StandaloneERC20
- StandaloneERC721
- TokenVesting
- PaymentSplitter
## License
OpenZeppelin is released under the [MIT License](LICENSE).
[Slack]: https://slack.openzeppelin.org
[Zeppelin]: https://zeppelin.solutions
OpenZeppelin is released under the [MIT License](LICENSE).