@twin.org/dlt-iota 0.0.3-next.5 → 0.0.3-next.6

package/README.md

@@ -1,6 +1,6 @@
 # TWIN DLT IOTA
 
-DLT helpers for use with IOTA.
+This package provides utilities for integrating applications with IOTA distributed ledger capabilities, including client construction, transaction submission, sponsored transaction support, and smart contract migration helpers. It is intended for services that need a reliable and repeatable approach to ledger operations without rebuilding common primitives.
 
 ## Installation
 
@@ -8,14 +8,12 @@ DLT helpers for use with IOTA.
 npm install @twin.org/dlt-iota
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of the IOTA Gas Station and Redis up and running.
-
-The simplest way to set up the testing environment using our unified container:
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
 
 ```shell
-docker run -d --name twin-gas-station-test -p 9527:9527 -p 6379:6379 -p 9184:9184 twinfoundation/twin-gas-station-test:latest
+docker run -d --name twin-dlt-iota -p 9527:9527 -p 6379:6379 -p 9184:9184 twinfoundation/twin-gas-station-test:latest
 ```
 
 ## Examples

package/dist/es/index.js

@@ -1,6 +1,7 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 export * from "./iota.js";
+export * from "./iotaIdentityUtils.js";
 export * from "./iotaSmartContractUtils.js";
 export * from "./models/IAdminCapFields.js";
 export * from "./models/IContractData.js";
@@ -10,6 +11,7 @@ export * from "./models/IGasStationExecuteResponse.js";
 export * from "./models/IGasStationReserveGasResponse.js";
 export * from "./models/IGasStationReserveGasResult.js";
 export * from "./models/IIotaClient.js";
+export * from "./models/IIotaControllerCapInfo.js";
 export * from "./models/IIotaTransaction.js";
 export * from "./models/IIotaTransactionBlockResponse.js";
 export * from "./models/IIotaConfig.js";

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./iota.js\";\nexport * from \"./iotaSmartContractUtils.js\";\nexport * from \"./models/IAdminCapFields.js\";\nexport * from \"./models/IContractData.js\";\nexport * from \"./models/IGasReservationResult.js\";\nexport * from \"./models/IGasStationConfig.js\";\nexport * from \"./models/IGasStationExecuteResponse.js\";\nexport * from \"./models/IGasStationReserveGasResponse.js\";\nexport * from \"./models/IGasStationReserveGasResult.js\";\nexport * from \"./models/IIotaClient.js\";\nexport * from \"./models/IIotaTransaction.js\";\nexport * from \"./models/IIotaTransactionBlockResponse.js\";\nexport * from \"./models/IIotaConfig.js\";\nexport * from \"./models/IIotaDryRun.js\";\nexport * from \"./models/IIotaResponseOptions.js\";\nexport * from \"./models/IMigrationStateFields.js\";\nexport * from \"./models/ISmartContractDeployments.js\";\nexport * from \"./models/ISmartContractObject.js\";\nexport * from \"./models/networkTypes.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,WAAW,CAAC;AAC1B,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./iota.js\";\nexport * from \"./iotaIdentityUtils.js\";\nexport * from \"./iotaSmartContractUtils.js\";\nexport * from \"./models/IAdminCapFields.js\";\nexport * from \"./models/IContractData.js\";\nexport * from \"./models/IGasReservationResult.js\";\nexport * from \"./models/IGasStationConfig.js\";\nexport * from \"./models/IGasStationExecuteResponse.js\";\nexport * from \"./models/IGasStationReserveGasResponse.js\";\nexport * from \"./models/IGasStationReserveGasResult.js\";\nexport * from \"./models/IIotaClient.js\";\nexport * from \"./models/IIotaControllerCapInfo.js\";\nexport * from \"./models/IIotaTransaction.js\";\nexport * from \"./models/IIotaTransactionBlockResponse.js\";\nexport * from \"./models/IIotaConfig.js\";\nexport * from \"./models/IIotaDryRun.js\";\nexport * from \"./models/IIotaResponseOptions.js\";\nexport * from \"./models/IMigrationStateFields.js\";\nexport * from \"./models/ISmartContractDeployments.js\";\nexport * from \"./models/ISmartContractObject.js\";\nexport * from \"./models/networkTypes.js\";\n"]}

package/dist/es/iotaIdentityUtils.js

