# IID Module

> @Sascha1337: Excuse me editing this document - but how is the status and evolution on this topic right here, by today? Thanks !

## Abstract

Every digital asset in the Cosmos context should have a universally addressable Interchain Identifier (IID).
Interchain Identifiers are a standards-compliant mechanism for uniquely identifying and referring to digital assets within chain namespaces.
IIDs also enable (off-chain) assertions to be made about (on-chain) digital assets – for instance, in the form of Verifiable Credentials.
Each IID is associated with an IID Document, which contains all the data needed to compose and interact with an asset's properties and services.

The `IID Module` implements the [Interchain Identifier (IID) Specification](https://github.com/interNFT/nft-rfc/blob/main/nft_rfc_009.md).

## Context

Applications using this module will enable assets on Cosmos networks to be interoperable with the systems and tooling for Decentralised Identifiers (DIDs), which conform with the [W3C DID Core](https://w3c.github.io/did-core/) and related family of specifications.
The types of assets for which this is relevant includes Non-Fungible Tokens (NFTs), Fungible Tokens, Wallets Accounts, Self-sovereign Digital Identifiers, Name Records, or any other uniquely identifiable asset type.

Any module which perfoms IID registry functions may implement the same methods as the IID module. Or application modules may use the services of the IID Module to perform these functions.

Integrating IID registry functions within application-specific modules has the advantage of reducing redundancies by having the application module as a context.

For application chains which have multiple modules that use IIDs (e.g. an NFT module plus Fungible Tokens module, plus Self-sovereign Identity Module), developers might find it more convenient to include the IID Module to service all their application-specific modules.

## Concepts

### DIDs and IIDs

Decentralized Identifiers (DIDs) are the [W3C specification](https://w3c.github.io/did-core/) for identifying any subject in the physical or digital realm. DIDs implement standardised DID Methods to produce fully-qualified Universal Resource Identifier (URI), as defined by RFC3986.

Interchain Identifiers (IIDs) are a DID Method for identifying on-chain assets – such as NFTs, fungible tokens, namespace records and account wallets.

### IID Document

Properties of an IID are conceptually stored in the format of an IID Document object. Which contains core properties (as defined by [W3C DID Core](https://w3c.github.io/did-core/)):
- Identifiers
- DID Subject
- DID Controller
- Also Known As
- Verification Methods
- Cryptographic material
- Verification Relationships
- Authentication
- Assertion
- Key Agreement
- Capability Invocation
- Capability Delegation
- Service

As well as two additonal property sets which are unique to digital assets:
- Linked Resources
- Accorded Rights

Property extensions may be added by application developers who need to implement their own [DID Method](https://w3c.github.io/did-core/#method-syntax) for a specific use-case (although it is anticipated that the IID method should serve most).

### IID Registry

The IID Module is a [Verifiable Data Registry](https://w3c.github.io/did-core/#dfn-verifiable-data-registry) sytem to CRUD decentralized identifiers and IID documents.

Resolving a given IID using the IID Module services returns the data necessary to produce an IID document in a [DID-conformant format](https://w3c.github.io/did-core/#dfn-did-documents), which can be serialized as JSON-LD.

### IID Method

The IID Method defines a standard way to:
- Create an IID
- Set the properties associated with the IID
- Read (resolve) an IID Document to produce a conformant JSON-LD representation.
- Update IID Document properties
- Deactivate an IID
- Delete an IID

### IID Resolver

The IID resolver is a [DID resolver](https://w3c.github.io/did-core/#dfn-did-resolvers) service that takes an IID as input and produces an IID Document as output (which conforms to the [W3C DID documents](https://w3c.github.io/did-core/#dfn-did-documents) format).

### IID Deactivation

If an IID has been [deactivated](https://w3c.github.io/did-core/#method-operations), the IID document metadata includes a property with the boolean value `true`.

## State

### IID Registry

IID Documents include the four standard DID Core properties:
1. [Identifiers]()
2. [Verification Methods]()
3. [Verification Relationships]()
4. [Service]()

And two new properties:

6. [Linked Resources]()
7. [Accorded Rights]()

[comment]: <> (add links to proto artifacts)

The IID Universal Resource Identifier string and its associated IID Document properties, are stored under the `0x21` key.

### IID Document Properties

| Property | Required? | Value | constraints |
| -------- | -------- | -------- |-------- |
| id |yes |A string that conforms to the rules in § 3.1 DID Syntax.|
|alsoKnownAs |no |A set of strings that conform to the rules of [RFC3986] for URIs.|
|controller| no |A string or a set of strings that conform to the rules in § 3.1 DID Syntax.|
verificationMethod| no |A set of Verification Method maps that conform to the rules in § Verification Method properties.|
|authentication| no| A set of either Verification Method maps that conform to the rules in § Verification Method properties) or strings that conform to the rules in § 3.2 DID URL Syntax.|
|assertionMethod| no||
|keyAgreement| no||
|capabilityInvocation| no|
|capabilityDelegation| no
|service| no|A set of Service Endpoint maps that conform to the rules in § Service properties.|
linkedResources|no | |
|accordedRights|no | |

### Verification Method Properties
| Property | Required? | Value | constraints |
| -------- | -------- | -------- |-------- |
|id |yes| A string that conforms to the rules in § 3.2 DID URL Syntax|
|controller| yes| A string that conforms to the rules in § 3.1 DID Syntax|
|type| yes| A string|
|publicKeyJwk |no |A map representing a JSON Web Key that conforms to [RFC7517]. See definition of publicKeyJwk for additional constraints.|
|publicKeyBase58| no| A string that conforms to a base58btc encoded public key.|

### Service properties

| Property | Required? | Value | constraints |
| -------- | -------- | -------- |-------- |
|id| yes| A string that conforms to the rules of [RFC3986] for URIs.|
|type| yes |A string or a set of strings.|
|serviceEndpoint| yes A string that conforms to the rules of [RFC3986] for URIs, a map, or a set composed of a one or more strings that conform to the rules of [RFC3986] for URIs and/or maps.|

#### Linked Resources

| Property | Required? | Value | constraints |
| -------- | -------- | -------- |-------- |
| | | | |

#### Accorded Rights

| Property | Required? | Value | constraints |
| -------- | -------- | -------- |-------- |

### Authorization
Only the Controller/s specified in the `Controller` property are authorized to update, revoke or deactivate an IID or edit the IID Document properties. This includes changing Controller/s.

type Controller struct {
    Did          string
    PublicKey    string
}

A Controller is identified by a DID. This enables controllers to manage their cryptographic keys - including key rotation.

Processing of the Verification Method for authorizing a Controller to change the state of an IID record is performed by an Authorization module, such as the `Auth Module` for standard .sdk signatures, or alternatives, such as the `AuthZ Module` for processing Authorization Capabilities using _zCaps_.

## Messages

### MsgCreateIdentifier

An IID with all of the required details can be submitted by any account via a `MsgCreateIdentifier` transaction, which consists of the following values. If the Id in the IidDocument is missing, then a unique Id is generated during the message processing.

| Property | Type | Description |
| -------- | ---- | ----------- |
| Creator | string | The controller that is creating the IID |
| IidDocument | [IidDocument](#IID-Document-Properties) | The IID document being created |

**State Modifications:**

- Create a new IID with the specified attributes

**Authorization:**

- None

A `MsgCreateIdentifier` transaction can be handled according to the following pseudocode.

// PSEUDOCODE //
// Check if MsgCreateIdentifier is valid. If it is, create identifier //

upon receiving txIidCreateIdentifier from sender do

    // Check if transaction is correctly formatted. Includes fee payment.
    if !correctlyFormatted(txIidCreateIdentifier)
        throw
    
    iidDoc = txIidCreateIdentifier.IidDocument
    
    // Check that IID Doc is valid
    if !isValidIidDoc(iidDoc)
        throw
    
    // If Id was not provided, generate a unique id as a service
    if (len(iidDoc.Id) == 0)
        iidDoc.Id = generateId()
    
    // Check that identifier does not already exist
    if identifierExists(iidDoc.Id)
        throw
    
    store(Iids, <iidDoc.Id|'iids'>, iidDoc) // Store created IID Doc in Iids mapping

### MsgUpdateIidDocument

An IID document's properties can be updated by an authorized controller of the IID via a `MsgUpdateIidDocument` transaction, which includes the following values:

| Property | Type | Description |
| -------- | ---- | ----------- |
| Id | string | The ID of the IID document being updated |
| Controller | string | The controller that is updating the IID document |
| Identifiers | list | (Optional) List of updated identifiers |
| VerificationMethods | list | (Optional) List of updated verification methods |
| VerificationRelationships | list | (Optional) List of updated verification relationships |
| Service | Service | (Optional) Updated service |
| LinkedResources | list | (Optional) Updated linked resources |
| AccordedRights | list | (Optional) Updated accorded rights |

**State Modifications:**

- Update IID Document property attributes

**Authorization:**

- The _UpdateIidDocument_ capability can only be invoked by the authorized Controller/s of the IID.

A `MsgUpdateIidDocument` transaction can be handled according to the following pseudocode.

// PSEUDOCODE //
// Check if MsgUpdateIidDocument is valid. If it is, update the identifier //

upon receiving txIidUpdateIidDocument from sender do

    // Check if transaction is correctly formatted. Includes fee payment.
    if !correctlyFormatted(txIidUpdateIidDocument)
        throw
    
    // Try to load IID using the ID in the transaction
    iidDoc = load(Iids, <txIidUpdateIidDocument.Id|'iids'>) // iids is a const key, txIidUpdateIidDocument.Id is variable
    
    if (iidDoc == nil)
        // There is no IID for the specified ID
        throw
    
    if !isAuthorizedController(iidDoc, txIidUpdateIidDocument.Controller)
        // Controller that send the transaction is not authorized
        throw
    
    // Update Identifiers if this is not nil in the transaction
    if (txIidUpdateIidDocument.Identifiers != nil)
        iidDoc.Identifiers = txIidUpdateIidDocument.Identifiers
        
    // Update VerificationMethods if this is not nil in the transaction
    if (txIidUpdateIidDocument.VerificationMethods != nil)
        iidDoc.VerificationMethods = txIidUpdateIidDocument.VerificationMethods
        
    // Update VerificationRelationships if this is not nil in the transaction
    if (txIidUpdateIidDocument.VerificationRelationships != nil)
        iidDoc.VerificationRelationships = txIidUpdateIidDocument.VerificationRelationships
    
    // Update Service if this is not nil in the transaction
    if (txIidUpdateIidDocument.Service != nil)
        iidDoc.Service = txIidUpdateIidDocument.Service

    // Update LinkedResources if this is not nil in the transaction
    if (txIidUpdateIidDocument.LinkedResources != nil)
        iidDoc.LinkedResources = txIidUpdateIidDocument.LinkedResources

    // Update AccordedRights if this is not nil in the transaction
    if (txIidUpdateIidDocument.AccordedRights != nil)
        iidDoc.AccordedRights = txIidUpdateIidDocument.AccordedRights
    
    store(Iids, <iidDoc.Id|'iids'>, iidDoc) // Store updated IID Doc in Iids mapping
    
    emitEvent('update_iid_document')

### MsgDeactivateIdentifier

[comment]: <> (needs a discussion on Deletion vs deactivation as DID-core does not use the term deletion and there are specific expectations for the response when reolving a deactivated DID - shaun)

An IID can be deactivated by an authorized controller of the IID via a `MsgDeactivateIdentifier` transaction, which consists of the following values:

| Property | Type | Description |
| -------- | ---- | ----------- |
| Id | string | The IID being deactivated |
| Controller | string | The controller that is deactivating the IID |

**State Modifications:**

- Deactivate the specified IID

**Authorization:**

- The _DeactivateIdentifier_ capability can only be invoked by the authorized Controller/s of the IID.

#### `MsgDeactivateIdentifier` transaction

// PSEUDOCODE //
// Check if MsgDeactivateIdentifier is valid. If true, update the identifier //

upon receiving txIidDeactivateIdentifier from sender do

    // Check if transaction is correctly formatted. Includes fee payment.
    if !correctlyFormatted(txIidDeactivateIdentifier)
        throw
    
    // Try to load IID using the ID in the transaction
    iidDoc = load(Iids, <txIidDeactivateIdentifier.Id|'iids'>) // iids is a const key, txIidDeactivateIdentifier.Id is variable
    
    if (iidDoc == nil)
        // There is no IID for the specified ID
        throw
    
    if !isAuthorizedController(iidDoc, txIidUpdateIdentifier.Controller)
        // Controller that send the transaction is not authorized
        throw
        
    if (iidDoc.Active == False)
        // IID is already deactivated
        throw
    
    iidDoc.Active = False
    
    store(Iids, <iidDoc.Id|'iids'>, iidDoc) // Store deactivated IID Doc in Iids mapping

## Queries

[comment]: <> (I did not got into PSEUDOCODE depth for queries. Queries are usually not even documented I believe)

### QueryIdentifierDocument

Returns the requested document.

## Hooks

Other modules may register operations to execute when a specific event has occurred within the IID module. These events can be registered to execute immediately `Before` or `After` the IID event (as indicated by the hook name):

- `AfterIdentifierCreated(Context, Did)`
- called when an identifier is created
- `BeforeIdentifierUpdated(Context, Did)`
- called when an identifier is updated
- `AfterIdentifierUpdated(Context, Did)`
- called when an identifier is updated
- `BeforeIdentifierDeactivated(Context, Did)`
- called when an identifier is deactivated
- `AfterIdentifierDeactivated(Context, Did)`
- called when an identifier is deactivated
- `BeforeIdentifierDeleted(Context, Did)`
- called when an identifier is deleted
- `AfterIdentifierDeleted(Context, Did)`
- called when an identifier is deleted

[comment]: <> (These are completely optional and we can do without them. Most modules in Cosmos SDK do not define hooks at all. I just wrote out what the most obvious hooks could be)

## Events

| Type | Attribute Key | Attribute Value |
| -------- | -------- | -------- |
| create_identifier | did | {createdDid} |
| create_identifier | creator | {creatorDid} |
| generate_identifier | did | {createdDid} |
| generate_identifier | creator | {creatorDid} |
| update_iid_document | did | {updatedIidDocumentId} |
| update_iid_document | controller | {controllerUpdatingTheDoc} |
| deactivate_identifier | did | {deactivatedIdentifier} |
| deactivate_identifier | controller | {controllerDeactivatingTheDoc} |
| delete_identifier | did | {deletedIdentifier} |

[comment]: <> (Here we should list all of the relevant attributes that one will have access to when they search for events. For example, if I query the list of IID creation events, I might want to know the 'did' [already listed above], but also the creator etc.)

## Parameters

The IID module defines the following global parameters:

| Key | Type | Example |
| -------- | -------- | -------- |
| namespace| string | did:earth:ixo: |
| @context| uri | https://www.w3.org/ns/did/v1 |

[comment]: <> (If we're going to add more parameters, please take a look at https://github.com/cosmos/cosmos-sdk/blob/master/x/mint/spec/04_params.md as a reference for what they should look like)