openzeppelin / docs.openzeppelin.com Goto Github PK

Buidler is now Hardhat (https://github.com/nomiclabs/hardhat)

We need to update the Learn guides to use Hardhat now that it has been released.

In the setting-up Learn guide, we should add a notice about Windows Subsystem for Linux (WSL) for Windows users.

Hi

When I run oz deploy on mainnet I get this error:

CrToken got deployment failed with error: insufficient funds for gas * price + value

I have 0.8329846 Ether in my account

truffle-config.js

var HDWalletProvider = require("truffle-hdwallet-provider");
require('dotenv').config()  // Store environment-specific variable from '.env' to process.env


module.exports = {

networks: {

mainnet: {
      provider: () => new HDWalletProvider("XXXXXXXX", "https://mainnet.infura.io/v3/XXXXX" ),
      network_id: 1,       // mainnet
      gas: 2200000,
      gasPrice: 150000000000
    }

}
,
 compilers: {
     solc: {
       version: "0.6.12"
     }
  }
};

Following the last steps captured in this image, produces the following error:

Before trying this I upgraded node version to the one you put in the installation guide:

The Getting Started page of OZ CLI seems to have a broken link:

The "TIP" paragraph offers deepers explanation on how to set up a node project but I was unable to find the content.
Happy to be redirected if I misunderstood.

After the facts: I found the content mentioned in the link here

In the writing-automated-tests#writing-unit-tests page, the link to "guide for ERC20 tests" is broken.

highlight.js seems to be having issues with some of our code (see here):

We should check if there's anything we can do to improve this.

Design a nice footer for all pages promoting the forum as a place for questions and suggestions.

From #47

Hello, before days , i developed my own help site with docs.openzeppelin.com project, all the theme is very alike (because i am not a programmer, so just revised some details, icons, links and others)
use this project on my own site is ok (at least i think), but can i put my own project open source ? is it ok ?

my doc site: https://insight.dtstack.com/public/helpSite/home/v1.0/home.html

From #47

Hey folks! Terrific work on these docs. I'm particularly a fan of the learning resources you created.

I don't see a license on this repo. Looking at your TOS, it looks like the content is under copyright - is that correct? I'm wondering if any of this content could be used on ethereum.org (e.g. adding some of your dapp content to our dapp page. Would that be something you'd be ok with? We'd be happy to give you credit where we make any use of your work. I could also share any PRs for you folks to review before publishing any changes.

Please let me know. Thanks!

In the ERC-777 guide, the _mint function is called with one additional arguments (seems like msg.sender was used twice) where as the function is actually expecting only 4 arguments.

Example call in docs screenshot:
_mint(msg.sender, msg.sender, initialSupply, "", "");

ERC777.sol _mint function implementation:
function _mint( address account, uint256 amount, bytes memory userData, bytes memory operatorData ) ......

The proper call should probably be this:
_mint(msg.sender, initialSupply, "", "");

Keeping the docs at a subdirectory (ie openzeppelin.com/docs) is better for SEO than using a subdomain (ie docs.openzeppelin.com) (read here).

If you're a startup or small business looking to optimize your SEO, consider subdirectories over subdomains. Boosting the authority of your root domain should be a universal goal of any organization. The subdirectory strategy concentrates your keywords onto a single domain while the subdomain strategy spreads your keywords across multiple distinct domains. In a word, the subdirectory strategy results in better root domain authority. Higher domain authority leads to better search rankings which translates to more engagement.

Consider the multitude of disruptive PaaS startups with docs.disruptivepaas.com and blog.disruptivepaas.com. Why not switch to disruptivepaas.com/docs and disruptivepaas.com/blog to boost the authority of your root domain with all those docs searches and StackOverflow backlinks?

However, to avoid losing the current positioning, we need to ensure every existing page is properly 301'ed to the corresponding subdomain.

An incorrect internal xref link, such as xref:upgrades::writing-contracts.adoc instead of xref:upgrades::writing-upgradeable.adoc (see OpenZeppelin/openzeppelin-sdk@1b21b29) is rendered as a link to https://docs.openzeppelin.com/cli/2.6/dependencies#upgrades::writing-contracts.adoc#use-upgradeable-packages.

This makes it impossible to detect broken links with a wget spider. We should either scan for these links in the generated html, or configure the asciidoc processor so that it fails if the xref target is not found.

As noted on this comment, we should make the Contracts v3.x redirects versionless once the new docsite is out.

We currently have a set of Gulp scripts initially inherited from antora-ui-default that feels scary to work with.

I would like us to replace it with something that is easier to keep updated and extend. I think @web/rollup-plugin-html applied to the handlebars templates could be a good setup.

From #47

The docsite is deployed from specific branches of each repo (usually docs-v*). This is good because it prevents new documentation for unreleased features to show up on the docs.

However, when doing small fixes such as typos, it is desirable for that change to propagate to all deployed sites. We've been manually cherry-picking these commits into the doc branch, but this is cumbersome, and relies on maintainers remembering to do it.

It'd be great if we had a bot that automatically did the cherry-picking for PRs with a special label (docs-fix?). It'd perform this process silently, and only report back on the (merged) PR if it got a merge conflict when applying the cherry-pick.

In OpenZeppelin/openzeppelin-contracts#2058, @frangio mentioned he doesn't agree with some aspects of the current writing style in our docs, including:

• having colons before a list starts
• capitalizing after colons on enumerations (like in the 'next steps' sections)
• including $ in console code snippets

We should settle on a writing style and use it throughout our docs.

It would be nice to link to the content that we publish on the forum (announcements, some guides).

This is not difficult to do. See Embedding a list of Discourse Topics in another site.

We need a uniform way to easily add this on any page that we want, selecting the tags that we want to feature on that page.

Some users are visiting the docs for older versions of a project when they are actually interested in the latest version. We can have a banner at the top of older versions reminding people that they're not looking at the latest version.

Blocks marked as diff (using [source,diff]) don't get proper styles.

https://docs.openzeppelin.com doesn't currently have search, it would be great to have this functionality.

The old ZeppelinOS documentation website has search https://docs.zeppelinos.org/versions
(There were issues with this search where the results were not clear on which version the results applied to, so community members could end up using old versions and get confused).

https://docs.openzeppelin.com/learn/upgrading-smart-contracts

Each page could have an Edit this page button/link at the bottom of the page which is a link to the page in the repo, so that community members can easily make edits to improve the documentation.

A community member sent me fixes to a document as it wasn't obvious where the source document was.

On page learn/writing-automated-tests in the first code example the test file is named // test/Box.js in other examples // test/Box.test.js.

We will save the test as test/Box.js.

There's several improvements we can/should make to the sidebar.

• Remember scrolling position (+ collapsed items?) when navigating between pages.
• Change cursor to pointer when hovering over collapsible items.
• Add indicators for collapsed state.
• Review positioning of sections on shorter viewport heights.
• Fix "current" indicator for items longer than 1 line.

We should add a section on prerequisites for different platforms, both for the CLI and ZepKit.

When an item on the navbar is a link to a page, clicking on both the label and the arrow causes the site to navigate to the page. I'd expect the arrow to collapse instead.

So this navbar has no issues

.List
 * xref:page.adoc[Item A]
 * xref:other_page.adoc[Item B]

But this one does

.xref:about_pages.adoc[List]
 * xref:page.adoc[Item A]
 * xref:other_page.adoc[Item B]

Repro:

1. Head to https://docs.openzeppelin.com/cli/2.8/getting-started
2. Click on "Setting Up a Development Environment" in the first TIP Box.

Expected: it navigates to https://docs.openzeppelin.com/learn/setting-up-a-node-project (I guess?)

Actual: it navigates to https://docs.openzeppelin.com/cli/2.8/getting-started#learn::set-up-dev-environment, which results in reloading the same page.

Related to #231 (comment).

I've noticed that Bulding a GSN-powered DApp links to projects that are in maintenance mode, and AFAIK the development moved to OpenGSN. Would it make sense to remove the section "Bulding a GSN-powered DApp" from your docs, or point to the OpenGSN website?

Dependabot encountered the following error when parsing your .dependabot/config.yml:

The property '#/update_configs/0/version_requirement_updates' value "increase_versions_if_required" did not match one of the following values: off, auto, widen_ranges, increase_versions, increase_versions_if_necessary

Please update the config file to conform with Dependabot's specification using our docs and online validator.

Code blocks marked as typescript using triple backticks don't get stylized.

This is what the HTML looks like:

<code class="language-typescript hljs" data-lang="typescript">... </code>

OpenZeppelin Contracts 3.0 RC shows as previous version when using the version selector

https://docs.openzeppelin.com/contracts/2.x/
https://docs.openzeppelin.com/contracts/3.x-rc/

In the docs under environment setup you require to install @openzeppelin/contracts-ethereum-package, later on in creating our contract the example contract is:

// contracts/Counter.sol
pragma solidity ^0.5.0;

import "@openzeppelin/contracts-ethereum-package/contracts/GSN/GSNRecipient.sol";

contract Counter is GSNRecipient {
    uint256 public value;
the contract is:

But the GSNRecipient abstract contract doesn't exist in @openzeppelin/contracts-ethereum-package/contracts/GSN/GSNRecipient.sol", but in openzeppelin-contracts/contracts/GSN/GSNRecipient.sol.

In @openzeppelin/contracts-ethereum-package/contracts/GSN/GSNRecipient.sol" the abstract contact is called GSNRecipientUpgradeSafe.

Currently the left hand sidebar in the documentation has:

• Test Helpers
  • Overview
  • Configuration
  • API Reference

A community member via Intercom suggested:

would like to suggest that in the left sidebar, for the entry 'API Reference', please include all the sub-elements too (like balance, BN, constants, etc.) so that it is convenient to seek. Thanks.

So the side-bar could look like the following:
\/ Test Helpers

• Overview
• Configuration
• API Reference
  • balance
  • BN
  • constants
  • ether
    ...

This style of navigation is available in: https://docs.openzeppelin.com/contracts/3.x/tokens

For smart contract documentaiton we're currently only showing the @dev NatSpec entries. We should also show @param documentation.

Autogenerated docs from contracts natspec show links in plain text. They should be formatted as actual links. Check out what is the standard way for writing links in natspec (markdown? html? a custom notation?) and process it when generating the docs.

(reported by @ylv-io)

Some external contributors have recently created PRs to fix or improve our docsite, which is great 🙂! We should add a minimum set of instructions in the CONTRIBUTING.md or in the docs package README.md for them. Some things to take into consideration:

• After fixing an .md file, run npm run start and go to http://localhost:3000 to check that the implemented changes (in terms of both content and css styles) are working fine.
• If the implemented changes correspond to the latest version of the docs (let's say it's version 2.2.0), also apply them to the latest version in docs/docs/website/versioned_docs/version-2.2.0 or docs/docs/website/versioned_sidebars/version-2.2.0-sidebars.json as appropiate.
• Check if this changes also apply to older versions of the docs and update them (same as above, inside docs/docs/website/versioned_docs/version-*older_version* or docs/docs/website/versioned_sidebars/version-*older_version*-sidebars.json as appropiate).

We're doing an overall review of the site, redesigning some parts, and restructuring the content. Mainly we are making sure that all of our tools have a place in the site, and that we have guides introducing people to all of our tools and how to use them together.

This issue tracks all the related efforts.

Content

All projects should follow this structure: first Overview, then articles organized conceptually, finally API Reference.

• Restructure Contracts documentation (OpenZeppelin/openzeppelin-contracts#2002)
• Restructure SDK documentation (OpenZeppelin/openzeppelin-sdk#1286)
• Restructure Starter Kits documentation (OpenZeppelin/starter-kit#87)
• Create documentation for all other projects. Take from README as much as possible.
  • test-helpers
  • test-environment
  • network
  • gsn-helpers
  • gsn-provider
  • solidity-hot-loader
  • contract-loader
  • solidity-docgen
• Create "entry guides" section in the site (potential name: "Learn") (some of these may be links to guides elsewhere in the site)
  • Deploying a smart contract
  • Writing smart contracts (Contracts)
  • Managing a smart contract project (CLI / Upgrades)
  • Interacting with your contracts (CLI / loader / hot-loader)
  • Testing contracts (Test-env / Test-helpers)
  • About the GSN (Contracts / GSN helpers / GSN provider (include "building a gsn dapp"))
  • About upgrades (CLI / Upgrades)
  • About dapps (CLI / Network.js / Starter kit / hot loader (include "writing a dapp"))
• Include a link to our audits service in the warning boxes

Design

• Redesing sidebar to accomodate the bigger list of tools, and one or two more levels of depth, with collapsible indicators
• Make sure more than one level of depth works in the sidebar
• Redesign landing page
• Design a nice footer for all pages promoting the forum as a place for questions and suggestions

Infrastructure

• Fix current errors preventing publishing [email protected] docs
• Fix caching of the build on Netlify
• Fix build previews for the repos (OpenZeppelin/docs-utils)
• Add Antora structure to all new repos
  • test-env (OpenZeppelin/openzeppelin-test-environment#28)
  • test-helpers (OpenZeppelin/openzeppelin-test-helpers#100)
  • network
  • gsn-helpers
  • gsn-provider
  • hot-loader
  • contract-loader
  • solidity-docgen (OpenZeppelin/solidity-docgen@979c42b)
• Add Netlify webhooks to all new repos added to the site
• Create automation to merge docs changes to the branches used for the site
• Use JavaScript/TypeScript documentation generators for API reference
• Add redirects from the old pages (OpenZeppelin/netlify-redirects#1)

Update Learn guides to use oz deploy rather than oz create which has been deprecated.

The following guides need to be updated:
https://docs.openzeppelin.com/learn/deploying-and-interacting#deploying-a-smart-contract
https://docs.openzeppelin.com/learn/connecting-to-public-test-networks#working-on-testnet
https://docs.openzeppelin.com/learn/upgrading-smart-contracts#upgrading-a-contract-via-cli

Reported in the community forum: https://forum.openzeppelin.com/t/create-deploying-upgradable-contract-error/2876

We are showing "warning", "caution", and "important" admonitions/alert boxes with the text "Warning".

We should make each show the appropriate label.

Add explanation of gas overhead of calling upgradeable contract functions to upgrading-smart-contracts.adoc

Feedback received in Community Forum: https://forum.openzeppelin.com/t/upgradeable-gas-cost-overhead/3661

As part of the CI checks, ensure that the docsite has no broken links. Check if there is an npm package to handle this.

Alternatively, the following command uses wget to crawl the site, and report the results. Note that it requires the app to be running in a local port, so we need to actually start the dev server, or a python SimpleHTTPServer on the built site (see here for a similar one).

wget -r -l8000 --spider -e robots=off -D localhost http://localhost:8000 -o ./broken-links.log

Other tools, from a quick google search. Remember that the checker does not need to be js-based, as it runs on the netlify build (or another CI) which supports python or ruby.

• https://simpleit.rocks/web/html/how-to-check-local-websites-for-broken-links/
• http://wummel.github.io/linkchecker/
• https://www.npmjs.com/package/broken-link-checker

I would expect to have both previous buttons next at the end of each section, for navigation purposes, as we had before in the zeppelinos docsite:

Hi

I deployed my contract but when I called initialize method got this error:

Choose the kind of deployment upgradeable
? Pick a network mainnet
? Pick a contract to deploy CrToken
√ Contract CrToken deployed
All implementations have been deployed
? Call a function to initialize the instance after creating it? Yes
? Select which function * initialize()
× Setting everything up to create contract instances
insufficient funds for gas * price + value

Now I can't call my methods again

I want to call initialize method without deploy again

I get this error

oz call
? Pick a network mainnet
A contract address must be specified.

my code is:

pragma solidity ^0.6.0;


import '@openzeppelin/contracts-ethereum-package/contracts/Initializable.sol';
import '@openzeppelin/contracts-ethereum-package/contracts/presets/ERC20PresetMinterPauser.sol';
import '@openzeppelin/contracts-ethereum-package/contracts/access/Ownable.sol';
contract CrToken is Initializable, ERC20PresetMinterPauserUpgradeSafe   {

 uint256 private _totalSupply;


  function initialize() public initializer {
    ERC20PresetMinterPauserUpgradeSafe.initialize("Cryptomind", "CR");
      _setupDecimals(8);
	   _totalSupply = totalSupply();
	 
	   _mint(msg.sender, 2000000000 * (10 ** 8));
	  
  }


}

We should have a reference to @openzeppelin/contracts-ethereum-package in the contracts documentation, it is referenced in the OpenZeppelin SDK documentation.

https://docs.openzeppelin.com/sdk/2.5/linking

NOTE: Make sure you install @openzeppelin/contracts-ethereum-package and not the vanilla @openzeppelin/contracts. The latter is set up for general usage, while @openzeppelin/contracts-ethereum-package is tailored for being used with the OpenZeppelin SDK. This means that its contracts are already set up to be upgradeable.

So we could have something like this in the OpenZeppelin Contracts documentation at the install section https://docs.openzeppelin.com/contracts/2.x/#install:

NOTE: If you are using OpenZeppelin SDK, make sure you use @openzeppelin/contracts-ethereum-package and not the vanilla @openzeppelin/contracts. The latter is set up for general usage, while @openzeppelin/contracts-ethereum-package is tailored for being used with the OpenZeppelin SDK. This means that its contracts are already set up to be upgradeable. See Linking OpenZeppelin contracts for how to use.

Reported by @blancoagostina. Seen in ERC777.defaultOperators.

The problem is that the ] in address[] is interpreted as closing an asciidoc pass:normal[...] macro. Not sure how to fix it yet.

At this time, if you had bumped a new version of the docsite, you won't be able to rebump it without first removing all the already generated files (docusaurus won't let you do it). Consider adding a a function in the scripts/bump-docs.js to remove the following files and directories before trying to generate the provided version (let's say it's v2.2.0):

• docs/website/versioned_docs/version-2.2.0/
• /docs/website/versioned_sidebars/version-2.2.0-sidebars.json
• Remove 2.2.0 from the array of versions inside docs/website/versions.json

Update Learn guides to use Solidity 0.6. Currently the guides use Solidity 0.5