How registering an EVM package in the ZeppelinOS ecosystem will look like

Hey there! We are designing the process of registering an EVM package on the ZeppelinOS vouching ecosystem, and wanted to share our ideas before releasing it.

What's in an EVM package?

What would you expect to see when browsing the list of EVM packages on ZeppelinOS? We believe that the bare minimum should be the following:

  • A name and version
  • A link to github or other code repository
  • A short description
  • The address to the actual EVM package
  • The address of the maintainer

Note that the first three items can be gathered from the package.json, while the addresses are present on the zos.network.json files.

What are the steps for registering the EVM package?

After the EVM package is deployed, a small metadata file needs to be compiled with all the info listed above, and uploaded to a public location. Once ready, a transaction is sent to the ZeppelinOS on-chain vouching registry to register the EVM package. This transaction carries the URI of the metadata file (and the hash of the contents), the address where the package is deployed, and the initial amount of to vouch for the package.

Where is the data hosted?

We have several options for this. While we could support any hosting location, including IPFS, we may want to start out with a simple and reliable location.

  • We could store the metadata file directly on github. We ask the user to commit and push the metadata file, and use a raw github URL to the file (this is my preferred option).

  • We could use a centralized S3 bucket backed by Zeppelin, though this requires set up and maintenance on our end, as well as monitoring to prevent abuse.

How would the package owner run this?

We would add a new zos register command, that confirms the current data to be uploaded (gathered from package.json), and issues the transaction. The user is offered to publish the package and freeze it, if they haven't done so yet.

$ zos register --vouch 1000
> The current package version is not yet published the network. This is required to be able to register it. 
> Do you want to publish and freeze it now? [y/n/h] h
> Publishing your package will create an on-chain registry of the implementation contracts that compose your package. This is required for other users to be able to link to your package. Freezing the version means closing it so it does not accept any further changes.
> Do you want to publish and freeze it now? [y/n/h] y
> Publishing...
> Creating App...
> ...
> Published!
>
> Will now register the following new package:
> name: openzeppelin-eth
> version: 2.1.0
> description: Library of smart contracts
> homepage: github.com/openzeppelin/openzeppelin-eth
> address: 0x12345...
> This information cannot be changed after registration. If you want to change it, edit your `package.json` and commit it to version control.
> 1000 ZEP tokens will be vouched for  this registration, of which 900 can be withdrawn later (100 are locked in for registering).
> Do you want to proceed? [y/n] y
> Registering...
> Registration successful with id 334232!

Registration information for the current version is then stored in a zos.network.json file. If the user attempts to re-register, they are notified that the package is already registered with a certain ID.

The command zos register should always default to mainnet and to a well-known registry address, but both should be overrideable via options, to facilitate testing.

How does the owner submit a new version?

After running a zos bump to set up a new version, the process of registering it for vouching is exactly the same as before.

How does the owner manage their tokens?

The user can add or remove tokens from a version, plus check their vouching on all of his package versions. The command for this would be zos vouch:

$ zos vouch --list
> You have vouched for the following versions of openzeppelin-eth:
> 2.1.0: 1000 ZEP
> 2.2.0: 500 ZEP

$ zos vouch --balance
> You have 3000 ZEP tokens

$ zos vouch --add 1000 --version v2.1.0
> Will vouch 1000 tokens to openzeppelin-eth v2.1.0. Are you sure? [y/n]
> Vouching...
> Vouch successful! You now have 2000 tokens vouching for v2.1.0.

$ zos vouch --remove 500 --version v2.1.0
> Will remove 500 tokens from openzeppelin-eth v2.1.0. Are you sure? [y/n]
> Removing vouching...
> Operation successful! You now have 1500 tokens vouching for v2.1.0.

Where is this listed?

We'll be working on a DApp that will act as a front end to the ZeppelinOS ecosystem. It will include a ranking on EVM packages based on how much ZEP was vouched, as well as the challenges open to them. Stay tuned!

It'd be good to see a human-readable name here, but I can't think of an easy way to do this.

Here are some changes to the wording for register:

$ zos register --vouch 1000
> The current package version must be published to the network in order to register it.
> Do you want to publish and freeze your package now? [y/n/h] h
> Publishing your package will create an on-chain registry of your contracts. This is required for other users to link to your package. Freezing the version means closing it so it does not accept any further changes.
> Do you want to publish and freeze your package now? [y/n/h] y
> Publishing...
> Creating App...
> ...
> Published!
>
> Will now register the following new package:
> name: openzeppelin-eth
> version: 2.1.0
> description: Library of smart contracts
> homepage: github.com/openzeppelin/openzeppelin-eth
> address: 0x12345...
> This information cannot be changed after registration. If you want to change it, edit your `package.json` and push it to github.
> 1000 ZEP tokens will be vouched for this registration, of which 900 can be withdrawn later (100 are locked for registering).
> Do you want to proceed? [y/n] y
> Registering...
> Registration successful with id 334232!

Isn't it the same EVM package, conceptually, and the developer is just publishing a new version? If so, the above text mentions "creating a new package" and such, which should
be changed to reflect this is not a new package, but an upgrade to an "old" one.

What do you think about making zos vouch be an alias of zos vouch --list

Small modifications to support multiple package names:

$ zos vouch --list
> You have vouched for the following packages: 
> openzeppelin-eth:
>         v2.1.0: 1000 ZEP
>         v2.2.0: 500 ZEP
> tpl-eth:
>         v1.0.0: 1337 ZEP
$ zos vouch --balance
> You have 3000 ZEP tokens

$ zos vouch --add 1000 --version v2.1.0
> Will vouch 1000 tokens to openzeppelin-eth v2.1.0. Are you sure? [y/n]
> Vouching...
> Vouch successful! You now have 2000 ZEP vouching for openzeppelin-eth v2.1.0.

$ zos vouch --remove 500 --version v2.1.0
> Will remove 500 tokens from openzeppelin-eth v2.1.0. Are you sure? [y/n]
> Removing vouching...
> Operation successful! You now have 1500 tokens vouching for openzeppelin-eth v2.1.0.

Great work @spalladino! Would love to hear @rrecuero's thoughts on this too.

Thanks for the comments @maraoz!

We can use the owner of the github repo as a human-friendly name. Also, we plan on using reverse ENS lookups for all addresses on the DApp, so we can display .eth names when available.

True! It is a separate EVM package but only at the protocol level, from the dev's perspective is a new version of the existing one. We'll need to use separate language for a new one and an update. Good catch!

Part of the app design includes an image for each package. Have there been any thoughts around this?

Iā€™m thinking we could take an approach similar to favicons. If a ā€˜zepiconā€™ file is in the same directory as the package.json, we can display that image along with the package. It could be optional as well.

I'd rely on the icon of the github user (or organization) that owns the repo for now. We can pluck the og:image meta tag from the homepage listed in the JSON manifest.

CORS makes pulling from og:image tag a little challenging.

Given the dependence on Github, instead I used the Github API to pull in the userā€™s profile image. Simple.

If we add other repos, such as Gitlab, we can add additional strategies.

2 Likes

Greetings again @spalladino !

I just posted a series of questions and screenshots at the following question [Error while linking to openzeppelin-eth] Could you please help me to get my environment ready to go? Thanks in advance,

Cheers!