feat: export missing utilities and enhance deployment tracking (#706)

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

Author: MiguelLZPF

.changeset/ats-upstream-enhancements.md

@@ -0,0 +1,23 @@
+---
+"@hashgraph/asset-tokenization-contracts": minor
+---
+
+feat: export missing utilities and enhance deployment tracking
+
+Export missing infrastructure and domain utilities from scripts index:
+
+- Export Hedera utilities (`fetchHederaContractId`, `getMirrorNodeUrl`, `isHederaNetwork`) for mirror node integration
+- Export deployment file utilities (`loadDeployment`, `findLatestDeployment`, `listDeploymentFiles`) for deployment management
+- Export verification utilities (`verifyContract`, `verifyContractCode`, `verifyContractInterface`) for post-deployment validation
+- Export selector utility (`getSelector`) for function selector generation
+- Export transparent proxy deployment operation (`deployTransparentProxy`)
+- Export bond token deployment from factory (`deployBondFromFactory`)
+
+Enhance deployment workflows with better tracking:
+
+- Add optional `existingBlrImplementation` parameter to track BLR implementation address when using existing BLR
+- Replace ambiguous `contractId` field with explicit `implementationContractId` and `proxyContractId` fields for proxied contracts (BLR, Factory)
+- Improve deployment documentation and upgrade history tracking
+- Better integration with Hedera tooling requiring explicit contract IDs
+
+These changes improve the public API consistency and provide better deployment documentation for downstream consumers like GBP.

packages/ats/contracts/scripts/index.ts

@@ -43,6 +43,7 @@ export * from "./infrastructure/networkConfig";
 // Infrastructure operations
 export * from "./infrastructure/operations/deployContract";
 export * from "./infrastructure/operations/deployProxy";
+export * from "./infrastructure/operations/transparentProxyDeployment";
 export * from "./infrastructure/operations/upgradeProxy";
 export * from "./infrastructure/operations/registerFacets";
 export * from "./infrastructure/operations/registerAdditionalFacets";
@@ -55,9 +56,13 @@ export * from "./infrastructure/operations/generateRegistryPipeline";
 
 // Infrastructure utilities
 export * from "./infrastructure/utils/validation";
+export * from "./infrastructure/utils/deploymentFiles";
+export * from "./infrastructure/utils/verification";
 export * from "./infrastructure/utils/transaction";
 export * from "./infrastructure/utils/logging";
 export * from "./infrastructure/utils/naming";
+export * from "./infrastructure/utils/hedera";
+export * from "./infrastructure/utils/selector";
 export * from "./infrastructure/utils/time";
 
 // Infrastructure checkpoint system (deployment resumability)
@@ -112,6 +117,7 @@ export * from "./domain/factory/deploy";
 
 // Token deployment from factory
 export * from "./domain/factory/deployEquityToken";
+export * from "./domain/factory/deployBondToken";
 
 // ========================================
 // Workflows

packages/ats/contracts/scripts/infrastructure/checkpoint/utils.ts

@@ -82,13 +82,15 @@ export function checkpointToDeploymentOutput(checkpoint: DeploymentCheckpoint):
       },
       blr: {
         implementation: steps.blr.implementation,
+        implementationContractId: steps.blr.implementationContractId,
         proxy: steps.blr.proxy,
-        contractId: steps.blr.contractId,
+        proxyContractId: steps.blr.proxyContractId,
       },
       factory: {
         implementation: steps.factory.implementation,
+        implementationContractId: steps.factory.implementationContractId,
         proxy: steps.factory.proxy,
-        contractId: steps.factory.contractId,
+        proxyContractId: steps.factory.proxyContractId,
       },
     },
 

packages/ats/contracts/scripts/infrastructure/types/checkpoint.ts

@@ -114,8 +114,12 @@ export interface DeploymentCheckpoint {
     blr?: DeployedContract & {
       /** Implementation address */
       implementation: string;
+      /** Hedera Contract ID for implementation (if deployed on Hedera network) */
+      implementationContractId?: string;
       /** Proxy address */
       proxy: string;
+      /** Hedera Contract ID for proxy (if deployed on Hedera network) */
+      proxyContractId?: string;
       /** Whether BLR is external (existingBlr workflow) */
       isExternal?: boolean;
     };
@@ -141,8 +145,12 @@ export interface DeploymentCheckpoint {
     factory?: DeployedContract & {
       /** Implementation address */
       implementation: string;
+      /** Hedera Contract ID for implementation (if deployed on Hedera network) */
+      implementationContractId?: string;
       /** Proxy address */
       proxy: string;
+      /** Hedera Contract ID for proxy (if deployed on Hedera network) */
+      proxyContractId?: string;
     };
   };
 

packages/ats/contracts/scripts/workflows/deploySystemWithExistingBlr.ts

@@ -64,14 +64,16 @@ export interface DeploymentWithExistingBlrOutput {
     };
     blr: {
       implementation: string;
+      implementationContractId?: string;
       proxy: string;
-      contractId?: string;
+      proxyContractId?: string;
       isExternal: true; // Marker to indicate BLR was not deployed here
     };
     factory: {
       implementation: string;
+      implementationContractId?: string;
       proxy: string;
-      contractId?: string;
+      proxyContractId?: string;
     };
   };
 
