refactor(contracts): enhance deployment infrastructure and standardize network configuration

Comprehensive refactoring of contract deployment system to improve reliability,
usability, and maintainability:

BREAKING CHANGE: Network name 'localhost' renamed to 'local' in configuration
- Update .env files: LOCALHOST_* → LOCAL_*
- Hardhat network config: 'localhost' → 'local'
- Affects Configuration.ts, hardhat.config.ts, .env.sample

Network Configuration Improvements:
- Standardize network naming (localhost → local) for clarity
- Add realistic timeouts per network (10s local → 300s mainnet)
- Reduce max gas limit from 30M to 15M for safer defaults
- Clarify network type distinctions (simulated vs real local nodes)

Batch Processing Enhancements:
- Introduce DEFAULT_BATCH_SIZE constant (15 facets/batch)
- Replace hardcoded batch size of 2 throughout codebase
- Add 1-second delays between batches to prevent RPC overload
- Improve gas management for large configuration deployments

Checkpoint System Improvements:
- Add warning when checkpoint dir is inside node_modules
- Document checkpointDir option in ResumeOptions type
- Help prevent checkpoint loss on npm install/ci

Developer Experience:
- Add deployment convenience scripts at root and package level
- Update documentation with new CLI patterns
- Standardize script naming (deploy:hedera:testnet, etc.)
- Simplify deployment workflows for common scenarios

Infrastructure Code Quality:
- Use constants instead of magic numbers
- Consistent parameter defaults across functions
- Improved JSDoc documentation with examples
- Better separation of concerns in network configs

Files affected:
- Configuration & environment: .env.sample, Configuration.ts, hardhat.config.ts
- Build scripts: package.json (root + contracts)
- CLI entry points: cli/hardhat.ts, cli/standalone.ts
- Domain layer: bond/equity createConfiguration
- Infrastructure: constants, networkConfig, operations, checkpoint system
- Workflows: deploySystemWithNewBlr, deploySystemWithExistingBlr
- Documentation: scripts/README.md

Signed-off-by: Miguel_LZPF <miguel.carpena@io.builders>

Author: MiguelLZPF

package.json

@@ -81,6 +81,12 @@
     "ats:contracts:test:coverage": "npm run test:coverage --workspace=packages/ats/contracts",
     "ats:contracts:test:ci": "npm run test:ci --workspace=packages/ats/contracts --if-present || npm run test --workspace=packages/ats/contracts",
     "ats:contracts:clean": "npm run clean --workspace=packages/ats/contracts",
+    "ats:contracts:deploy": "npm run deploy --workspace=packages/ats/contracts",
+    "ats:contracts:deploy:local": "npm run deploy:local --workspace=packages/ats/contracts",
+    "ats:contracts:deploy:hedera:local": "npm run deploy:hedera:local --workspace=packages/ats/contracts",
+    "ats:contracts:deploy:hedera:previewnet": "npm run deploy:hedera:previewnet --workspace=packages/ats/contracts",
+    "ats:contracts:deploy:hedera:testnet": "npm run deploy:hedera:testnet --workspace=packages/ats/contracts",
+    "ats:contracts:deploy:hedera:mainnet": "npm run deploy:hedera:mainnet --workspace=packages/ats/contracts",
     "ats:contracts:publish": "npm run publish --workspace=packages/ats/contracts",
     "ats:sdk:build": "npm run build --workspace=packages/ats/sdk",
     "ats:sdk:test": "npm run test --workspace=packages/ats/sdk",

packages/ats/contracts/.env.sample

@@ -4,9 +4,9 @@
 # Hardhat (in-memory test network) - uses Hardhat's built-in accounts
 # No private keys needed for hardhat network
 
-# Localhost (generic local Ethereum node)
-LOCALHOST_PRIVATE_KEY_0='0xEXAMPLEPRIVATEKEY0'
-LOCALHOST_PRIVATE_KEY_1='0xEXAMPLEPRIVATEKEY1'
+# Local (generic local Ethereum node)
+LOCAL_PRIVATE_KEY_0='0xEXAMPLEPRIVATEKEY0'
+LOCAL_PRIVATE_KEY_1='0xEXAMPLEPRIVATEKEY1'
 # ... add more keys as needed
 
 # Hedera Local (Docker-based Hedera local node)
