IOTA Identity is Coming to Layer 1

Shimmer ·

Explore IOTA Identity on Shimmer Now

TL;DR:
The upcoming Stardust upgrade of IOTA enables IOTA Identity to come to the network's Layer 1. The new implementation is a major upgrade over the previous data method as it enables identities to interact with NFTs, native tokens, and smart contracts while improving data availability, accessibility, and synchronization guarantees. With the Stardust protocol upgrade now live on the Shimmer network, the new UTXO-based decentralized identifier method and other capabilities are waiting to be tested.

The upcoming Stardust update to the IOTA network will significantly extend the capabilities of the protocol and introduce new ways of designing solutions on the ledger. This improvement has inspired us to rethink how IOTA Identity should work on IOTA and how we can interact with the extended capabilities. The Stardust upgrade to Shimmer, IOTA’s testing network, enables us to explore these new capabilities.

Not only does Stardust transform IOTA into an infrastructure layer for smart contract chains but it also makes it a multi-asset ledger and introduces mechanisms to make arbitrary data permanently available on all IOTA nodes. For a general overview of what Stardust can do, this blog post gives a nice overview; but in summary, Stardust adds new outputs to Layer 1 that significantly extend the capabilities of the IOTA ledger.

One of these new capabilities – on-ledger permanent data storage – allows us to store decentralized identifier (DID) documents directly in the ledger, opening up a whole range of new possibilities. DIDs can directly interact with any of the other output types and can be composed of smart contracts. In this blog post, we’ll take a deeper look at what this capability enables.

More efficient and capable DID methods

The current DID implementation on Chrysalis utilizes data messages on the Tangle to broadcast DID documents that are indexed by all nodes but pruned away after a certain amount of time. This means that the resolvers of DIDs need access to a node that stores all data messages going through the Tangle, a so-called “permanode”. However, permanodes require significant resources to run, back up, and potentially restore. The new features of Stardust enable us to offer a more resilient, effective, and resource-efficient solution. A DID document stored directly in the ledger state is free from the shortcomings of a permanode since an unspent output is not pruned by nodes and so there is no need for a permanode. This improves the availability, accessibility, and synchronization offered by our current implementation.

We envision the UTXO-based DID method as the method for high-assurance identities (such as issuers of Verifiable Credentials) and identities that profit from directly interacting with other Layer 1 artifacts (like NFTs and native tokens) as well as those that need to be composed of smart contracts. Storing Identities on the ledger will guarantee their latest state is in sync with all other nodes and makes DID resolution possible from any node. However, ledger storage space is a scarce resource, which means a deposit of tokens, like MIOTA or SMR, is required to cover the byte cost of the stored document. This is a refundable deposit proportional to the size of the stored document and can be fully reclaimed when destroying the output. You can read more about it here.

Because a deposit might be undesirable for some use cases, we are also working on a replacement for our current DID method. We anticipate that this replacement will not need a deposit per identity, though it will lack the Layer 1 integration of the UTXO method. This method is intended for use cases where large numbers of identities need to be made publicly available, and where a deposit per identity would be unfeasible – for example, where cheap sensors need to be equipped with identities but the deposit exceeds the cost of the sensor.

In summary, we want to deliver two DID methods for Stardust on the IOTA mainnet that are complementary to each other, with the following trade-offs:

  1. The UTXO-based DID method that unlocks the full Layer 1 integration, requires a storage deposit and is intended for high-assurance identities.
  2. A DID method that replaces the current Chrysalis method and which does not require a deposit per identity lacks direct Layer 1 integration and is intended to make large numbers of identities resolvable in the ecosystem.

The two DID methods are intended to be complementary in terms of their guarantees. This means that developers building on IOTA Identity will have a choice of which trade-offs to accept and will even be able to use both methods in parallel, giving them the best of both worlds.

In this blog post, we want to focus on the UTXO-based method, describe how it works, and how it can be utilized. We will follow up on the second method once we have completed the necessary research.

Technical overview