@@ -0,0 +1,77 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { IdentityClient, IdentityClientReadOnly, OnChainIdentity } from "@iota/identity-wasm/node/index.js";
+import { Ed25519PublicKey } from "@iota/iota-sdk/keypairs/ed25519";
+import { GeneralError, Guards, Is, NotFoundError } from "@twin.org/core";
+import { Iota } from "./iota.js";
+/**
+ * Utility class for resolving IOTA Identity on-chain objects required by
+ * the NFT mint_with_identity() Move contract function.
+ */
+export class IotaIdentityUtils {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "IotaIdentityUtils";
+    /**
+     * Resolve the on-chain object IDs for an identity and its controller token.
+     * Returns the IDs needed to call mint_with_identity() on the NFT Move contract.
+     * @param identityId The DID of the identity (e.g. "did:iota:testnet:0x...").
+     * @param controllerAddress The on-chain address of the controller wallet.
+     * @param client The IOTA client instance.
+     * @returns The identity object ID and controller token object ID.
+     * @throws NotFoundError if the identity does not exist on-chain.
+     * @throws GeneralError if the identity has been deleted or the controller token is not found.
+     */
+    static async getControllerCapInfo(identityId, controllerAddress, client) {
+        Guards.stringValue(IotaIdentityUtils.CLASS_NAME, "identityId", identityId);
+        Guards.stringValue(IotaIdentityUtils.CLASS_NAME, "controllerAddress", controllerAddress);
+        // Extract the Object ID from the DID — last colon-delimited segment, prefixed with 0x.
+        // IOTA DIDs have the format did:iota:<network>:<hex> where <hex> has no 0x prefix.
+        const idParts = identityId.split(":");
+        const identityObjectId = `0x${idParts[idParts.length - 1]}`;
+        let onChain;
+        let controllerToken;
+        try {
+            // Both are IotaClient@1.11.0 but TypeScript resolves them from different module
+            // entry points (dist/esm vs dist/cjs). The protected `transport` field causes a
+            // class-compatibility failure even though the runtime types are identical.
+            // Casting through the function's own parameter type keeps this refactor-safe.
+            const identityClientReadOnly = await IdentityClientReadOnly.create(client);
+            // getControllerTokenForAddress requires IdentityClient even though the operation is
+            // read-only — the signer is never called, only the embedded CoreClientReadOnly is
+            // used. TransactionSigner is a structural interface, so a minimal object literal
+            // that satisfies its shape avoids importing the heavyweight JWK store machinery.
+            const noOpSigner = {
+                sign: async (_txData) => {
+                    throw new GeneralError(IotaIdentityUtils.CLASS_NAME, "unexpectedSignerCall", undefined);
+                },
+                publicKey: async () => new Ed25519PublicKey(new Uint8Array(32)),
+                iotaPublicKeyBytes: async () => new Uint8Array(32),
+                keyId: () => ""
+            };
+            const identityClient = await IdentityClient.create(identityClientReadOnly, noOpSigner);
+            onChain = await OnChainIdentity.getById(identityObjectId, identityClient);
+            if (!Is.undefined(onChain) && !onChain.hasDeletedDid()) {
+                controllerToken = await onChain.getControllerTokenForAddress(controllerAddress, identityClient);
+            }
+        }
+        catch (error) {
+            throw new GeneralError(IotaIdentityUtils.CLASS_NAME, "getControllerCapInfoFailed", undefined, Iota.extractPayloadError(error));
+        }
+        if (Is.undefined(onChain)) {
+            throw new NotFoundError(IotaIdentityUtils.CLASS_NAME, "identityNotFound", identityId);
+        }
+        if (onChain.hasDeletedDid()) {
+            throw new GeneralError(IotaIdentityUtils.CLASS_NAME, "identityDeleted", { identityId });
+        }
+        if (Is.undefined(controllerToken)) {
+            throw new NotFoundError(IotaIdentityUtils.CLASS_NAME, "controllerTokenNotFound", identityId);
+        }
+        return {
+            identityObjectId,
+            controllerCapObjectId: controllerToken.id()
+        };
+    }
+}
+//# sourceMappingURL=iotaIdentityUtils.js.map

