openzeppelin / openzeppelin-sdk

OpenZeppelin SDK repository for CLI and upgrades.js. No longer actively developed.

OpenZeppelin SDK is not being actively developed. We recommend using Upgrades Plugins instead.

For more information, see Building for interoperability: why we’re focusing on Upgrades Plugins.

OpenZeppelin SDK

Formerly known as ZeppelinOS

OpenZeppelin is a platform to develop, deploy and operate smart contract projects on Ethereum and every other EVM and eWASM-powered blockchain.

This repository includes the OpenZeppelin Command-Line Interface and Upgrades Library.

Install

First, install Node.js and npm. Then, install the OpenZeppelin SDK running:

npm install --global @openzeppelin/cli

If you get an EACCESS permission denied error while installing, please refer to the npm documentation on global installs permission errors. Alternatively, you may run sudo npm install --unsafe-perm --global @openzeppelin/cli, but this is highly discouraged, and you should rather either use a node version manager or manually change npm's default directory.

Usage

We recommend to use the OpenZeppelin SDK through the openzeppelin sdk command-line interface.

To start, create a directory for the project and access it:

mkdir my-project
cd my-project

Use npm to create a package.json file:

npm init

And initialize the OpenZeppelin SDK project:

openzeppelin init my-project

Now it is possible to use openzeppelin deploy to create instances for these contracts that later can be upgraded, and many more things.

Run openzeppelin --help for more details about thes and all the other functions of the OpenZeppelin CLI.

The OpenZeppelin SDK documentation explains how to build a project using our platform, how to upgrade contracts, how to share packages for other projects to reuse, how to vouch for the quality of a package, how to use the JavaScript libraries to operate the project, and it explains details of the platform and some advanced topics.

Security

If you find a security issue, please contact us at [email protected]. We give rewards for reported issues, according to impact and severity.

Maintainers

• @spalladino
• @jcarpanelli
• @ylv-io

Community

Join our Community Forum or community channel on Telegram, where you can talk to all the OpenZeppelin developers, contributors, partners, and users.

You can also follow the recent developments of the project in the OpenZeppelin blog and Twitter account.

Contributing

To set up a local development environment for contributing, clone the repository and run yarn in the root of the project.

Please refer to the contributing guide for more details on how to contribute.

License

MIT © OpenZeppelin

openzeppelin-sdk's Issues

Remove "required" from description of --yes flag in set-admin command

This would have users add the --yes flag automatically, without first understanding the warnings of this command.

Implement Project subclass for lightweight upgrades

Following #59, implement a subclass of Project in zos/lib that creates upgradeable contracts without relying on App, Package, Provider, and Factory. The interface should cover at least:

async createProxy(contractClass, { packageName, contractName, initMethod, initArgs })
async upgradeProxy(proxyAddress, contractClass, { packageName, contractName, initMethod, initArgs })
async changeProxyAdmin(proxyAddress, newAdmin) 

Sample usage:

const Project = require('zos-lib').Project
const project = new Project()
const MyContract = artifacts.require("MyContract")
const myInstance = project.createProxy(MyContract, { initMethod: 'initialize', initArgs: [42] })

Error `replacement transaction underpriced` when deploying multiple contracts via infura

When running a zos push in a project with multiple contracts, the first one deploys ok, but the rest throw ProviderError: replacement transaction underpriced. Reproduced with truffle-hdwallet-provider 0.0.6, and zos 1.4.1, using rinkeby via infura.

Document best practices regarding versioning of zos.json files

Ensure it is mentioned in the documentation that zos.json files should be checked into version control (ie git added), and why this is the case.

Setup simple integration tests

We are detecting issues that only arise with geth, parity, infura, or certain web3 providers. These issues are uncaught by our current unit tests. We need a set of tests that run on different infrastructures, installing the CLI and using it directly from the command line. These tests probably don't need to run on every commit, but either every X days or on every tag.

Ask user for password to unlock account if needed

If the user is working with a locked account in a node, they need to manually open a separate console to unlock it before running any CLI operation. Instead, detect locked accounts and prompt for the password.

Avoid asking for the password as an option in the command line, since it can be easily sniffed (and is even kept in bash history). Instead, ask for them interactively, or use a dedicated file descriptor or environment variable for automated workflows.

