Skip to content
This repository was archived by the owner on Jan 24, 2022. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ original_id: advanced
We expand on several advanced topics for the more intrepid users of ZeppelinOS.

## Deploying to mainnet
The [Building upgradeable applications](building.md) guide explains how to
The [Building upgradeable applications](building.html) guide explains how to
deploy an application to a local network, which is very good for testing.
Once you are happy with your initial contracts, you can deploy them to mainnet
using the `--network` flag.
Expand Down Expand Up @@ -63,14 +63,14 @@ transparent for your users.
## The proxy system
The upgradeability system in ZeppelinOS is based on a proxy system: for each deployed contract implementation (the _logic contract_), another, user-facing contract is deployed as well (the _proxy_). The proxy will be the one in charge of the contract's storage, but will forward all function calls to the backing logic contract. The only exception to this are calls made by the owner of the proxy for administrative purposes, which will be handled by the proxy itself.

The way the proxy forwards calls to the logic contract relies on [`delegatecall`](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7.md), the mechanism the EVM provides to execute foreign code on local storage. This is normally used for libraries such as [`SafeMath`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol), which provide useful functionality but have no storage. ZeppelinOS, however, exploits this mechanism to provide upgradeability: a user only interacts with the proxy, and, when a new logic contract is available, the proxy owner simply points it to the upgraded contract. All of this is achieved in a way that is transparent for the user, as the proxy address is always the same.
The way the proxy forwards calls to the logic contract relies on [`delegatecall`](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7.html), the mechanism the EVM provides to execute foreign code on local storage. This is normally used for libraries such as [`SafeMath`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol), which provide useful functionality but have no storage. ZeppelinOS, however, exploits this mechanism to provide upgradeability: a user only interacts with the proxy, and, when a new logic contract is available, the proxy owner simply points it to the upgraded contract. All of this is achieved in a way that is transparent for the user, as the proxy address is always the same.

