Add OUSD V3 and OETHb migration contracts

.claude/skills/add-network/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: add-network
+description: |
+  Checklist for adding a new EVM network (mainnet or testnet) to the
+  origin-dollar repo. Walks through every file that needs touching:
+  hardhat config, package.json scripts, utils/{addresses,hardhat-helpers}.js,
+  fork-test.sh, deploy/{network}/ directory, and (optionally) CI lanes. Use
+  when the user wants to add support for a new chain — e.g. "register
+  Sepolia", "add Hyperliquid", "wire up Mantle." References PR #2485 (Plume)
+  and PR #2839 (HyperEVM) as worked examples.
+when-to-use: |
+  - User asks to add support for a new chain in this repo.
+  - User wants to register a testnet for staging contracts before mainnet.
+  - User asks "what files do I need to change to add {chain}?"
+  - User refers to "the add-network skill" or invokes it directly.
+---
+
+# 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:
+
+| Dimension | Options | Affects |
+|---|---|---|
+| **Mainnet or testnet** | mainnet, testnet | Whether you bother with CI lanes; whether the network appears in top-level README's "Deployed on …" list. |
+| **L1 / L2 / sidechain** | L1, OP Stack rollup, ZK rollup, sidechain | Whether you need L1StandardBridge addresses, finality assumptions, canonical-bridge support. |
+| **Native asset** | ETH, custom token | Affects gas / fee plumbing in adapters and strategies. |
+| **Primary bridge protocols** | CCIP, CCTP, LayerZero, OP canonical, custom | Drives which adapters get deployed + what address constants you'll need. |
+| **EVM-compatible explorer** | Etherscan family, Blockscout, custom | Drives `etherscan.customChains` config. |
+
+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).
+
+```js
+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:
+
+```js
+const {
+  // ... existing imports
+  isSepolia,
+  isSepoliaFork,
+  isSepoliaForkTest,
+  sepoliaProviderUrl,
+} = require("./utils/hardhat-helpers.js");
+```
+
+**(b) `networks.<name>` entry** — within the `networks` config:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```js
+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):
+
+```bash
+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.
+
+## 10. `contracts/deployments/{network}/`
+
+This directory is auto-created by `hardhat-deploy` on first run. To make it
+explicit and discoverable, commit a stub `.chainId` file with the chain ID:
+
+```
+$ echo "11155111" > contracts/deployments/sepolia/.chainId
+```
+
+## 11. `contracts/test/helpers.js` (only if fork/unit tests follow)
+
+Add to the `network detection` flags block (~line 314–328):
+
+```js
+const isSepolia = hre.network.name === "sepolia";
+const isSepoliaFork = process.env.FORK_NETWORK_NAME === "sepolia";
+const isSepoliaOrFork = isSepolia || isSepoliaFork;
+// ...
+module.exports = { isSepolia, isSepoliaFork, isSepoliaOrFork, ... }
+```
+
+Also branch `getAssetAddresses(hre)` if the new network has different token addresses than mainnet.
+
+## 12. `contracts/test/_fixture-{network}.js` (optional)
+
+Only if you'll have unit or fork tests for the network. Copy
+`test/_fixture-base.js` as a template and adapt for the new network's
+fixtures.
+
+## 13. `.github/workflows/defi.yml` (optional)
+
+Add a `contracts-{network}-forktest` job mirroring the existing pattern
+(~line 173–228). Requires CI secrets configured for `{NETWORK}_PROVIDER_URL`.
+Skip if you don't need CI-level fork tests for the network.
+
+## 14. `contracts/scripts/defender-actions/` (optional)
+
+Only relevant if cross-chain relay automation or scheduled jobs need to run
+for the new network. Mirror existing scripts (e.g.,
+`scripts/defender-actions/crossChainRelay.js`).
+
+## 15. Top-level `README.md`
+
+Add the network to the "Deployed on Ethereum Mainnet, Base, Arbitrum, Sonic,
+Plume, Holesky, Hoodi, …" list at the top.
+
+## 16. Verify
+
+```bash
+cd contracts
+pnpm hardhat compile                       # compiles
+pnpm prettier:sol && pnpm prettier:js      # format
+pnpm lint:sol && pnpm lint:js              # lint
+pnpm hardhat console --network {network}   # provider resolves (will error on connect if URL is empty, that's OK)
+pnpm hardhat deploy --network {network} --dry-run   # deploy wiring sanity
+```
+
+## 17. Smoke test on the new network
+
+After actual deploy:
+- Read back a key contract's address via `hardhat console`.
+- Read a public view function to confirm the deployment actually accepted calls.
+- For CREATE3 deploys: confirm peer-chain addresses are byte-identical.
+
+---
+
+## Edge cases & gotchas
+
+- **Sonic** added `isSonicForkTest` as a separate flag from `isSonicFork`. Some networks need both depending on how tests are wired. Look at existing usage in `test/helpers.js` to decide.
+- **HyperEVM** has no Etherscan-family verifier; uses `customChains` with the
+  HyperEVM block explorer endpoint.
+- **Plume Explorer** is Blockscout-compatible at `explorer.plume.org/api`; no
+  API key needed.
+- **Base / Base Sepolia**: basescan.org's V1 API is deprecated. Use the
+  Etherscan V2 multichain API key with a `customChains` entry pointing at
+  Etherscan's per-chain endpoint.
+- **L2s**: register both directions in `addresses.js` — the L2-side bridge
+  components AND the L1-side companion components on the L1's address entry
+  (L1StandardBridge for the L2's rollup, etc.).
+- **`accounts`** field in `networks.<name>`: do NOT use `defaultAccounts`
+  blindly. Specify deployer + governor PK env vars so devs can override
+  per-environment.
+
+## Reference PRs
+
+- **PR #2485** (Plume) — https://github.com/OriginProtocol/origin-dollar/pull/2485
+  L2 network with full token + vault deploy, LayerZero integration.
+- **PR #2839** (HyperEVM) — https://github.com/OriginProtocol/origin-dollar/pull/2839
+  Sidechain with strategy proxies + cross-chain relay scripts.
+
+When in doubt, look at how the most-similar existing network is wired and
+mirror that pattern. Don't invent new conventions.

.husky/pre-commit

@@ -1,4 +1,3 @@
 #!/bin/sh
-
 cd contracts
 pnpm run lint:js

contracts/abi/createx.json

@@ -97,5 +97,29 @@
         ],
         "stateMutability": "payable",
         "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "bytes32",
+                "name": "salt",
+                "type": "bytes32"
+            },
+            {
+                "internalType": "bytes32",
+                "name": "initCodeHash",
+                "type": "bytes32"
+            }
+        ],
+        "name": "computeCreate2Address",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "computedAddress",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
     }
 ]