hardhat-multibaas-plugin

Integrate MultiBaas into your Hardhat workflow!

MultiBaas is blockchain middleware that makes it fast and easy to develop, deploy, and operate on the Ethereum and OMG blockchain platforms. This plugin makes it easy to deploy contracts to MultiBaas from within your existing Hardhat workflow. Your DApp can then use the MultiBaas REST API to interact with smart contracts.

For more information on MultiBaas, see our introductory walkthrough and our developer documentation.

Usage

Installation

On your Hardhat workspace, set up a package.json file (if not yet added) with

npm init

or

yarn init

Then, add the hardhat-multibaas-plugin package:

npm i hardhat-multibaas-plugin --save-dev

or

yarn add hardhat-multibaas-plugin -D

Configuration

To configure hardhat-multibaas-plugin, you need to define a MBConfig configuration option:

/**
 * A configuration option used to configure MultiBaas Deployer.
 *
 * @field host the MultiBaas instance's host URL
 * @field apiKey the API key used to deploy a smart contract
 * @field allowUpdateAddress a list of networks that support overriding an address
 * if there exists an address on MultiBaas with the same label.
 * @field allowUpdateContract a list of networks that support overriding a contract
 * if there exists a contract on MultiBaas with the same (label, version) but
 * different bytecode. */
interface MBConfig {
  host: string;
  apiKey: string;
  allowUpdateAddress: string[];
  allowUpdateContract: string[];
}

To use hardhat-multibaas-plugin with hardhat, configure the networks and mbConfig fields in your hardhat.config.ts as follows:

import "hardhat-multibaas-plugin";

module.exports = {
  defaultNetwork: "development",
  networks: {
    development: {
      url: `<YOUR MULTIBAAS DEPLOYMeENT URL>/web3/<YOUR API KEY>`,
      chainId: `<NETWORK's CHAIN ID>`,
      accounts: ["<ACCOUNT 1's PRIVATE KEY>", "<ACCOUNT 2's PRIVATE KEY>"],
    },
  },
  mbConfig: {
    apiKey: "<YOUR API KEY>",
    host: "<YOUR MULTIBAAS DEPLOYMENT URL>",
    allowUpdateAddress: ["development"],
    allowUpdateContract: ["development"],
  },
  // other hardhat configurations...
};

A sample configuration file can be found in the sample folder

Testing/Deploying smart contracts

See the sample folder for a complete Geting Started guide with hardhat-multibaas-plugin.

The plugin uses a single deploy function to upload a smart contract's artifact, deploy then link the contract on MultiBaas:

deploy: (
  // A `ethers.js` Signer or a `hardhat-ethers` FactoryOptions
  signerOrOptions: Signer | FactoryOptions,
  contractName: string,
  contractArguments?: unknown[],
  options?: DeployOptions,
) => Promise<DeployResult>;

in which DeployResult is the data returned from a successful deployment using the plugin. It has the following fields:

/**
 * Result of MultiBaas Deployer's deploy function.
 *
 * @field contract an `ethers.js`'s `Contract`
 * @field mbContract a MultiBaas contract
 * @field mbAddress a MultiBaas address
 **/
export interface DeployResult {
  contract: Contract;
  mbContract: MultiBaasContract;
  mbAddress: MultiBaasAddress;
}

DeployOptions consists of different options that you can specify when deploying a contract using the plugin. It has the following fields:

export interface DeployOptions {
  /**
   * Overwrite the default contractLabel. If set and a duplicate is found,
   * the contract is assigned a newer version.
   */
  contractLabel?: string;
  /**
   * Version override. Will fail if another binary with the same version is found.
   */
  contractVersion?: string;
  /**
   * Overwrite the default address label. If set and a duplicate is found,
   * the address is instead updated (or returned with an error, chosen by global setting `allowUpdateAddress`).
   *
   * The auto-generated address label is never a duplicate.
   */
  addressLabel?: string;

  /**
   * Override the default deploy transaction arguments
   * (gasLimit, gasPrice, etc)
   **/
  overrides?: unknown;

  /**
   * The kind of the proxy. Defaults to 'transparent'.
   **/
  proxyKind?: "uups" | "transparent" | "beacon";

  /**
   * The block to start syncing the contract from.
   *
   * empty string: disable the MultiBaas Event Monitor
   *  0: sync from the first block
   * <0: sync from this number of blocks prior to the current block
   * >0: sync from a specific block number
   *
   * Defaults to -100, or 100 blocks prior to the current block.
   **/
  startingBlock?: string;
}

The deployProxy function will deploy a proxied smart contract that uses OpenZeppelin's Hardhat Upgrades plugin. It automatically deploys the implementation contract, proxy, and admin, as required, and then links the proxy smart contract. It defaults to a 'transparent' proxy type, but can be overridden.

deployProxy: (
  signerOrOptions: Signer | FactoryOptions,
  contractName: string,
  contractArguments?: unknown[],
  options?: DeployOptions,
) => Promise<DeployProxyResult>;

in which the DeployProxyResult extends the data included in DeployResult with the following additional fields:

export interface DeployProxyResult extends DeployResult {
  adminAddress: string;
  implementationAddress: string;
}

For contracts that have been deployed outside of hardhat-multibaas-plugin, it is possible to simply link them in MultiBaas by calling the link function and providing the deployed address.

link: (
  signerOrOptions: Signer | FactoryOptions,
  contractName: string,
  address: string,
  options?: DeployOptions,
) => Promise<DeployResult>;

Copyright

Copyright (c) 2021 Curvegrid Inc.