From d92f36929703c9b8078f54dec0b0e6ada962de4a Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:07:37 -0300 Subject: [PATCH 1/7] fix deploying and interacting --- packages/cli/docs/modules/ROOT/pages/dependencies.adoc | 2 +- .../cli/docs/modules/ROOT/pages/deploying-with-create2.adoc | 2 +- packages/cli/docs/modules/ROOT/pages/getting-started.adoc | 2 +- .../modules/ROOT/pages/creating-upgradeable-from-solidity.adoc | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/docs/modules/ROOT/pages/dependencies.adoc b/packages/cli/docs/modules/ROOT/pages/dependencies.adoc index 1adddf756..859156594 100644 --- a/packages/cli/docs/modules/ROOT/pages/dependencies.adoc +++ b/packages/cli/docs/modules/ROOT/pages/dependencies.adoc @@ -40,7 +40,7 @@ NOTE: Make sure you install `@openzeppelin/contracts-ethereum-package` and not t [[creating-an-erc20-token]] == Creating an ERC20 Token -Let's deploy an ERC20 token contract to our development network. Make sure to xref:learn::deploy-and-interact.adoc#local-blockchain[have a Ganache instance running], or start one by running: +Let's deploy an ERC20 token contract to our development network. Make sure to xref:learn::deploying-and-interacting.adoc#local-blockchain[have a Ganache instance running], or start one by running: [source,console] ---- diff --git a/packages/cli/docs/modules/ROOT/pages/deploying-with-create2.adoc b/packages/cli/docs/modules/ROOT/pages/deploying-with-create2.adoc index c0f7644fe..0682aa231 100644 --- a/packages/cli/docs/modules/ROOT/pages/deploying-with-create2.adoc +++ b/packages/cli/docs/modules/ROOT/pages/deploying-with-create2.adoc @@ -8,7 +8,7 @@ In this guide we will precompute the address where a contract will be deployed a ==== This guide features advanced usage of OpenZeppelin tools, and requires familiarity with Solidity, development blockchains and the OpenZeppelin CLI. -For a refresher on the topics, head to xref:learn::deploy-and-interact.adoc[Deploying and Interacting With Smart Contracts]. +For a refresher on the topics, head to xref:learn::deploying-and-interacting.adoc[Deploying and Interacting With Smart Contracts]. ==== == Creating a Smart Contract diff --git a/packages/cli/docs/modules/ROOT/pages/getting-started.adoc b/packages/cli/docs/modules/ROOT/pages/getting-started.adoc index 369b6b913..9c3988203 100644 --- a/packages/cli/docs/modules/ROOT/pages/getting-started.adoc +++ b/packages/cli/docs/modules/ROOT/pages/getting-started.adoc @@ -72,7 +72,7 @@ We will use https://truffleframework.com/ganache[Ganache] as a _development netw Development networks are mini blockchains that run just on your computer, and are much faster than the actual Ethereum network. We will use one for coding and testing. -TIP: Head to xref:learn::deploy-and-interact.adoc#local-blockchain[Setting up a Local Blockchain] to learn more about using Ganache. +TIP: Head to xref:learn::deploying-and-interacting.adoc#local-blockchain[Setting up a Local Blockchain] to learn more about using Ganache. Open a separate terminal and start a new Ganache process: diff --git a/packages/lib/docs/modules/ROOT/pages/creating-upgradeable-from-solidity.adoc b/packages/lib/docs/modules/ROOT/pages/creating-upgradeable-from-solidity.adoc index d0921f0dc..e54d65c05 100644 --- a/packages/lib/docs/modules/ROOT/pages/creating-upgradeable-from-solidity.adoc +++ b/packages/lib/docs/modules/ROOT/pages/creating-upgradeable-from-solidity.adoc @@ -8,7 +8,7 @@ In this guide, we will learn how to create a contract https://en.wikipedia.org/w ==== This guide features advanced usage of OpenZeppelin tools, and requires familiarity with Solidity, development blockchains and the OpenZeppelin CLI. -For a refresher on the topics, head to xref:learn::deploy-and-interact.adoc[Deploying and Interacting With Smart Contracts]. +For a refresher on the topics, head to xref:learn::deploying-and-interacting.adoc[Deploying and Interacting With Smart Contracts]. ==== == Setting Up From d73c1e0ac0dc0e78f6393684f2583406e52cf4f1 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:15:00 -0300 Subject: [PATCH 2/7] fix pattern.adoc --- packages/cli/docs/modules/ROOT/pages/configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/docs/modules/ROOT/pages/configuration.adoc b/packages/cli/docs/modules/ROOT/pages/configuration.adoc index ba54dcbf1..7cc9f24d2 100644 --- a/packages/cli/docs/modules/ROOT/pages/configuration.adoc +++ b/packages/cli/docs/modules/ROOT/pages/configuration.adoc @@ -114,7 +114,7 @@ Any Solidity libraries used by the project's contracts are tracked in the `solid Another thing to notice in these files are the version numbers. The `` keeps track of the latest app version, and matches `` from `project.json`. The ``, on the other hand, keeps track of which version of the contracts the proxies are pointing to. Say you deploy a contract in your app version 1.0.0, and then bump the version to 1.1.0 and push some upgraded code for that same contract. This will be reflected in the ``, but not yet in the proxy, which will display 1.0.0 in `` and the old logic contract address in ``. Once you run `oz update` to your contract, `` will show the new 1.1.0 version, and `` will point to the new ``. Note that this version identifier will refer to the version of the dependency (and not the app) if the proxy points to a dependent Ethereum Package. -The field `` contains the address of the ProxyAdmin contract, used to manage the xref:pattern.adoc#transparent-proxies-and-function-clashes[transparent proxy pattern] in the project's proxies. +The field `` contains the address of the ProxyAdmin contract, used to manage the xref:upgrades::proxies.adoc#transparent-proxies-and-function-clashes[transparent proxy pattern] in the project's proxies. Also, notice the fields ``, ``, and ``. These contain the addresses of contracts the OpenZeppelin CLI uses to facilitate the creation of proxies and the management of different versions of your contracts. These contracts will only be deployed once you `publish` your project to a desired network. That is, your project will not have an `app`, `package`, or `provider` unless explicitly running the `publish` command, or if the project was created with the `--publish` flag. Note that this step is required for projects that produce an Ethereum Package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the xref:architecture.adoc[Contract Architecture] section. From e0107e9d258d76fb66f7a0f2afc0d0a13890b7b0 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:15:09 -0300 Subject: [PATCH 3/7] fix architecture.adoc --- packages/cli/docs/modules/ROOT/pages/configuration.adoc | 2 +- packages/cli/docs/modules/ROOT/pages/faq.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/docs/modules/ROOT/pages/configuration.adoc b/packages/cli/docs/modules/ROOT/pages/configuration.adoc index 7cc9f24d2..5b2120b71 100644 --- a/packages/cli/docs/modules/ROOT/pages/configuration.adoc +++ b/packages/cli/docs/modules/ROOT/pages/configuration.adoc @@ -116,7 +116,7 @@ Another thing to notice in these files are the version numbers. The `` contains the address of the ProxyAdmin contract, used to manage the xref:upgrades::proxies.adoc#transparent-proxies-and-function-clashes[transparent proxy pattern] in the project's proxies. -Also, notice the fields ``, ``, and ``. These contain the addresses of contracts the OpenZeppelin CLI uses to facilitate the creation of proxies and the management of different versions of your contracts. These contracts will only be deployed once you `publish` your project to a desired network. That is, your project will not have an `app`, `package`, or `provider` unless explicitly running the `publish` command, or if the project was created with the `--publish` flag. Note that this step is required for projects that produce an Ethereum Package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the xref:architecture.adoc[Contract Architecture] section. +Also, notice the fields ``, ``, and ``. These contain the addresses of contracts the OpenZeppelin CLI uses to facilitate the creation of proxies and the management of different versions of your contracts. These contracts will only be deployed once you `publish` your project to a desired network. That is, your project will not have an `app`, `package`, or `provider` unless explicitly running the `publish` command, or if the project was created with the `--publish` flag. Note that this step is required for projects that produce an Ethereum Package. To read more about the architecture of contracts we are using to publish your project on-chain please refer to the xref:contracts-architecture.adoc[Contract Architecture] section. Finally, the `dependencies` field stores information about linked Ethereum Packages. For each dependency, the `` tracks the address of the deployed `package` in the network, and `` is the exact semver identifier being used for the dependency. The `custom-deploy` field will be present only when a version of the Ethereum Package is deployed using the `--deploy-dependencies` flag of the `push` command, in which case `` will be `true`. diff --git a/packages/cli/docs/modules/ROOT/pages/faq.adoc b/packages/cli/docs/modules/ROOT/pages/faq.adoc index 9ba454b1c..5d42d1161 100644 --- a/packages/cli/docs/modules/ROOT/pages/faq.adoc +++ b/packages/cli/docs/modules/ROOT/pages/faq.adoc @@ -49,7 +49,7 @@ However, if you are using OpenZeppelin Upgrades programmatically you could poten [[how-can-i-create-an-upgradeable-instance-from-solidity-code]] == How Can I Create an Upgradeable Instance From Solidity Code? -You can create upgradeable instances from Solidity code by using your project's xref:contracts-architecture.adoc#app.sol[`App`] contract, and then calling its `create` function from Solidity. Note that to be able to do this, your project needs to be published, that is, it needs to have the OpenZeppelin xref:architecture.adoc[Contracts Architecture] enabled. +You can create upgradeable instances from Solidity code by using your project's xref:contracts-architecture.adoc#app.sol[`App`] contract, and then calling its `create` function from Solidity. Note that to be able to do this, your project needs to be published, that is, it needs to have the OpenZeppelin xref:contracts-architecture.adoc[Contracts Architecture] enabled. To see an example of how this is done, please refer to the example project https://github.com/OpenZeppelin/openzeppelin-sdk/tree/master/examples/creating-instances-from-solidity[`creating-instances-from-solidity`]. From 67960565b19b0e2fd8f245d9bea53fa41616ae18 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:15:57 -0300 Subject: [PATCH 4/7] fix dependencies.adoc --- packages/cli/docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/docs/modules/ROOT/pages/index.adoc b/packages/cli/docs/modules/ROOT/pages/index.adoc index af17c35cf..6496b4bb3 100644 --- a/packages/cli/docs/modules/ROOT/pages/index.adoc +++ b/packages/cli/docs/modules/ROOT/pages/index.adoc @@ -34,7 +34,7 @@ Below is a short list of the most used commands: == Learn More * Head to xref:getting-started.adoc[Getting Started] to see the CLI in action by deploying and upgrading a smart contract! - * xref:using-dependencies.adoc[Using Dependencies] showcases a more complex project being built, including leveraging the xref:contracts::index.adoc[OpenZeppelin Contracts] library. + * xref:dependencies.adoc[Using Dependencies] showcases a more complex project being built, including leveraging the xref:contracts::index.adoc[OpenZeppelin Contracts] library. * If you are a Truffle user, go to xref:truffle.adoc[Using With Truffle] for information on using both tools on the same project. * Take a look at the API reference for all xref:commands.adoc[CLI commands]. * For an overview of the internals of the CLI, you can read on the xref:contracts-architecture.adoc[Contracts Architecture] and different xref:configuration.adoc[Configuration Files]. From 8aca18e8e29e176e301cd5af569d403fb1b9d881 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:17:03 -0300 Subject: [PATCH 5/7] fix mainnet.adoc --- packages/cli/docs/modules/ROOT/pages/dependencies.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/docs/modules/ROOT/pages/dependencies.adoc b/packages/cli/docs/modules/ROOT/pages/dependencies.adoc index 859156594..cca9f5bfe 100644 --- a/packages/cli/docs/modules/ROOT/pages/dependencies.adoc +++ b/packages/cli/docs/modules/ROOT/pages/dependencies.adoc @@ -207,7 +207,7 @@ Success! We have our exchange up and running, gathering ETH in exchange for our We forgot to add a method to withdraw the funds from the token exchange contract! While this would typically mean that the funds are locked in there forever, we can upgrade the contract with the OpenZeppelin CLI to add a way to collect those funds. -NOTE: While upgrading a contract is certainly useful in situations like this, where you need to fix a bug or add a missing feature, it could still be used to change the rules of the game. For instance, you could upgrade the token exchange contract to alter the rate at any time. Because of this, it is important to have a proper xref:learn::mainnet.adoc#project-governance[Project Governance] in place. +NOTE: While upgrading a contract is certainly useful in situations like this, where you need to fix a bug or add a missing feature, it could still be used to change the rules of the game. For instance, you could upgrade the token exchange contract to alter the rate at any time. Because of this, it is important to have a proper xref:learn::preparing-for-mainnet.adoc#project-governance[Project Governance] in place. Let's modify the `TokenExchange` contract to add a `withdraw` method, only callable by an `owner`. From 936165ab65928b97aa4214fa9aa200b946c5cb00 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:18:30 -0300 Subject: [PATCH 6/7] fix public-staging.adoc --- .../docs/modules/ROOT/pages/publishing-ethereum-package.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc b/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc index 09db5a0e0..63e3265b3 100644 --- a/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc +++ b/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc @@ -9,7 +9,7 @@ In this guide we'll describe how you can create your own Ethereum Package, and m ==== This guide features advanced usage of OpenZeppelin tools, and requires familiarity with using public networks, upgradeable contracts, and the OpenZeppelin CLI. -For a refresher on the topics, head to xref:learn::public-staging.adoc[Deploying to a Public Test Network] and xref:learn::on-upgrades.adoc[Upgrades]. +For a refresher on the topics, head to xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] and xref:learn::on-upgrades.adoc[Upgrades]. ==== == Storing Your Project On-chain @@ -34,7 +34,7 @@ $ npx oz push All contracts have been deployed ---- -NOTE: For your Ethereum Pacakge to be used by others, it needs to be deployed on a real network instead of a local one. Take a look at xref:learn::public-staging.adoc[Deploying to a Public Test Network] for detailed instructions for this process. +NOTE: For your Ethereum Pacakge to be used by others, it needs to be deployed on a real network instead of a local one. Take a look at xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] for detailed instructions for this process. Ethereum Packages are upgradeable, which means they track the different implementation contracts that correspond to each version of the package. We'll use the xref:commands.adoc#publish[`oz publish`] command for this, which will deploy an xref:contracts-architecture.adoc#app.sol[`App`] contract and register the implementations there: From 023f94df08a008f1e37fc833fe2af69dad6ac372 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 27 Mar 2020 18:19:37 -0300 Subject: [PATCH 7/7] fix on-upgrades.adoc --- .../docs/modules/ROOT/pages/publishing-ethereum-package.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc b/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc index 63e3265b3..8005d400a 100644 --- a/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc +++ b/packages/cli/docs/modules/ROOT/pages/publishing-ethereum-package.adoc @@ -9,12 +9,12 @@ In this guide we'll describe how you can create your own Ethereum Package, and m ==== This guide features advanced usage of OpenZeppelin tools, and requires familiarity with using public networks, upgradeable contracts, and the OpenZeppelin CLI. -For a refresher on the topics, head to xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] and xref:learn::on-upgrades.adoc[Upgrades]. +For a refresher on the topics, head to xref:learn::connecting-to-public-test-networks.adoc[Deploying to a Public Test Network] and xref:learn::upgrading-smart-contracts.adoc[Upgrades]. ==== == Storing Your Project On-chain -So far, we've mostly limited ourselves to depoying contracts using xref:commands.adoc#create[`oz deploy`], which creates _upgradeable instances_ by deploying _proxies_ to an existing implementation contract (refer to xref:learn::on-upgrades.adoc#how-upgrades-work[How Upgrades Work] to brush up on this). Here, we will instead deploy just the implementations, so that other people can create new proxies pointing to them. +So far, we've mostly limited ourselves to depoying contracts using xref:commands.adoc#create[`oz deploy`], which creates _upgradeable instances_ by deploying _proxies_ to an existing implementation contract (refer to xref:learn::upgrading-smart-contracts.adoc#how-upgrades-work[How Upgrades Work] to brush up on this). Here, we will instead deploy just the implementations, so that other people can create new proxies pointing to them. To achieve this, we'll use two low-level CLI commands: xref:commands.adoc#add[`oz add`] and xref:commands.adoc#push[`oz push`]. These work simmilarly to `git add` and `git push`: they will register contracts in your project and deploy them to a network.