Do not discard the password after unlocking, since the CLI operations may take long enough that the account is re-locked. Capture these errors, and re-unlock the account as needed.

Clarify `push` command in the documentation

We are only explaining that push "pushes the code to the network", without any more info. This causes users to blindly follow the instructions we provide on CLI usage, without understanding what happens on each step.

Add better documentation for push in the docs to clarify this.

Question: how will inherit a contract affect the storage order?

Dear ZOS team,

We (boba.pikt.io) want to upgrade our legacy contract, and one of the task is to change the owner mechanism from our customized version to the Ownable provided by zos, we want to know if that will affect what's being discussed here: https://docs.zeppelinos.org/docs/advanced.html#preserving-the-storage-structure

By the way, please kindly advice if this is the best place to ask question, or should we go to some ZOS-preferred discussion channel?

Thank you !

@xinbenlv

Error in commands tests cause process to exit

Tests added in zeppelinos/zos-cli#298 seem to forcefully exit the process if an error occurs during the execution of the command. This is probably caused by the error handler registered in the commander.js program, which runs a process.exit(1) in those cases.

Make sure to stub, not register at all, or add a NODE_ENV check on the error handler on the commands tests.

Add package-lock.json

Commit all package-lock.json files created by lerna bootstrap, as well as node_modules/ in .gitignore.

Track owner addresses for App/Package/Provider in network.json files

We should track the owner address of the App, Package, and Provider contracts deployed to a network in the zos.network.json file. This way, we can validate whether the from address actually has permissions to run a particular action, before attempting to actually execute it, and save the user from wasting time and gas into a failing tx.

This would complement the owner tracking of individual proxies in #3.

Contract is only checked on `zos add` for issues

We're currently checking that a contract does not have a constructor and does not have selfdestruct calls only when adding it. However, the user may modify it afterwards, adding a ctor/selfdestruct, and it will be picked up and pushed by the CLI, without issuing any warnings.

On the other hand, note that issuing a warning for the same contract on every push can be annoying for the user. We may want to check the contract for issues on every add and push, but only when its bytecode changes.

Affects #80, #142.

Link and unlink commands should not recompile contracts

Running zos link or zos unlink should not run a recompilation step.

Add thorough documentation for lib contracts architecture

As a user peeks into the zos.network.json files, they'll notice these entries with addresses, which are not explained in the documentation. The only info provided today is in the Reference, but there is no explanation at all in the Guides.

Add a chapter or subchapter on these classes, describing the on-chain architecture of a zOS project.

Add project governance section to docsite

Add a section on the docsite about project governance. Use the blogpost on multisig governance as a basis.

Error thrown when using push command with HDWalletProvider

A new error is being thrown since most recent release when using push command with HDWalletProvider:
Command output (error):

zos push --network infura_ropsten
Compiling contracts
Compiling ./contracts/Campaign.sol...
Compiling zos-lib/contracts/migrations/Migratable.sol...

Compilation warnings encountered:
Writing artifacts to ./build/contracts

Deploying new UpgradeabilityProxyFactory...
Successfully written zos.infura_ropsten.json
Web3ProviderEngine does not support synchronous requests.

truffle config:

...
 infura_ropsten: {
      name: "infura_ropsten",
      provider: function () {
        return new HDWalletProvider(process.env.WALLET_MNEMONIC, `https://mainnet.infura.io/v3/${process.env.INFURA_API_KEY}`)
      },
      ...
    },

Allow initializing logic contracts

It would be a good practice to initialize deployed logic contracts, to prevent anyone from messing with them, and potentially causing issues related to selfdestructs. Provide a way to define initialization parameters when pushing logic contracts.

Preserve App, Package, and Directory addresses in aborted deployments

Given an initial zos push operation that deploys Factory, App, Package, and Directory contracts, we want to preserve them as they are being deployed, in case the deployment fails mid-run. Make sure the addresses of each contract is stored in the zos.network.json file as they are deployed, and that the push picks up from there on subsequent operations.

Related to https://github.com/zeppelinos/zos-cli/issues/319

.

Design lightweight functions for creating upgradeable instances

Today, using ZeppelinOS involves spinning up an App with Factory, with a Package, with an ImplementationProvider where the implementations are registered, before a proxy can be created. Some users have expressed concern as to locking-in to this structure, and are interested only in using the proxies themselves.

