Gemforge

https://gemforge.xyz
Admin
Gemforge is an open-source command-line tool for automating the building, deployment, and upgrading...
Tokens:14,508
Snippets:126
Trust Score:4.5
Update:11 months ago
Show doc for...
Tokens:
Raw
### Gemforge Verify Command Output Example

Source: https://gemforge.xyz/commands/verify

This output demonstrates the process of the `verify` command, including network and wallet setup, loading existing deployment records, checking validity, and the verification status of a contract. It shows a case where the contract is already verified and skipped.

```bash
GEMFORGE: Selected target: testnet
GEMFORGE: Setting up target network connection "base_sepolia" ...
GEMFORGE:    Network chainId: 84532
GEMFORGE: Setting up wallet "wallet2" ...
GEMFORGE: Wallet deployer address: 0x82180b6EF1245318E631E18B391CD7b4a0C216B0
GEMFORGE: Load existing deployment ...
GEMFORGE:    Existing deployment found at: 0xE59350a5F03d5A29666eBA977a7122C26CDC3dB2
GEMFORGE: Checking if existing deployment is still valid...
GEMFORGE: Verifying contract DiamondProxy deployed at 0xE59350a5F03d5A29666eBA977a7122C26CDC3dB2 ...
Start verifying contract `0xE59350a5F03d5A29666eBA977a7122C26CDC3dB2` deployed on mainnet

Contract [src/generated/DiamondProxy.sol:DiamondProxy] "0xE59350a5F03d5A29666eBA977a7122C26CDC3dB2" is already verified. Skipping verification.
GEMFORGE: ...verified.
```

--------------------------------

### Gemforge Scaffold Initialization (Bash)

Source: https://gemforge.xyz/commands/scaffold

Sets up a minimal demo project with Gemforge in the current directory. This command acts as a starting point for new projects, saving setup time by providing a pre-configured environment for Foundry or Hardhat.

```bash
gemforge scaffold 

```

--------------------------------

### Scaffold a New Gemforge Project

Source: https://gemforge.xyz/getting-started

Generates new Diamond smart contract project scaffolding in a specified folder. This command is useful for starting a new project or creating example projects.

```bash
gemforge scaffold --folder /path/to/new_or_empty_folder
```

--------------------------------

### Install Gemforge Globally using pnpm

Source: https://gemforge.xyz/getting-started

Installs the Gemforge CLI globally on your system using the pnpm package manager. Requires Node.js v16 or above. This command makes the `gemforge` executable available in your terminal.

```bash
pnpm add --global gemforge
```

--------------------------------

### Build Gemforge Contracts

Source: https://gemforge.xyz/getting-started

Generates all necessary Diamond code and compiles the project contracts. This command should be run from within the project folder after setup or initialization.

```bash
gemforge build
```

--------------------------------

### Start Local Mainnet Fork with Anvil

Source: https://gemforge.xyz/development/simulating-upgrades

This command starts a local fork of the Ethereum Mainnet using Anvil. It requires an Alchemy API key to be set in the environment variable `ALCHEMY_API_KEY` to connect to the Mainnet RPC.

```bash
anvil --fork-url https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY
```

--------------------------------

### Gemforge Deployment State File Structure

Source: https://gemforge.xyz/commands/deploy

Example structure of the JSON file used to store the deployment state when pausing a Gemforge deployment. It includes facet cut information, initialization contract address, and initialization data.

```json
{
  "cuts": [
    {
      "facetAddress": "0x0000000000000000000000000000000000000000",
      "action": 2,
      "functionSelectors": [
        "0xbf9f7311"
      ]
    }
    // ...
 ],
  "initContractAddress": "0x0000000000000000000000000000000000000000",
  "initData": "0x"
}
```

--------------------------------

### Gemforge Deployment Records JSON Structure

Source: https://gemforge.xyz/commands/deploy

The `gemforge.deployments.json` file stores addresses, constructor arguments, and transaction hashes for deployed contracts per target. This JSON structure illustrates an example of these deployment records for 'local' and 'testnet' chains.

```json
{
  "local": {
    "chainId": 31337,
    "contracts": [
      {
        "name": "DiamondProxy",
        "fullyQualifiedName": "contracts/generated/DiamondProxy.sol:DiamondProxy",
        "sender": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
        "txHash": "0x4a304d29c18e4e3d9e8194f63d1d4e484304b9079f0d390ac3c06a8790c1494b",
        "onChain": {
          "address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
          "constructorArgs": [
            "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
          ]
        }
      }
    ]
  },
  "testnet": {
    "chainId": 11155111,
    "contracts": [
      {
        "name": "DiamondProxy",
        "fullyQualifiedName": "contracts/generated/DiamondProxy.sol:DiamondProxy",
        "sender": "0xb1B6e377aA6ec6928A1D499AE58483B2B99658Ec",
        "txHash": "0xf2e22d2e01c637cfb0f8996a762574ed15046d5ad745f826b547ee74e1e67f4b",
        "onChain": {
          "address": "0xA91C335D79b8401E1df5FA9D5C1D441f963F8eB0",
          "constructorArgs": [
            "0xb1B6e377aA6ec6928A1D499AE58483B2B99658Ec"
          ]
        }
      }
    ]
  }
}
```

--------------------------------

### Solidity Contract for Initial Diamond Setup

