Feat/initialize facet operational counter

.changeset/ci-lint-format-workflows.md

@@ -0,0 +1,6 @@
+---
+"@hashgraph/asset-tokenization-contracts": patch
+"@hashgraph/mass-payout-contracts": patch
+---
+
+Add PR-gating lint and format CI workflows for ATS and MP, align workflow name prefixes with filenames, pin Node.js version via .nvmrc, and remove obsolete NODE_OPTIONS heap workarounds.

.changeset/fix-hiero-solo-facet-registration.md

@@ -0,0 +1,12 @@
+---
+"@hashgraph/asset-tokenization-contracts": patch
+---
+
+Fix BBND-1703: Hiero Solo deployment failure during facet registration.
+
+The `deploySystemWithNewBlr` workflow's "Step 4/12: Registering facets in BLR" step was racing on the Hedera Solo JSON-RPC relay. It fired one parallel `eth_call` per facet (≈101 concurrent reads of `getStaticResolverKey()`) via `Promise.all`, which Hardhat's in-process provider absorbs but the Hedera relay rejects/rate-limits. The deterministic resolver keys are already available offline via `getFacetDefinition()` from `@scripts/domain`, so the registration phase now reads them synchronously from the registry instead of fanning out RPC calls.
+
+Two related fixes ride along:
+
+- The `error()` / `warn()` / `debug()` loggers were silently dropping their `data` argument in text mode, masking the real exception body in CI logs (`❌ Deployment failed:` with no details). Text mode now also prints `Error.name` / `message` / `stack` and ethers-specific fields (`reason`, `shortMessage`, `code`, `data`).
+- `registerFacets()` had an off-by-one in its batch loop (`length / FACET_REGISTRATION_BATCH_SIZE` without `Math.ceil` plus `i <= iterations`) that would have sent an empty final transaction whenever the facet count was an exact multiple of the batch size. Hardened with `Math.ceil`, strict `<`, and a defensive empty-slice guard.

.changeset/maf-hold-at-snapshot.md

@@ -0,0 +1,30 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+# HoldAtSnapshot split
+
+Extract `heldBalanceOfAtSnapshot` from `SnapshotsFacet` into a dedicated
+`HoldAtSnapshotFacet` registered under `_HOLD_AT_SNAPSHOT_RESOLVER_KEY`.
+
+## Changes
+
+- Added `contracts/facets/holdAtSnapshot/IHoldAtSnapshot.sol`,
+  `HoldAtSnapshot.sol`, `HoldAtSnapshotFacet.sol`.
+- Added `_HOLD_AT_SNAPSHOT_RESOLVER_KEY` constant in `resolverKeys.sol`.
+- Removed `heldBalanceOfAtSnapshot` from `ISnapshots.sol`, `Snapshots.sol`,
+  and `SnapshotsFacet.sol` (11 → 10 selectors).
+- `IAsset` now inherits `IHoldAtSnapshot`.
+- Updated `Configuration.ts` and 7 `createConfiguration.ts` scripts
+  (equity, bond, bondFixedRate, bondKpiLinkedRate,
+  bondSustainabilityPerformanceTargetRate, loan, loanPortfolio) to register
+  `HoldAtSnapshotFacet`.
+- Added `test/contracts/integration/holdAtSnapshot/holdAtSnapshot.test.ts`
+  covering revert cases (SnapshotIdNull, SnapshotIdDoesNotExists), happy paths,
+  historical correctness across two snapshots, and multi-holder independence.
+- Removed `heldBalanceOfAtSnapshot` assertions from `snapshots.test.ts`.
+
+## Non-breaking
+
+The 4-byte selector of `heldBalanceOfAtSnapshot` is unchanged. Any call
+through `IAsset` continues to work without modification.

.changeset/maf-lock-at-snapshot.md