package/dist/es/iotaIdentityUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iotaIdentityUtils.js","sourceRoot":"","sources":["../../src/iotaIdentityUtils.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tIdentityClient,\n\tIdentityClientReadOnly,\n\tOnChainIdentity\n} from \"@iota/identity-wasm/node/index.js\";\nimport type { IotaClient } from \"@iota/iota-sdk/client\";\nimport type { PublicKey } from \"@iota/iota-sdk/cryptography\";\nimport { Ed25519PublicKey } from \"@iota/iota-sdk/keypairs/ed25519\";\nimport { GeneralError, Guards, Is, NotFoundError } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { Iota } from \"./iota.js\";\nimport type { IIotaControllerCapInfo } from \"./models/IIotaControllerCapInfo.js\";\n\n/**\n * Utility class for resolving IOTA Identity on-chain objects required by\n * the NFT mint_with_identity() Move contract function.\n */\nexport class IotaIdentityUtils {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<IotaIdentityUtils>();\n\n\t/**\n\t * Resolve the on-chain object IDs for an identity and its controller token.\n\t * Returns the IDs needed to call mint_with_identity() on the NFT Move contract.\n\t * @param identityId The DID of the identity (e.g. \"did:iota:testnet:0x...\").\n\t * @param controllerAddress The on-chain address of the controller wallet.\n\t * @param client The IOTA client instance.\n\t * @returns The identity object ID and controller token object ID.\n\t * @throws NotFoundError if the identity does not exist on-chain.\n\t * @throws GeneralError if the identity has been deleted or the controller token is not found.\n\t */\n\tpublic static async getControllerCapInfo(\n\t\tidentityId: string,\n\t\tcontrollerAddress: string,\n\t\tclient: IotaClient\n\t): Promise<IIotaControllerCapInfo> {\n\t\tGuards.stringValue(IotaIdentityUtils.CLASS_NAME, nameof(identityId), identityId);\n\t\tGuards.stringValue(IotaIdentityUtils.CLASS_NAME, nameof(controllerAddress), controllerAddress);\n\n\t\t// Extract the Object ID from the DID — last colon-delimited segment, prefixed with 0x.\n\t\t// IOTA DIDs have the format did:iota:<network>:<hex> where <hex> has no 0x prefix.\n\t\tconst idParts = identityId.split(\":\");\n\t\tconst identityObjectId = `0x${idParts[idParts.length - 1]}`;\n\n\t\tlet onChain: OnChainIdentity | undefined;\n\t\tlet controllerToken: Awaited<ReturnType<OnChainIdentity[\"getControllerTokenForAddress\"]>>;\n\n\t\ttry {\n\t\t\t// Both are IotaClient@1.11.0 but TypeScript resolves them from different module\n\t\t\t// entry points (dist/esm vs dist/cjs). The protected `transport` field causes a\n\t\t\t// class-compatibility failure even though the runtime types are identical.\n\t\t\t// Casting through the function's own parameter type keeps this refactor-safe.\n\t\t\tconst identityClientReadOnly = await IdentityClientReadOnly.create(\n\t\t\t\tclient as unknown as Parameters<(typeof IdentityClientReadOnly)[\"create\"]>[0]\n\t\t\t);\n\n\t\t\t// getControllerTokenForAddress requires IdentityClient even though the operation is\n\t\t\t// read-only — the signer is never called, only the embedded CoreClientReadOnly is\n\t\t\t// used. TransactionSigner is a structural interface, so a minimal object literal\n\t\t\t// that satisfies its shape avoids importing the heavyweight JWK store machinery.\n\t\t\tconst noOpSigner = {\n\t\t\t\tsign: async (_txData: Uint8Array): Promise<string> => {\n\t\t\t\t\tthrow new GeneralError(IotaIdentityUtils.CLASS_NAME, \"unexpectedSignerCall\", undefined);\n\t\t\t\t},\n\t\t\t\tpublicKey: async (): Promise<PublicKey> => new Ed25519PublicKey(new Uint8Array(32)),\n\t\t\t\tiotaPublicKeyBytes: async (): Promise<Uint8Array> => new Uint8Array(32),\n\t\t\t\tkeyId: (): string => \"\"\n\t\t\t};\n\t\t\tconst identityClient = await IdentityClient.create(identityClientReadOnly, noOpSigner);\n\n\t\t\tonChain = await OnChainIdentity.getById(identityObjectId, identityClient);\n\t\t\tif (!Is.undefined(onChain) && !onChain.hasDeletedDid()) {\n\t\t\t\tcontrollerToken = await onChain.getControllerTokenForAddress(\n\t\t\t\t\tcontrollerAddress,\n\t\t\t\t\tidentityClient\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tIotaIdentityUtils.CLASS_NAME,\n\t\t\t\t\"getControllerCapInfoFailed\",\n\t\t\t\tundefined,\n\t\t\t\tIota.extractPayloadError(error)\n\t\t\t);\n\t\t}\n\n\t\tif (Is.undefined(onChain)) {\n\t\t\tthrow new NotFoundError(IotaIdentityUtils.CLASS_NAME, \"identityNotFound\", identityId);\n\t\t}\n\n\t\tif (onChain.hasDeletedDid()) {\n\t\t\tthrow new GeneralError(IotaIdentityUtils.CLASS_NAME, \"identityDeleted\", { identityId });\n\t\t}\n\n\t\tif (Is.undefined(controllerToken)) {\n\t\t\tthrow new NotFoundError(IotaIdentityUtils.CLASS_NAME, \"controllerTokenNotFound\", identityId);\n\t\t}\n\n\t\treturn {\n\t\t\tidentityObjectId,\n\t\t\tcontrollerCapObjectId: controllerToken.id()\n\t\t};\n\t}\n}\n"]}