Source: https://gemforge.xyz/development/initialization

This Solidity contract defines the `init` function which is called during the initial deployment of a Diamond. It accesses and modifies the application's storage, taking an initial value as an argument.

```solidity
// file: src/init/InitDiamond.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;

import { AppStorage, LibAppStorage } from "../libs/LibAppStorage.sol";

contract InitDiamond {
  function init(uint initialValue) external {
    AppStorage storage s = LibAppStorage.diamondStorage();

    // update storage here
    s.var1 = initialValue
    // s.var2 = ...
  }
}
```

--------------------------------

### Configure Initial Diamond Deployment Initialization

Source: https://gemforge.xyz/development/initialization

This configuration sets up a specific contract and function to be called for initial setup of a Diamond. It specifies the contract name ('InitDiamond') and the function name ('init') to execute after the initial deployment.

```javascript
// file: gemforge.config.cjs
module.exports = {
  // ...
  diamond: {
    // ...
    // custom initialization call
    init: {
      // The diamond initialization contract name
      contract: 'InitDiamond',
      // The diamond initialization function name
      function: 'init',
    },
    // ...
  },
  // ...
}
```

--------------------------------

### Gemforge Query JSON Output Structure

Source: https://gemforge.xyz/commands/query

This snippet provides an example of the JSON output generated by the Gemforge 'query' command with the `--json` option. It details the structure of the data, including the proxy address, counts of unrecognized components, and a map of recognized facets with their associated functions and selectors.

```json
{
  "proxyAddress": "0x...",
  "unrecognizedFacets": 0,
  "unrecognizedFunctions": 0,
  "facets": {
    "DiamondCutFacet": {
      "address": "0x...",
      "functions": [
        {
          "name": "diamondCut",
          "selector": "0x1f931c1c"
        }
      ]
    }
    // ...
  }
}
```

--------------------------------

### Gemforge Output for Manual Upgrade Transaction

Source: https://gemforge.xyz/development/multisig

This console output example demonstrates the format of the transaction parameters and data that Gemforge provides when `manualCut` is enabled. It includes the Diamond proxy address and the raw transaction data (`Tx data`) required for the manual upgrade. This output is intended to be copied and pasted into a multisig/MPC wallet's transaction builder.

```log
GEMFORGE: Outputting upgrade tx params and skipping actual tx call...

GEMFORGE: ================================================================================

GEMFORGE: Diamond: 0x3351cb6fD12655854DDAa85b0D9857d3e20a1310

GEMFORGE: Tx data: 0x1f931c1c0000000...00000000000000000

GEMFORGE: ================================================================================
```

--------------------------------

### Gemforge Query Output to File

Source: https://gemforge.xyz/commands/query

This snippet illustrates how to redirect the query output to a specified file using the `--output <file>` option. This is particularly useful when combined with the `--json` option to save structured data for later use. The example shows saving the JSON output to './query-result.txt'.

```bash
gemforge query local --json --output ./query-result.txt
```

--------------------------------

### Define and Import Custom Structs for Gemforge Proxy Interface

Source: https://gemforge.xyz/development/custom-structs

This example demonstrates defining a custom struct in a separate Solidity file, importing it into a facet contract, and configuring Gemforge to include this import in the generated diamond proxy interface. This ensures that methods using custom structs compile correctly.

```solidity
// file: src/Structs.sol
struct GameParams {
  uint maxPlayers;
}

```

```solidity
// file: src/MyFacet.sol
import "Structs.sol";

contract MyFacet {
  function createGame(GameParams memory params);
}

```

```javascript
// file: gemforge.config.cjs
module.exports = {
  ...
  generator: {
    // proxy interface options
    proxyInterface: {
      // imports to include in the generated IDiamondProxy interface
      imports: [
        "src/Structs.sol"
      ],
    },
  },
  ...
}

```

```solidity
// file: src/generated/IDiamondProxy.sol

import "../Structs.sol";

interface IDiamondProxy {
  function createGame(GameParams memory params); // will successfully compile!
}

```

--------------------------------

### Share Code with Libraries in Solidity

Source: https://gemforge.xyz/development/facets

Illustrates sharing common functionality across Solidity facets using internal libraries. This method is suitable for encapsulating reusable logic that can be called from multiple contracts without requiring inheritance. The example shows a library with a calculation function used by two facets.

```solidity
// file: src/libs/LibCalculator.sol
library LibCalculator {
  function calculateVal(uint i) internal pure returns (uint) {
    return 123 + i;
  }
}

// file: src/facets/FirstFacet.sol
contract FirstFacet {
  function getVal1(uint a) external pure returns (uint) {
    return LibCalculator.calculateVal(a);
  }
}

// file: src/facets/SecondFacet.sol
contract SecondFacet {
  function getVal2(uint b) external pure returns (uint) {
    return LibCalculator.calculateVal(b);
  }
}
```

--------------------------------

### Safe and Unsafe Storage Variable Modifications in Solidity

Source: https://gemforge.xyz/development/storage

Illustrates the rules for safely adding new variables to storage structs in a deployed Diamond. Variables must only be appended to the end of a struct to avoid memory corruption. Examples show correct and incorrect methods for extending `PlayerGameResult`, `Player`, and `AppStorage` structs.

