@twin.org/nft-models 0.0.3-next.2 → 0.0.3-next.4

package/README.md

@@ -1,6 +1,6 @@
 # TWIN NFT Models
 
-Contains models and classes for use with NFTs.
+This package defines the shared interfaces, factories, and API models used by NFT connectors, services, and clients in this repository. It provides a stable contract layer that keeps implementations interoperable across different runtime environments.
 
 ## Installation
 

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

@@ -1 +1 @@
-{"version":3,"file":"IIrc27Metadata.js","sourceRoot":"","sources":["../../../src/models/IIrc27Metadata.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Model defining the IRC27 NFT Standards.\n * https://github.com/iotaledger/tips/blob/main/tips/TIP-0027/tip-0027.md\n */\nexport interface IIrc27Metadata {\n\t/**\n\t * The standard marker.\n\t */\n\tstandard: \"IRC27\";\n\n\t/**\n\t * The version\n\t */\n\tversion: \"v1.0\";\n\n\t/**\n\t * A mime type for the content of the NFT.\n\t */\n\ttype: string;\n\n\t/**\n\t * Url pointing to the NFT file location with MIME type defined in type.\n\t */\n\turi: string;\n\n\t/**\n\t * Alphanumeric text string defining the human identifiable name for the NFT\n\t */\n\tname: string;\n\n\t/**\n\t * Alphanumeric text string defining the human identifiable collection name.\n\t */\n\tcollectionName?: string;\n\n\t/**\n\t * Object containing key value pair where payment address mapped to the payout percentage.\n\t */\n\troyalties?: {\n\t\t[id: string]: number;\n\t};\n\n\t/**\n\t * Alphanumeric text string to define the human identifiable name of the creator.\n\t */\n\tissuerName?: string;\n\n\t/**\n\t * Alphanumeric text string to define a basic description of the NFT.\n\t */\n\tdescription?: string;\n\n\t/**\n\t * Array objects defining additional attributes of the NFT\n\t */\n\tattributes?: {\n\t\ttrait_type: string;\n\t\tvalue: unknown;\n\t}[];\n}\n"]}
+{"version":3,"file":"IIrc27Metadata.js","sourceRoot":"","sources":["../../../src/models/IIrc27Metadata.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Model defining the IRC27 NFT Standards.\n * https://docs.iota.org/developer/references/framework/stardust/irc27\n */\nexport interface IIrc27Metadata {\n\t/**\n\t * The standard marker.\n\t */\n\tstandard: \"IRC27\";\n\n\t/**\n\t * The version\n\t */\n\tversion: \"v1.0\";\n\n\t/**\n\t * A mime type for the content of the NFT.\n\t */\n\ttype: string;\n\n\t/**\n\t * Url pointing to the NFT file location with MIME type defined in type.\n\t */\n\turi: string;\n\n\t/**\n\t * Alphanumeric text string defining the human identifiable name for the NFT\n\t */\n\tname: string;\n\n\t/**\n\t * Alphanumeric text string defining the human identifiable collection name.\n\t */\n\tcollectionName?: string;\n\n\t/**\n\t * Object containing key value pair where payment address mapped to the payout percentage.\n\t */\n\troyalties?: {\n\t\t[id: string]: number;\n\t};\n\n\t/**\n\t * Alphanumeric text string to define the human identifiable name of the creator.\n\t */\n\tissuerName?: string;\n\n\t/**\n\t * Alphanumeric text string to define a basic description of the NFT.\n\t */\n\tdescription?: string;\n\n\t/**\n\t * Array objects defining additional attributes of the NFT\n\t */\n\tattributes?: {\n\t\ttrait_type: string;\n\t\tvalue: unknown;\n\t}[];\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"INftComponent.js","sourceRoot":"","sources":["../../../src/models/INftComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\n\n/**\n * Interface describing an NFT component.\n */\nexport interface INftComponent extends IComponent {\n\t/**\n\t * Mint an NFT.\n\t * @param tag The tag for the NFT.\n\t * @param immutableMetadata The immutable metadata for the NFT.\n\t * @param metadata The metadata for the NFT.\n\t * @param namespace The namespace of the connector to use for the NFT, defaults to component configured namespace.\n\t * @param identity The identity to perform the nft operation with.\n\t * @returns The id of the created NFT in urn format.\n\t */\n\tmint<T = unknown, U = unknown>(\n\t\ttag: string,\n\t\timmutableMetadata?: T,\n\t\tmetadata?: U,\n\t\tnamespace?: string,\n\t\tidentity?: string\n\t): Promise<string>;\n\n\t/**\n\t * Resolve an NFT.\n\t * @param id The id of the NFT to resolve.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns The data for the NFT.\n\t */\n\tresolve<T = unknown, U = unknown>(\n\t\tid: string,\n\t\tcontrollerIdentity?: string\n\t): Promise<{\n\t\tissuer: string;\n\t\towner: string;\n\t\ttag: string;\n\t\timmutableMetadata?: T;\n\t\tmetadata?: U;\n\t}>;\n\n\t/**\n\t * Burn an NFT.\n\t * @param id The id of the NFT to burn in urn format.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\tburn(id: string, controllerIdentity?: string): Promise<void>;\n\n\t/**\n\t * Transfer an NFT.\n\t * @param id The id of the NFT to transfer in urn format.\n\t * @param recipientIdentity The recipient identity for the NFT.\n\t * @param recipientAddress The recipient address for the NFT.\n\t * @param metadata Optional mutable data to include during the transfer.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\ttransfer<U = unknown>(\n\t\tid: string,\n\t\trecipientIdentity: string,\n\t\trecipientAddress: string,\n\t\tmetadata?: U,\n\t\tcontrollerIdentity?: string\n\t): Promise<void>;\n\n\t/**\n\t * Update the mutable data of the NFT.\n\t * @param id The id of the NFT to update in urn format.\n\t * @param metadata The mutable data to update.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\tupdate<U = unknown>(id: string, metadata: U, controllerIdentity?: string): Promise<void>;\n}\n"]}
+{"version":3,"file":"INftComponent.js","sourceRoot":"","sources":["../../../src/models/INftComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\n\n/**\n * Interface describing an NFT component.\n */\nexport interface INftComponent extends IComponent {\n\t/**\n\t * Mint an NFT.\n\t * @param tag The tag for the NFT.\n\t * @param immutableMetadata The immutable metadata for the NFT.\n\t * @param metadata The metadata for the NFT.\n\t * @param namespace The namespace of the connector to use for the NFT, defaults to component configured namespace.\n\t * @param identity The identity to perform the nft operation with.\n\t * @returns The id of the created NFT in urn format.\n\t */\n\tmint<T = unknown, U = unknown>(\n\t\ttag: string,\n\t\timmutableMetadata?: T,\n\t\tmetadata?: U,\n\t\tnamespace?: string,\n\t\tidentity?: string\n\t): Promise<string>;\n\n\t/**\n\t * Resolve an NFT.\n\t * @param id The id of the NFT to resolve.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns The data for the NFT.\n\t */\n\tresolve<T = unknown, U = unknown>(\n\t\tid: string,\n\t\tcontrollerIdentity?: string\n\t): Promise<{\n\t\tissuer: string;\n\t\tissuerIdentityId: string;\n\t\ttag: string;\n\t\timmutableMetadata?: T;\n\t\tmetadata?: U;\n\t}>;\n\n\t/**\n\t * Burn an NFT.\n\t * @param id The id of the NFT to burn in urn format.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\tburn(id: string, controllerIdentity?: string): Promise<void>;\n\n\t/**\n\t * Transfer an NFT.\n\t * @param id The id of the NFT to transfer in urn format.\n\t * @param recipientAddress The recipient address for the NFT.\n\t * @param metadata Optional mutable data to include during the transfer.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\ttransfer<U = unknown>(\n\t\tid: string,\n\t\trecipientAddress: string,\n\t\tmetadata?: U,\n\t\tcontrollerIdentity?: string\n\t): Promise<void>;\n\n\t/**\n\t * Update the mutable data of the NFT.\n\t * @param id The id of the NFT to update in urn format.\n\t * @param metadata The mutable data to update.\n\t * @param controllerIdentity The identity to perform the nft operation with.\n\t * @returns Nothing.\n\t */\n\tupdate<U = unknown>(id: string, metadata: U, controllerIdentity?: string): Promise<void>;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"INftConnector.js","sourceRoot":"","sources":["../../../src/models/INftConnector.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\n\n/**\n * Interface describing an NFT connector.\n */\nexport interface INftConnector extends IComponent {\n\t/**\n\t * Mint an NFT.\n\t * @param controllerIdentity The identity of the user to access the vault keys.\n\t * @param tag The tag for the NFT.\n\t * @param immutableMetadata The immutable metadata for the NFT.\n\t * @param metadata The metadata for the NFT.\n\t * @returns The id of the created NFT in urn format.\n\t */\n\tmint<T = unknown, U = unknown>(\n\t\tcontrollerIdentity: string,\n\t\ttag: string,\n\t\timmutableMetadata?: T,\n\t\tmetadata?: U\n\t): Promise<string>;\n\n\t/**\n\t * Resolve an NFT.\n\t * @param id The id of the NFT to resolve.\n\t * @returns The data for the NFT.\n\t */\n\tresolve<T = unknown, U = unknown>(\n\t\tid: string\n\t): Promise<{\n\t\tissuer: string;\n\t\towner: string;\n\t\ttag: string;\n\t\timmutableMetadata?: T;\n\t\tmetadata?: U;\n\t}>;\n\n\t/**\n\t * Burn an NFT.\n\t * @param controller The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to burn in urn format.\n\t * @returns Nothing.\n\t */\n\tburn(controller: string, id: string): Promise<void>;\n\n\t/**\n\t * Transfer an NFT.\n\t * @param controllerIdentity The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to transfer in urn format.\n\t * @param recipientIdentity The recipient identity for the NFT.\n\t * @param recipientAddress The recipient address for the NFT.\n\t * @param metadata Optional mutable data to include during the transfer.\n\t * @returns Nothing.\n\t */\n\ttransfer<U = unknown>(\n\t\tcontrollerIdentity: string,\n\t\tid: string,\n\t\trecipientIdentity: string,\n\t\trecipientAddress: string,\n\t\tmetadata?: U\n\t): Promise<void>;\n\n\t/**\n\t * Update the mutable data of the NFT.\n\t * @param controllerIdentity The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to update in urn format.\n\t * @param metadata The mutable data to update.\n\t * @returns Nothing.\n\t */\n\tupdate<U = unknown>(controllerIdentity: string, id: string, metadata: U): Promise<void>;\n}\n"]}
+{"version":3,"file":"INftConnector.js","sourceRoot":"","sources":["../../../src/models/INftConnector.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\n\n/**\n * Interface describing an NFT connector.\n */\nexport interface INftConnector extends IComponent {\n\t/**\n\t * Mint an NFT.\n\t * @param controllerIdentity The identity of the user to access the vault keys.\n\t * @param tag The tag for the NFT.\n\t * @param immutableMetadata The immutable metadata for the NFT.\n\t * @param metadata The metadata for the NFT.\n\t * @returns The id of the created NFT in urn format.\n\t */\n\tmint<T = unknown, U = unknown>(\n\t\tcontrollerIdentity: string,\n\t\ttag: string,\n\t\timmutableMetadata?: T,\n\t\tmetadata?: U\n\t): Promise<string>;\n\n\t/**\n\t * Resolve an NFT.\n\t * @param id The id of the NFT to resolve.\n\t * @returns The data for the NFT.\n\t */\n\tresolve<T = unknown, U = unknown>(\n\t\tid: string\n\t): Promise<{\n\t\tissuer: string;\n\t\tissuerIdentityId: string;\n\t\ttag: string;\n\t\timmutableMetadata?: T;\n\t\tmetadata?: U;\n\t}>;\n\n\t/**\n\t * Burn an NFT.\n\t * @param controller The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to burn in urn format.\n\t * @returns Nothing.\n\t */\n\tburn(controller: string, id: string): Promise<void>;\n\n\t/**\n\t * Transfer an NFT.\n\t * @param controllerIdentity The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to transfer in urn format.\n\t * @param recipientAddress The recipient address for the NFT.\n\t * @param metadata Optional mutable data to include during the transfer.\n\t * @returns Nothing.\n\t */\n\ttransfer<U = unknown>(\n\t\tcontrollerIdentity: string,\n\t\tid: string,\n\t\trecipientAddress: string,\n\t\tmetadata?: U\n\t): Promise<void>;\n\n\t/**\n\t * Update the mutable data of the NFT.\n\t * @param controllerIdentity The controller of the NFT who can make changes.\n\t * @param id The id of the NFT to update in urn format.\n\t * @param metadata The mutable data to update.\n\t * @returns Nothing.\n\t */\n\tupdate<U = unknown>(controllerIdentity: string, id: string, metadata: U): Promise<void>;\n}\n"]}

package/dist/es/models/api/INftResolveResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"INftResolveResponse.js","sourceRoot":"","sources":["../../../../src/models/api/INftResolveResponse.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Response to resolving the NFT.\n */\nexport interface INftResolveResponse {\n\t/**\n\t * The data that was resolved.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The issuer of the NFT.\n\t\t */\n\t\tissuer: string;\n\n\t\t/**\n\t\t * The owner of the NFT.\n\t\t */\n\t\towner: string;\n\n\t\t/**\n\t\t * The tag data for the NFT.\n\t\t */\n\t\ttag: string;\n\n\t\t/**\n\t\t * The immutable data for the NFT.\n\t\t */\n\t\timmutableMetadata?: unknown;\n\n\t\t/**\n\t\t * The metadata for the NFT.\n\t\t */\n\t\tmetadata?: unknown;\n\t};\n}\n"]}
+{"version":3,"file":"INftResolveResponse.js","sourceRoot":"","sources":["../../../../src/models/api/INftResolveResponse.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Response to resolving the NFT.\n */\nexport interface INftResolveResponse {\n\t/**\n\t * The data that was resolved.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The issuer of the NFT.\n\t\t */\n\t\tissuer: string;\n\n\t\t/**\n\t\t * The on-chain Object ID of the verified IOTA Identity that minted this NFT.\n\t\t * Empty string when not minted with identity verification.\n\t\t */\n\t\tissuerIdentityId: string;\n\n\t\t/**\n\t\t * The tag data for the NFT.\n\t\t */\n\t\ttag: string;\n\n\t\t/**\n\t\t * The immutable data for the NFT.\n\t\t */\n\t\timmutableMetadata?: unknown;\n\n\t\t/**\n\t\t * The metadata for the NFT.\n\t\t */\n\t\tmetadata?: unknown;\n\t};\n}\n"]}

package/dist/es/models/api/INftTransferRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"INftTransferRequest.js","sourceRoot":"","sources":["../../../../src/models/api/INftTransferRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Transfer the NFT and update the metadata.\n */\nexport interface INftTransferRequest {\n\t/**\n\t * The data to be used in the transfer.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the NFT to transfer in urn format.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The data to be used in the transfer.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The recipient identity for the NFT.\n\t\t */\n\t\trecipientIdentity: string;\n\n\t\t/**\n\t\t * The recipient address for the NFT.\n\t\t */\n\t\trecipientAddress: string;\n\n\t\t/**\n\t\t * The metadata for the NFT.\n\t\t */\n\t\tmetadata?: unknown;\n\t};\n}\n"]}
+{"version":3,"file":"INftTransferRequest.js","sourceRoot":"","sources":["../../../../src/models/api/INftTransferRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Transfer the NFT and update the metadata.\n */\nexport interface INftTransferRequest {\n\t/**\n\t * The data to be used in the transfer.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the NFT to transfer in urn format.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The data to be used in the transfer.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The recipient address for the NFT.\n\t\t */\n\t\trecipientAddress: string;\n\n\t\t/**\n\t\t * The metadata for the NFT.\n\t\t */\n\t\tmetadata?: unknown;\n\t};\n}\n"]}

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

@@ -1,6 +1,6 @@
 /**
  * Model defining the IRC27 NFT Standards.
- * https://github.com/iotaledger/tips/blob/main/tips/TIP-0027/tip-0027.md
+ * https://docs.iota.org/developer/references/framework/stardust/irc27
  */
 export interface IIrc27Metadata {
     /**

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

@@ -21,7 +21,7 @@ export interface INftComponent extends IComponent {
      */
     resolve<T = unknown, U = unknown>(id: string, controllerIdentity?: string): Promise<{
         issuer: string;
-        owner: string;
+        issuerIdentityId: string;
         tag: string;
         immutableMetadata?: T;
         metadata?: U;
@@ -36,13 +36,12 @@ export interface INftComponent extends IComponent {
     /**
      * Transfer an NFT.
      * @param id The id of the NFT to transfer in urn format.
-     * @param recipientIdentity The recipient identity for the NFT.
      * @param recipientAddress The recipient address for the NFT.
      * @param metadata Optional mutable data to include during the transfer.
      * @param controllerIdentity The identity to perform the nft operation with.
      * @returns Nothing.
      */
-    transfer<U = unknown>(id: string, recipientIdentity: string, recipientAddress: string, metadata?: U, controllerIdentity?: string): Promise<void>;
+    transfer<U = unknown>(id: string, recipientAddress: string, metadata?: U, controllerIdentity?: string): Promise<void>;
     /**
      * Update the mutable data of the NFT.
      * @param id The id of the NFT to update in urn format.

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

@@ -19,7 +19,7 @@ export interface INftConnector extends IComponent {
      */
     resolve<T = unknown, U = unknown>(id: string): Promise<{
         issuer: string;
-        owner: string;
+        issuerIdentityId: string;
         tag: string;
         immutableMetadata?: T;
         metadata?: U;
@@ -35,12 +35,11 @@ export interface INftConnector extends IComponent {
      * Transfer an NFT.
      * @param controllerIdentity The controller of the NFT who can make changes.
      * @param id The id of the NFT to transfer in urn format.
-     * @param recipientIdentity The recipient identity for the NFT.
      * @param recipientAddress The recipient address for the NFT.
      * @param metadata Optional mutable data to include during the transfer.
      * @returns Nothing.
      */
-    transfer<U = unknown>(controllerIdentity: string, id: string, recipientIdentity: string, recipientAddress: string, metadata?: U): Promise<void>;
+    transfer<U = unknown>(controllerIdentity: string, id: string, recipientAddress: string, metadata?: U): Promise<void>;
     /**
      * Update the mutable data of the NFT.
      * @param controllerIdentity The controller of the NFT who can make changes.

package/dist/types/models/api/INftResolveResponse.d.ts

@@ -11,9 +11,10 @@ export interface INftResolveResponse {
          */
         issuer: string;
         /**
-         * The owner of the NFT.
+         * The on-chain Object ID of the verified IOTA Identity that minted this NFT.
+         * Empty string when not minted with identity verification.
          */
-        owner: string;
+        issuerIdentityId: string;
         /**
          * The tag data for the NFT.
          */

package/dist/types/models/api/INftTransferRequest.d.ts

@@ -15,10 +15,6 @@ export interface INftTransferRequest {
      * The data to be used in the transfer.
      */
     body: {
-        /**
-         * The recipient identity for the NFT.
-         */
-        recipientIdentity: string;
         /**
          * The recipient address for the NFT.
          */

package/docs/changelog.md

@@ -1,4 +1,18 @@
-# @twin.org/nft-models - Changelog
+# Changelog
+
+## [0.0.3-next.4](https://github.com/twinfoundation/nft/compare/nft-models-v0.0.3-next.3...nft-models-v0.0.3-next.4) (2026-04-20)
+
+
+### Features
+
+* add on-chain identity binding to NFT minting ([#58](https://github.com/twinfoundation/nft/issues/58)) ([730a16d](https://github.com/twinfoundation/nft/commit/730a16d70fc026c920dbede0e4dafc96f37b729a))
+
+## [0.0.3-next.3](https://github.com/twinfoundation/nft/compare/nft-models-v0.0.3-next.2...nft-models-v0.0.3-next.3) (2026-03-03)
+
+
+### Features
+
+* update docs ([75dc85e](https://github.com/twinfoundation/nft/commit/75dc85ed0476666d0a1cc5d83ca0a5db29b69992))
 
 ## [0.0.3-next.2](https://github.com/twinfoundation/nft/compare/nft-models-v0.0.3-next.1...nft-models-v0.0.3-next.2) (2026-02-25)
 

package/docs/examples.md

@@ -1 +1,90 @@
-# @twin.org/nft-models - Examples
+# NFT Models Examples
+
+These examples focus on connector contracts and shared request models so multiple implementations can follow the same API surface.
+
+## NftConnectorFactory
+
+```typescript
+import { NftConnectorFactory, type INftConnector } from '@twin.org/nft-models';
+
+class MockNftConnector implements INftConnector {
+  public className(): string {
+    return 'MockNftConnector';
+  }
+
+  public async mint(controllerIdentity: string, tag: string): Promise<string> {
+    return `nft:entity-storage:${controllerIdentity}:${tag}`;
+  }
+
+  public async resolve(id: string): Promise<{ issuer: string; owner: string; tag: string }> {
+    return {
+      issuer: 'did:example:issuer-1',
+      owner: 'did:example:owner-1',
+      tag: id
+    };
+  }
+
+  public async burn(): Promise<void> {}
+
+  public async transfer(): Promise<void> {}
+
+  public async update(): Promise<void> {}
+}
+
+NftConnectorFactory.register('mock-nft', () => new MockNftConnector());
+
+const connectorNames = NftConnectorFactory.names();
+const connector = NftConnectorFactory.get<INftConnector>('mock-nft');
+
+console.log(connectorNames.includes('mock-nft')); // true
+console.log(connector.className()); // MockNftConnector
+```
+
+## INftComponent Request Shapes
+
+```typescript
+import type {
+  IIrc27Metadata,
+  INftMintRequest,
+  INftTransferRequest,
+  INftUpdateRequest
+} from '@twin.org/nft-models';
+
+const immutableMetadata: IIrc27Metadata = {
+  standard: 'IRC27',
+  version: 'v1.0',
+  type: 'image/png',
+  uri: 'ipfs://bafybeigdyr...',
+  name: 'Genesis Badge',
+  description: 'A launch collectible'
+};
+
+const mintRequest: INftMintRequest = {
+  tag: 'genesis-badge',
+  immutableMetadata,
+  metadata: {
+    season: 1,
+    rarity: 'legendary'
+  },
+  namespace: 'iota'
+};
+
+const transferRequest: INftTransferRequest = {
+  recipientIdentity: 'did:example:collector-8',
+  recipientAddress: '0x5df99c44d4f6f66d5a7f7298f46a0fdb6a4ac23a',
+  metadata: {
+    transferredAt: '2026-03-10T10:00:00.000Z'
+  }
+};
+
+const updateRequest: INftUpdateRequest = {
+  metadata: {
+    rarity: 'mythic',
+    season: 2
+  }
+};
+
+console.log(mintRequest.namespace); // iota
+console.log(transferRequest.recipientIdentity); // did:example:collector-8
+console.log(updateRequest.metadata.season); // 2
+```

package/docs/reference/interfaces/IIrc27Metadata.md

@@ -1,11 +1,11 @@
 # Interface: IIrc27Metadata
 
 Model defining the IRC27 NFT Standards.
-https://github.com/iotaledger/tips/blob/main/tips/TIP-0027/tip-0027.md
+https://docs.iota.org/developer/references/framework/stardust/irc27
 
 ## Properties
 
-### standard
+### standard {#standard}
 
 > **standard**: `"IRC27"`
 
@@ -13,7 +13,7 @@ The standard marker.
 
 ***
 
-### version
+### version {#version}
 
 > **version**: `"v1.0"`
 
@@ -21,7 +21,7 @@ The version
 
 ***
 
-### type
+### type {#type}
 
 > **type**: `string`
 
@@ -29,7 +29,7 @@ A mime type for the content of the NFT.
 
 ***
 
-### uri
+### uri {#uri}
 
 > **uri**: `string`
 
@@ -37,7 +37,7 @@ Url pointing to the NFT file location with MIME type defined in type.
 
 ***
 
-### name
+### name {#name}
 
 > **name**: `string`
 
@@ -45,17 +45,17 @@ Alphanumeric text string defining the human identifiable name for the NFT
 
 ***
 
-### collectionName?
+### collectionName? {#collectionname}
 
-> `optional` **collectionName**: `string`
+> `optional` **collectionName?**: `string`
 
 Alphanumeric text string defining the human identifiable collection name.
 
 ***
 
-### royalties?
+### royalties? {#royalties}
 
-> `optional` **royalties**: `object`
+> `optional` **royalties?**: `object`
 
 Object containing key value pair where payment address mapped to the payout percentage.
 
@@ -65,25 +65,25 @@ Object containing key value pair where payment address mapped to the payout perc
 
 ***
 
-### issuerName?
+### issuerName? {#issuername}
 
-> `optional` **issuerName**: `string`
+> `optional` **issuerName?**: `string`
 
 Alphanumeric text string to define the human identifiable name of the creator.
 
 ***
 
-### description?
+### description? {#description}
 
-> `optional` **description**: `string`
+> `optional` **description?**: `string`
 
 Alphanumeric text string to define a basic description of the NFT.
 
 ***
 
-### attributes?
+### attributes? {#attributes}
 
-> `optional` **attributes**: `object`[]
+> `optional` **attributes?**: `object`[]
 
 Array objects defining additional attributes of the NFT
 

package/docs/reference/interfaces/INftBurnRequest.md

@@ -4,7 +4,7 @@ Burn the NFT.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 

package/docs/reference/interfaces/INftComponent.md

@@ -8,7 +8,7 @@ Interface describing an NFT component.
 
 ## Methods
 
-### mint()
+### mint() {#mint}
 
 > **mint**\<`T`, `U`\>(`tag`, `immutableMetadata?`, `metadata?`, `namespace?`, `identity?`): `Promise`\<`string`\>
 
@@ -64,9 +64,9 @@ The id of the created NFT in urn format.
 
 ***
 
-### resolve()
+### resolve() {#resolve}
 
-> **resolve**\<`T`, `U`\>(`id`, `controllerIdentity?`): `Promise`\<\{ `issuer`: `string`; `owner`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
+> **resolve**\<`T`, `U`\>(`id`, `controllerIdentity?`): `Promise`\<\{ `issuer`: `string`; `issuerIdentityId`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
 
 Resolve an NFT.
 
@@ -96,13 +96,13 @@ The identity to perform the nft operation with.
 
 #### Returns
 
-`Promise`\<\{ `issuer`: `string`; `owner`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
+`Promise`\<\{ `issuer`: `string`; `issuerIdentityId`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
 
 The data for the NFT.
 
 ***
 
-### burn()
+### burn() {#burn}
 
 > **burn**(`id`, `controllerIdentity?`): `Promise`\<`void`\>
 
@@ -130,9 +130,9 @@ Nothing.
 
 ***
 
-### transfer()
+### transfer() {#transfer}
 
-> **transfer**\<`U`\>(`id`, `recipientIdentity`, `recipientAddress`, `metadata?`, `controllerIdentity?`): `Promise`\<`void`\>
+> **transfer**\<`U`\>(`id`, `recipientAddress`, `metadata?`, `controllerIdentity?`): `Promise`\<`void`\>
 
 Transfer an NFT.
 
@@ -150,12 +150,6 @@ Transfer an NFT.
 
 The id of the NFT to transfer in urn format.
 
-##### recipientIdentity
-
-`string`
-
-The recipient identity for the NFT.
-
 ##### recipientAddress
 
 `string`
@@ -182,7 +176,7 @@ Nothing.
 
 ***
 
-### update()
+### update() {#update}
 
 > **update**\<`U`\>(`id`, `metadata`, `controllerIdentity?`): `Promise`\<`void`\>
 

package/docs/reference/interfaces/INftConnector.md

@@ -8,7 +8,7 @@ Interface describing an NFT connector.
 
 ## Methods
 
-### mint()
+### mint() {#mint}
 
 > **mint**\<`T`, `U`\>(`controllerIdentity`, `tag`, `immutableMetadata?`, `metadata?`): `Promise`\<`string`\>
 
@@ -58,9 +58,9 @@ The id of the created NFT in urn format.
 
 ***
 
-### resolve()
+### resolve() {#resolve}
 
-> **resolve**\<`T`, `U`\>(`id`): `Promise`\<\{ `issuer`: `string`; `owner`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
+> **resolve**\<`T`, `U`\>(`id`): `Promise`\<\{ `issuer`: `string`; `issuerIdentityId`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
 
 Resolve an NFT.
 
@@ -84,13 +84,13 @@ The id of the NFT to resolve.
 
 #### Returns
 
-`Promise`\<\{ `issuer`: `string`; `owner`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
+`Promise`\<\{ `issuer`: `string`; `issuerIdentityId`: `string`; `tag`: `string`; `immutableMetadata?`: `T`; `metadata?`: `U`; \}\>
 
 The data for the NFT.
 
 ***
 
-### burn()
+### burn() {#burn}
 
 > **burn**(`controller`, `id`): `Promise`\<`void`\>
 
@@ -118,9 +118,9 @@ Nothing.
 
 ***
 
-### transfer()
+### transfer() {#transfer}
 
-> **transfer**\<`U`\>(`controllerIdentity`, `id`, `recipientIdentity`, `recipientAddress`, `metadata?`): `Promise`\<`void`\>
+> **transfer**\<`U`\>(`controllerIdentity`, `id`, `recipientAddress`, `metadata?`): `Promise`\<`void`\>
 
 Transfer an NFT.
 
@@ -144,12 +144,6 @@ The controller of the NFT who can make changes.
 
 The id of the NFT to transfer in urn format.
 
-##### recipientIdentity
-
-`string`
-
-The recipient identity for the NFT.
-
 ##### recipientAddress
 
 `string`
@@ -170,7 +164,7 @@ Nothing.
 
 ***
 
-### update()
+### update() {#update}
 
 > **update**\<`U`\>(`controllerIdentity`, `id`, `metadata`): `Promise`\<`void`\>
 

package/docs/reference/interfaces/INftMintRequest.md

@@ -4,7 +4,7 @@ Mint the data and return the NFT id.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **body**: `object`
 
@@ -18,18 +18,18 @@ The tag for the NFT.
 
 #### immutableMetadata?
 
-> `optional` **immutableMetadata**: `unknown`
+> `optional` **immutableMetadata?**: `unknown`
 
 The immutable metadata for the NFT.
 
 #### metadata?
 
-> `optional` **metadata**: `unknown`
+> `optional` **metadata?**: `unknown`
 
 The metadata for the NFT.
 
 #### namespace?
 
-> `optional` **namespace**: `string`
+> `optional` **namespace?**: `string`
 
 The namespace of the connector to use for the NFT, defaults to component configured namespace.

package/docs/reference/interfaces/INftResolveRequest.md

@@ -4,7 +4,7 @@ Resolve the NFT.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 

package/docs/reference/interfaces/INftResolveResponse.md

@@ -4,7 +4,7 @@ Response to resolving the NFT.
 
 ## Properties
 
-### body
+### body {#body}
 
 > **body**: `object`
 
@@ -16,11 +16,12 @@ The data that was resolved.
 
 The issuer of the NFT.
 
-#### owner
+#### issuerIdentityId
 
-> **owner**: `string`
+> **issuerIdentityId**: `string`
 
-The owner of the NFT.
+The on-chain Object ID of the verified IOTA Identity that minted this NFT.
+Empty string when not minted with identity verification.
 
 #### tag
 
@@ -30,12 +31,12 @@ The tag data for the NFT.
 
 #### immutableMetadata?
 
-> `optional` **immutableMetadata**: `unknown`
+> `optional` **immutableMetadata?**: `unknown`
 
 The immutable data for the NFT.
 
 #### metadata?
 
-> `optional` **metadata**: `unknown`
+> `optional` **metadata?**: `unknown`
 
 The metadata for the NFT.

package/docs/reference/interfaces/INftTransferRequest.md

@@ -4,7 +4,7 @@ Transfer the NFT and update the metadata.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 
@@ -18,18 +18,12 @@ The id of the NFT to transfer in urn format.
 
 ***
 
-### body
+### body {#body}
 
 > **body**: `object`
 
 The data to be used in the transfer.
 
-#### recipientIdentity
-
-> **recipientIdentity**: `string`
-
-The recipient identity for the NFT.
-
 #### recipientAddress
 
 > **recipientAddress**: `string`
@@ -38,6 +32,6 @@ The recipient address for the NFT.
 
 #### metadata?
 
-> `optional` **metadata**: `unknown`
+> `optional` **metadata?**: `unknown`
 
 The metadata for the NFT.

package/docs/reference/interfaces/INftUpdateRequest.md

@@ -4,7 +4,7 @@ Update the mutable data for the NFT.
 
 ## Properties
 
-### pathParams
+### pathParams {#pathparams}
 
 > **pathParams**: `object`
 
@@ -18,7 +18,7 @@ The id of the NFT to transfer in urn format.
 
 ***
 
-### body
+### body {#body}
 
 > **body**: `object`
 
@@ -26,6 +26,6 @@ The data to be used in the update.
 
 #### metadata?
 
-> `optional` **metadata**: `unknown`
+> `optional` **metadata?**: `unknown`
 
 The metadata for the NFT.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/nft-models",
-	"version": "0.0.3-next.2",
-	"description": "Contains models and classes for use with NFTs",
+	"version": "0.0.3-next.4",
+	"description": "Shared NFT interfaces, request and response models, and connector contracts.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/nft.git",