@@ -0,0 +1,28 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+# LockAtSnapshot split
+
+Extract `lockedBalanceOfAtSnapshot` from `SnapshotsFacet` into a dedicated
+`LockAtSnapshotFacet` registered under `_LOCK_AT_SNAPSHOT_RESOLVER_KEY`.
+
+## Changes
+
+- Added `contracts/facets/lockAtSnapshot/ILockAtSnapshot.sol`,
+  `LockAtSnapshot.sol`, `LockAtSnapshotFacet.sol`.
+- Added `_LOCK_AT_SNAPSHOT_RESOLVER_KEY` constant in `resolverKeys.sol`.
+- Removed `lockedBalanceOfAtSnapshot` from `Snapshots.sol`, `ISnapshots.sol`,
+  and `SnapshotsFacet.sol` (10 → 9 selectors).
+- `IAsset` now inherits `ILockAtSnapshot`.
+- Updated `Configuration.ts` and 7 `createConfiguration.ts` scripts
+  (equity, bond, bondFixedRate, bondKpiLinkedRate, bondSPTR, loan,
+  loanPortfolio) to register `LockAtSnapshotFacet`.
+- Added `test/contracts/integration/lockAtSnapshot/lockAtSnapshot.test.ts`
+  covering null snapshot, unknown snapshot, zero-lock, exact-amount,
+  historical isolation, and multi-holder scenarios.
+
+## Non-breaking
+
+The 4-byte selector of `lockedBalanceOfAtSnapshot` is unchanged. Any call
+through `IAsset` continues to work without modification.

.changeset/maf-split-adjust-balances.md

@@ -0,0 +1,5 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+Consolidate 8 balance-adjustment functions from ScheduledBalanceAdjustmentsFacet, EquityUSAFacet, and ERC1410TokenHolderFacet into a single AdjustBalancesFacet at the flat contracts/facets/adjustBalances/ path.

.changeset/maf-split-holdAtSnapshotByPartition.md

@@ -0,0 +1,5 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+refactor(contracts): split HoldAtSnapshotByPartition facet out of Snapshots

.changeset/poc-auto-operational-counter.md

@@ -0,0 +1,57 @@
+---
+"@io-builders/ats-contracts": minor
+---
+
+## PoC: Counter-Based Auto-Operational Activation
+
+Introduces an O(1) counter mechanism that eliminates the need for an explicit
+`setOperationalStatus` transaction after every initialisation or upgrade flow.
+
+### Problem
+
+The current approach requires operators to call `setOperationalStatus` as a separate
+on-chain transaction after all facets are ready. This transaction iterates all facets in
+batches of 10, violating the Minimum-Action-per-Facet (MAF) principle and growing linearly
+with config size.
+
+### Solution
+
+Each `setFacetToReady` call now atomically increments a counter. When the counter reaches
+`configTargetCount` (set once before the first registration), the config transitions to
+operational and emits `TokenOperational` — all within the same transaction as the last
+facet registration.
+
+### Changes
+
+**`IInitializer`**
+
+- Added `event TokenOperational(bytes32 indexed configId, uint256 indexed versionId)`
+- Added `setConfigTargetCount(bytes32, uint256, uint256)` — set before first `setFacetToReady`
+- Added `getConfigInitializedCount(bytes32, uint256)` — how many facets have registered
+- Added `getConfigTargetCount(bytes32, uint256)` — the configured target
+
+**`InitializerStorageWrapper`**
+
+- Extended `InitializerDataStorage` with `configInitializedCount` and `configTargetCount` mappings
+- `setFacetToReady` now calls `_tryAutoActivate()` (private, O(1)) after marking the facet ready
+- Added `setConfigTargetCount`, `getConfigInitializedCount`, `getConfigTargetCount` internal helpers
+
+**`Initializer` / `InitializerFacet`**
+
+- Exposed the three new functions as external selectors
+
+**Gas benchmark**
+
+- `GasBenchmarkInitializerHarness.sol` — standalone harness for gas measurement without full diamond
+- `gasBenchmarkInitializer.test.ts` — benchmarks N = {1, 5, 10, 25, 50, 100} facets,
+  asserts every single call stays below the Hedera 7.5M practical gas limit
+
+**ADR**
+
+- `docs/adr/ADR-002-counter-based-auto-operational.md` documents the decision, tradeoffs,
+  and rejected alternatives
+
+### Backward compatibility
+
+`setConfigTargetCount` defaults to 0. When 0, `_tryAutoActivate` is a no-op and
+`setOperationalStatus` continues to work exactly as before. No breaking changes.

