Skip to main content

Update Metadata in Dynamic Notarizations

Update Metadata in Dynamic Notarizations​

This guide demonstrates how to update the updatable metadata of a Dynamic Notarization. Metadata updates are independent of state updates and do not affect the version counter.

Prerequisites​

  • A Dynamic Notarization already created and published to the IOTA network
  • The notarization must not be update-locked
  • Sufficient funds for gas costs

Understanding Metadata Types​

Dynamic notarizations have two types of metadata:

  • Immutable Description: Set at creation time and cannot be changed
  • Updatable Metadata: Can be modified after creation

1. Get the Notarization Client​

First, ensure you have a funded notarization client with the necessary permissions.

examples/utils/utils.rs
loading...

2. Create a Dynamic Notarization with Metadata​

Create a dynamic notarization with initial updatable metadata:

examples/06_update_metadata.rs
loading...

3. Check Current Metadata​

Before updating, inspect the current metadata state:

examples/06_update_metadata.rs
loading...

4. Update Metadata​

Update the metadata with new content. You can set it to a new value or clear it entirely:

examples/06_update_metadata.rs
loading...

5. Clear Metadata​

You can also clear the metadata by setting it to None:

examples/06_update_metadata.rs
loading...

Key Features of Metadata Updates​

Version Counter Independence​

Unlike state updates, metadata updates do not affect the state version counter:

  • State version count remains unchanged after metadata updates
  • Only state content updates increment the version counter

Timestamp Behavior​

Metadata updates do not change the "last state change" timestamp:

  • Creation timestamp remains unchanged
  • Last state change timestamp is only updated by state content changes
  • Metadata changes have their own tracking mechanism

Immutable vs Updatable​

  • Immutable Description: Cannot be changed after creation
  • Updatable Metadata: Can be modified, cleared, or reset multiple times

Metadata Operations​

You can perform several operations on updatable metadata:

  • Set new value: Replace existing metadata with new content
  • Clear metadata: Set to None to remove metadata
  • Multiple updates: Update as many times as needed

Error Handling​

Metadata updates may fail if:

  • The notarization is update-locked (locked notarizations cannot be updated)
  • Insufficient gas funds
  • Network connectivity issues
note

Metadata updates are allowed on dynamic notarizations even when they have transfer locks. Only update locks prevent metadata modifications.

Full Example Code​

examples/06_update_metadata.rs
loading...

Running Examples Locally​

In order to run the examples, you will need to run an IOTA network locally.

If you want to use something different, you will need to modify the API and faucet endpoints in the examples to match your setup.