Add Network

Add a network to origin-dollar

Adding a network in this codebase is mechanical but spread across ~12–15 files. Follow this checklist top to bottom. Skip the (optional) items if you don't need fork tests / CI / Defender automation for the new network.

Working dir convention. All file paths below are relative to the repo root /Volumes/origin/origin-dollar/. Run all commands from contracts/.

0. Decide network classification

Up front, classify the network. This drives which files actually need touching:

Pick the answers before editing any files — they affect which sections below apply.

1. Gather constants

You'll need these before touching any file. Keep them in a scratch note:

• chainId (e.g., Sepolia = 11155111)
• providerURL env var name (e.g., SEPOLIA_PROVIDER_URL)
• CCIP chain selector (if using CCIP — look up at https://docs.chain.link/ccip/directory)
• Canonical bridge addresses (if L2 — L1StandardBridge, L2StandardBridge)
• Explorer URL + API key (or Blockscout-style endpoint)
• Deployer / governor / strategist EOAs or multisigs
• WETH / USDC / etc. token addresses (mainnet equivalents on the new chain)
• Per-network address registry contents the strategies will need

2. contracts/utils/hardhat-helpers.js

Add the network-detection flags and provider URL. Mirror the existing pattern for similar networks (e.g., if adding an L2 testnet, copy how holesky / hoodi look).

const isSepolia = process.env.NETWORK === "sepolia";
const isSepoliaFork = process.env.FORK_NETWORK_NAME === "sepolia";
const isSepoliaForkTest = isSepoliaFork && isForkTest;
const isSepoliaUnitTest = isSepolia && process.env.IS_TEST === "true";
// ...

const sepoliaProviderUrl = process.env.SEPOLIA_PROVIDER_URL || "";

Also branch in adjustTheForkBlockNumber() for the new network if you use BLOCK_NUMBER fork pinning.

Export everything at the bottom of the file so hardhat.config.js can import.

3. contracts/hardhat.config.js

Three sections to update:

(a) Imports — add the new flags + providerUrl to the destructure at the top:

const {
  // ... existing imports
  isSepolia,
  isSepoliaFork,
  isSepoliaForkTest,
  sepoliaProviderUrl,
} = require("./utils/hardhat-helpers.js");

(b) networks.<name> entry — within the networks config:

sepolia: {
  url: sepoliaProviderUrl,
  accounts: [
    process.env.DEPLOYER_PK || privateKeyPlaceholder,
    process.env.GOVERNOR_PK || privateKeyPlaceholder,
  ],
  chainId: 11155111,
  tags: ["sepolia"],
  live: true,
  saveDeployments: true,
},

(c) namedAccounts — add per-network deployer/governor/strategist indexes:

namedAccounts: {
  deployer: { default: 0, sepolia: 0, baseSepolia: 0, ... },
  governorAddr: { default: 1, sepolia: 1, baseSepolia: 1, ... },
  strategistAddr: { default: 2, sepolia: 2, baseSepolia: 2, ... },
},

(d) Etherscan verification — within etherscan config:

etherscan: {
  apiKey: {
    sepolia: process.env.ETHERSCAN_API_KEY,
    baseSepolia: process.env.ETHERSCAN_API_KEY,  // Etherscan V2 multichain key
    // ...
  },
  customChains: [
    // Add an entry if the network isn't built into hardhat-verify.
    {
      network: "baseSepolia",
      chainId: 84532,
      urls: {
        apiURL: "https://api-sepolia.basescan.org/api",
        browserURL: "https://sepolia.basescan.org",
      },
    },
  ],
},

4. contracts/package.json

Add per-network scripts. Minimum set:

{
  "scripts": {
    "deploy:sepolia": "hardhat deploy --network sepolia",
    "node:sepolia": "FORK=true FORK_NETWORK_NAME=sepolia hardhat node",
    "test:sepolia-fork": "FORK_NETWORK_NAME=sepolia bash fork-test.sh"
  }
}

If you'll have coverage runs or Anvil-based local nodes:

{
  "test:coverage:sepolia-fork": "REPORT_COVERAGE=true FORK_NETWORK_NAME=sepolia bash fork-test.sh",
  "node:anvil:sepolia": "anvil --fork-url $SEPOLIA_PROVIDER_URL"
}

5. contracts/utils/addresses.js

Add the new network and populate it with what the strategies need:

addresses.sepolia = {};
addresses.sepolia.WETH = "0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9";
addresses.sepolia.CCIPRouter = "0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59";
// ...

For L2s, document both sides of the lane in the L1's entry (e.g., the L1 side stores both Sepolia-side endpoints AND L1StandardBridge for the L2's rollup). Otherwise deploy scripts have to cross-reference and that gets brittle.

6. contracts/utils/deploy.js

Usually no changes. Check for any isMainnet* / isBase* style helper predicates inside withConfirmation or deployWithConfirmation that gate on network — mirror them if your new network needs the same behaviour.

7. contracts/fork-test.sh

Add an elif branch in the network-mapping switch (~line 30–60):

elif [[ $FORK_NETWORK_NAME == "sepolia" ]]; then
  PROVIDER_URL=$SEPOLIA_PROVIDER_URL;
  BLOCK_NUMBER=$SEPOLIA_BLOCK_NUMBER;
elif [[ $FORK_NETWORK_NAME == "baseSepolia" ]]; then
  PROVIDER_URL=$BASE_SEPOLIA_PROVIDER_URL;
  BLOCK_NUMBER=$BASE_SEPOLIA_BLOCK_NUMBER;

8. contracts/dev.env

Document the new env vars (this file is copied to .env for local dev):

SEPOLIA_PROVIDER_URL=
SEPOLIA_BLOCK_NUMBER=
BASE_SEPOLIA_PROVIDER_URL=
BASE_SEPOLIA_BLOCK_NUMBER=

9. contracts/deploy/{network}/

Create the directory and add numbered deploy scripts. Pattern from PR #2485 (Plume) and PR #2839 (HyperEVM):

• 001_mock_*.js — mocks if testnet (Mock vault, Mock OToken, etc.)
• 002_*.js … 00N_*.js — actual strategy / contract deploys
• Final script — wiring (authorise adapters, set caps, whitelist on vault)

Each script:

1. Exports a deployFunction async with (hre) signature.
2. Tags: {module.exports.tags = ["network-name", "specific-tag"]}.
3. Uses helpers from utils/deploy.js:
   • withConfirmation(promise) — awaits and logs.
   • deployWithConfirmation(name, args, contractName) — deploys with verify support.
   • deployProxyWithCreateX(name, args, salt, contractName) — CREATE3 for peer-parity addresses.