@openzeppelin/hardhat-defender
    TypeScript icon, indicating that this package has built-in type declarations

    1.8.1 • Public • Published

    OpenZeppelin Hardhat Defender

    Docs NPM Package

    Hardhat plugin for integrating upgrades and deployment verifications with OpenZeppelin Defender. This package adds functions to your Hardhat scripts so you can propose upgrades for your contracts and approve them via Defender Admin (depends on @openzeppelin/hardhat-upgrades and ethers.js) and verify deployments.

    Why?

    Use this package to manage upgrades for mainnet contracts using Hardhat scripts, and then approve them by a multisig through Defender Admin.

    You can use @openzeppelin/hardhat-upgrades to deploy your upgradeable contracts via deployProxy, and then transfer the admin powers to a multi-signature wallet via transferProxyAdminOwnership for additional security.

    When you want to upgrade, use proposeUpgrade to prepare the upgrade, and create a new upgrade proposal in Defender Admin. The multisig admins can then review the upgrade in Defender, and sign their approval.

    Approve an Upgrade in Defender Admin

    You can also verify the deployment on Defender, which checks that the compilation artifact matches the deployed code, so reviewers can check that the new implementation matches the source code.

    Review bytecode verification

    Installation

    npm install --save-dev @openzeppelin/hardhat-defender
    npm install --save-dev @nomiclabs/hardhat-ethers ethers # peer dependencies
    

    Register the plugin in your hardhat.config.js:

    // Javascript
    require('@openzeppelin/hardhat-defender');
    
    // Typescript
    import '@openzeppelin/hardhat-defender';

    And add your Defender Team API key to the exported configuration in hardhat.config.js:

    module.exports = {
      defender: {
        apiKey: process.env.API_KEY,
        apiSecret: process.env.API_SECRET,
      }
    }

    Upgrades

    You can use this plugin in a Hardhat script to propose an upgrade for a contract previously deployed with deployProxy:

    // scripts/propose-upgrade.js
    const { defender } = require("hardhat");
    
    async function main() {
      const BoxV2 = await ethers.getContractFactory("BoxV2");
      const proposal = await defender.proposeUpgrade(BOX_ADDRESS, BoxV2);
      console.log("Upgrade proposal created at:", proposal.url);
    }
    
    main();

    This will automatically check that the Box contract deployed at BOX_ADDRESS can be safely upgraded to BoxV2, deploy the BoxV2 implementation contract, and create a new upgrade proposal in Defender Admin.

    Note that proposeUpgrade will only deploy the implementation contract, but will not change anything in your proxy contract. Any changes must be approved by the upgrade admin(s), who can do so either via Defender or manually.

    Verification

    You can upload the compilation artifact for a contract to Defender, along with its deployment address. Defender will check that the code on chain matches the artifact, and display a verification notice on the application.

    // scripts/verify-deploy.js
    const { defender } = require('hardhat');
    
    async function main() {
      const verification = await defender.verifyDeployment(BOX_ADDRESS, 'Box', MY_REPO_URL);
      console.log(`Verified artifact with hash`, verification.providedSha256);
    }
    
    main();

    Alternatively, you can also upload the compilation artifact to a public URL and then have Defender retrieve the artifact from that location for verification, through the verifyDeploymentWithUploadedArtifact function. You can get the artifact to upload for a specific contract using getDeploymentArtifact, or an artifact that contains the build info for all your contracts using getDeploymentBuildInfo. You can also get the hash of the artifact for a given contract using getBytecodeDigest to check for matches against a pre existing verification on Defender.

    Learn more

    Keywords

    none

    Install

    npm i @openzeppelin/hardhat-defender

    DownloadsWeekly Downloads

    596

    Version

    1.8.1

    License

    MIT

    Unpacked Size

    42.8 kB

    Total Files

    31

    Last publish

    Collaborators

    • ericglau
    • frangio
    • amxx
    • spalladino