```solidity
struct PlayerGameResult {
  uint score;  // <- BAD, will cause memory conflicts!!!
  boolean won;
  uint playTime; // <- Good, since it's added at the end of the AppStorage struct
}

struct Player {
  address wallet;
  uint currentGame;  // <- BAD, will cause memory conflicts!!!
  mapping(uint => PlayerGameResult);
  uint numGamesWon; // <- Good, since it's added at the end of the AppStorage struct
}

struct AppStorage {
  uint numGames;
  uint numGamesInProgress; // <- BAD, will cause memory conflicts!!!
  mapping(address => Player) players;
  uint numGamesCompleted; // <- Good, since it's added at the end of the AppStorage struct
}

```

--------------------------------

### Gemforge CLI Help Output

Source: https://gemforge.xyz/getting-started

Displays the help information for the Gemforge command-line interface. This output lists available commands and global options, such as `init`, `scaffold`, `build`, and `deploy`.

```bash
> gemforge --help
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

```

--------------------------------

### Initialize Gemforge in an Existing Project

Source: https://gemforge.xyz/getting-started

Creates a `gemforge.config.cjs` configuration file in the current directory for an existing Diamond Standard project. This command assumes the project uses the diamond-2-hardhat reference repository.

```bash
gemforge init
```

--------------------------------

### Gemforge Help Command Overview

Source: https://gemforge.xyz/commands

Displays a list of available Gemforge commands and their general usage. This command is essential for understanding the scope of Gemforge's capabilities.

```shell
gemforge --help
```

--------------------------------

### Gemforge Configuration for Omni-chain Deployment (gemforge.config.cjs)

Source: https://gemforge.xyz/development/omni-chain-addresses

This configuration file demonstrates how to set up wallets and targets for omni-chain deployments using Gemforge. It specifies the wallet, network, initialization arguments, and the CREATE3 salt, which is crucial for ensuring the Diamond proxy contract is deployed to the same address on multiple chains.

```javascript
// gemforge.config.cjs

const WALLET = 'wallet1'
const SALT =
"0xf8aac9c60a8577e3e439a5639f65f9eca367e2c6de7086f4b4076c0a895d1902";

module.exports = {
  ...
  wallets: {
    [WALLET]: {...}
  },
  ...
  targets: {
    mainnet: {
      // Ethereum Mainnet chain
      network: 'mainnet', 
      wallet: WALLET,
      initArgs: []
      create3Salt: SALT,
    },
    base: {
      // BASE chain
      network: 'base', 
      wallet: WALLET, // same wallet
      initArgs: [],
      create3Salt: SALT, // same salt
    }
  }
  ...
}
```

--------------------------------

### Gemforge Specific Command Help

Source: https://gemforge.xyz/commands

Provides detailed usage information for a specific Gemforge command, including its options and purpose. This is useful for understanding how to configure and execute individual commands.

```shell
gemforge init --help
```

--------------------------------

### Deploy to Local Mainnet Fork with Gemforge

Source: https://gemforge.xyz/development/simulating-upgrades

This command deploys your contract to the locally running Mainnet fork using Gemforge. This allows you to simulate upgrades and test changes before deploying to the live Mainnet.

```bash
gemforge deploy mainnetFork
```

--------------------------------

### Gemforge Scaffold Initialization in Specific Folder (Bash)

Source: https://gemforge.xyz/commands/scaffold

Sets up a minimal demo project with Gemforge in a specified folder. This command allows users to choose the directory for their new project's scaffold, automatically creating the folder if it does not exist. Gemforge will warn if the target folder is not empty.

```bash
gemforge scaffold --folder /path/to/folder

```

--------------------------------

### Gemforge Deploy Command (CLI)

Source: https://gemforge.xyz/configuration/targets

Command-line interface command to deploy contracts to a specified Gemforge target. This is the primary method for initiating contract deployments after configuration.

```bash
gemforge deploy testnet
```

--------------------------------

### Gemforge Target Configuration (JavaScript)

Source: https://gemforge.xyz/configuration/targets

Defines deployment targets for Gemforge, specifying network, wallet, initialization arguments, and optional CREATE3 salt and upgrade configurations. This configuration is essential for managing deployments to different environments.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  targets: {
    // Target named "local"
    local: {
      // Network to deploy to
      network: 'local',
      // Wallet to use for deployment
      wallet: 'wallet1',
      // Initialization method arguments
      initArgs: []
      // OPTIONAL - CREATE3 salt. If empty or ommitted a random SALT is used.
      create3Salt: '0x...'
    },
    // Target named "testnet"
    testnet: {
      // Network to deploy to
      network: 'sepolia',
      // Wallet to use for deployment
      wallet: 'wallet2',
      // Initialization method arguments
      initArgs: [],
      // OPTIONAL - CREATE3 salt. If empty or ommitted a random SALT is used.
      create3Salt: '0x...'
      // OPTIONAL - Configuration for upgrades
      upgrades: {
        // Whether Gemforge should skip the diamondCut() call so that it can be done manually.
        manualCut: true
      }
    }
  }
  ...
}
```

--------------------------------

### Run Gemforge Verify Command

Source: https://gemforge.xyz/commands/verify

This command verifies the source code of deployed contracts on Etherscan and similar block explorers. It requires a `<target>` argument, which must be defined in the targets configuration. The command queries deployment records and sends source-code verification calls to the configured block explorer's API. It assumes contract artifacts are available in the build output folder.

```bash
gemforge verify <target>
```

--------------------------------

### Initialize Gemforge Configuration (CLI)

Source: https://gemforge.xyz/commands/init

Initializes a Gemforge configuration file (`gemforge.config.cjs`) for an existing Diamond standard project. This command allows Gemforge to interact with your project. It assumes standard Diamond libraries and core facets are present. The config file name can be customized using the `--name` option, but the `.cjs` extension is required.

```bash
gemforge init
```

```bash
gemforge init --name <custom_file_name>
```

--------------------------------

### Deploy Gemforge Contracts to Local Network

Source: https://gemforge.xyz/getting-started

Deploys the built Diamond code and facets to a local test node running at http://localhost:8545. This command is used for testing deployment processes.

```bash
gemforge deploy local
```

--------------------------------

### Initialize Diamond Storage with LibAppStorage.sol

Source: https://gemforge.xyz/development/storage

Demonstrates how to define and access application storage within a Diamond using the `LibAppStorage` library. This pattern ensures flexibility and ease of use for data management. It utilizes assembly for direct slot manipulation.

```solidity
struct AppStorage {
  bool diamondInitialzied;
  // ...other storage variables here
}