package/dist/es/models/IIotaControllerCapInfo.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IIotaControllerCapInfo.js.map

package/dist/es/models/IIotaControllerCapInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IIotaControllerCapInfo.js","sourceRoot":"","sources":["../../../src/models/IIotaControllerCapInfo.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * On-chain object IDs needed to call mint_with_identity() on the NFT Move contract.\n */\nexport interface IIotaControllerCapInfo {\n\t/**\n\t * The on-chain Object ID of the Identity Move object (hex string, e.g. \"0x...\").\n\t * Used as the Identity argument in mint_with_identity().\n\t */\n\tidentityObjectId: string;\n\n\t/**\n\t * The on-chain Object ID of the ControllerToken Move object (hex string, e.g. \"0x...\").\n\t * Proves that the controller address controls identityObjectId.\n\t * Used as the ControllerCap argument in mint_with_identity().\n\t */\n\tcontrollerCapObjectId: string;\n}\n"]}

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./iota.js";
+export * from "./iotaIdentityUtils.js";
 export * from "./iotaSmartContractUtils.js";
 export * from "./models/IAdminCapFields.js";
 export * from "./models/IContractData.js";
@@ -8,6 +9,7 @@ export * from "./models/IGasStationExecuteResponse.js";
 export * from "./models/IGasStationReserveGasResponse.js";
 export * from "./models/IGasStationReserveGasResult.js";
 export * from "./models/IIotaClient.js";
+export * from "./models/IIotaControllerCapInfo.js";
 export * from "./models/IIotaTransaction.js";
 export * from "./models/IIotaTransactionBlockResponse.js";
 export * from "./models/IIotaConfig.js";

package/dist/types/iotaIdentityUtils.d.ts

@@ -0,0 +1,23 @@
+import type { IotaClient } from "@iota/iota-sdk/client";
+import type { IIotaControllerCapInfo } from "./models/IIotaControllerCapInfo.js";
+/**
+ * Utility class for resolving IOTA Identity on-chain objects required by
+ * the NFT mint_with_identity() Move contract function.
+ */
+export declare class IotaIdentityUtils {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Resolve the on-chain object IDs for an identity and its controller token.
+     * Returns the IDs needed to call mint_with_identity() on the NFT Move contract.
+     * @param identityId The DID of the identity (e.g. "did:iota:testnet:0x...").
+     * @param controllerAddress The on-chain address of the controller wallet.
+     * @param client The IOTA client instance.
+     * @returns The identity object ID and controller token object ID.
+     * @throws NotFoundError if the identity does not exist on-chain.
+     * @throws GeneralError if the identity has been deleted or the controller token is not found.
+     */
+    static getControllerCapInfo(identityId: string, controllerAddress: string, client: IotaClient): Promise<IIotaControllerCapInfo>;
+}

package/dist/types/models/IIotaControllerCapInfo.d.ts

@@ -0,0 +1,16 @@
+/**
+ * On-chain object IDs needed to call mint_with_identity() on the NFT Move contract.
+ */
+export interface IIotaControllerCapInfo {
+    /**
+     * The on-chain Object ID of the Identity Move object (hex string, e.g. "0x...").
+     * Used as the Identity argument in mint_with_identity().
+     */
+    identityObjectId: string;
+    /**
+     * The on-chain Object ID of the ControllerToken Move object (hex string, e.g. "0x...").
+     * Proves that the controller address controls identityObjectId.
+     * Used as the ControllerCap argument in mint_with_identity().
+     */
+    controllerCapObjectId: string;
+}

package/docs/changelog.md

