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

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,84 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { IdentityClient, IdentityClientReadOnly, Jwk, JwkMemStore, KeyIdMemStore, OnChainIdentity, Storage, StorageSigner } from "@iota/identity-wasm/node/index.js";
+import { decodeIotaPrivateKey } from "@iota/iota-sdk/cryptography";
+import { Ed25519Keypair } from "@iota/iota-sdk/keypairs/ed25519";
+import { Base64Url, 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);
+        Guards.object(IotaIdentityUtils.CLASS_NAME, "client", client);
+        // Extract the Object ID from the DID — last colon-delimited segment.
+        // On-chain DIDs include the 0x prefix in the segment; the check avoids double-prefixing.
+        const idParts = identityId.split(":");
+        const lastSegment = idParts[idParts.length - 1];
+        const identityObjectId = lastSegment.startsWith("0x") ? lastSegment : `0x${lastSegment}`;
+        let onChain;
+        let controllerToken;
+        try {
+            // IIotaClient and the IotaClient expected by identity-wasm resolve from different
+            // module entry points (dist/esm vs dist/cjs). The protected `transport` field causes
+            // a structural incompatibility even though the runtime types are identical.
+            const identityClientReadOnly = await IdentityClientReadOnly.create(client);
+            // getControllerTokenForAddress requires IdentityClient even though the operation
+            // is read-only — the signer is never called, only the embedded read-only client.
+            // StorageSigner is used (rather than a plain object satisfying TransactionSigner
+            // structurally) because IdentityClient.create() validates iotaPublicKeyBytes()
+            // through an internal WASM code path that only accepts bytes from the library's
+            // own signer implementations. Plain JS objects fail with "Unsupported curve"
+            // even for valid Ed25519 keys because they take a different callback path.
+            const noOpKeypair = new Ed25519Keypair();
+            const rawPublic = noOpKeypair.getPublicKey().toRawBytes();
+            const { secretKey: rawPrivate } = decodeIotaPrivateKey(noOpKeypair.getSecretKey());
+            const noOpSigner = new StorageSigner(new Storage(new JwkMemStore(), new KeyIdMemStore()), "", new Jwk({
+                kty: "OKP" /* JwkType.Okp */,
+                crv: "Ed25519",
+                alg: "EdDSA" /* JwsAlgorithm.EdDSA */,
+                x: Base64Url.encode(rawPublic),
+                d: Base64Url.encode(rawPrivate)
+            }));
+            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\tJwk,\n\tJwkMemStore,\n\tJwkType,\n\tJwsAlgorithm,\n\tKeyIdMemStore,\n\tOnChainIdentity,\n\tStorage,\n\tStorageSigner\n} from \"@iota/identity-wasm/node/index.js\";\nimport { decodeIotaPrivateKey } from \"@iota/iota-sdk/cryptography\";\nimport { Ed25519Keypair } from \"@iota/iota-sdk/keypairs/ed25519\";\nimport { Base64Url, GeneralError, Guards, Is, NotFoundError } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { Iota } from \"./iota.js\";\nimport type { IIotaClient } from \"./models/IIotaClient.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: IIotaClient\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\t\tGuards.object(IotaIdentityUtils.CLASS_NAME, nameof(client), client);\n\n\t\t// Extract the Object ID from the DID — last colon-delimited segment.\n\t\t// On-chain DIDs include the 0x prefix in the segment; the check avoids double-prefixing.\n\t\tconst idParts = identityId.split(\":\");\n\t\tconst lastSegment = idParts[idParts.length - 1];\n\t\tconst identityObjectId = lastSegment.startsWith(\"0x\") ? lastSegment : `0x${lastSegment}`;\n\n\t\tlet onChain: OnChainIdentity | undefined;\n\t\tlet controllerToken: Awaited<ReturnType<OnChainIdentity[\"getControllerTokenForAddress\"]>>;\n\n\t\ttry {\n\t\t\t// IIotaClient and the IotaClient expected by identity-wasm resolve from different\n\t\t\t// module entry points (dist/esm vs dist/cjs). The protected `transport` field causes\n\t\t\t// a structural incompatibility even though the runtime types are identical.\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\n\t\t\t// is read-only — the signer is never called, only the embedded read-only client.\n\t\t\t// StorageSigner is used (rather than a plain object satisfying TransactionSigner\n\t\t\t// structurally) because IdentityClient.create() validates iotaPublicKeyBytes()\n\t\t\t// through an internal WASM code path that only accepts bytes from the library's\n\t\t\t// own signer implementations. Plain JS objects fail with \"Unsupported curve\"\n\t\t\t// even for valid Ed25519 keys because they take a different callback path.\n\t\t\tconst noOpKeypair = new Ed25519Keypair();\n\t\t\tconst rawPublic = noOpKeypair.getPublicKey().toRawBytes();\n\t\t\tconst { secretKey: rawPrivate } = decodeIotaPrivateKey(noOpKeypair.getSecretKey());\n\t\t\tconst noOpSigner = new StorageSigner(\n\t\t\t\tnew Storage(new JwkMemStore(), new KeyIdMemStore()),\n\t\t\t\t\"\",\n\t\t\t\tnew Jwk({\n\t\t\t\t\tkty: JwkType.Okp,\n\t\t\t\t\tcrv: \"Ed25519\",\n\t\t\t\t\talg: JwsAlgorithm.EdDSA,\n\t\t\t\t\tx: Base64Url.encode(rawPublic),\n\t\t\t\t\td: Base64Url.encode(rawPrivate)\n\t\t\t\t})\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 { IIotaClient } from "./models/IIotaClient.js";
+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: IIotaClient): 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,18 @@
-# @twin.org/dlt-iota - Changelog
+# Changelog
+
+## [0.0.3-next.7](https://github.com/twinfoundation/dlt/compare/dlt-iota-v0.0.3-next.6...dlt-iota-v0.0.3-next.7) (2026-03-13)
+
+
+### Bug Fixes
+
+* buffer usage required for identity ([#60](https://github.com/twinfoundation/dlt/issues/60)) ([0ba7d16](https://github.com/twinfoundation/dlt/commit/0ba7d165662b0083aa2b4c1325dd8c2e65defa2e))
+
+## [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
+```