library LibAppStorage {
    bytes32 internal constant DIAMOND_APP_STORAGE_POSITION = keccak256("diamond.app.storage");

    function diamondStorage() internal pure returns (AppStorage storage ds) {
        bytes32 position = DIAMOND_APP_STORAGE_POSITION;
        assembly {
            ds.slot := position
        }
    }
}

```

```solidity
AppStorage storage s = LibAppStorage.diamondStorage();
return s.diamondInitialzied;

```

--------------------------------

### Upgrade Initialization Command-Line Parameters

Source: https://gemforge.xyz/development/initialization

These command-line parameters are used to specify a contract and method for initialization during a Diamond upgrade. Gemforge will deploy the specified contract and execute the method in the Diamond's context. The method is expected to take no arguments.

```bash
gemforge deploy <target>
  --upgrade-init-contract <contract name> 
  --upgrade-init-method <contract method name>
```

--------------------------------

### Custom Upgrade Initialization with Gemforge

Source: https://gemforge.xyz/commands/deploy

Utilize `--upgrade-init-*` parameters to run custom initialization code during a Diamond upgrade. Specify the contract and method using `--upgrade-init-contract` and `--upgrade-init-method`. The method must not take any arguments.

```bash
gemforge deploy <target> \
  --upgrade-init-contract <contract name> \
  --upgrade-init-method <contract method name>
```

--------------------------------

### Update Gemforge Deployments for Mainnet Forking

Source: https://gemforge.xyz/development/simulating-upgrades

This snippet demonstrates how to update the `gemforge.deployments.json` file to include entries for the `mainnetFork`. It requires duplicating the contract deployment details from the `mainnet` entry to the `mainnetFork` entry.

```json
// File: gemforge.deployments.json
{
  "mainnet": {
    "chainId": 1,
    "contracts": /*...*/
  },
  "mainnetFork": {
    // Should be a copy of everything under the "mainnet" key above
  }
}
```

--------------------------------

### Resume Gemforge Deployment from File

Source: https://gemforge.xyz/commands/deploy

Resumes a previously paused Gemforge deployment using the state saved in a JSON file. This command will apply the facet cuts and complete the deployment process. Post-build hooks are executed upon successful resumption.

```shell
gemforge deploy <target> --resume-cut-from-file cut.json
```

--------------------------------

### Configure Gemforge for Mainnet Forking

Source: https://gemforge.xyz/development/simulating-upgrades

This snippet shows how to configure Gemforge to use a local fork of the Mainnet. It involves setting up network configurations and target definitions within `gemforge.config.cjs`. Ensure the `rpcUrl` for `mainnetFork` points to your local RPC endpoint.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  networks: {
    mainnet: {
      rpcUrl: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
    },
    mainnetFork: {
      rpcUrl: `http://localhost:8545/`,
    }
  },
  targets: {
    mainnet: {
      network: 'mainnet',
      wallet: 'wallet1',
      initArgs: []
    },
    mainnetFork: {
      network: 'mainnetFork',
      wallet: 'wallet1',
      initArgs: []
    }
  }
  ...
}
```

--------------------------------

### Configure Target-Specific Initialization Arguments

Source: https://gemforge.xyz/development/initialization

This configuration specifies the arguments to be passed to the initialization function for different deployment targets. It allows for distinct initialization parameters for each target, such as 'local' and 'testnet'.

```javascript
// file: gemforge.config.cjs
module.exports = {
  ...
  targets: {
    local: {
      network: 'local',
      wallet: 'wallet1',
      initArgs: [1] // initialValue = 1
    },
    testnet: {
      network: 'sepolia',
      wallet: 'wallet2',
      initArgs: [2] // initialValue = 2
    }
  }
  ...
}
```

--------------------------------

### Solidity Contract for Upgrade Initialization

Source: https://gemforge.xyz/development/initialization

This Solidity contract demonstrates how to implement initialization logic that should only run once during an upgrade. It checks a storage variable to ensure the function has not been executed previously, preventing redundant operations.

```solidity
// file: src/init/UpgradeInit1.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;

