@twin.org/dlt-iota 0.0.2-next.1 → 0.0.2-next.11

package/dist/esm/index.mjs

@@ -1,4 +1,4 @@
-import { toB64 } from '@iota/bcs';
+import { toB64, bcs } from '@iota/bcs';
 import { IotaClient } from '@iota/iota-sdk/client';
 import { Ed25519Keypair } from '@iota/iota-sdk/keypairs/ed25519';
 import { Transaction } from '@iota/iota-sdk/transactions';
@@ -34,18 +34,17 @@ class Iota {
     static DEFAULT_INCLUSION_TIMEOUT = 60;
     /**
      * Runtime name for the class.
-     * @internal
      */
-    static _CLASS_NAME = "Iota";
+    static CLASS_NAME = "Iota";
     /**
      * Create a new IOTA client.
      * @param config The configuration.
      * @returns The client instance.
      */
     static createClient(config) {
-        Guards.object(Iota._CLASS_NAME, "config", config);
-        Guards.object(Iota._CLASS_NAME, "config.clientOptions", config.clientOptions);
-        Guards.string(Iota._CLASS_NAME, "config.clientOptions.url", config.clientOptions.url);
+        Guards.object(Iota.CLASS_NAME, "config", config);
+        Guards.object(Iota.CLASS_NAME, "config.clientOptions", config.clientOptions);
+        Guards.string(Iota.CLASS_NAME, "config.clientOptions.url", config.clientOptions.url);
         return new IotaClient(config.clientOptions);
     }
     /**
@@ -53,7 +52,7 @@ class Iota {
      * @param config The configuration to populate.
      */
     static populateConfig(config) {
-        Guards.object(Iota._CLASS_NAME, "config.clientOptions", config.clientOptions);
+        Guards.object(Iota.CLASS_NAME, "config.clientOptions", config.clientOptions);
         config.vaultMnemonicId ??= Iota.DEFAULT_MNEMONIC_SECRET_NAME;
         config.vaultSeedId ??= Iota.DEFAULT_SEED_SECRET_NAME;
         config.coinType ??= Iota.DEFAULT_COIN_TYPE;
@@ -70,10 +69,10 @@ class Iota {
      * @returns The list of addresses.
      */
     static getAddresses(seed, coinType, accountIndex, startAddressIndex, count, isInternal) {
-        Guards.integer(Iota._CLASS_NAME, "coinType", coinType);
-        Guards.integer(Iota._CLASS_NAME, "accountIndex", accountIndex);
-        Guards.integer(Iota._CLASS_NAME, "startAddressIndex", startAddressIndex);
-        Guards.integer(Iota._CLASS_NAME, "count", count);
+        Guards.integer(Iota.CLASS_NAME, "coinType", coinType);
+        Guards.integer(Iota.CLASS_NAME, "accountIndex", accountIndex);
+        Guards.integer(Iota.CLASS_NAME, "startAddressIndex", startAddressIndex);
+        Guards.integer(Iota.CLASS_NAME, "count", count);
         const addresses = [];
         for (let i = startAddressIndex; i < startAddressIndex + count; i++) {
             // Derive the keypair using the seed
@@ -93,9 +92,9 @@ class Iota {
      * @returns The key pair containing private key and public key.
      */
     static getKeyPair(seed, coinType, accountIndex, addressIndex, isInternal) {
-        Guards.integer(Iota._CLASS_NAME, "coinType", coinType);
-        Guards.integer(Iota._CLASS_NAME, "accountIndex", accountIndex);
-        Guards.integer(Iota._CLASS_NAME, "addressIndex", addressIndex);
+        Guards.integer(Iota.CLASS_NAME, "coinType", coinType);
+        Guards.integer(Iota.CLASS_NAME, "accountIndex", accountIndex);
+        Guards.integer(Iota.CLASS_NAME, "addressIndex", addressIndex);
         const keyPair = Bip44.keyPair(seed, KeyType.Ed25519, coinType ?? Iota.DEFAULT_COIN_TYPE, accountIndex, isInternal ?? false, addressIndex);
         return keyPair;
     }
@@ -103,7 +102,7 @@ class Iota {
      * Prepare and post a transaction.
      * @param config The configuration.
      * @param vaultConnector The vault connector.
-     * @param loggingConnector The logging connector.
+     * @param logging The logging component.
      * @param identity The identity of the user to access the vault keys.
      * @param client The client instance.
      * @param source The source address.
@@ -112,27 +111,27 @@ class Iota {
      * @param options The transaction options.
      * @returns The transaction result.
      */
-    static async prepareAndPostValueTransaction(config, vaultConnector, loggingConnector, identity, client, source, amount, recipient, options) {
+    static async prepareAndPostValueTransaction(config, vaultConnector, logging, identity, client, source, amount, recipient, options) {
         try {
             const txb = new Transaction();
             const [coin] = txb.splitCoins(txb.gas, [txb.pure.u64(amount)]);
             txb.transferObjects([coin], txb.pure.address(recipient));
             // Check if gas station configuration is present
             if (Is.object(config.gasStation)) {
-                return await this.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, source, txb);
+                return await Iota.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, source, txb);
             }
-            const result = await this.prepareAndPostTransaction(config, vaultConnector, loggingConnector, identity, client, source, txb, options);
+            const result = await Iota.prepareAndPostTransaction(config, vaultConnector, logging, identity, client, source, txb, options);
             return result;
         }
         catch (error) {
-            throw new GeneralError(Iota._CLASS_NAME, "valueTransactionFailed", undefined, Iota.extractPayloadError(error));
+            throw new GeneralError(Iota.CLASS_NAME, "valueTransactionFailed", undefined, Iota.extractPayloadError(error));
         }
     }
     /**
      * Prepare and post a transaction.
      * @param config The configuration.
      * @param vaultConnector The vault connector.
-     * @param loggingConnector The logging connector.
+     * @param logging The logging component.
      * @param identity The identity of the user to access the vault keys.
      * @param client The client instance.
      * @param owner The owner of the address.
@@ -140,17 +139,17 @@ class Iota {
      * @param options The transaction options.
      * @returns The transaction response.
      */
-    static async prepareAndPostTransaction(config, vaultConnector, loggingConnector, identity, client, owner, transaction, options) {
+    static async prepareAndPostTransaction(config, vaultConnector, logging, identity, client, owner, transaction, options) {
         // Check if gas station configuration is present
         if (Is.object(config.gasStation)) {
-            return this.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, owner, transaction, options);
+            return Iota.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, owner, transaction, options);
         }
         // Traditional transaction flow
         // Dry run the transaction if cost logging is enabled to get the gas and storage costs
         if (Is.stringValue(options?.dryRunLabel)) {
-            await Iota.dryRunTransaction(client, loggingConnector, transaction, owner, options.dryRunLabel);
+            await Iota.dryRunTransaction(client, logging, transaction, owner, options.dryRunLabel);
         }
-        const seed = await this.getSeed(config, vaultConnector, identity);
+        const seed = await Iota.getSeed(config, vaultConnector, identity);
         const addressKeyPair = Iota.findAddress(config.maxAddressScanRange ?? Iota.DEFAULT_SCAN_RANGE, config.coinType ?? Iota.DEFAULT_COIN_TYPE, seed, owner);
         const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
         try {
@@ -176,7 +175,7 @@ class Iota {
             return response;
         }
         catch (error) {
-            throw new GeneralError(Iota._CLASS_NAME, "transactionFailed", undefined, Iota.extractPayloadError(error));
+            throw new GeneralError(Iota.CLASS_NAME, "transactionFailed", undefined, Iota.extractPayloadError(error));
         }
     }
     /**
@@ -211,7 +210,7 @@ class Iota {
                 return addressKeyPair;
             }
         }
-        throw new GeneralError(Iota._CLASS_NAME, "addressNotFound", { address });
+        throw new GeneralError(Iota.CLASS_NAME, "addressNotFound", { address });
     }
     /**
      * Extract error from SDK payload.
@@ -224,8 +223,11 @@ class Iota {
             if (!Is.empty(error.inner)) {
                 error.inner = Iota.extractPayloadError(error.inner);
             }
+            if (!Is.empty(error.cause)) {
+                error.cause = Iota.extractPayloadError(error.cause);
+            }
             if (error.code === "InsufficientGas") {
-                return new GeneralError(Iota._CLASS_NAME, "insufficientFunds");
+                return new GeneralError(Iota.CLASS_NAME, "insufficientFunds");
             }
             else if (error.message?.startsWith("ErrorObject")) {
                 const msg = /message: "(.*)"/.exec(error.message);
@@ -237,7 +239,7 @@ class Iota {
         const baseError = BaseError.fromError(error);
         if (baseError.name === "Base" && !Is.stringValue(baseError.source)) {
             baseError.name = "IOTA";
-            baseError.source = Iota._CLASS_NAME;
+            baseError.source = Iota.CLASS_NAME;
         }
         return baseError;
     }
@@ -277,7 +279,7 @@ class Iota {
                 if (packageObject?.error?.code === "notExists") {
                     return false;
                 }
-                throw new GeneralError(Iota._CLASS_NAME, "packageObjectError", {
+                throw new GeneralError(Iota.CLASS_NAME, "packageObjectError", {
                     packageId,
                     error: packageObject.error
                 });
@@ -285,16 +287,15 @@ class Iota {
             return true;
         }
         catch (error) {
-            throw new GeneralError(Iota._CLASS_NAME, "packageNotFoundOnNetwork", {
-                packageId,
-                error: Iota.extractPayloadError(error)
-            });
+            throw new GeneralError(Iota.CLASS_NAME, "packageNotFoundOnNetwork", {
+                packageId
+            }, Iota.extractPayloadError(error));
         }
     }
     /**
      * Dry run a transaction and log the results.
      * @param client The IOTA client.
-     * @param logging The logging connector.
+     * @param logging The logging component.
      * @param txb The transaction to dry run.
      * @param sender The sender address.
      * @param operation The operation to log.
@@ -311,7 +312,7 @@ class Iota {
                 transactionBlock: builtTx
             });
             if (dryRunResult.effects.status?.status !== "success") {
-                throw new GeneralError(this._CLASS_NAME, "dryRunFailed", {
+                throw new GeneralError(Iota.CLASS_NAME, "dryRunFailed", {
                     error: dryRunResult.effects?.status?.error
                 });
             }
@@ -328,25 +329,23 @@ class Iota {
                 balanceChanges: dryRunResult.balanceChanges ?? [],
                 objectChanges: dryRunResult.objectChanges ?? []
             };
-            if (logging) {
-                await logging.log({
-                    level: "info",
-                    source: Iota._CLASS_NAME,
-                    ts: Date.now(),
-                    message: "transactionCosts",
-                    data: {
-                        operation,
-                        ...result
-                    }
-                });
-            }
+            await logging?.log({
+                level: "info",
+                source: Iota.CLASS_NAME,
+                ts: Date.now(),
+                message: "transactionCosts",
+                data: {
+                    operation,
+                    cost: JSON.stringify(result)
+                }
+            });
             return result;
         }
         catch (error) {
-            if (error instanceof GeneralError) {
+            if (BaseError.isErrorName(error, GeneralError.CLASS_NAME)) {
                 throw error;
             }
-            throw new GeneralError(Iota._CLASS_NAME, "dryRunFailed", undefined, Iota.extractPayloadError(error));
+            throw new GeneralError(Iota.CLASS_NAME, "dryRunFailed", undefined, Iota.extractPayloadError(error));
         }
     }
     /**
@@ -400,11 +399,11 @@ class Iota {
      * @returns The transaction response.
      */
     static async prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, owner, transaction, options) {
-        Guards.object(this._CLASS_NAME, "config.gasStation", config.gasStation);
+        Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
         try {
             // Reserve gas from the gas station
             const gasBudget = config.gasBudget ?? 50000000;
-            const gasReservation = await this.reserveGas(config, gasBudget);
+            const gasReservation = await Iota.reserveGas(config, gasBudget);
             // Set transaction parameters for sponsoring
             transaction.setSender(owner);
             transaction.setGasOwner(gasReservation.sponsorAddress);
@@ -413,14 +412,14 @@ class Iota {
             // Build and sign transaction
             const unsignedTxBytes = await transaction.build({ client });
             // Sign the transaction with the user's private key
-            const seed = await this.getSeed(config, vaultConnector, identity);
+            const seed = await Iota.getSeed(config, vaultConnector, identity);
             const addressKeyPair = Iota.findAddress(config.maxAddressScanRange ?? Iota.DEFAULT_SCAN_RANGE, config.coinType ?? Iota.DEFAULT_COIN_TYPE, seed, owner);
             const keypair = Ed25519Keypair.fromSecretKey(addressKeyPair.privateKey);
             const signature = await keypair.signTransaction(unsignedTxBytes);
-            return await this.executeAndConfirmGasStationTransaction(config, client, gasReservation.reservationId, unsignedTxBytes, signature.signature, options);
+            return await Iota.executeAndConfirmGasStationTransaction(config, client, gasReservation.reservationId, unsignedTxBytes, signature.signature, options);
         }
         catch (error) {
-            throw new GeneralError(Iota._CLASS_NAME, "gasStationTransactionFailed", undefined, Iota.extractPayloadError(error));
+            throw new GeneralError(Iota.CLASS_NAME, "gasStationTransactionFailed", undefined, Iota.extractPayloadError(error));
         }
     }
     /**
@@ -430,7 +429,7 @@ class Iota {
      * @returns The gas reservation result.
      */
     static async reserveGas(config, gasBudget) {
-        Guards.object(this._CLASS_NAME, "config.gasStation", config.gasStation);
+        Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
         const requestData = {
             // eslint-disable-next-line camelcase
             gas_budget: gasBudget,
@@ -438,7 +437,7 @@ class Iota {
             reserve_duration_secs: 30
         };
         const baseUrl = StringHelper.trimTrailingSlashes(config.gasStation.gasStationUrl);
-        const result = await FetchHelper.fetchJson(this._CLASS_NAME, `${baseUrl}/v1/reserve_gas`, HttpMethod.POST, requestData, {
+        const result = await FetchHelper.fetchJson(Iota.CLASS_NAME, `${baseUrl}/v1/reserve_gas`, HttpMethod.POST, requestData, {
             headers: {
                 Authorization: `Bearer ${config.gasStation.gasStationAuthToken}`
             }
@@ -459,7 +458,7 @@ class Iota {
      * @returns The transaction response.
      */
     static async executeGasStationTransaction(config, reservationId, transactionBytes, userSignature) {
-        Guards.object(this._CLASS_NAME, "config.gasStation", config.gasStation);
+        Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
         const requestData = {
             // eslint-disable-next-line camelcase
             reservation_id: reservationId,
@@ -469,7 +468,7 @@ class Iota {
             user_sig: userSignature
         };
         const baseUrl = StringHelper.trimTrailingSlashes(config.gasStation.gasStationUrl);
-        const result = await FetchHelper.fetchJson(this._CLASS_NAME, `${baseUrl}/v1/execute_tx`, HttpMethod.POST, requestData, {
+        const result = await FetchHelper.fetchJson(Iota.CLASS_NAME, `${baseUrl}/v1/execute_tx`, HttpMethod.POST, requestData, {
             headers: {
                 Authorization: `Bearer ${config.gasStation.gasStationAuthToken}`
             }
@@ -495,8 +494,8 @@ class Iota {
      * @returns The transaction response (confirmed if waitForConfirmation is true).
      */
     static async executeAndConfirmGasStationTransaction(config, client, reservationId, transactionBytes, userSignature, options) {
-        Guards.object(this._CLASS_NAME, "config.gasStation", config.gasStation);
-        const response = await this.executeGasStationTransaction(config, reservationId, transactionBytes, userSignature);
+        Guards.object(Iota.CLASS_NAME, "config.gasStation", config.gasStation);
+        const response = await Iota.executeGasStationTransaction(config, reservationId, transactionBytes, userSignature);
         if (options?.waitForConfirmation ?? true) {
             const confirmedTransaction = await Iota.waitForTransactionConfirmation(client, response.digest, config, {
                 showEffects: options?.showEffects ?? true,
@@ -509,4 +508,434 @@ class Iota {
     }
 }
 
-export { Iota };
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Utility class providing common smart contract operations for IOTA-based contracts.
+ * This class uses composition pattern to provide shared functionality without inheritance complexity.
+ */
+class IotaSmartContractUtils {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "IotaSmartContractUtils";
+    /**
+     * Migrate a smart contract object to the current version using admin privileges.
+     * This is a generic migration method that works with any IOTA smart contract.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param vaultConnector The vault connector for key management.
+     * @param walletConnector The wallet connector for address generation.
+     * @param logging Optional logging component.
+     * @param gasBudget The gas budget for the transaction.
+     * @param identity The identity of the controller with admin privileges.
+     * @param objectId The ID of the object to migrate.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param deploymentConfig The deployment configuration containing object IDs.
+     * @param walletAddressIndex Optional wallet address index for the controller.
+     * @returns Promise that resolves when migration is complete.
+     */
+    static async migrateSmartContract(config, client, vaultConnector, walletConnector, logging, gasBudget, identity, objectId, namespace, packageId, deploymentConfig, walletAddressIndex) {
+        try {
+            const txb = new Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = IotaSmartContractUtils.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await IotaSmartContractUtils.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await IotaSmartContractUtils.getContractObjectIds(client, namespace, config.network, deploymentConfig, packageId, adminAddress);
+            txb.moveCall({
+                target: `${packageId}::${moduleName}::migrate_${moduleName}`,
+                arguments: [txb.object(adminCapId), txb.object(migrationStateId), txb.object(objectId)]
+            });
+            const result = await Iota.prepareAndPostTransaction(config, vaultConnector, logging, identity, client, adminAddress, txb, {
+                dryRunLabel: config.enableCostLogging ? "migrate_object" : undefined
+            });
+            if (result.effects?.status?.status !== "success") {
+                throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrationFailed", {
+                    error: result.effects?.status?.error,
+                    objectId
+                });
+            }
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrateSmartContractFailed", { objectId }, error);
+        }
+    }
+    /**
+     * Enable migration operations using admin privileges.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param vaultConnector The vault connector for key management.
+     * @param walletConnector The wallet connector for address generation.
+     * @param logging Optional logging component.
+     * @param gasBudget The gas budget for the transaction.
+     * @param identity The identity of the controller with admin privileges.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param deploymentConfig The deployment configuration containing object IDs.
+     * @param walletAddressIndex Optional wallet address index for the controller.
+     * @returns Promise that resolves when migration is enabled.
+     */
+    static async enableMigration(config, client, vaultConnector, walletConnector, logging, gasBudget, identity, namespace, packageId, deploymentConfig, walletAddressIndex) {
+        try {
+            const txb = new Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = IotaSmartContractUtils.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await IotaSmartContractUtils.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await IotaSmartContractUtils.getContractObjectIds(client, namespace, config.network, deploymentConfig, packageId, adminAddress);
+            txb.moveCall({
+                target: `${packageId}::${moduleName}::enable_migration`,
+                arguments: [txb.object(adminCapId), txb.object(migrationStateId)]
+            });
+            const result = await Iota.prepareAndPostTransaction(config, vaultConnector, logging, identity, client, adminAddress, txb, {
+                dryRunLabel: config.enableCostLogging ? "enable_migration" : undefined
+            });
+            if (result.effects?.status?.status !== "success") {
+                throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "enableMigrationFailed", {
+                    error: result.effects?.status?.error
+                });
+            }
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "enableMigrationFailed", undefined, error);
+        }
+    }
+    /**
+     * Disable migration operations using admin privileges.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param vaultConnector The vault connector for key management.
+     * @param walletConnector The wallet connector for address generation.
+     * @param logging Optional logging component.
+     * @param gasBudget The gas budget for the transaction.
+     * @param identity The identity of the controller with admin privileges.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param deploymentConfig The deployment configuration containing object IDs.
+     * @param walletAddressIndex Optional wallet address index for the controller.
+     * @returns Promise that resolves when migration is disabled.
+     */
+    static async disableMigration(config, client, vaultConnector, walletConnector, logging, gasBudget, identity, namespace, packageId, deploymentConfig, walletAddressIndex) {
+        try {
+            const txb = new Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = IotaSmartContractUtils.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await IotaSmartContractUtils.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await IotaSmartContractUtils.getContractObjectIds(client, namespace, config.network, deploymentConfig, packageId, adminAddress);
+            txb.moveCall({
+                target: `${packageId}::${moduleName}::disable_migration`,
+                arguments: [txb.object(adminCapId), txb.object(migrationStateId)]
+            });
+            const result = await Iota.prepareAndPostTransaction(config, vaultConnector, logging, identity, client, adminAddress, txb, {
+                dryRunLabel: config.enableCostLogging ? "disable_migration" : undefined
+            });
+            if (result.effects?.status?.status !== "success") {
+                throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "disableMigrationFailed", {
+                    error: result.effects?.status?.error
+                });
+            }
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "disableMigrationFailed", undefined, error);
+        }
+    }
+    /**
+     * Check if migration is currently active for a smart contract.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param deploymentConfig The deployment configuration containing object IDs.
+     * @param identity The identity for MigrationState discovery.
+     * @param walletConnector The wallet connector for address generation.
+     * @param walletAddressIndex Optional wallet address index.
+     * @returns True if migration is enabled, false otherwise.
+     */
+    static async isMigrationActive(config, client, namespace, packageId, deploymentConfig, identity, walletConnector, walletAddressIndex) {
+        try {
+            // Get admin address for discovery
+            const adminAddress = await IotaSmartContractUtils.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the migration state ID
+            const { migrationStateId } = await IotaSmartContractUtils.getContractObjectIds(client, namespace, config.network, deploymentConfig, packageId, adminAddress);
+            const migrationStateResponse = await client.getObject({
+                id: migrationStateId,
+                options: {
+                    showContent: true,
+                    showType: true
+                }
+            });
+            if (!migrationStateResponse.data?.content) {
+                throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrationStateNotReadable", {
+                    migrationStateId
+                });
+            }
+            const content = migrationStateResponse.data.content;
+            if (content.dataType === "moveObject" && Is.objectValue(content.fields)) {
+                const fields = content.fields;
+                return Is.boolean(fields.enabled) ? fields.enabled : false;
+            }
+            return false;
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "isMigrationActiveFailed", undefined, error);
+        }
+    }
+    /**
+     * Get the current contract version from the deployed smart contract.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param identity The identity for package controller address.
+     * @param walletConnector The wallet connector for address generation.
+     * @param walletAddressIndex Optional wallet address index.
+     * @returns The current version number of the contract.
+     */
+    static async getCurrentContractVersion(config, client, namespace, packageId, identity, walletConnector, walletAddressIndex) {
+        try {
+            const tx = new Transaction();
+            const moduleName = IotaSmartContractUtils.getModuleName(namespace);
+            tx.moveCall({
+                target: `${packageId}::${moduleName}::get_current_version`,
+                arguments: []
+            });
+            const controllerAddress = await IotaSmartContractUtils.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            const result = await client.devInspectTransactionBlock({
+                sender: controllerAddress,
+                transactionBlock: tx
+            });
+            if (Is.arrayValue(result.results) &&
+                Is.object(result.results[0]) &&
+                Is.arrayValue(result.results[0].returnValues)) {
+                const versionBytes = result.results[0].returnValues[0];
+                // Convert to Uint8Array if it's a regular array
+                const byteData = versionBytes[0];
+                if (!Is.arrayValue(byteData) && !Is.uint8Array(byteData)) {
+                    throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "invalidVersionData");
+                }
+                // Convert to Uint8Array for BCS parsing
+                const uint8Data = Is.uint8Array(byteData) ? byteData : new Uint8Array(byteData);
+                // The version is returned as a u64, decode it from bytes using BCS
+                // IOTA Move contracts return data in BCS format
+                const version = Number(bcs.u64().parse(uint8Data));
+                return version;
+            }
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "getCurrentContractVersionNoData", {
+                resultExists: Is.arrayValue(result.results),
+                resultLength: Is.arrayValue(result.results) ? result.results.length : 0,
+                hasReturnValues: Is.arrayValue(result.results?.[0]?.returnValues)
+            });
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "getCurrentContractVersionFailed", undefined, error);
+        }
+    }
+    /**
+     * Validate that an object version is compatible with the current contract.
+     * @param config The IOTA configuration.
+     * @param client The IOTA client instance.
+     * @param namespace The contract namespace (e.g., "nft", "verifiable_storage").
+     * @param packageId The deployed package ID for the contract.
+     * @param identity The identity for version checking.
+     * @param objectId The object ID to validate.
+     * @param walletConnector The wallet connector for address generation.
+     * @param versionExtractor Function to extract version from object content.
+     * @param walletAddressIndex Optional wallet address index.
+     * @returns True if the object version is compatible, false otherwise.
+     */
+    static async validateObjectVersion(config, client, namespace, packageId, identity, objectId, walletConnector, versionExtractor, walletAddressIndex) {
+        try {
+            // Get current contract version
+            const currentVersion = await IotaSmartContractUtils.getCurrentContractVersion(config, client, namespace, packageId, identity, walletConnector, walletAddressIndex);
+            // Get object version
+            const objectResponse = await client.getObject({
+                id: objectId,
+                options: {
+                    showContent: true,
+                    showType: true
+                }
+            });
+            if (!objectResponse.data?.content) {
+                throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "objectNotReadable", {
+                    objectId
+                });
+            }
+            const content = objectResponse.data.content;
+            if (content.dataType === "moveObject" && Is.objectValue(content.fields)) {
+                const objectVersion = versionExtractor(content);
+                return objectVersion <= currentVersion;
+            }
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "objectInvalidFormat", {
+                objectId,
+                content
+            });
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "validateObjectVersionFailed", { objectId }, error);
+        }
+    }
+    /**
+     * Get the module name for a given namespace.
+     * @param namespace The contract namespace.
+     * @returns The module name in snake_case format.
+     * @internal
+     */
+    static getModuleName(namespace) {
+        // Convert namespace to snake_case for module name
+        return StringHelper.snakeCase(namespace);
+    }
+    /**
+     * Get the package controller address for transactions.
+     * @param walletConnector The wallet connector for address generation.
+     * @param identity The identity to use.
+     * @param addressIndex Optional address index to use.
+     * @returns The controller address.
+     * @internal
+     */
+    static async getPackageControllerAddress(walletConnector, identity, addressIndex = 0) {
+        const addresses = await walletConnector.getAddresses(identity, 0, addressIndex, 1);
+        return addresses[0];
+    }
+    /**
+     * Get contract object IDs (AdminCap and MigrationState) from deployment config with fallback discovery.
+     * @param client The IOTA client instance.
+     * @param namespace The contract namespace.
+     * @param network The network name.
+     * @param deploymentConfig The deployment configuration.
+     * @param packageId The package ID.
+     * @param adminAddress The admin address for object discovery.
+     * @returns Object containing adminCapId and migrationStateId.
+     * @internal
+     */
+    static async getContractObjectIds(client, namespace, network, deploymentConfig, packageId, adminAddress) {
+        try {
+            // First try to load from deployment JSON
+            const networkConfig = deploymentConfig[network];
+            if (Is.objectValue(networkConfig)) {
+                const migrationStateId = networkConfig.migrationStateId;
+                // AdminCap must be discovered from blockchain (not stored in JSON)
+                const adminCapId = await IotaSmartContractUtils.discoverAdminCap(client, packageId, namespace, adminAddress);
+                if (Is.stringValue(migrationStateId) && Is.stringValue(adminCapId)) {
+                    return { adminCapId, migrationStateId };
+                }
+            }
+            // Fallback: discover both from blockchain
+            return await IotaSmartContractUtils.discoverContractObjectsFromBlockchain(client, packageId, namespace, adminAddress);
+        }
+        catch (error) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "getContractObjectIdsFailed", { namespace, network, packageId }, error);
+        }
+    }
+    /**
+     * Discover AdminCap object from the blockchain.
+     * @param client The IOTA client instance.
+     * @param packageId The package ID.
+     * @param namespace The contract namespace.
+     * @param adminAddress The admin address.
+     * @returns The AdminCap object ID.
+     * @internal
+     */
+    static async discoverAdminCap(client, packageId, namespace, adminAddress) {
+        const adminCapType = `${packageId}::${IotaSmartContractUtils.getModuleName(namespace)}::AdminCap`;
+        const adminCapObjects = await client.getOwnedObjects({
+            owner: adminAddress,
+            filter: {
+                StructType: adminCapType
+            },
+            options: {
+                showContent: true,
+                showType: true
+            }
+        });
+        if (Is.arrayValue(adminCapObjects.data) && adminCapObjects.data.length > 0) {
+            const adminCapObject = adminCapObjects.data[0];
+            if (Is.stringValue(adminCapObject.data?.objectId)) {
+                return adminCapObject.data.objectId;
+            }
+        }
+        throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "adminCapNotFound", {
+            adminCapType,
+            adminAddress
+        });
+    }
+    /**
+     * Discover contract objects from blockchain as fallback.
+     * @param client The IOTA client instance.
+     * @param packageId The package ID.
+     * @param namespace The contract namespace.
+     * @param adminAddress The admin address.
+     * @returns Object containing adminCapId and migrationStateId.
+     * @internal
+     */
+    static async discoverContractObjectsFromBlockchain(client, packageId, namespace, adminAddress) {
+        // Discover AdminCap
+        const adminCapId = await IotaSmartContractUtils.discoverAdminCap(client, packageId, namespace, adminAddress);
+        // Discover MigrationState through transaction history
+        const migrationStateType = `${packageId}::${IotaSmartContractUtils.getModuleName(namespace)}::MigrationState`;
+        const transactions = await client.queryTransactionBlocks({
+            filter: {
+                FromAddress: adminAddress
+            },
+            options: {
+                showObjectChanges: true,
+                showEffects: true
+            },
+            limit: 20,
+            order: "descending"
+        });
+        // Look for MigrationState object creation in transaction history
+        let migrationStateId;
+        for (const tx of transactions.data) {
+            const objectChanges = tx.objectChanges;
+            if (Is.arrayValue(objectChanges)) {
+                for (const change of objectChanges) {
+                    if ((change.type === "created" || change.type === "mutated") &&
+                        "objectType" in change &&
+                        change.objectType === migrationStateType) {
+                        migrationStateId = change.objectId;
+                        break;
+                    }
+                }
+                if (migrationStateId) {
+                    break;
+                }
+            }
+        }
+        if (!migrationStateId) {
+            throw new GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrationStateNotFound", {
+                migrationStateType,
+                adminAddress
+            });
+        }
+        return { adminCapId, migrationStateId };
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Network types supported for deployment
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const NetworkTypes = {
+    /**
+     * Testnet.
+     */
+    Testnet: "testnet",
+    /**
+     * Devnet.
+     */
+    Devnet: "devnet",
+    /**
+     * Mainnet.
+     */
+    Mainnet: "mainnet"
+};
+
+export { Iota, IotaSmartContractUtils, NetworkTypes };