gemforge v2.7.0

Gemforge

Command-line tool for building, deploying and upgrading Diamond Standard contracts on EVM chains.

Why

The Diamond Standard (EIP-2535) is one of the best ways to build and deploy infinite sized, upgradeable contracts.

But utilizing the standard involves having to write a lot of boilerplate code, including but not limited to the core diamond proxy contract, interface code to enable easy access for dapps, deployment code which calculates what facets to add and remove in each upgrade, etc.

Gemforge to the rescue!

By automating almost all aspects of this boilerplate code whilst still remaining highly configurable, Gemforge lessens the workload and saves time when developing with Diamond Standard.

Gemforge is already used in production.

Features

• Auto-generates Diamond proxy code.
• Auto-generates deployment code for Foundry tests.
• Auto-calculates facet deployment and upgrades accurately and efficiently.
• Deploy multiple instances to a single chain.
• Clean existing deployments.
• Records diamond addresses to JSON file for history tracking.
• Pre- and post- hooks for both build and deploy steps.
• Generates Foundry and Hardhat scaffolding.
• Highly configurable per project.
• Fully documented

See who is using Gemforge.

Installation

Node.js 20+ is required to run Gemforge. We recommend using nvm to handle different Node versions.

We recommend installing gemforge globally:

• pnpm: pnpm add --global gemforge
• npm: npm install --global gemforge
• yarn: yarn global add gemforge

Usage

You can use gemforge --help to see what commands are available:

Usage: gemforge [options] [command]

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  init [options]              Initialize a gemforge config file for an existing project.
  scaffold [options]          Generate diamond smart contract project scaffolding.
  build [options]             Build a project.
  deploy [options] [network]  Deploy the diamond to a network.
  help [command]              display help for command

And usegemforge <command> --help to help for a specific command. E.g, for gemforge init --help:

Usage: gemforge deploy [options] [network]

Deploy the diamond to a network.

Arguments:
  network                network to deploy to (default: "local")

Options:
  -v, --verbose          verbose logging output
  -q, --quiet            disable logging output
  -f, --folder <folder>  folder to run gemforge in (default: ".")
  -c, --config <config>  gemforge config file to use (default: "gemforge.config.cjs")
  -n, --new              do a fresh deployment, ignoring any existing one
  -h, --help             display help for command

Full documentation is available at https://gemforge.xyz.

Development

Note: This section is only relevant for those wishing to work on the Gemforge tool itself. To use Gemforge with your project please read the official documentation.

Building

Building the tool:

> pnpm build

Watching for changes and re-building:

> pnpm dev

Testing

To run the tests, you will need Foundry and the Solidity compiler installed, see ci-docker-image.

Then run the following commands in 2 new terminal windows to start up local test nodes:

> pnpm run-foundry-testnet # terminal 1
> pnpm run-hardhat-testnet # terminal 2

Now you can run the tests in the original terminal:

> pnpm test

Troubleshooting tests

Note: If you get a Error: [object Object] error when running tests it's due to a Typescript syntax error in the test code somewhere.

Publishing

To publish a new release:

> pnpm release

Contributing

Issues and PRs are welcome. Please read the contributing guidelines.

License

MIT - see LICENSE.md