If you want to find out more about different possible proxy patterns, be sure to check [this post](https://blog.zeppelinos.org/proxy-patterns/).



## Preserving the storage structure
As mentioned in the [Building upgradeable applications](building.md) guide, when upgrading your contracts, you need to make sure that all variables declared in prior versions are kept in the code. New variables must be declared below the previously existing ones, as such:
As mentioned in the [Building upgradeable applications](building.html) guide, when upgrading your contracts, you need to make sure that all variables declared in prior versions are kept in the code. New variables must be declared below the previously existing ones, as such:

```sol
contract MyContract_v1 {
Expand All @@ -88,7 +88,7 @@ Note that this must be so _even if you no longer use the variables_. There is no
This restriction is due to how [Solidity uses the storage space](https://solidity.readthedocs.io/en/v0.4.21/miscellaneous.html#layout-of-state-variables-in-storage). In short, the variables are allocated storage space in the order they appear (for the whole variable or some pointer to the actual storage slot, in the case of dynamically sized variables). When we upgrade a contract, its storage contents are preserved. This entails that if we remove variables, the new ones will be assigned storage space that is already occupied by the old variables.

## Initializers vs. constructors
As we saw in the [Building upgradeable applications](building.md) guide, we did not include a constructor in our contracts, but used instead an `initialize` function. The reason for this is that constructors do not work as regular functions: they are invoked once upon a contract's creation, but their code is never stored in the blockchain. This means that they cannot be called from the contract's proxy as we call other functions. Thus, if we want to initialize variables in the _proxy's storage_, we need to include a regular function for doing so.
As we saw in the [Building upgradeable applications](building.html) guide, we did not include a constructor in our contracts, but used instead an `initialize` function. The reason for this is that constructors do not work as regular functions: they are invoked once upon a contract's creation, but their code is never stored in the blockchain. This means that they cannot be called from the contract's proxy as we call other functions. Thus, if we want to initialize variables in the _proxy's storage_, we need to include a regular function for doing so.

The ZeppelinOS CLI provides a way for calling this function and passing it the necessary arguments when creating the proxy:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@ original_id: apis

You can find the API reference for the CLI and the Library here:

- [`zos` command reference](climain.md)
- [`zos` command reference](climain.html)
- `zos-lib` is a low-level library to develop, deploy and operate upgradeable smart contracts on Ethereum and every other EVM and eWASM-powered blockchain. Please follow the links in the sidebar to learn more about the available contracts.
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Building an upgradeable app
original_id: building
---

After installing `zos` and setting up your ZeppelinOS project as described in the [setup](setup.md) guide, you are now ready to create your upgradeable application.
After installing `zos` and setting up your ZeppelinOS project as described in the [setup](setup.html) guide, you are now ready to create your upgradeable application.

Let's start by installing the [ZeppelinOS lib](https://github.com/zeppelinos/zos-lib), which you will need to make your contract code upgradeable.

Expand Down Expand Up @@ -67,7 +67,7 @@ After these simple steps, your upgradeable application is now on-chain! Congratu

If, at a later stage, you want to upgrade your smart contract code in order to fix a bug or add a new feature, you can do it seamlessly using ZeppelinOS. Remember not to restart your development node, or you will lose your previous deployment!

> **Note**: while ZeppelinOS supports arbitrary changes in functionality, you will need to preserve all variables that appear in prior versions of your contracts, declaring any new variables below the already existing ones. You can find more details in the [advanced topics](advanced.md) page.
> **Note**: while ZeppelinOS supports arbitrary changes in functionality, you will need to preserve all variables that appear in prior versions of your contracts, declaring any new variables below the already existing ones. You can find more details in the [advanced topics](advanced.html) page.

Open `MyContract.sol` again, and add a new function:
```js
Expand Down Expand Up @@ -111,4 +111,4 @@ truffle(local)> myContract.x()
43
```

In order to learn how to use the ZeppelinOS standard libraries in an upgradeable app, please follow the [next guide](using.md).
In order to learn how to use the ZeppelinOS standard libraries in an upgradeable app, please follow the [next guide](using.html).
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ original_id: crafty

Have you ever wondered what may happen if you combined an Aragon token and fire? A fire-spewing eagle? Burnt chicken? What if Augur's oracles were augmented with Decentraland's tiles, would they start predicting the real estate market? Now, you no longer need to ponder at these vital questions: the Ethereum community will answer them for you!

In [Crafty](https://crafty.zeppelin.solutions), users can create new ERC20 tokens, with a few added goodies (following [EIP-1046](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1046.md)): a picture, and a short description. This allows for each token to have that extra bit of personality that makes something unique. But that's not all: the only way to get these tokens is by crafting them, which requires ingredients (any ERC20!) to be spent. And since the craftable tokens themselves can also be used as ingredients, the posibilities are endless! Not only that, but we'll make all of our contracts upgradeable, to be able to change the code in the future. Wohoo!
In [Crafty](https://crafty.zeppelin.solutions), users can create new ERC20 tokens, with a few added goodies (following [EIP-1046](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1046.html)): a picture, and a short description. This allows for each token to have that extra bit of personality that makes something unique. But that's not all: the only way to get these tokens is by crafting them, which requires ingredients (any ERC20!) to be spent. And since the craftable tokens themselves can also be used as ingredients, the posibilities are endless! Not only that, but we'll make all of our contracts upgradeable, to be able to change the code in the future. Wohoo!

## Project setup

Expand All @@ -16,7 +16,7 @@ This guide will show you the process of making the contracts in the Crafty game
npm install --global zos
```

See [here](setup.md) for more detailed setup info.
See [here](setup.html) for more detailed setup info.

All snippets here were extracted from the public [Crafty repository](https://github.com/zeppelinos/crafty).

Expand Down Expand Up @@ -114,7 +114,7 @@ The returned value is the address of the newly created `Crafty` upgradeable inst
This scenario is a bit more complex, since multiple ZeppelinOS contracts are being combined together, but it is nonetheless fairly easy to setup. Let's first recap what a `CraftableToken` is:

1. It is detailed ERC20 token (i.e. has name and symbol)
1. It supports the [EIP-1046](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1046.md) extension of the ERC20 standard (i.e. we'll add a `tokenURI` parameter and variable)
1. It supports the [EIP-1046](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1046.html) extension of the ERC20 standard (i.e. we'll add a `tokenURI` parameter and variable)
1. It is mintable
1. It has additional storage of the token's ingredients, which require some validation

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: zos-lib quickstart
original_id: libstart
---

> **Note**: this section describes a low-level method for using ZeppelinOS. To follow the recommended development experience, use the [higher-level CLI guide](setup.md).
> **Note**: this section describes a low-level method for using ZeppelinOS. To follow the recommended development experience, use the [higher-level CLI guide](setup.html).


`zos-lib` is a library to develop, deploy and operate upgradeable smart contracts on Ethereum and every other EVM and eWASM-powered blockchain.
Expand All @@ -19,5 +19,5 @@ npm install zos-lib
```

Next, learn how to:
- [Programmatically develop and deploy a single upgradeable smart contract](low_level_contract.md) (for fixing bugs or adding new features)
- [Programmatically develop and operate a complex upgradeable app](low_level_app.md) with multiple smart contracts which are connected to the [ZeppelinOS upgradeable standard library](stdlib.md)
- [Programmatically develop and deploy a single upgradeable smart contract](low_level_contract.html) (for fixing bugs or adding new features)
- [Programmatically develop and operate a complex upgradeable app](low_level_app.html) with multiple smart contracts which are connected to the [ZeppelinOS upgradeable standard library](stdlib.html)
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Low level upgradable app
original_id: low_level_app
---

> **Note**: this guide shows a low-level method for operating a complex upgradeable decentralized application. For a CLI-aided developer experience, use the [higher-level CLI guide](setup.md).
> **Note**: this guide shows a low-level method for operating a complex upgradeable decentralized application. For a CLI-aided developer experience, use the [higher-level CLI guide](setup.html).

> **Note**: for a fully working project with this example, see the [`examples/complex`](https://github.com/zeppelinos/zos-lib/tree/master/examples/complex) folder of the `zos-lib` repository.

Expand Down Expand Up @@ -79,7 +79,7 @@ Remember that the proxy is the contract that will receive the calls and hold the

Now let's suppose we want to give some sort of retribution to the donors, so we mint new [ERC721](http://erc721.org/) cryptocollectibles for each donation.

In order to do this, we link the [ZeppelinOS standard library](stdlib.md) to our application by running:
In order to do this, we link the [ZeppelinOS standard library](stdlib.html) to our application by running:

```sh
npm install openzeppelin-zos
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ sidebar_label: Low level upgradeable contract
original_id: low_level_contract
---

> **Note**: this guide shows a low-level method for operating a single upgradeable smart contract. For a CLI-aided developer experience, use the [higher-level CLI guide](setup.md).
> **Note**: this guide shows a low-level method for operating a single upgradeable smart contract. For a CLI-aided developer experience, use the [higher-level CLI guide](setup.html).

> **Note**: for a fully working project with this example, see the [`examples/simple`](https://github.com/zeppelinos/zos-lib/tree/master/examples/simple) folder of the `zos-lib` repository.

To develop an upgradeable smart contract, we need to create a simple [upgradeability proxy](https://blog.zeppelinos.org/proxy-patterns/). This is a [special contract](proxies.md) that will hold the storage of our upgradeable contract and redirect function calls to a `logic` contract, which we can update.
To develop an upgradeable smart contract, we need to create a simple [upgradeability proxy](https://blog.zeppelinos.org/proxy-patterns/). This is a [special contract](proxies.html) that will hold the storage of our upgradeable contract and redirect function calls to a `logic` contract, which we can update.

Let's walk through the following example to see how it works:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@ zos init my-app

This creates a `zos.json` file, which contains all the information about your application. For details about this file format, please see the [advanced topics](advanced.md#format-of-zosjson-and-zos-network-json-files) section.

You are now ready to [start building your upgradable application](building.md).
You are now ready to [start building your upgradable application](building.html).
10 changes: 5 additions & 5 deletions packages/docs/docs/website/versioned_docs/version-1.0.0/start.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,18 @@ ZeppelinOS is a platform to develop, deploy and operate upgradeable smart contra

## Getting Started

Install ZeppelinOS and setup your project as described in the [Setup guide](setup.md).
Install ZeppelinOS and setup your project as described in the [Setup guide](setup.html).

In order to build an upgradeable application with ZeppelinOS, follow our
[Building upgradeable applications](building.md) guide.
[Building upgradeable applications](building.html) guide.

If you would like to use the ZeppelinOS on-chain standard libraries in your app,
follow our [Using the stdlib in your app](using.md) guide.
follow our [Using the stdlib in your app](using.html) guide.

If you are interested in deploying your own standard libraries for ZeppelinOS,
see our [Developing a new standard library](developing.md) guide.
see our [Developing a new standard library](developing.html) guide.

Two demo apps based on ZeppelinOS are described in [Basil](basil.md) and [Crafty](crafty.md).
Two demo apps based on ZeppelinOS are described in [Basil](basil.html) and [Crafty](crafty.html).

## Security

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ original_id: using

Besides allowing you to build upgradeable applications, ZeppelinOS provides on-chain standard libraries that you can use in your app.

To use an stdlib in your contracts, you will need to set up a `zos` project as described in the [Setup](setup.md) guide. Then, you need to run the `link` command with the name of the npm package of the stdlib you want to use. For example:
To use an stdlib in your contracts, you will need to set up a `zos` project as described in the [Setup](setup.html) guide. Then, you need to run the `link` command with the name of the npm package of the stdlib you want to use. For example:

```sh
zos link openzeppelin-zos
```

`openzeppelin-zos` is [a ZeppelinOS standard library provided by the OpenZeppelin community](stdlib.md), in which you can find many useful contracts. You can now include contracts from the stdlib in your app:
`openzeppelin-zos` is [a ZeppelinOS standard library provided by the OpenZeppelin community](stdlib.html), in which you can find many useful contracts. You can now include contracts from the stdlib in your app:

```sol
import "openzeppelin-zos/contracts/token/ERC721/MintableERC721Token.sol";
Expand Down Expand Up @@ -65,4 +65,4 @@ truffle(local)> MyContract.at(<myContractAddress>).setToken(<tokenAddress>)

Remember that the addresses of both your contract and the token can be found in the `zos.local.json` network configuration file.

This completes the setup and deployment of an upgradable application that uses an stdlib provided by ZeppelinOS. If you would like to contribute your own stdlib to ZeppelinOS, please see the [Developing a new standard library](developing.md) guide.
This completes the setup and deployment of an upgradable application that uses an stdlib provided by ZeppelinOS. If you would like to contribute your own stdlib to ZeppelinOS, please see the [Developing a new standard library](developing.html) guide.
Loading