The goal of the UTXO method is to make DID documents available on Layer 1 while following the DID standard as closely as possible. To that end, we utilize another innovation introduced by the Stardust upgrade, the Alias Output.

The Alias Output has a state metadata property that can contain arbitrary data up to a certain size. The DID document is stored in that property. For the method-specific identifier (or “ID”) of the DID, the Alias ID is utilized. The Alias ID itself is derived from the content of the creating transactions and is globally unique and immutable after creation. These properties make it suitable as a DID and at the same time a meaningful identifier on Layer 1 for extended use-cases.

In summary, the Alias Output provides four capabilities that are particularly suitable for hosting identities:

  1. The Alias ID is a globally unique identifier that cannot be changed after creation, which fits the immutable nature of DIDs perfectly. The DID contains the Alias ID, so DID and Output can be easily converted to each other. A simple example: The last part of the DID (the method-specific identifier) did:iota:0x0a6cf67b1faff3c4c9097ce91d84b1df490917b39a64a5b6ef30476ce4c528d3 is the Alias ID of the corresponding Alias Output.
  2. The Output can store arbitrary data in its state metadata, which is where the DID document is stored.
  3. Only the state controller is allowed to update the state of the Alias Output, such as the DID document in the state metadata, which means the state controller becomes the DID controller in DID terminology.
  4. A DID in an Alias Output inherits all the capabilities of that output, such as the ability to send and receive tokens or mint native assets. We explore these use cases in more detail below.

Because the Alias Output is capable of interacting with NFTs and native tokens and enables smart contract chains to be anchored to Layer 1, it sits in the middle of the Layer 1 web, which is where DIDs should be, too.

Looking ahead, to be fully compliant with the DID spec, we need to extend the Alias Output to allow for multiple controllers. We expect this update to land before Stardust goes onto the IOTA mainnet.

Use cases

In the following section, we want to demonstrate the interactions of UTXO identities with the other Layer 1 artifacts and describe the use cases unlocked by these interactions. For each interaction, we’ve supplied examples in the library, which can be found here:

Identities controlling other identities

Since an Alias Output can control other Alias Outputs, an identity can effectively control another identity. This allows us to create hierarchies of identities and model situations like subsidiaries for companies or custodians for humans. In this context, control must be distinguished between two parties: the governor and the state controller. The state controller has the ability to make changes to the DID document and can therefore decide how to represent the identity. The governor controls who is allowed to make updates to an identity by assigning a state controller. As an example, let’s consider the case of a smartphone manufacturer called Phonemkr and its two subsidiaries: Phoneshop, where people can buy phones, and Phoneshippr which ships the phones. Phoneshop is supposed to manage the identity of the shipping subsidiary, but the manufacturer wants to retain ultimate control over both.


This is achieved by setting the address of an identity's Alias Output as the state controller or governor unlock condition of another identity. Currently, the Alias Output only allows for a single state controller, but our intention is to work on allowing multiple controllers with future updates of the protocol. In the above example, multiple controllers would allow both the manufacturer and the shop to make updates to the identity, providing more flexibility.

Authenticating senders and receivers of funds

Identities can receive and hold IOTA coins and native tokens, and send them to other identities. This can identify the sender and receiver of funds, thereby providing a stronger assurance to the receiver and sender, respectively.

Because an Alias Output can hold tokens, any DID can easily be converted into an address. Suppose Alice has just exchanged DIDs with Bob and she wants to send him some funds. During the DID exchange, Alice required Bob to authenticate his DID to her, proving that the DID he shares is truly his. This way, when Alice sends funds to the address of his Alias Output, she can be sure that whoever controls Bob’s identity will be able to access the funds. This is most likely Bob himself, but it may also be any other address such as an Alias or NFT address.

Inversely, if someone receives funds from an Alias Output that contains a DID, they can be sure that the owner of the DID sent the funds. This enables the origin of the funds to be authenticated, which could, for example, support anti-money laundering measures.

Because observers can see the movement of funds, it might be preferable to use different identities for different use cases instead of using a single identity for all interactions (this also applies to identity interactions in general).