import { AppStorage, LibAppStorage } from "../libs/LibAppStorage.sol";

contract UpgradeInit1 {
  function init() external {
    AppStorage storage s = LibAppStorage.diamondStorage();
    if (s.upgradeInit1Executed) {
      revert("UpgradeInit1 already executed");
    }
    s.upgradeInit1Executed = true;

    // do more stuff here...
  }
}
```

--------------------------------

### Deploy Diamond Contracts with Gemforge

Source: https://gemforge.xyz/commands/deploy

The `gemforge deploy <target>` command deploys or upgrades Diamond contracts on a network. It automatically detects changes and upgrades the proxy, or performs a new deployment if none exists. The `<target>` must be defined in the targets configuration.

```bash
gemforge deploy <target>
```

--------------------------------

### CREATE3 Factory ABI

Source: https://gemforge.xyz/development/omni-chain-addresses

The Application Binary Interface (ABI) for the CREATE3 factory contract. This ABI defines the functions available for interacting with the factory, specifically `deploy` for deploying contracts and `getDeployed` for checking the deployment address.

```json
/** Deploy a contract using the given salt value, with msg.sender as the deployer. */
function deploy(bytes32 salt, bytes memory creationCode) external payable returns (address deployed);
/** Calcualate the address at which the following deployer wallet and salt value would deploy a contract. */
function getDeployed(address deployer, bytes32 salt) external view returns (address deployed);
```

--------------------------------

### Gemforge Query Command Usage

Source: https://gemforge.xyz/commands/query

This snippet shows the basic command-line usage for querying a Diamond contract. It requires a target network or environment to be specified. The command queries on-chain data and matches it with local contract artifacts.

```bash
gemforge query <target>
```

--------------------------------

### Gemforge Upgrade Configuration (JavaScript)

Source: https://gemforge.xyz/configuration/targets

Configures Gemforge to handle contract upgrades, specifically allowing for manual execution of the `diamondCut()` function. This enhances security by enabling pre-execution review of upgrade transactions.

```javascript
targets: {
  // Target named "main"
  main: {
    upgrades: {
      // Whether the diamondCut() call will be done manually.
      manualCut: true
    }
  }
}
```

--------------------------------

### Force Fresh Deployment with Gemforge

Source: https://gemforge.xyz/commands/deploy

Use the `--new` CLI argument with `gemforge deploy <target> --new` to force a fresh deployment of the Diamond and its facets, disregarding any existing on-chain Diamond. This will replace existing deployment records.

```bash
gemforge deploy <target> --new
```

--------------------------------

### Configure Gemforge Build and Deploy Hooks

Source: https://gemforge.xyz/configuration/hooks

Defines shell commands to be executed as pre- and post- hooks for build and deploy operations in Gemforge. These are configured within the gemforge.config.cjs file.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  hooks: {
    // shell command to execute before build
    preBuild: 'echo "pre-build"',
    // shell command to execute after build
    postBuild: 'echo "post-build"',
    // shell command to execute before deploy
    preDeploy: 'echo "pre-deploy"',
    // shell command to execute after deploy
    postDeploy: 'echo "post-deploy"',
  },
  ...
}
```

--------------------------------

### Configure Gemforge Project Paths

Source: https://gemforge.xyz/configuration/paths

This Javascript configuration snippet defines the 'paths' object for a Gemforge project. It specifies locations for built artifacts, source files (including facet patterns), generated Solidity files and support scripts, deployment records, and library dependencies like diamond-2-hardhat. Ensure these paths align with your project structure.

```javascript
module.exports = {
  ...
  paths: {
    // contract built artifacts folder
    artifacts: 'out',
    // source files
    src: {
      // file patterns to include in facet parsing
      facets: [
        // include all .sol files in the facets directory ending "Facet"
        'src/facets/*Facet.sol'
      ],
    },
    // folders for gemforge-generated files
    generated: {
      // output folder for generated .sol files
      solidity: 'src/generated',
      // output folder for support scripts and files
      support: '.gemforge',
      // deployments JSON file
      deployments: 'gemforge.deployments.json',
    },
    // library files
    lib: {
      // diamond library
      diamond: 'lib/diamond-2-hardhat',
    }
  },
  ...
}

```

--------------------------------

### Configure Gemforge Networks (JavaScript/CJS)

Source: https://gemforge.xyz/configuration/networks