.changeset/slow-places-shout.md

@@ -0,0 +1,23 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+Add irreversible token deactivation via `DeactivateFacet`.
+
+**New `DeactivateFacet` — one-way retirement of a security token**
+Introduces a dedicated facet that permanently retires a token from active use. Once `deactivate()` is called by an account holding `DEACTIVATE_ROLE`, every operation guarded by `onlyActivated` reverts with `Deactivated`. The transition is intentionally one-way: there is no `reactivate` counterpart. The facet exposes two selectors: `deactivate()` and `isDeactivated()`.
+
+**New `DeactivateStorageWrapper` — diamond storage for the deactivation flag**
+Persists the deactivation state at a dedicated `_DEACTIVATE_STORAGE_POSITION` slot. Single-field struct (`bool deactivated`) designed for forward compatibility — future metadata (operator, timestamp, reason) can be appended without changing the slot. Provides `deactivate()`, `isDeactivated()`, and `requireActivated()` internals.
+
+**New `DeactivateModifiers` + `onlyActivated` wired into `CoreModifiers`**
+Adds the `onlyActivated` modifier as a reusable mix-in backed by `DeactivateStorageWrapper.requireActivated()`. `CoreModifiers` is updated to inherit `DeactivateModifiers`, making the guard available to all facets that already extend `CoreModifiers` without any further import changes.
+
+**New `DEACTIVATE_ROLE` constant and storage slot**
+`constants/roles.sol` and `constants/storagePositions.sol` receive the new `DEACTIVATE_ROLE` and `_DEACTIVATE_STORAGE_POSITION` entries. `IAsset.sol` is updated to expose the `IDeactivate` interface. The auto-generated `factory/ERC3643/interfaces/roles.sol` is regenerated accordingly.
+
+**Registry and configuration updated**
+`atsRegistry.data.ts` registers `DeactivateFacet` with its selectors. All existing `createConfiguration` scripts for bond, equity, and loan-portfolio token types are updated to include the new facet in the default diamond cut.
+
+**Integration tests**
+`deactivate.test.ts` covers: successful deactivation by role holder, revert on second call, revert when caller lacks `DEACTIVATE_ROLE`, revert on operations guarded by `onlyActivated` after deactivation, and `isDeactivated` read path.

.github/workflows/000-flow-changeset-check.yaml

@@ -48,7 +48,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
 
       - name: Check for bypass labels
         id: bypass

.github/workflows/001-flow-pull-request-formatting.yaml

@@ -1,4 +1,4 @@
-name: "000: [FLOW] PR Formatting"
+name: "001: [FLOW] PR Formatting"
 on:
   pull_request_target:
     # This covers: new PRs, title edits, new commits, and assignee changes - everything the workflow actually validates

.github/workflows/002-user-ats-release.yaml

@@ -1,4 +1,4 @@
-name: "000: [USER] ATS Release"
+name: "002: [USER] ATS Release"
 
 on:
   # Manual trigger with preview/release option
@@ -43,7 +43,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: v22.20.0
+          node-version-file: .nvmrc
 
       - name: Install dependencies
         run: npm ci

.github/workflows/003-user-mp-release.yaml

@@ -1,4 +1,4 @@
-name: "000: [USER] MP Release"
+name: "003: [USER] MP Release"
 
 on:
   # Manual trigger with preview/release option
@@ -43,7 +43,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
 
       - name: Install dependencies
         run: npm ci

.github/workflows/100-flow-ats-test.yaml

@@ -24,7 +24,6 @@ jobs:
     runs-on: token-studio-linux-large
     timeout-minutes: 45
     env:
-      NODE_OPTIONS: "--max-old-space-size=32768"
       CONTRACT_SIZER_RUN_ON_COMPILE: "false"
       REPORT_GAS: "false"
       CLIENT_PRIVATE_KEY_ECDSA_1: ${{ secrets.CLIENT_PRIVATE_KEY_ECDSA_1 }}
@@ -63,7 +62,8 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
+          cache: "npm"
 
       - name: Install dependencies
         run: npm ci

.github/workflows/101-flow-mp-test.yaml

@@ -1,4 +1,4 @@
-name: "100: [FLOW] MP Test"
+name: "101: [FLOW] MP Test"
 
 on:
   push:
@@ -25,7 +25,6 @@ jobs:
     runs-on: token-studio-linux-large
     timeout-minutes: 45
     env:
-      NODE_OPTIONS: "--max-old-space-size=32768"
       CONTRACT_SIZER_RUN_ON_COMPILE: "false"
       REPORT_GAS: "false"
       CLIENT_PRIVATE_KEY_ECDSA_1: ${{ secrets.CLIENT_PRIVATE_KEY_ECDSA_1 }}
@@ -64,7 +63,8 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
+          cache: "npm"
 
       - name: Install dependencies
         run: npm ci

.github/workflows/102-flow-ats-deployment-test.yaml

@@ -1,4 +1,4 @@
-name: "100: [FLOW] ATS Deployment Test"
+name: "102: [FLOW] ATS Deployment Test"
 
 on:
   pull_request:
@@ -35,7 +35,6 @@ jobs:
     runs-on: token-studio-linux-large
     timeout-minutes: 10
     env:
-      NODE_OPTIONS: "--max-old-space-size=32768"
       CONTRACT_SIZER_RUN_ON_COMPILE: "false"
       REPORT_GAS: "false"
 
@@ -51,7 +50,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
 
       - name: Restore dependencies from cache
         id: deps-cache
@@ -102,7 +101,6 @@ jobs:
     runs-on: token-studio-linux-large
     timeout-minutes: 15
     env:
-      NODE_OPTIONS: "--max-old-space-size=32768"
       CONTRACT_SIZER_RUN_ON_COMPILE: "false"
       REPORT_GAS: "false"
 
@@ -118,7 +116,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
 
       - name: Restore dependencies from cache
         id: deps-cache
@@ -221,9 +219,8 @@ jobs:
     needs:
       - build
     runs-on: token-studio-linux-large
-    timeout-minutes: 30
+    timeout-minutes: 45
     env:
-      NODE_OPTIONS: "--max-old-space-size=32768"
       CONTRACT_SIZER_RUN_ON_COMPILE: "false"
       REPORT_GAS: "false"
 
@@ -239,7 +236,7 @@ jobs:
       - name: Setup NodeJS Environment
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.20.0
+          node-version-file: .nvmrc
 
       - name: Check Docker availability
         id: docker-check

.github/workflows/103-flow-ats-lint.yaml

@@ -0,0 +1,26 @@
+name: "103: [FLOW] ATS Lint and Format"
+
+on:
+  pull_request:
+    paths:
+      - "packages/ats/**"
+      - "apps/ats/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/103-flow-ats-lint.yaml"
+      - ".github/workflows/800-call-lint-format.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-format:
+    name: lint-and-format
+    uses: ./.github/workflows/800-call-lint-format.yaml
+    with:
+      module: ats

.github/workflows/104-flow-mp-lint.yaml

@@ -0,0 +1,26 @@
+name: "104: [FLOW] MP Lint and Format"
+
+on:
+  pull_request:
+    paths:
+      - "packages/mass-payout/**"
+      - "apps/mass-payout/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/104-flow-mp-lint.yaml"
+      - ".github/workflows/800-call-lint-format.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-format:
+    name: lint-and-format
+    uses: ./.github/workflows/800-call-lint-format.yaml
+    with:
+      module: mass-payout