On a technical level, an identity can control funds because the address of an Alias Output can be used as the Unlock Condition of any output, which allows the Alias Output to control the Basic Output and its funds. Funds are sent by creating a Basic Output controlled by Bob’s Alias Output. The Identity Alias Output here provides a permanent identifier to receive funds while allowing security best practices, such as key rotation. This effectively allows funds to be transferred to DIDs on Layer 1.

DIDs issuing NFTs

With the introduction of the Stardust protocol upgrade, NFTs can now be minted and transferred on Layer 1 through a dedicated NFT Output. DIDs can help prove the identity of the issuer of an NFT.


Suppose our example smartphone manufacturer “Phonemkr” wants to issue digital product passports in the form of NFTs for each phone they sell. “Phonemkr” creates its identity in an Alias Output and provably links its DID to its website phonemkr.com. If “Phonemkr” issues NFTs with its identity as the issuer, this will effectively prove that phonemkr.com issued those NFTs.

Note that Domain Linkage is an upcoming extension to IOTA identity, but is not yet included in the current release.

Similar to transferring funds, NFTs can also be owned by and transferred to DIDs, since the Unlock Condition of an NFT Output can be an Alias Output representing a DID, providing assurances about who you receive NFTs from or send NFTs to.

Furthermore, identities can be unlocked (read as “owned”) by NFTs. This might seem strange at first and is not generally recommended for humans, but can be very beneficial for things or organizations that are represented and traded through their respective NFTs. This allows the ownership of a thing (or organization) and the control of the respective identity to be transferred in one atomic interaction.

DIDs issuing native tokens

If the minter of native tokens is a DID, the minter can provide better assurances and more trust to token holders. With this information, token holders can verify who originally created a native token and thereby check if a native token they have received originated from wherever they expected it to, or verify the claims of somebody regarding whichever assets they minted.

Technically this works because native tokens are created through a Foundry Output which in turn is controlled by a single Alias Output. Having an Identity embedded in this Alias Output enables the identity of the minter to be resolved.

Extending DID functionality with smart contracts

The Stardust protocol upgrade will enable the state of IOTA Smart Contract (ISC) chains to be anchored into Alias Outputs in the ledger. With IOTA Identity, smart contract chains can be provably linked to identities. As described above under “Identities controlling other identities’”, identities can be organized hierarchically, allowing a single identity to create and control multiple other Alias Outputs. This means an identity in an Alias Output can govern the Alias Output of an ISC chain. This lets users identify the governor of a chain and helps them decide whether they want to trust and interact with the chain. It also lets external observers verify and prove who has ultimate control of the chain.

Storing identities in Layer 1 outputs will also enable composability through smart contracts. Additional functionality for identities not covered by the DID standard can be built into smart contracts, such as advanced or more specialized Identity and Access Management (IAM) use cases. We will follow up on this topic closer to the release of smart contracts on Shimmer.

Start building now!

In this blog post, we explored the new capabilities of IOTA Identity enabled by Stardust. To recap:

  • Identities can control other identities, which enables flexible modeling of who can change the representation of an identity and who is allowed to make these updates in the first place.
  • Identities can provide more trust when sending and receiving funds.
  • Identities can increase the trust holders have towards the issuers of NFTs and native tokens.
  • Identities enabled the authentication of smart contract chains and will allow deeper integration in the future.

To get the latest alpha version of the IOTA Identity library targeting the Shimmer network follow:

We want to get an early version into your hands as soon as possible so you can explore all these new possibilities. But please be aware that this is an alpha version and we are still working on providing the most ergonomic API and extension points to customize your implementations, so expect potentially breaking changes in the next versions.

In the coming weeks, we’ll continue polishing and stabilizing the UTXO method and start implementing the second method to have both ready before the Stardust protocol upgrade hits the IOTA mainnet.

In the meantime, if you have feedback regarding the current state of the library, head over to GitHub and create an issue or reach out on Discord in #identity. We look forward to hearing from you!

Links in this article

Follow us on our official channels for all the latest Shimmer news:
Discord | Twitter | LinkedIn | Reddit