This snippet shows how to configure network settings for Gemforge projects. It includes defining RPC URLs for local and test networks, and optional contract verification settings for Foundry and Hardhat.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  networks: {
    // Local network
    local: {
      // RPC endpoint URL
      rpcUrl: 'http://localhost:8545',
    },
    // Base Sepolia test network
    base_sepolia: {
      // RPC endpoint URL
      rpcUrl: () => process.env.BASE_SEPOLIA_RPC_URL,
      // OPTIONAL: Contract source code verification - takes place as soon as any contract is deployed by Gemforge
      contractVerification: {
        // if using Foundry
        foundry: {
          // URL to block explorer contract source submission API
          apiUrl: 'https://api-sepolia.basescan.org/api',
          // secret API key to use when submitting
          apiKey: () => process.env.BASESCAN_API_KEY,
        },
        // if using Hardhat
        hardhat: {
          networkId: 'baseSepolia' // name of network as defined in hardhat config file
        },
      },
    },
  },
  ...
}
```

--------------------------------

### Perform Dry Run Deployment with Gemforge

Source: https://gemforge.xyz/commands/deploy

The `--dry` option (`gemforge deploy <target> --dry`) simulates a deployment without making any on-chain changes. It provides useful logging to show what actions would be taken, applicable to deployments, upgrades, resets, and fresh deployments.

```bash
gemforge deploy <target> --dry
```

--------------------------------

### Pause Gemforge Deployment to File

Source: https://gemforge.xyz/commands/deploy

Pauses a Gemforge deployment and saves the state to a specified JSON file. This allows for manual intervention before completing the deployment, such as approving upgrades. The output file contains the facet cut data.

```shell
gemforge deploy <target> --pause-cut-to-file cut.json
```

--------------------------------

### Solidity Compiler Header - Gemforge

Source: https://gemforge.xyz/configuration/compiler

All generated Solidity files by Gemforge include these two standard header lines. These lines specify the SPDX license identifier and the compatible Solidity compiler version, ensuring compliance and proper compilation.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;

```

--------------------------------

### Configure Manual Multisig Upgrades in Gemforge

Source: https://gemforge.xyz/development/multisig

This configuration snippet shows how to set the `manualCut` option to `true` within the `targets.main.upgrades` configuration. This instructs Gemforge to output the raw transaction data for `diamondCut()` instead of executing it directly, allowing for manual signing and sending from a multisig or MPC wallet. No external dependencies are required for this configuration.

```yaml
targets:
  main:
    upgrades:
      manualCut: true
```

--------------------------------

### Gemforge Query JSON Output

Source: https://gemforge.xyz/commands/query

This snippet demonstrates how to obtain a JSON representation of the query results using the `--json` CLI option. This structured output is useful for programmatic analysis and integration with other tools. The output includes the proxy address, unrecognized facets/functions, and a detailed breakdown of recognized facets and their functions.

```bash
gemforge query local --json
```

--------------------------------

### Gemforge Compiler Configuration - gemforge.config.cjs

Source: https://gemforge.xyz/configuration/compiler

This configuration snippet shows how to set the SPDX license and Solidity compiler version within the `gemforge.config.cjs` file. These settings are crucial for controlling the header information in all generated Solidity source files.

```javascript
// gemforge.config.cjs
module.exports = {
  ... ,
  solc: {
    // SPDX License - to be inserted in all generated .sol files
    license: 'MIT',
    // Solidity compiler version - to be inserted in all generated .sol files
    version: '0.8.21',
  },
  ...
}

```

--------------------------------

### Gemforge Configuration for Source Code Verification (General)

Source: https://gemforge.xyz/development/source-verification

This configuration snippet shows how to enable contract source code verification for a specific network within the Gemforge configuration file. The `contractVerification` key must be present for verification to occur. If verification fails, Gemforge will stop the deployment process.

```javascript
// File: gemforge.config.cjs
module.exports = {
  ...
  networks: {
    ...
    // Base Sepolia test network
    base_sepolia: {
      // RPC endpoint URL
      rpcUrl: 'https://sepolia.base.org',
      // Contract source code verification will take place for targets using this network if this key is present!
      contractVerification: {
        // ... configuration here!
      },
    },
  },
  ...
}
```

--------------------------------

### Hardhat Configuration for Etherscan Verification

Source: https://gemforge.xyz/development/source-verification

This Hardhat configuration file sets up network details and Etherscan integration for source code verification. It defines the network's RPC URL, chain ID, and API endpoints, including a custom chain configuration for Base Sepolia.

```typescript
// File: hardhat.config.ts
require("dotenv").config();
import type { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config: HardhatUserConfig = {
  solidity: "0.8.21",
  networks: {
    baseSepolia: {
      url: 'https://sepolia.base.org',
    }
  },
  etherscan: {
    apiKey: {
      baseSepolia: process.env.BASESCAN_API_KEY
    },
    customChains: [
      {
        network: "baseSepolia",
        chainId: 84532,
        urls: {
          apiURL: "https://api-sepolia.basescan.org/api",
          browserURL: "https://sepolia.basescan.org"
        }
      }
    ]    
  },
};

export default config;
```

--------------------------------

### Configure Diamond Initialization and Core Facets in Gemforge

Source: https://gemforge.xyz/configuration/diamond

