chore: rename deployments.json to legacy-addresses.json and simplify README (#1333)

fusmanii · claude · web-flow · commit 8638b8471701 · 2026-02-25T11:42:43.000-08:00
Replace the manually-maintained deployments/README.md address tables with a
pointer to broadcast/deployed-addresses.json as the source of truth. Rename
deployments/deployments.json to legacy-addresses.json to reduce redundancy
and clarify its legacy Hardhat role. Update all references across the codebase.

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ This [script](https://github.com/across-protocol/contracts/blob/555475cdee6109af
 
 ## Deployed Contract Versions
 
-The latest contract deployments can be found in `/deployments/deployments.json`.
+The latest contract deployments can be found in `/broadcast/deployed-addresses.json` (auto-generated by `yarn extract-addresses`). Legacy Hardhat deployment addresses are in `/deployments/legacy-addresses.json`.
 
 ## Requirements
 
@@ -148,7 +148,7 @@ solana program set-upgrade-authority \
   --new-upgrade-authority $MULTISIG
 ```
 
-Update and commit `deployments/deployments.json` with the deployed program ID and deployment slot.
+Update and commit `deployments/legacy-addresses.json` with the deployed program ID and deployment slot.
 
 Upload the IDL and set the upgrade authority to the multisig:
 
diff --git a/deploy/016_deploy_zksync_spokepool.ts b/deploy/016_deploy_zksync_spokepool.ts
@@ -52,7 +52,7 @@ const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
   let newAddress: string;
   // On production, we'll rarely want to deploy a new proxy contract so we'll default to deploying a new implementation
   // contract.
-  // If a SpokePool can be found in deployments/deployments.json, then only deploy an implementation contract.
+  // If a SpokePool can be found in deployments/legacy-addresses.json, then only deploy an implementation contract.
   const proxy = getDeployedAddress("SpokePool", spokeChainId, false);
   const implementationOnly = proxy !== undefined;
   if (implementationOnly) {
diff --git a/deploy/022_upgrade_spokepool.ts b/deploy/022_upgrade_spokepool.ts
@@ -1,6 +1,6 @@
 import { DeployFunction } from "hardhat-deploy/types";
 import { getContractFactory } from "../utils";
-import * as deployments from "../deployments/deployments.json";
+import * as deployments from "../deployments/legacy-addresses.json";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
 import { FILL_DEADLINE_BUFFER, QUOTE_TIME_BUFFER, WETH } from "./consts";
 
diff --git a/deploy/059_deploy_lens_spokepool.ts b/deploy/059_deploy_lens_spokepool.ts
@@ -52,7 +52,7 @@ const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
   let newAddress: string;
   // On production, we'll rarely want to deploy a new proxy contract so we'll default to deploying a new implementation
   // contract.
-  // If a SpokePool can be found in deployments/deployments.json, then only deploy an implementation contract.
+  // If a SpokePool can be found in deployments/legacy-addresses.json, then only deploy an implementation contract.
   const proxy = getDeployedAddress("SpokePool", spokeChainId, false);
   const implementationOnly = proxy !== undefined;
   if (implementationOnly) {
diff --git a/deployments/README.md b/deployments/README.md
diff --git a/deployments/legacy-addresses.json b/deployments/legacy-addresses.json
diff --git a/package.json b/package.json
@@ -48,7 +48,7 @@
     "test:report-gas": "IS_TEST=true REPORT_GAS=true hardhat test",
     "evm-contract-sizes": "sh scripts/evm-contract-sizes.sh",
     "generate-evm-artifacts": "rm -rf typechain && TYPECHAIN=ethers yarn hardhat typechain",
-    "process-hardhat-export": "hardhat export --export-all ./cache/massExport.json && ts-node ./scripts/processHardhatExport.ts && prettier --write ./deployments/deployments.json",
+    "process-hardhat-export": "hardhat export --export-all ./cache/massExport.json && ts-node ./scripts/processHardhatExport.ts && prettier --write ./deployments/legacy-addresses.json",
     "pre-commit-hook": "sh scripts/preCommitHook.sh",
     "extract-addresses": "./script/utils/extract_foundry_addresses.sh",
     "generate-constants-json": "ts-node ./script/utils/GenerateConstantsJson.ts"
diff --git a/script/utils/DeploymentUtils.sol b/script/utils/DeploymentUtils.sol
@@ -159,7 +159,7 @@ contract DeploymentUtils is Script, Test, Constants, DeployedAddresses, Config {
     }
 
     /**
-     * @notice Get deployed address from deployments.json
+     * @notice Get deployed address from deployed-addresses.json
      * @param contractName Name of the contract
      * @param chainId Chain ID
      * @param throwOnError Whether to throw error if not found
diff --git a/script/utils/EXTRACT_ADDRESSES.md b/script/utils/EXTRACT_ADDRESSES.md
@@ -179,7 +179,7 @@ The script recognizes these chains:
 ## How It Works
 
 1. The script scans the `broadcast/` directory for `run-latest.json` files
-2. It also reads from `deployments/deployments.json` for additional contract addresses
+2. It also reads from `deployments/legacy-addresses.json` for additional contract addresses
 3. It extracts contract addresses from each file's transaction data
 4. It organizes the data by chain ID and contract name
 5. It generates the three output files with the extracted information
diff --git a/script/utils/ExtractDeployedFoundryAddresses.ts b/script/utils/ExtractDeployedFoundryAddresses.ts
@@ -143,7 +143,7 @@ function readDeploymentsFile(deploymentsDir: string): BroadcastFile[] {
   const trackedFiles = getTrackedFiles(deploymentsDir);
 
   try {
-    const deploymentsPath = path.join(deploymentsDir, "deployments.json");
+    const deploymentsPath = path.join(deploymentsDir, "legacy-addresses.json");
     const resolvedPath = path.resolve(deploymentsPath);
 
     // Only include if file exists AND is tracked by git (committed or staged)
@@ -152,7 +152,7 @@ function readDeploymentsFile(deploymentsDir: string): BroadcastFile[] {
 
       for (const [chainId, contracts] of Object.entries(data)) {
         if (typeof contracts === "object" && contracts !== null) {
-          // Create a virtual broadcast file for deployments.json
+          // Create a virtual broadcast file for legacy-addresses.json
           deploymentsFiles.push({
             scriptName: "DeploymentsJson",
             chainId: parseInt(chainId),
@@ -164,15 +164,15 @@ function readDeploymentsFile(deploymentsDir: string): BroadcastFile[] {
       }
     }
   } catch (error) {
-    console.error(`Error reading deployments.json: ${error}`);
+    console.error(`Error reading legacy-addresses.json: ${error}`);
   }
 
   return deploymentsFiles;
 }
 
 function extractContractAddresses(broadcastFile: BroadcastFile): Contract[] {
   if (broadcastFile.isDeploymentsJson && broadcastFile.deploymentsData) {
-    // Handle deployments.json format
+    // Handle legacy-addresses.json format
     const contracts: Contract[] = [];
     const deploymentsData = broadcastFile.deploymentsData;
 
@@ -359,7 +359,7 @@ function generateAddressesFile(broadcastFiles: BroadcastFile[], outputFile: stri
     if (contracts.length > 0) {
       const chainId = broadcastFile.chainId;
       const chainName = getChainName(chainId);
-      // For deployments.json, use contract name as scriptName for each contract
+      // For legacy-addresses.json, use contract name as scriptName for each contract
       if (broadcastFile.isDeploymentsJson) {
         for (const contract of contracts) {
           const scriptName = contract.contractName;
@@ -507,17 +507,17 @@ function main(): void {
   console.log(`Scanning broadcast directory: ${broadcastDir}`);
   console.log(`Scanning deployments directory: ${deploymentsDir}`);
 
-  // Read deployments.json
+  // Read legacy-addresses.json
   const deploymentsFiles = readDeploymentsFile(deploymentsDir);
 
   // Find all broadcast files
   const broadcastFiles = findBroadcastFiles(broadcastDir);
 
-  // Combine both sources (order is important, deployments.json should be first)
+  // Combine both sources (order is important, legacy-addresses.json should be first)
   const allFiles = [...deploymentsFiles, ...broadcastFiles];
 
   if (allFiles.length === 0) {
-    console.error("No run-latest.json files found in broadcast directory and no deployments.json found");
+    console.error("No run-latest.json files found in broadcast directory and no legacy-addresses.json found");
     process.exit(1);
   }
 
diff --git a/scripts/processHardhatExport.ts b/scripts/processHardhatExport.ts
@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import * as existingDeployments from "../deployments/deployments.json";
+import * as existingDeployments from "../deployments/legacy-addresses.json";
 
 export type Deployments = Record<string, Record<string, { address: string; blockNumber: number }>>;
 // Prunes the hardhat export file sent to the cache directory to only contain the deployment addresses of each contract
@@ -19,7 +19,7 @@ export async function run(): Promise<void> {
           const blockNumber = findDeploymentBlockNumber(castExport[chainId][0].name, contractName);
           const existingBlockNumber = (existingDeployments as Deployments)[chainId][contractName].blockNumber;
           console.log(
-            `Not updating ${contractName} as it has a later block number set in deployments.json than the one in deployments/${contractName}.json`
+            `Not updating ${contractName} as it has a later block number set in legacy-addresses.json than the one in deployments/${contractName}.json`
           );
           const hasLaterBlockNumber = existingBlockNumber > blockNumber;
           if (hasLaterBlockNumber) return; // If we have already found a later block number for this contract, then ignore this one.
@@ -30,7 +30,10 @@ export async function run(): Promise<void> {
     });
     console.log("Constructed the following address export for release:\n", processedOutput);
 
-    fs.writeFileSync(`${path.resolve(__dirname)}/../deployments/deployments.json`, JSON.stringify(processedOutput));
+    fs.writeFileSync(
+      `${path.resolve(__dirname)}/../deployments/legacy-addresses.json`,
+      JSON.stringify(processedOutput)
+    );
   } catch (error) {}
 }
 
diff --git a/src/DeploymentUtils.ts b/src/DeploymentUtils.ts
@@ -21,7 +21,7 @@ export function getDeployedAddress(
 ): string | undefined {
   const address = DEPLOYMENTS[networkId.toString()]?.contracts[contractName]?.address;
   if (!address && throwOnError) {
-    throw new Error(`Contract ${contractName} not found on ${networkId} in deployments.json`);
+    throw new Error(`Contract ${contractName} not found on ${networkId} in deployed-addresses.json`);
   }
 
   return address;
@@ -51,7 +51,7 @@ export function getDeployedBlockNumber(contractName: string, networkId: number):
   try {
     return DEPLOYMENTS[networkId.toString()]?.contracts[contractName]?.block_number;
   } catch (_) {
-    throw new Error(`Contract ${contractName} not found on ${networkId} in deployments.json`);
+    throw new Error(`Contract ${contractName} not found on ${networkId} in deployed-addresses.json`);
   }
 }
 
@@ -67,7 +67,7 @@ export function getContractInfoFromAddress(contractAddress: string): { chainId:
         returnValue.push({ chainId: Number(_chainId), contractName: _contractName });
     })
   );
-  if (returnValue.length === 0) throw new Error(`Contract ${contractAddress} not found in deployments.json`);
+  if (returnValue.length === 0) throw new Error(`Contract ${contractAddress} not found in deployed-addresses.json`);
   if (returnValue.length > 1) throw new Error(`Multiple deployments found for ${contractAddress}`);
   return returnValue[0];
 }
diff --git a/utils/utils.hre.ts b/utils/utils.hre.ts
@@ -53,7 +53,7 @@ export async function deployNewProxy(
     unsafeAllowArgs.push("state-variable-immutable");
   }
 
-  // If a SpokePool can be found in deployments/deployments.json, then only deploy an implementation contract.
+  // If a SpokePool can be found in deployments/legacy-addresses.json, then only deploy an implementation contract.
   let proxyAddress = getDeployedAddress("SpokePool", chainId, false);
   implementationOnly ??= proxyAddress !== undefined;
   let implementationAddress: string;

Original file line number	Diff line number	Diff line change
`@@ -159,7 +159,7 @@ contract DeploymentUtils is Script, Test, Constants, DeployedAddresses, Config {`
`159`	`159`	`}`
`160`	`160`
`161`	`161`	`/**`
`162`		`- * @notice Get deployed address from deployments.json`
	`162`	`+ * @notice Get deployed address from deployed-addresses.json`
`163`	`163`	`* @param contractName Name of the contract`
`164`	`164`	`* @param chainId Chain ID`
`165`	`165`	`* @param throwOnError Whether to throw error if not found`