@twin.org/dlt-iota 0.0.2-next.2 → 0.0.2-next.4

package/dist/cjs/index.cjs

@@ -105,7 +105,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.
@@ -114,7 +114,7 @@ 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 transactions.Transaction();
             const [coin] = txb.splitCoins(txb.gas, [txb.pure.u64(amount)]);
@@ -123,7 +123,7 @@ class Iota {
             if (core.Is.object(config.gasStation)) {
                 return await this.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, source, txb);
             }
-            const result = await this.prepareAndPostTransaction(config, vaultConnector, loggingConnector, identity, client, source, txb, options);
+            const result = await this.prepareAndPostTransaction(config, vaultConnector, logging, identity, client, source, txb, options);
             return result;
         }
         catch (error) {
@@ -134,7 +134,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 owner The owner of the address.
@@ -142,7 +142,7 @@ 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 (core.Is.object(config.gasStation)) {
             return this.prepareAndPostGasStationTransaction(config, vaultConnector, identity, client, owner, transaction, options);
@@ -150,7 +150,7 @@ class Iota {
         // Traditional transaction flow
         // Dry run the transaction if cost logging is enabled to get the gas and storage costs
         if (core.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 addressKeyPair = Iota.findAddress(config.maxAddressScanRange ?? Iota.DEFAULT_SCAN_RANGE, config.coinType ?? Iota.DEFAULT_COIN_TYPE, seed, owner);
@@ -296,7 +296,7 @@ class Iota {
     /**
      * 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.
@@ -511,4 +511,436 @@ class 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 transactions.Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = this.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await this.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await this.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 core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrationFailed", {
+                    error: result.effects?.status?.error,
+                    objectId
+                });
+            }
+        }
+        catch (error) {
+            throw new core.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 transactions.Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = this.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await this.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await this.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 core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "enableMigrationFailed", {
+                    error: result.effects?.status?.error
+                });
+            }
+        }
+        catch (error) {
+            throw new core.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 transactions.Transaction();
+            txb.setGasBudget(gasBudget);
+            const moduleName = this.getModuleName(namespace);
+            // Get admin address for the transaction
+            const adminAddress = await this.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the required object IDs from deployment config
+            const { adminCapId, migrationStateId } = await this.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 core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "disableMigrationFailed", {
+                    error: result.effects?.status?.error
+                });
+            }
+        }
+        catch (error) {
+            throw new core.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 this.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            // Get the migration state ID
+            const { migrationStateId } = await this.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 core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "migrationStateNotReadable", {
+                    migrationStateId
+                });
+            }
+            const content = migrationStateResponse.data.content;
+            if (content.dataType === "moveObject" && core.Is.objectValue(content.fields)) {
+                const fields = content.fields;
+                return core.Is.boolean(fields.enabled) ? fields.enabled : false;
+            }
+            return false;
+        }
+        catch (error) {
+            throw new core.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 transactions.Transaction();
+            const moduleName = this.getModuleName(namespace);
+            tx.moveCall({
+                target: `${packageId}::${moduleName}::get_current_version`,
+                arguments: []
+            });
+            const controllerAddress = await this.getPackageControllerAddress(walletConnector, identity, walletAddressIndex);
+            const result = await client.devInspectTransactionBlock({
+                sender: controllerAddress,
+                transactionBlock: tx
+            });
+            if (core.Is.arrayValue(result.results) &&
+                core.Is.object(result.results[0]) &&
+                core.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 (!core.Is.arrayValue(byteData) && !core.Is.uint8Array(byteData)) {
+                    throw new core.GeneralError(this.CLASS_NAME, "invalidVersionData");
+                }
+                // Convert to Uint8Array for BCS parsing
+                const uint8Data = core.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.bcs.u64().parse(uint8Data));
+                return version;
+            }
+            throw new core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "getCurrentContractVersionNoData", {
+                resultExists: core.Is.arrayValue(result.results),
+                resultLength: core.Is.arrayValue(result.results) ? result.results.length : 0,
+                hasReturnValues: core.Is.arrayValue(result.results?.[0]?.returnValues)
+            });
+        }
+        catch (error) {
+            throw new core.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 this.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 core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "objectNotReadable", {
+                    objectId
+                });
+            }
+            const content = objectResponse.data.content;
+            if (content.dataType === "moveObject" && core.Is.objectValue(content.fields)) {
+                const objectVersion = versionExtractor(content);
+                return objectVersion <= currentVersion;
+            }
+            throw new core.GeneralError(IotaSmartContractUtils.CLASS_NAME, "objectInvalidFormat", {
+                objectId,
+                content
+            });
+        }
+        catch (error) {
+            throw new core.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 core.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 (core.Is.objectValue(networkConfig)) {
+                const migrationStateId = networkConfig.migrationStateId;
+                // AdminCap must be discovered from blockchain (not stored in JSON)
+                const adminCapId = await this.discoverAdminCap(client, packageId, namespace, adminAddress);
+                if (core.Is.stringValue(migrationStateId) && core.Is.stringValue(adminCapId)) {
+                    return { adminCapId, migrationStateId };
+                }
+            }
+            // Fallback: discover both from blockchain
+            return await this.discoverContractObjectsFromBlockchain(client, packageId, namespace, adminAddress);
+        }
+        catch (error) {
+            throw new core.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}::${this.getModuleName(namespace)}::AdminCap`;
+        const adminCapObjects = await client.getOwnedObjects({
+            owner: adminAddress,
+            filter: {
+                StructType: adminCapType
+            },
+            options: {
+                showContent: true,
+                showType: true
+            }
+        });
+        if (core.Is.arrayValue(adminCapObjects.data) && adminCapObjects.data.length > 0) {
+            const adminCapObject = adminCapObjects.data[0];
+            if (core.Is.stringValue(adminCapObject.data?.objectId)) {
+                return adminCapObject.data.objectId;
+            }
+        }
+        throw new core.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 this.discoverAdminCap(client, packageId, namespace, adminAddress);
+        // Discover MigrationState through transaction history
+        const migrationStateType = `${packageId}::${this.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 (core.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 core.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"
+};
+
 exports.Iota = Iota;
+exports.IotaSmartContractUtils = IotaSmartContractUtils;
+exports.NetworkTypes = NetworkTypes;