Design a set of functions to just create an upgradeable instance of a contract, without requiring setting up a ZeppelinOS app. Consider integrating these functions with existing frameworks, such as web3 or truffle-contracts.

Derived from #10

Warn if a contract initializer fails to call a parent initializer

When writing an initializer function, all parent initializers must be manually called. We could use the AST to check if there are any base contracts, and if they declare their own initialize functions, and then check if the contract's initialize function does call them. If it doesn't, we can show a warning to the user.

For instance:

contract BaseContract {
  uint256 public y;

  function initialize() public {
    y = 42;
  }
}

contract MyContract is BaseContract {
  uint256 public x;

  function initialize(uint256 _x)  public {
    BaseContract.initialize(); // Warn if this call is missing!
    x = _x;
  }
}

Document new Initializable interface

Add a new section in the documentation explicitly explaining how to use the implementation pushed in #2. Evaluate either adding a new section, making it part of a tutorial, or both.

Multiple dependencies support

Umbrella issue for multiple dependencies support in ZeppelinOS.

• Update lib contracts
• Update lib models
• Update lib examples
• Update CLI main commands
• Update documentation
• Add CLI command to remove a dependency
• Update stdlib model tests
• Update TestApp model to work with new Projects
• Update CLI status check
• Update CLI status fetch and pull
• Validate CLI json version
• (optional) Auto upgrade from CLI previous json format

Add link to documentation on selfdestruct warning