This Javascript configuration snippet defines settings for the 'diamond' object within a Gemforge project. It specifies whether to include public methods in the IDiamondProxy interface, configures an optional diamond initialization contract and function, and lists the core facet contracts and protected method selectors that should not be removed during upgrades.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  diamond: {
    // Whether to include public methods when generating the IDiamondProxy interface. Default is to only include external methods.
    publicMethods: false,
    // OPTIONAL - The diamond initialization contract - to be called when first deploying the diamond.
    init: {
      // The diamond initialization contract name
      contract: 'InitDiamond',
      // The diamond initialization function name
      function: 'init',
    },
    // Names of core facet contracts - these will not be modified/removed once deployed.
    // This default list is based on the diamond-2-hardhat library.
    // NOTE: WE RECOMMEND NOT CHANGING ANY OF THESE EXISTING NAMES UNLESS YOU KNOW WHAT YOU ARE DOING.
    coreFacets: [
      'OwnershipFacet',
      'DiamondCutFacet',
      'DiamondLoupeFacet',
    ],
    // Function selectors that should NEVER be removed from the diamond.
    // The default list is all the external methods of the default list of core facets defined above.
    // NOTE: This is an array of function selectors, not method names.
    protectedMethods: [
      '0x8da5cb5b', // OwnershipFacet.owner()
      '0xf2fde38b', // OwnershipFacet.transferOwnership()
      '0x1f931c1c', // DiamondCutFacet.diamondCut()
      '0x7a0ed627', // DiamondLoupeFacet.facets()
      '0xcdffacc6', // DiamondLoupeFacet.facetAddress()
      '0x52ef6b2c', // DiamondLoupeFacet.facetAddresses()
      '0xadfca15e', // DiamondLoupeFacet.facetFunctionSelectors()
      '0x01ffc9a7', // DiamondLoupeFacet.supportsInterface()
    ],
  },
  ...
}
```

--------------------------------

### Gemforge Verbose Logging

Source: https://gemforge.xyz/commands

Enables verbose logging output for a Gemforge command, providing detailed information about the execution process. This is useful for debugging and understanding command execution flow.

```shell
gemforge build -v
```

--------------------------------

### Gemforge Configuration with Dotenv Package (Node.js)

Source: https://gemforge.xyz/configuration/security

Illustrates how to use the `dotenv` package to load environment variables from a `.env` file into your Gemforge configuration. This method simplifies managing environment-specific secrets, such as mnemonic phrases, by keeping them in a separate file. Remember to add `.env` to your `.gitignore`.

```javascript
require('dotenv').config();
module.exports = {
  // ... process.env.MNEMONIC will now be set
}
```

--------------------------------

### Configure Mnemonic and Private Key Wallets (JavaScript)

Source: https://gemforge.xyz/configuration/wallets

This snippet demonstrates how to configure different wallet types, specifically 'mnemonic' and 'private-key', within the Gemforge configuration file. It shows the structure for defining wallet names, types, and their respective configuration parameters such as mnemonic phrases or private keys. The configuration can also accept functions to dynamically retrieve sensitive credentials.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  wallets: {
    // Wallet named "wallet1"
    wallet1: {
      // Wallet type - mnemonic
      type: 'mnemonic',
      // Wallet config
      config: {
        // Mnemonic phrase
        words: 'your menomonic phrase here',
        // 0-based index of the account to use
        index: 0,
      }
    },
    wallet2: {
      // Wallet type - private key
      type: 'private-key',
      // Wallet config
      config: {
        // Private key
        key: '0x....',
      },
    },
    // ...
    // add more wallets here
    // ...
  },
  ...
}
```

```javascript
config: {
  words: () => 'my mnemonic ...'
}
```

```javascript
config: {
  key: () => '0x...'
}
```

--------------------------------

### CREATE3 Factory Raw Signed Transaction

Source: https://gemforge.xyz/development/omni-chain-addresses

This is a raw signed transaction to deploy the CREATE3 factory contract. It's used when manually deploying the factory on a new chain, ensuring that sufficient funds are present in the deploying wallet and the transaction is correctly signed.

```blockchain
0xf903f68085174876e800830557308080b903a3608060405234801561000f575f80fd5b506103868061001d5f395ff3fe608060405260043610610028575f3560e01c806350f1c4641461002c578063cdcb760a14610074575b5f80fd5b348015610037575f80fd5b5061004b61004636600461020e565b610087565b60405173ffffffffffffffffffffffffffffffffffffffff909116815260200160405180910390f35b61004b61008236600461027d565b6100ea565b6040517fffffffffffffffffffffffffffffffffffffffff000000000000000000000000606084901b166020820152603481018290525f906054016040516020818303038152906040528051906020012091506100e382610147565b9392505050565b6040517fffffffffffffffffffffffffffffffffffffffff0000000000000000000000003360601b166020820152603481018390525f906054016040516020818303038152906040528051906020012092506100e383833461019c565b5f604051305f5260ff600b53826020527f21c35dbe1b344a2488cf3321d6ce542f8e9f305544ff09e4993a62319a497c1f6040526055600b20601452806040525061d6945f52600160345350506017601e2090565b5f6f67363d3d37363d34f03d5260086018f35f52836010805ff5806101c85763301164255f526004601cfd5b8060145261d6945f5260016034536017601e2091505f8085516020870186855af16101fa576319b991a85f526004601cfd5b50803b6100e3576319b991a85f526004601cfd5b5f806040838503121561021f575f80fd5b823573ffffffffffffffffffffffffffffffffffffffff81168114610242575f80fd5b946020939093013593505050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b5f806040838503121561028e575f80fd5b82359150602083013567ffffffffffffffff808211156102ac575f80fd5b818501915085601f8301126102bf575f80fd5b8135818111156102d1576102d1610250565b604051601f82017fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0908116603f0116810190838211818310171561031757610317610250565b8160405282815288602084870101111561032f575f80fd5b826020860160208301375f602084830101528095505050505050925092905056fea2646970667358221220992118230e4c9ffed4926da567e9fee8d8a102c65d41aa5ee3579d36ca97124164736f6c634300081500331ba03333333333333333333333333333333333333333333333333333333333333333a03333333333333333333333333333333333333333333333333333333333333333
```

--------------------------------

### Reset Diamond Contracts with Gemforge