@@ -33,8 +33,8 @@ HEDERA_MAINNET_PRIVATE_KEY_1='0xEXAMPLEPRIVATEKEY9'
 # Hardhat (no external endpoint, uses in-memory network)
 # HARDHAT_JSON_RPC_ENDPOINT not required
 
-# Localhost (generic local Ethereum node, defaults to http://127.0.0.1:8545)
-LOCALHOST_JSON_RPC_ENDPOINT='http://127.0.0.1:8545'
+# Local (generic local Ethereum node, defaults to http://127.0.0.1:8545)
+LOCAL_JSON_RPC_ENDPOINT='http://127.0.0.1:8545'
 
 # Hedera Local (Docker-based Hedera local node)
 HEDERA_LOCAL_JSON_RPC_ENDPOINT='http://127.0.0.1:7546'

packages/ats/contracts/Configuration.ts

@@ -230,15 +230,15 @@ const NETWORK_ENV_PREFIX_SEPARATOR_REGEX = /-/g;
  *
  * Network Types:
  * - hardhat: Hardhat's in-memory test network (ephemeral, no persistence)
- * - localhost: Generic local Ethereum node (e.g., Hardhat node, Ganache, Anvil)
+ * - local: Generic local Ethereum node (e.g., Hardhat node, Ganache, Anvil)
  * - hedera-local: Local Hedera node running in Docker
  * - hedera-previewnet: Hedera previewnet (public test network)
  * - hedera-testnet: Hedera testnet (primary test network)
  * - hedera-mainnet: Hedera mainnet (production network)
  */
 export const NETWORKS = [
   "hardhat",
-  "localhost",
+  "local",
   "hedera-local",
   "hedera-previewnet",
   "hedera-testnet",
@@ -262,7 +262,7 @@ const formatNetworkEnvPrefix = (network: Network): string =>
  * @deprecated Old network names. Use new names from NETWORKS instead.
  */
 export const NETWORK_ALIASES: Record<string, Network> = {
-  local: "localhost",
+  localhost: "local",
   previewnet: "hedera-previewnet",
   testnet: "hedera-testnet",
   mainnet: "hedera-mainnet",
@@ -424,7 +424,7 @@ export default class Configuration {
           jsonRpc: Configuration._getEnvironmentVariable({
             name: `${network.toUpperCase().replace(/-/g, "_")}_JSON_RPC_ENDPOINT`,
             defaultValue:
-              network === "localhost"
+              network === "local"
                 ? "http://127.0.0.1:8545"
                 : network === "hedera-local"
                   ? "http://127.0.0.1:7546"
@@ -435,7 +435,7 @@ export default class Configuration {
           mirror: Configuration._getEnvironmentVariable({
             name: `${network.toUpperCase().replace(/-/g, "_")}_MIRROR_NODE_ENDPOINT`,
             defaultValue:
-              network === "localhost"
+              network === "local"
                 ? ""
                 : network === "hedera-local"
                   ? "http://127.0.0.1:5600"

packages/ats/contracts/hardhat.config.ts

@@ -253,9 +253,9 @@ const config: HardhatUserConfig = {
       blockGasLimit: 30_000_000,
       hardfork: "cancun",
     },
-    localhost: {
-      url: Configuration.endpoints.localhost.jsonRpc,
-      accounts: Configuration.privateKeys.localhost,
+    local: {
+      url: Configuration.endpoints.local.jsonRpc,
+      accounts: Configuration.privateKeys.local,
       timeout: 60_000,
     },
     "hedera-local": {

packages/ats/contracts/package.json

@@ -52,8 +52,15 @@
     "lint:js": "eslint .",
     "lint:js:fix": "eslint . --fix",
     "generate:registry": "npx ts-node scripts/tools/generateRegistry.ts",
+    "deploy": "npm run build && npx ts-node -r tsconfig-paths/register scripts/cli/standalone.ts",
+    "deploy:local": "NETWORK=local npm run deploy",
+    "deploy:local:auto": "npx hardhat node > hardhat-node.log 2>&1 & sleep 3 && npm run deploy:local; kill $!",
+    "deploy:hedera:local": "NETWORK=hedera-local npm run deploy",
+    "deploy:hedera:previewnet": "NETWORK=hedera-previewnet npm run deploy",
+    "deploy:hedera:testnet": "NETWORK=hedera-testnet npm run deploy",
+    "deploy:hedera:mainnet": "NETWORK=hedera-mainnet npm run deploy",
+    "local:hardhat": "npx hardhat node",
     "deploy:hardhat": "npx hardhat run scripts/cli/hardhat.ts",
-    "deploy:standalone": "npm run compile && npx ts-node -r tsconfig-paths/register scripts/cli/standalone.ts",
     "publish": "npm publish",
     "compile": "npx hardhat compile",
     "compile:traces": "npx hardhat --show-stack-traces compile",

packages/ats/contracts/scripts/README.md

@@ -31,7 +31,8 @@ This README provides comprehensive reference documentation for the deployment sy
 | ---------------------------------------------------- | ------------------------ | --------------------------- |
 | `npm run deploy:hardhat -- --network hardhat`        | In-memory testing        | Hardhat project             |
 | `npm run deploy:hardhat -- --network hedera-testnet` | Testnet deployment       | Hardhat + `.env`            |
-| `npm run deploy:standalone`                          | Standalone deployment    | Compiled artifacts + `.env` |
+| `npm run deploy`                                     | Standalone deployment    | Compiled artifacts + `.env` |
+| `npm run deploy:hedera:testnet`                      | Testnet shortcut         | `.env` configured           |
 | `npm run generate:registry`                          | Update contract metadata | Contracts compiled          |
 
 ---
@@ -518,11 +519,11 @@ Check the output file in `deployments/{network}_{timestamp}.json`:
 
 The deployment system supports three modes:
 
-| Mode           | Entry Point                            | Signer Source         | Use Case                                  | Command                                      |
-| -------------- | -------------------------------------- | --------------------- | ----------------------------------------- | -------------------------------------------- |
-| **Hardhat**    | [cli/hardhat.ts](cli/hardhat.ts)       | `ethers.getSigners()` | Hardhat project deployment                | `npm run deploy:hardhat -- --network <name>` |
-| **Standalone** | [cli/standalone.ts](cli/standalone.ts) | `ethers.Wallet`       | No Hardhat dependency, ~3x faster startup | `npm run deploy:standalone`                  |
-| **Module**     | Import in your code                    | Any ethers.js Signer  | Custom scripts, programmatic deployment   | See example below                            |
+| Mode           | Entry Point                            | Signer Source         | Use Case                                  | Command                                             |
+| -------------- | -------------------------------------- | --------------------- | ----------------------------------------- | --------------------------------------------------- |
+| **Hardhat**    | [cli/hardhat.ts](cli/hardhat.ts)       | `ethers.getSigners()` | Hardhat project deployment                | `npm run deploy:hardhat -- --network <name>`        |
+| **Standalone** | [cli/standalone.ts](cli/standalone.ts) | `ethers.Wallet`       | No Hardhat dependency, ~3x faster startup | `npm run deploy` or `npm run deploy:hedera:testnet` |
+| **Module**     | Import in your code                    | Any ethers.js Signer  | Custom scripts, programmatic deployment   | See example below                                   |
 
 ### Import as Module
 

packages/ats/contracts/scripts/cli/hardhat.ts

@@ -17,7 +17,7 @@
  */
 
 import { deploySystemWithNewBlr } from "../workflows/deploySystemWithNewBlr";
-import { getNetworkConfig, getAllNetworks } from "@scripts/infrastructure";
+import { getNetworkConfig, getAllNetworks, DEFAULT_BATCH_SIZE } from "@scripts/infrastructure";
 
 /**
  * Main deployment function for Hardhat environment.
@@ -57,8 +57,8 @@ async function main() {
   // Check for PartialBatchDeploy mode from environment
   const partialBatchDeploy = process.env.PARTIAL_BATCH_DEPLOY === "true";
 
-  // Get batch size from environment or default to 2
-  const batchSize = process.env.BATCH_SIZE ? parseInt(process.env.BATCH_SIZE) : 2;
+  // Get batch size from environment or use DEFAULT_BATCH_SIZE constant
+  const batchSize = process.env.BATCH_SIZE ? parseInt(process.env.BATCH_SIZE) : DEFAULT_BATCH_SIZE;
 
   try {
     // Deploy system with new BLR

packages/ats/contracts/scripts/cli/standalone.ts

@@ -13,15 +13,15 @@
  *   USE_TIMETRAVEL - Enable TimeTravel mode (default: false)
  *
  * Usage:
- *   NETWORK=hedera-testnet npx ts-node scripts/cli/standalone.ts
+ *   npm run deploy
  *   or
- *   npm run deploy:standalone
+ *   npm run deploy:hedera:testnet
  *
  * @module cli/standalone
  */
 
 import { deploySystemWithNewBlr } from "../workflows/deploySystemWithNewBlr";
-import { getAllNetworks, getNetworkConfig } from "@scripts/infrastructure";
+import { getAllNetworks, getNetworkConfig, DEFAULT_BATCH_SIZE } from "@scripts/infrastructure";
 import { Wallet, providers } from "ethers";
 
 /**
@@ -32,7 +32,7 @@ async function main() {
   const network = process.env.NETWORK || "hedera-testnet";
   const useTimeTravel = process.env.USE_TIMETRAVEL === "true";
   const partialBatchDeploy = process.env.PARTIAL_BATCH_DEPLOY === "true";
-  const batchSize = process.env.BATCH_SIZE ? parseInt(process.env.BATCH_SIZE) : 2;
+  const batchSize = process.env.BATCH_SIZE ? parseInt(process.env.BATCH_SIZE) : DEFAULT_BATCH_SIZE;
 
   console.log(`🚀 Starting ATS deployment (standalone mode)`);
   console.log("=".repeat(60));

packages/ats/contracts/scripts/domain/bond/createConfiguration.ts

@@ -18,6 +18,7 @@ import {
   ConfigurationError,
   createBatchConfiguration,
   OperationResult,
+  DEFAULT_BATCH_SIZE,
 } from "@scripts/infrastructure";
 import { BOND_CONFIG_ID, atsRegistry } from "@scripts/domain";
 
@@ -137,7 +138,7 @@ export async function createBondConfiguration(
   facetAddresses: Record<string, string>,
   useTimeTravel: boolean = false,
   partialBatchDeploy: boolean = false,
-  batchSize: number = 2,
+  batchSize: number = DEFAULT_BATCH_SIZE,
 ): Promise<OperationResult<ConfigurationData, ConfigurationError>> {
   // Get facet names based on time travel mode
   // Include TimeTravelFacet when useTimeTravel=true to provide time manipulation functions

packages/ats/contracts/scripts/domain/equity/createConfiguration.ts

@@ -18,6 +18,7 @@ import {
   ConfigurationError,
   OperationResult,
   createBatchConfiguration,
+  DEFAULT_BATCH_SIZE,
 } from "@scripts/infrastructure";
 import { EQUITY_CONFIG_ID, atsRegistry } from "@scripts/domain";
 
@@ -137,7 +138,7 @@ export async function createEquityConfiguration(
   facetAddresses: Record<string, string>,
   useTimeTravel: boolean = false,
   partialBatchDeploy: boolean = false,
-  batchSize: number = 2,
+  batchSize: number = DEFAULT_BATCH_SIZE,
 ): Promise<OperationResult<ConfigurationData, ConfigurationError>> {
   // Get facet names based on time travel mode
   // Include TimeTravelFacet when useTimeTravel=true to provide time manipulation functions