@@ -1,4 +1,11 @@
-# @twin.org/dlt-iota - Changelog
+# Changelog
+
+## [0.0.3-next.6](https://github.com/twinfoundation/dlt/compare/dlt-iota-v0.0.3-next.5...dlt-iota-v0.0.3-next.6) (2026-03-12)
+
+
+### Features
+
+* add IotaIdentityUtils to resolve IOTA identity controller cap info ([#57](https://github.com/twinfoundation/dlt/issues/57)) ([f15281a](https://github.com/twinfoundation/dlt/commit/f15281af3b2812bde5130a1813f9c0143f1462bf))
 
 ## [0.0.3-next.5](https://github.com/twinfoundation/dlt/compare/dlt-iota-v0.0.3-next.4...dlt-iota-v0.0.3-next.5) (2026-03-03)
 

package/docs/examples.md

@@ -1 +1,420 @@
-# @twin.org/dlt-iota - Examples
+# DLT IOTA Examples
+
+These snippets show practical ways to configure clients, derive addresses, post transactions, and manage contract migration flows in production-style integrations.
+
+## Iota
+
+```typescript
+import { Iota, NetworkTypes, type IIotaConfig } from '@twin.org/dlt-iota';
+
+const config: IIotaConfig = {
+  network: NetworkTypes.Testnet,
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  inclusionTimeoutSeconds: 45
+};
+
+Iota.populateConfig(config);
+const client = Iota.createClient(config);
+
+console.log(config.coinType); // 4218
+console.log(config.vaultMnemonicId); // mnemonic
+console.log(client !== undefined); // true
+```
+
+```typescript
+import { Bip39 } from '@twin.org/crypto';
+import { Iota } from '@twin.org/dlt-iota';
+
+const mnemonic =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const seed = Bip39.mnemonicToSeed(mnemonic);
+
+const addresses = Iota.getAddresses(seed, Iota.DEFAULT_COIN_TYPE, 0, 0, 3);
+const keyPair = Iota.getKeyPair(seed, Iota.DEFAULT_COIN_TYPE, 0, 0);
+const found = Iota.findAddress(50, Iota.DEFAULT_COIN_TYPE, seed, addresses[0]);
+
+console.log(addresses.length); // 3
+console.log(found.address === addresses[0]); // true
+console.log(keyPair.publicKey.length > 0); // true
+```
+
+```typescript
+import { Converter } from '@twin.org/core';
+import { Iota, type IIotaConfig } from '@twin.org/dlt-iota';
+import type { IVaultConnector } from '@twin.org/vault-models';
+
+const config: IIotaConfig = {
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  vaultMnemonicId: 'deployment-mnemonic',
+  vaultSeedId: 'deployment-seed'
+};
+
+const vaultConnector: IVaultConnector = {
+  async getSecret<T>(key: string): Promise<T> {
+    if (key.endsWith('/deployment-seed')) {
+      return Converter.bytesToBase64(new Uint8Array(32).fill(7)) as T;
+    }
+    if (key.endsWith('/deployment-mnemonic')) {
+      const value =
+        'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+      return value as T;
+    }
+    throw new Error('Unknown key');
+  }
+} as IVaultConnector;
+
+const mnemonicKey = Iota.buildMnemonicKey('deployer', config.vaultMnemonicId);
+const seedKey = Iota.buildSeedKey('deployer', config.vaultSeedId);
+const seed = await Iota.getSeed(config, vaultConnector, 'deployer');
+
+console.log(mnemonicKey); // deployer/deployment-mnemonic
+console.log(seedKey); // deployer/deployment-seed
+console.log(seed.length); // 32
+```
+
+```typescript
+import {
+  Iota,
+  type IIotaClient,
+  type IIotaConfig,
+  type IIotaTransaction,
+  type IIotaTransactionBlockResponse
+} from '@twin.org/dlt-iota';
+import type { IVaultConnector } from '@twin.org/vault-models';
+
+const config: IIotaConfig = {
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  waitForConfirmation: true
+};
+
+const tx = Iota.createTransaction();
+tx.setSender('0xabc123');
+
+const responseOptions = {
+  waitForConfirmation: true,
+  dryRunLabel: 'transfer_iota'
+};
+
+const client = {} as IIotaClient;
+const vaultConnector = {} as IVaultConnector;
+
+const result: IIotaTransactionBlockResponse = await Iota.prepareAndPostTransaction(
+  config,
+  vaultConnector,
+  undefined,
+  'deployer',
+  client,
+  '0xabc123',
+  tx as IIotaTransaction,
+  responseOptions
+);
+
+await Iota.waitForTransactionConfirmation(client, result.digest, config, {
+  showEffects: true,
+  showEvents: true,
+  showObjectChanges: true
+});
+
+console.log(typeof result.digest === 'string'); // true
+```
+
+```typescript
+import {
+  Iota,
+  type IIotaClient,
+  type IIotaConfig,
+  type IIotaTransaction,
+  type IIotaTransactionBlockResponse
+} from '@twin.org/dlt-iota';
+import type { IVaultConnector } from '@twin.org/vault-models';
+
+const config: IIotaConfig = {
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  gasBudget: 80_000_000,
+  gasStation: {
+    gasStationUrl: 'https://gasstation.testnet.example',
+    gasStationAuthToken: 'replace-with-token'
+  }
+};
+
+const client = {} as IIotaClient;
+const vaultConnector = {} as IVaultConnector;
+const tx = Iota.createTransaction();
+
+const gasReservation = await Iota.reserveGas(config, config.gasBudget ?? 50_000_000);
+const txBytes = new Uint8Array([1, 2, 3, 4]);
+const userSignature = 'base64-signature';
+
+const sponsoredResult = await Iota.executeGasStationTransaction(
+  config,
+  gasReservation.reservationId,
+  txBytes,
+  userSignature
+);
+
+const finalResult: IIotaTransactionBlockResponse =
+  await Iota.executeAndConfirmGasStationTransaction(
+    config,
+    client,
+    gasReservation.reservationId,
+    txBytes,
+    userSignature,
+    {
+      waitForConfirmation: true
+    }
+  );
+
+const postedResult = await Iota.prepareAndPostGasStationTransaction(
+  config,
+  vaultConnector,
+  'deployer',
+  client,
+  '0xabc123',
+  tx as IIotaTransaction
+);
+
+console.log(gasReservation.reservationId > 0); // true
+console.log(sponsoredResult.confirmedLocalExecution); // true
+console.log(typeof finalResult.digest === 'string'); // true
+console.log(typeof postedResult.digest === 'string'); // true
+```
+
+```typescript
+import { Iota, type IIotaClient, type IIotaConfig } from '@twin.org/dlt-iota';
+import type { ILoggingComponent } from '@twin.org/logging-models';
+
+const config: IIotaConfig = {
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  inclusionTimeoutSeconds: 30
+};
+
+const client = {} as IIotaClient;
+const tx = Iota.createTransaction();
+const logging = {} as ILoggingComponent;
+
+const packageExists = await Iota.packageExistsOnNetwork(client, '0x2');
+const dryRun = await Iota.dryRunTransaction(client, logging, tx, '0xabc123', 'mint_token');
+const isAbort = Iota.isAbortError(new Error('MoveAbort: abort code: 17'), 17);
+const parsedError = Iota.extractPayloadError({ code: 'InsufficientGas' });
+
+console.log(packageExists); // true
+console.log(dryRun.status); // success
+console.log(isAbort); // true
+console.log(parsedError.name); // General
+```
+
+```typescript
+import {
+  Iota,
+  type IIotaClient,
+  type IIotaConfig,
+  type IIotaTransactionBlockResponse
+} from '@twin.org/dlt-iota';
+import type { IVaultConnector } from '@twin.org/vault-models';
+
+const config: IIotaConfig = {
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  gasStation: {
+    gasStationUrl: 'https://gasstation.testnet.example',
+    gasStationAuthToken: 'replace-with-token'
+  }
+};
+
+const client = {} as IIotaClient;
+const vaultConnector = {} as IVaultConnector;
+
+const transferResult: IIotaTransactionBlockResponse = await Iota.prepareAndPostValueTransaction(
+  config,
+  vaultConnector,
+  undefined,
+  'deployer',
+  client,
+  '0xabc123',
+  5_000_000n,
+  '0xdef456'
+);
+
+console.log(typeof transferResult.digest === 'string'); // true
+```
+
+## IotaSmartContractUtils
+
+```typescript
+import {
+  IotaSmartContractUtils,
+  NetworkTypes,
+  type IIotaConfig,
+  type ISmartContractDeployments
+} from '@twin.org/dlt-iota';
+import type { IotaClient } from '@iota/iota-sdk/client';
+import type { ILoggingComponent } from '@twin.org/logging-models';
+import type { IVaultConnector } from '@twin.org/vault-models';
+import type { IWalletConnector } from '@twin.org/wallet-models';
+
+const config: IIotaConfig = {
+  network: NetworkTypes.Testnet,
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  },
+  enableCostLogging: true
+};
+
+const deploymentConfig: ISmartContractDeployments = {
+  testnet: {
+    packageId: '0x111',
+    deployedPackageId: '0x111',
+    migrationStateId: '0x222',
+    packageBytecode: 'base64'
+  }
+};
+
+const client = {} as IotaClient;
+const vaultConnector = {} as IVaultConnector;
+const walletConnector = {} as IWalletConnector;
+const logging = {} as ILoggingComponent;
+
+await IotaSmartContractUtils.enableMigration(
+  config,
+  client,
+  vaultConnector,
+  walletConnector,
+  logging,
+  80_000_000,
+  'controller',
+  'nft',
+  '0x111',
+  deploymentConfig
+);
+
+await IotaSmartContractUtils.disableMigration(
+  config,
+  client,
+  vaultConnector,
+  walletConnector,
+  logging,
+  80_000_000,
+  'controller',
+  'nft',
+  '0x111',
+  deploymentConfig
+);
+
+console.log(IotaSmartContractUtils.CLASS_NAME); // IotaSmartContractUtils
+```
+
+```typescript
+import {
+  IotaSmartContractUtils,
+  NetworkTypes,
+  type IIotaConfig,
+  type ISmartContractDeployments
+} from '@twin.org/dlt-iota';
+import type { IotaClient } from '@iota/iota-sdk/client';
+import type { ILoggingComponent } from '@twin.org/logging-models';
+import type { IVaultConnector } from '@twin.org/vault-models';
+import type { IWalletConnector } from '@twin.org/wallet-models';
+
+const config: IIotaConfig = {
+  network: NetworkTypes.Testnet,
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  }
+};
+
+const deploymentConfig: ISmartContractDeployments = {
+  testnet: {
+    packageId: '0x111',
+    deployedPackageId: '0x111',
+    migrationStateId: '0x222',
+    packageBytecode: 'base64'
+  }
+};
+
+const client = {} as IotaClient;
+const vaultConnector = {} as IVaultConnector;
+const walletConnector = {} as IWalletConnector;
+const logging = {} as ILoggingComponent;
+
+await IotaSmartContractUtils.migrateSmartContract(
+  config,
+  client,
+  vaultConnector,
+  walletConnector,
+  logging,
+  90_000_000,
+  'controller',
+  '0x999',
+  'nft',
+  '0x111',
+  deploymentConfig
+);
+
+const migrationActive = await IotaSmartContractUtils.isMigrationActive(
+  config,
+  client,
+  'nft',
+  '0x111',
+  deploymentConfig,
+  'controller',
+  walletConnector
+);
+
+console.log(migrationActive); // true
+```
+
+```typescript
+import { IotaSmartContractUtils, NetworkTypes, type IIotaConfig } from '@twin.org/dlt-iota';
+import type { IotaClient } from '@iota/iota-sdk/client';
+import type { IWalletConnector } from '@twin.org/wallet-models';
+
+type ContractObjectFields = {
+  fields: {
+    version: string;
+  };
+};
+
+const config: IIotaConfig = {
+  network: NetworkTypes.Testnet,
+  clientOptions: {
+    url: 'https://api.testnet.iota.cafe'
+  }
+};
+
+const client = {} as IotaClient;
+const walletConnector = {} as IWalletConnector;
+
+const currentVersion = await IotaSmartContractUtils.getCurrentContractVersion(
+  config,
+  client,
+  'nft',
+  '0x111',
+  'controller',
+  walletConnector
+);
+
+const isCompatible = await IotaSmartContractUtils.validateObjectVersion<ContractObjectFields>(
+  config,
+  client,
+  'nft',
+  '0x111',
+  'controller',
+  '0x777',
+  walletConnector,
+  content => Number(content.fields.version)
+);
+
+console.log(currentVersion >= 1); // true
+console.log(isCompatible); // true
+```

package/docs/reference/classes/IotaIdentityUtils.md

@@ -0,0 +1,65 @@
+# Class: IotaIdentityUtils
+
+Utility class for resolving IOTA Identity on-chain objects required by
+the NFT mint_with_identity() Move contract function.
+
+## Constructors
+
+### Constructor
+
+> **new IotaIdentityUtils**(): `IotaIdentityUtils`
+
+#### Returns
+
+`IotaIdentityUtils`
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### getControllerCapInfo()
+
+> `static` **getControllerCapInfo**(`identityId`, `controllerAddress`, `client`): `Promise`\<[`IIotaControllerCapInfo`](../interfaces/IIotaControllerCapInfo.md)\>
+
+Resolve the on-chain object IDs for an identity and its controller token.
+Returns the IDs needed to call mint_with_identity() on the NFT Move contract.
+
+#### Parameters
+
+##### identityId
+
+`string`
+
+The DID of the identity (e.g. "did:iota:testnet:0x...").
+
+##### controllerAddress
+
+`string`
+
+The on-chain address of the controller wallet.
+
+##### client
+
+`IotaClient`
+
+The IOTA client instance.
+
+#### Returns
+
+`Promise`\<[`IIotaControllerCapInfo`](../interfaces/IIotaControllerCapInfo.md)\>
+
+The identity object ID and controller token object ID.
+
+#### Throws
+
+NotFoundError if the identity does not exist on-chain.
+
+#### Throws
+
+GeneralError if the identity has been deleted or the controller token is not found.

package/docs/reference/index.md

@@ -3,6 +3,7 @@
 ## Classes
 
 - [Iota](classes/Iota.md)
+- [IotaIdentityUtils](classes/IotaIdentityUtils.md)
 - [IotaSmartContractUtils](classes/IotaSmartContractUtils.md)
 
 ## Interfaces
@@ -15,6 +16,7 @@
 - [IGasStationReserveGasResponse](interfaces/IGasStationReserveGasResponse.md)
 - [IGasStationReserveGasResult](interfaces/IGasStationReserveGasResult.md)
 - [IIotaConfig](interfaces/IIotaConfig.md)
+- [IIotaControllerCapInfo](interfaces/IIotaControllerCapInfo.md)
 - [IIotaDryRun](interfaces/IIotaDryRun.md)
 - [IIotaResponseOptions](interfaces/IIotaResponseOptions.md)
 - [IMigrationStateFields](interfaces/IMigrationStateFields.md)

package/docs/reference/interfaces/IIotaConfig.md

@@ -26,12 +26,6 @@ The network the operations are being performed on.
 
 The id of the entry in the vault containing the mnemonic.
 
-#### Default
-
-```ts
-mnemonic
-```
-
 ***
 
 ### vaultSeedId?
@@ -40,12 +34,6 @@ mnemonic
 
 The id of the entry in the vault containing the seed.
 
-#### Default
-
-```ts
-seed
-```
-
 ***
 
 ### coinType?
@@ -54,12 +42,6 @@ seed
 
 The coin type.
 
-#### Default
-
-```ts
-IOTA 4218
-```
-
 ***
 
 ### maxAddressScanRange?
@@ -68,12 +50,6 @@ IOTA 4218
 
 The maximum range to scan for addresses.
 
-#### Default
-
-```ts
-1000
-```
-
 ***
 
 ### inclusionTimeoutSeconds?
@@ -82,12 +58,6 @@ The maximum range to scan for addresses.
 
 The length of time to wait for the inclusion of a transaction in seconds.
 
-#### Default
-
-```ts
-60
-```
-
 ***
 
 ### gasStation?
@@ -105,12 +75,6 @@ If provided, transactions will be processed through the gas station.
 
 The default gas budget for all transactions (including sponsored and direct).
 
-#### Default
-
-```ts
-50000000
-```
-
 ***
 
 ### enableCostLogging?
@@ -118,9 +82,3 @@ The default gas budget for all transactions (including sponsored and direct).
 > `optional` **enableCostLogging**: `boolean`
 
 Enable cost logging for transactions.
-
-#### Default
-
-```ts
-false
-```

package/docs/reference/interfaces/IIotaControllerCapInfo.md

@@ -0,0 +1,22 @@
+# Interface: IIotaControllerCapInfo
+
+On-chain object IDs needed to call mint_with_identity() on the NFT Move contract.
+
+## Properties
+
+### identityObjectId
+
+> **identityObjectId**: `string`
+
+The on-chain Object ID of the Identity Move object (hex string, e.g. "0x...").
+Used as the Identity argument in mint_with_identity().
+
+***
+
+### controllerCapObjectId
+
+> **controllerCapObjectId**: `string`
+
+The on-chain Object ID of the ControllerToken Move object (hex string, e.g. "0x...").
+Proves that the controller address controls identityObjectId.
+Used as the ControllerCap argument in mint_with_identity().

package/docs/reference/interfaces/IIotaResponseOptions.md

@@ -14,12 +14,6 @@ Configuration for IOTA.
 
 Wait for confirmation of the transaction.
 
-#### Default
-
-```ts
-true
-```
-
 ***
 
 ### dryRunLabel?

package/locales/en.json

@@ -10,6 +10,13 @@
 			"gasStationTransactionFailed": "The gas station transaction failed",
 			"dryRunFailed": "The dry run execution failed"
 		},
+		"iotaIdentityUtils": {
+			"getControllerCapInfoFailed": "Getting the controller capability info for the identity failed",
+			"identityNotFound": "The identity could not be found \"{notFoundId}\"",
+			"identityDeleted": "The identity \"{identityId}\" has been deleted and cannot be used for minting",
+			"controllerTokenNotFound": "No controller token found for the identity \"{notFoundId}\" with the provided controller address",
+			"unexpectedSignerCall": "The no-op signer was unexpectedly called during a read-only identity lookup"
+		},
 		"iotaSmartContractUtils": {
 			"migrationFailed": "Smart contract migration failed",
 			"migrateSmartContractFailed": "Failed to migrate smart contract for object \"{objectId}\"",

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/dlt-iota",
-	"version": "0.0.3-next.5",
-	"description": "DLT helpers for use with IOTA",
+	"version": "0.0.3-next.6",
+	"description": "IOTA distributed ledger utilities for clients, transactions, and contract operations.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/dlt.git",
@@ -15,6 +15,7 @@
 	},
 	"dependencies": {
 		"@iota/bcs": "1.5.0",
+		"@iota/identity-wasm": "1.9.2-beta.1",
 		"@iota/iota-sdk": "1.11.0",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",