Source: https://gemforge.xyz/commands/deploy

The `--reset` argument (`gemforge deploy <target> --reset`) allows you to reset an existing Diamond to a fresh state by removing all non-core facet selectors. This deploys current facet contracts afresh while keeping the Diamond contract deployment record unchanged.

```bash
gemforge deploy <target> --reset
```

--------------------------------

### Gemforge Configuration for Foundry Source Code Verification

Source: https://gemforge.xyz/development/source-verification

This configuration enables source code verification for Foundry projects within Gemforge. It requires specifying the block explorer's API submission URL and an API key, retrieved from the block explorer's service. Failure during this process will halt the deployment.

```javascript
// File: gemforge.config.cjs
module.exports = {
  ...
  networks: {
    ...
    // Base Sepolia test network
    base_sepolia: {
      // RPC endpoint URL
      rpcUrl: 'https://sepolia.base.org',
      // Contract source code verification will take place for targets using this network
      contractVerification: {
        // if using Foundry
        foundry: {
          // URL to block explorer contract source submission API
          apiUrl: 'https://api-sepolia.basescan.org/api',
          // secret API key to use when submitting (get this by signing up on Basescan.org)
          apiKey: () => process.env.BASESCAN_API_KEY,
        },
      },
    },
  },
  ...
}
```

--------------------------------

### Configure Gemforge Generator Proxy Options (JavaScript)

Source: https://gemforge.xyz/configuration/generator

This snippet shows how to configure the generator section in the `gemforge.config.cjs` file, specifically for proxy contract options. It includes settings for a custom proxy template and imports for the proxy interface. This configuration allows for advanced customization of the generated proxy contract.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  generator: {
    // OPTIONAL - proxy contract (DiamondProxy.sol) options
    proxy: {
      // custom template to use instead of the Gemforge default one
      template: '/path/to/custom-DiamondProxy-template.sol'
    },
    // proxy interface options
    proxyInterface: {
      // imports to include in the generated IDiamondProxy interface
      imports: []
    },
  },
  ...
}
```

--------------------------------

### Gemforge Wallet Configuration with Environment Variables (Node.js)

Source: https://gemforge.xyz/configuration/security

Demonstrates how to configure a wallet in Gemforge using a mnemonic phrase loaded from an environment variable. This approach avoids storing sensitive seed phrases directly in the configuration file, enhancing security. It assumes the `MNEMONIC` environment variable is set.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  wallets: {
    wallet1: {
      // Wallet type - mnemonic
      type: 'mnemonic',
      // Wallet config
      config: {
        // Mnemonic phrase
        words: () => process.env.MNEMONIC,
        // 0-based index of the account to use
        index: 0,
      },
    },
  },
  ...
}
```

--------------------------------

### Gemforge Configuration for Hardhat Source Code Verification

Source: https://gemforge.xyz/development/source-verification

This configuration enables source code verification for Hardhat projects within Gemforge. It requires specifying the network ID as defined in the Hardhat configuration file. This allows Gemforge to correctly map the network for verification purposes.

```javascript
// File: gemforge.config.cjs
module.exports = {
  ...
  networks: {
    ...
    // Base Sepolia test network
    base_sepolia: {
      // RPC endpoint URL
      rpcUrl: 'https://sepolia.base.org',
      // Contract source code verification will take place for targets using this network
      contractVerification: {
        // if using hardhat
        hardhat: {
          // name of network as defined in the hardhat configuration file
          networkId: 'baseSepolia'
        },
      },
    },
  },
  ...
}
```

--------------------------------

### Share Code with Abstract Base Contract in Solidity

Source: https://gemforge.xyz/development/facets

Demonstrates how to share common logic between multiple Solidity facets by inheriting from an abstract base contract. This approach helps maintain code organization and reusability. The base contract defines an internal pure function, which is then utilized by derived facet contracts.

```solidity
// file: src/shared/FacetBase.sol
abstract contract FacetBase {
  function calculateVal(uint i) internal pure returns (uint) {
    return 123 + i;
  }
}

// file: src/facets/FirstFacet.sol
contract FirstFacet is FacetBase {
  function getVal1(uint a) external pure returns (uint) {
    return calculateVal(a);
  }
}

// file: src/facets/SecondFacet.sol
contract SecondFacet is FacetBase {
  function getVal2(uint b) external pure returns (uint) {
    return calculateVal(b);
  }
}
```

--------------------------------

### Use Environment Variables in Gemforge Post-Deploy Hook

Source: https://gemforge.xyz/configuration/hooks

Demonstrates how to use environment variables passed by Gemforge into a post-deploy hook script. The GEMFORGE_DEPLOY_TARGET and GEMFORGE_DEPLOY_CHAIN_ID variables can be accessed and utilized within Node.js scripts.

```javascript
// gemforge.config.cjs
module.exports = {
  ...
  hooks: {
    postDeploy: 'node ./postDeployScript.js',
  }
  ...
}

// postDeployScript.js
console.log(`Deployed target: ${process.env.GEMFORGE_DEPLOY_TARGET}`);

```

--------------------------------

### Gemforge Quiet Logging

Source: https://gemforge.xyz/commands

Disables normal logging output for a Gemforge command, reducing the amount of information displayed during execution. Fatal errors will still be logged.

```shell
gemforge build -q
```
Tokens:
Raw