@@ -155,6 +157,9 @@ export interface DeploySystemWithExistingBlrOptions extends ResumeOptions {
 
   /** Enable post-deployment bytecode verification (default: from network config) */
   verifyDeployment?: boolean;
+
+  /** Existing BLR implementation address (optional, for documentation) */
+  existingBlrImplementation?: string;
 }
 
 /**
@@ -351,7 +356,7 @@ export async function deploySystemWithExistingBlr(
     if (!checkpoint.steps.blr) {
       checkpoint.steps.blr = {
         address: blrAddress,
-        implementation: "N/A (External BLR)",
+        implementation: options.existingBlrImplementation || "N/A (External BLR)",
         proxy: blrAddress,
         txHash: "",
         deployedAt: new Date().toISOString(),
@@ -707,16 +712,20 @@ export async function deploySystemWithExistingBlr(
           contractId: await getContractId(proxyAdmin.address),
         },
         blr: {
-          implementation: "N/A (External BLR)",
+          implementation: options.existingBlrImplementation || "N/A (External BLR)",
+          implementationContractId: options.existingBlrImplementation
+            ? await getContractId(options.existingBlrImplementation)
+            : undefined,
           proxy: blrAddress,
-          contractId: await getContractId(blrAddress),
+          proxyContractId: await getContractId(blrAddress),
           isExternal: true,
         },
         factory: factoryResult
           ? {
               implementation: factoryResult.implementationAddress,
+              implementationContractId: await getContractId(factoryResult.implementationAddress),
               proxy: factoryResult.factoryAddress,
-              contractId: await getContractId(factoryResult.factoryAddress),
+              proxyContractId: await getContractId(factoryResult.factoryAddress),
             }
           : {
               implementation: "N/A (Not deployed)",

packages/ats/contracts/scripts/workflows/deploySystemWithNewBlr.ts

@@ -66,13 +66,15 @@ export interface DeploymentOutput {
     };
     blr: {
       implementation: string;
+      implementationContractId?: string;
       proxy: string;
-      contractId?: string;
+      proxyContractId?: string;
     };
     factory: {
       implementation: string;
+      implementationContractId?: string;
       proxy: string;
-      contractId?: string;
+      proxyContractId?: string;
     };
   };
 
@@ -681,13 +683,15 @@ export async function deploySystemWithNewBlr(
         },
         blr: {
           implementation: blrResult.implementationAddress,
+          implementationContractId: await getContractId(blrResult.implementationAddress),
           proxy: blrResult.blrAddress,
-          contractId: await getContractId(blrResult.blrAddress),
+          proxyContractId: await getContractId(blrResult.blrAddress),
         },
         factory: {
           implementation: factoryResult.implementationAddress,
+          implementationContractId: await getContractId(factoryResult.implementationAddress),
           proxy: factoryResult.factoryAddress,
-          contractId: await getContractId(factoryResult.factoryAddress),
+          proxyContractId: await getContractId(factoryResult.factoryAddress),
         },
       },
 

packages/ats/contracts/test/scripts/unit/checkpoint/utils.test.ts

@@ -33,8 +33,9 @@ describe("Checkpoint Utilities", () => {
           blr: {
             address: "0x2222222222222222222222222222222222222222",
             implementation: "0x2222222222222222222222222222222222222221",
+            implementationContractId: "0.0.2221",
             proxy: "0x2222222222222222222222222222222222222222",
-            contractId: "0.0.2222",
+            proxyContractId: "0.0.2222",
             txHash: "0xdef456",
             deployedAt: "2025-11-08T10:02:00.000Z",
           },
@@ -78,8 +79,9 @@ describe("Checkpoint Utilities", () => {
           factory: {
             address: "0x5555555555555555555555555555555555555555",
             implementation: "0x5555555555555555555555555555555555555554",
+            implementationContractId: "0.0.5554",
             proxy: "0x5555555555555555555555555555555555555555",
-            contractId: "0.0.5555",
+            proxyContractId: "0.0.5555",
             txHash: "0xstu901",
             gasUsed: "800000",
             deployedAt: "2025-11-08T10:14:00.000Z",
@@ -99,12 +101,14 @@ describe("Checkpoint Utilities", () => {
       expect(output.infrastructure.proxyAdmin.contractId).to.equal("0.0.1111");
 
       expect(output.infrastructure.blr.implementation).to.equal("0x2222222222222222222222222222222222222221");
+      expect(output.infrastructure.blr.implementationContractId).to.equal("0.0.2221");
       expect(output.infrastructure.blr.proxy).to.equal("0x2222222222222222222222222222222222222222");
-      expect(output.infrastructure.blr.contractId).to.equal("0.0.2222");
+      expect(output.infrastructure.blr.proxyContractId).to.equal("0.0.2222");
 
       expect(output.infrastructure.factory.implementation).to.equal("0x5555555555555555555555555555555555555554");
+      expect(output.infrastructure.factory.implementationContractId).to.equal("0.0.5554");
       expect(output.infrastructure.factory.proxy).to.equal("0x5555555555555555555555555555555555555555");
-      expect(output.infrastructure.factory.contractId).to.equal("0.0.5555");
+      expect(output.infrastructure.factory.proxyContractId).to.equal("0.0.5555");
 
       // Facets
       expect(output.facets).to.have.lengthOf(2);