When adding a contract with selfdestruct, the CLI raises a warning explaining it is a security risk (see zeppelinos/zos-cli#347). Add a link to the documentation in the message so users can go and check for more information.

If the documentation on that is not already written, then we need to write it as part of this issue.

Contract not initializing correctly

Setting up a simple contract that inherits from DetailedPremintedToken, but totalSupply gets incorrectly set to 0. From what I've gathered it seems the issue might be related with how I'm setting the initialize() method.

Contract:

pragma solidity ^0.4.21;
import "openzeppelin-zos/contracts/token/ERC20/DetailedPremintedToken.sol";

contract DanGrau is DetailedPremintedToken {
    string public name = "Daniel Grau";
    string public symbol = "Grau";
    uint8 public decimals = 4;
    uint256 public INITIAL_SUPPLY = 20000000 * 10**uint256(decimals);

    function initialize(address initialAccount) public isInitializer("DanGrau", "0")  {
        DetailedPremintedToken.initialize(initialAccount, name, symbol, decimals, INITIAL_SUPPLY);
    }
}

If I do:

$ zos add DanGrau

$ zos push --deploy-stdlib --network local

$ zos create DanGrau --init initialize --args <a ganache address> --network local

The contract does return variables such as name or symbol but totalSupply() keeps returning 0. And I see the same behavior if I truffle test, whether I use the TestApp() or interact directly with a DanGrau instance.

Could someone expand on calling initialize() functions manually? Not sure if that's where I'm messing up, any pointers will be appreciated

Evaluate resolver-engine for replacing custom Contracts class

See https://github.com/resolver-engine/resolver-engine

Allow running `zos` from any subfolder

Most CLI apps (such as git or npm) support being run from any subfolder within the project, as they crawl the folder hierarchy upwards until they reach a folder with a .git or package.json that signal the root. Given that we have a zos.json that indicates the project root, we should support running zos from any subfolder within the project.

Review Initializable and Migratable base contracts

The Migratable contract from zos-lib is not trivial to use, as there is often confusion around the need of specifying the contract name, or what does the "version" represent. We agreed on reviewing these contracts to see if we could somehow simplify them (they also currently emit a solc compiler warning, at least let's fix that!).

Add a section in the documentation explaining how to use the new contracts. Review the existing documentation around the usage of Migratable, change it to use the new versions, and clarify the need for it. Several users believe that it is mandatory to use Migratable for a contract to be used with zOS, increasing the fear of lock-in into the platform, so we need to make sure in the docs that it is not the case.

Estimate gas price when sending transactions

Truffle's mainnet default is 100 GWei, which is typically 20x-100x higher than the gas price required. If the user hasn't explicitly set a gas price, use a gas price API (such as eth gas station) or the value from previous blocks (similar to what the gasPrice subprovider does) to estimate a more reasonable value.

Note that newer versions of truffle/web3 may handle this automatically, if we upgrade.

Another possible enhancement could be to check the actual value of the tx (in either ETH or USD), and warn the user if it exceeds a certain threshold.

error testing upgradable smart contract in getting started guide

Hi. Im following the directions in the 'getting started guide' and Im on page 2, 'Building an upgradeable application' (https://docs.zeppelinos.org/docs/building.html) and everything goes fine until I get to the bottom where it shows how to test if it was upgraded or not, then I have a problem. The very first line is myContract = MyContract.at(0x1234567890000000000000) every time I put his in, I get:

Error: Invalid address passed to MyContract.at()

I see the contract on the local network when i do truffle networks or run the networks command from in the console. I see the gas money being deducted from my test ETH wallet so I know the contract is working and deployed. I dont understand why its saying that the contracts address is invalid. Its ALWAYS invalid, Ive done this and redone this a 100 times.

Consider confirmations for update commands

We could list the updates that will be triggered when running zos update, present them to the user, and have them confirm the action, since it is potentially destructive.

Export cli scripts for using them programmatically.

It would be great (and pretty straightforward to implement) if we provide a programmatic way of using the cli by exporting all the scripts. Users would be able to do stuff like:

import zos from 'zos' // or import { init, add, push } from 'zos'
...
zos.init({ version: '0.0.1', name: 'myAwesomeProject'})
zos.add({ contractData: [{ name: 'myContract', alias: 'awesomeContract' }]})
zos.push({ network: 'ropsten' })
...

Also, as this would be a new functionality, we should add the appropiate documentation to docs.

Evaluate automatically setting up an example project when building a lib

One of the challenges of building a lib in zOS today is understanding how the user is going to interact with it. We could think about options to automatically bootstrap a sample project that includes the lib under development, to facilitate testing.

Is it possible to know if contract needs to be created or upgraded ?

To simplify automatic redeployment I mean

So existing contracts get updated and newly added get upgraded

For example I start to develop a dapp with awesome zos and in 1st iteration I have contract A only. I create it. Then I add features to contract A and upgrade it.

But then I add another contract B.

How in my build script can I detect which contact needs which zos commands to be executed during build script?

So that A is just upgraded and B is created as it is first time it is deployed.

Thanks

New CLI command to change admin ownership of a proxy

Add a new command (transfer?) to the CLI, that allows delegating ownership of a proxy to another address.

The command should use the same convention as update to indicate which proxy/proxies are to be transferred: Provide the [alias] you added your contract with, or use --all flag to upgrade all. If no [address] is provided, all instances of that contract class will be upgraded.

Given that this is a potentially irreversible operation, add a confirmation before executing (but after listing all the proxies that would be transferred). Add support for a -y/--yes flag to skip confirmation.

Once the proxy was transferred, add a new attribute owner to it in the zos.network.json file. All subsequent calls to update should skip any proxies with an owner different than the current app.

Automate conversion to initializers

Since normal constructors cannot be used in upgradeable contracts, users currently have to convert the constructors to initializer functions and use a mechanism like Initializable to protect those functions.

This adds friction to the process of creating an upgradeable contract. We've been playing around with several ideas to automate this preprocessing and got down to two alternatives: 1) source code preprocessing to generate the initializer functions, 2) bytecode preprocessing to generate initializer contracts. This last idea grew out of the proposal in zeppelinos/zos-lib#61.

There are some related experiments in the labs repo: constructor without arguments, constructor with arguments but very inefficient, and source code preprocessing.

Support chainable proxies for automatic stdlib upgrades

The current unstructured-storage proxy implementation does not support chaining two or more proxies, since they compete with the same storage space for the implementation slot. This could be fixed by using a different slot for every proxy, though this may require changes on how proxies are deployed.

The use case for this is to support automatic upgrades on stdlib contracts, by creating a proxy linked not to the logic contract deployed by the library provider, but to a proxy of it, which is also managed by the library provider. This allows the proxy owner to upgrade his instance to a different implementation, but also allows the library provider to centrally upgrade all its clients.

Another use case is to atomically update multiple proxies in an application with a single transaction. Should an app rely on a large number of instances of the same contract, all proxies could be upgraded simultaneously if they delegate to another proxy. Note that, in this case, the proxy instances can be constant proxies, as upgradeability is managed on the second-level proxy.

These use cases were brought up by the Chicago Decentralized Software Group and by @shrugs respectively.

Ignore swarm hash from contract bytecode before generating the zos.network.json contract bytecode hash

It seems that in some cases (for example when changing the project's directory) truffle compile is generating a different contract metadata swarm hash between compilations, even though no changes are applied in the contract source code. When doing bytecode hash comparison, this could lead to warnings on changes in the source code since the last deploy in cases where there were actually no changes. A possible solution to this could be ignoring the swarm hash at the end of the bytecode before hashing it:

...a165627a7a72305820<32 bytes swarm hash>0029 -> ignore

New create-zos package to enable initialization via npm

Running npm init zos will look for a create-zos package on npm, and use it to initialize a new package for the user, running any custom code there. We should register a new package that adds the CLI as a dependency, and runs zos init using the package name and version transparently.

Support resumable transactions

Operations that involve blockchain transactions may take a long time in the CLI, even exceeding their timeout, due to network congestion, low gas price, or other issues. We want to support resuming a transaction, so when the user runs the same command again, instead of sending a new tx, the CLI waits on an existing one (assuming it's valid).

One idea to implement this, as discussed with @facuspagnuolo and @frangio, is to ensure that all commands are idempotent. Running push or upgrade twice in a row should yield the same end result. This way, we can merge the fetch/deploy methods we have in zos-lib to handle intermediate scenarios: having some contracts deployed, others in a pending transaction, others pending to be executed.

This also means that zos-lib should somehow return or yield partial results (tx sent, contract deployed, etc) so the CLI can store this information in the network json file. When the command is called again, the CLI provides this info back into zos-lib, which knows how to resume execution.

The only blockchain command that is not idempotent is create. We may want to skip this one for the time being, or rethink how to handle it.

Add inline documentation for lib exported functions

We've heard from some users that it isn't known that zOS can be used directly from zos-lib. This is especially useful for large projects who already have their build process set up, and they don't want to switch to a different tool, but rather use zOS from their scripts.

Document this usage based on the new zOS lib model from 2.0 once merged.

Track created logic contracts in lightweight project for reuse

The lightweight project from #70 should keep track of all logic contracts created, so when a new instance is requested, the same logic contract can be reused. This implies tracking not just the name of the contract, but also its bytecode hash to detect changes. We can track the same info as we do now in the CLI.

Support rolling back to a previous version

The CLI currently supports bumping the current version of the app, and then upgrading all proxies to that version. However, there is no way to rollback (from the CLI) to a previous version, in case something goes awry with the new deployment. The same applies to rolling back to a different version of a dependency.

Design how the rolling back process should go, and implement it.

Add support for managing dependencies in lightweight project

A lightweight project from #70 should support adding dependencies. The project should detect whether the dependency is deployed on the network, and deploy it if needed, or use the addresses of the logic contracts already deployed (present on the zos network json file).

The project should implement setDependency methods, and use the implementation contracts from the package if the packageName option is set. Note that the addresses of the implementation contracts can be retrieved from either the zos.network.json file, or by actually querying the ImplementationProvider on chain.

Extend `verify` command functionality to verify App/Package/Directory contracts

At present, the verify command can only be used to verify user's contracts. Extend its functionality to also verify zeppelinOS contracts (i.e., App, Implementation -etc- related contracts.)

zos not exiting terminal when using HDWalletProvider and Infura

Not sure where the issue is in details, but all zos commands exit cleanly when using --network local.

Using any infura network thats been setup with HDWalletProvider within truffle.js is hanging even when executing correctly on the last step and needs to be cancelled manually

For instance

[ZosNetworkFile] Successfully written zos.rinkeby.json
0x3a1bc630ce85bda9c63bab2aa....... //stuck here
^C //manual cancel

My first though was this was due to writing the file, but even zos status --network rinkeby is hanging at the end

Deploy eth-packages when running init command with --link and --push options

At this time, you cannot do the whole init-link-deploy process using the init command, because in order to make it work you have to also deploy the stdlibs that you are currently linking.
Implement the stdlib deploy process when someone uses the init command with both --link and --push options and make this example work:

foo@bar:~$ zos init test 0.0.1 --link openzeppelin-zos --push local

Support multiple versions on docsite

The docusaurus documentation site currently displays only the latest version. Given that we are releasing new versions, and have a major release coming soon, we want to keep the historical docs available. We can re-use code from the OZ docsite, which currently does support it.

Validate that an upgraded contract keeps same storage layout as the original one

(follows from zeppelinos/zos-lib#63)

The problem

For an upgrade to be safe, we need to ensure that the new contract shares the same storage layout as the previous version, and only appends new variables, without modifying the existing ones.

For instance, given:

contract V1 {
  uint a;
  uint b;
}

The following upgrade is valid, since it's only adding a new variable at the end of the storage:

contract V2 {
  uint a;
  uint b;
  uint c;
}

The following ones, on the other hand, are all invalid:

contract V2 {
  uint a;
  uint c; // New variable is inserted in the slot previously assigned to `b`
  uint b;
}

contract Base {
  uint base; // New `base` variable will be assigned the first slot
}
contract V2 is Base { 
  uint a;
  uint b;
}

contract V2 {
  uint a;
  string b; // Type of a variable is changed
}

Other potential breaking changes include modifying the fields of a struct, or changing inheritance order. Anything that alters the storage layout can potentially introduce bugs, and needs to be detected. To detect this, we need to figure out the storage layout, store it, and compare it when a new version is set.

Infering storage layout

The first step is to get the storage layout given a contract. The safest option to do this is to keep building on ethereum/solidity#4017, which is an enhancement to the Solidity compiler to provide this information directly. This requires considerable effort, and we'd need to wait until the new version of the compiler is released before we can make use of the feature.

A more lightweight alternative would be to extract this information from the AST. Assuming that the order of variables in storage is the same as the order in which they are declared (this is a safe assumption to make), we can walk the AST looking for nodes that correspond to state variables ("nodeType": "VariableDeclaration", "stateVariable": true), and store their order and type. Note that we'd also need to walk the linearizedBaseContracts (in the order specified) and also retrieve their state variables, to build a complete picture of the storage.

Ideally, we could output this information in a format as similar as possible as the one described here, so the transition to the information provided by solc is as smooth as possible.

Comparing storage layouts

Next step is to build a function that, given two storage layouts as extracted in the previous step, returns whether one is a valid extension of the other. It needs to check that variables types and names haven't changed, taking into account complex types (mappings, structs, etc) as well.

The output needs to be human-readable, so we can provide the user with information on where the problem is. Make sure the error is understandable when caused by a change in an ancestor: if a base contract changes its storage layout, it's something quite hidden to the user, so we need to be extra clear in those scenarios.

Recording storage info for a contract and checking

In order to compare a version with a new one, we need to store the storage layout information somewhere, and when the user proposes a new version, we perform the check. Ideally, we could to this when the user registers the new changes, but we need to have a git-like stage in place for that.

Instead, we can do that when the user runs zos push on a new version. On the first zos push, we store the storage layout info in the zos.network.json file (along with the bytecode hash). On subsequent ones, we recalculate the storage layout for the new contract, and compare it with the stored one. If it's ok, we allow the push and overwrite the storage layout. If not, we show the errors to the user. We'd also need to include an --ignore-warns-on-storage-layout (better name needed) flag so the user can push anyway, to work around false positives.

Provide lightweight upgradeability features

For small projects, it doesn't make sense to set up an App, Package, ImplementationDirectory, and ProxyFactory to manage just 2-3 contracts. This creates a barrier of entry, where zOS is considered a too big framework for their use case.

One option we could evaluate a lightweight mode for the CLI, where not all contracts are actually created, and the CLI manually manages the creation of proxies and lookup of contracts. Note that we already have all the information we need to create upgradeable instances in the zos.network.json files, so implementation would be straightforward.

Another option is to just offer standalone functions to create a new upgradeable contract given the implementation's bytecode. This could be provided as-is, or via integrations with popular frameworks (such as a MyTruffleContract.newUpgradeable({ upgradeabilityAdmin: myAccount })). This also helps with adoption in contexts where only a simple upgradeability solution is required, and not a full App/Package/Directory combo is needed.

Related issues:

• Design document #42
• Creating proxies from a lightweight project class #70
• Managing dependencies from the lightweight project #71
• Track created contracts for reuse #72
• Add serialisation methods to lightweight project #73
• Integrate lightweight project to CLI #74