## **Build with transaction metadata**

**Introduction**
The Cardano Transaction Metadata feature allows anyone to embed metadata into transactions, which is then stored in the blockchain. The following are the four most common uses of metadata:

**Validation and verification**

Metadata can be utilized to check and verify external physical objects and legitimate content, as the Cardano Foundation has demonstrated with Scantrust and Baia's Wine. This necessitates coupling with a physical identifier, such as a QR-code, but it's especially beneficial for low-cost supply chain tracking of fast-moving consumer goods.

**Authentication and attribution**

There are frequently physical identifiers to confirm the authenticity of credentials received from an educational institution, membership group, or similar. This is more difficult for digital courses and accreditations. For a low fee, a transaction with metadata might serve as an immutable and always-accessible evidence of certification.

**Secure record of information**

Metadata attached to a transaction and confirmed on the Cardano blockchain is immutable. This means that no one can alter it, and it will last as long as the Cardano blockchain exists. This is a fantastic way to save and back up vital information, or even just to leave a humorous message for the future.

**Timestamping**

Any transaction that requires payment data to be attached, as well as the history of ownership of particular assets, can benefit from timestamping. Metadata can be used to create a timestamp within a transaction, allowing anyone to verify the time and date of a purchase, sale, or transfer.

Metadata, in essence, can be utilized to tell a transaction's story. Metadata can act as a confirmation or assurance of authenticity when combined with off-chain infrastructure such as physical identifiers.

**Metadata Workshop**

The Cardano Foundation's integrations team hosted a session on transaction metadata on January 18, 2021. Jeremy Firster and Mel McCann from the Cardano Foundation's integrations team delivered the workshop. Jeremy and Mel introduced transaction metadata and discussed its potential for creating Cardano apps with IOHK's Alan McSherry and Ben O'Hanlon. The slides of the presentation are also available.

<iframe width="859" height="325" src="https://www.youtube.com/embed/LrN3ETZ3fRM" title="Building on Cardano: Metadata workshop and Q&amp;A session" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Schema
Metadata can be expressed as a JSON object with some restrictions:

All top-level keys must be integers between 0 and 2^64 - 1. Each metadata value is tagged with its type. Strings must be at most 64 bytes when UTF-8 is encoded. Bytestrings are hex-encoded, with a maximum length of 64 bytes. Metadata aren't stored as JSON on the Cardano blockchain but are instead stored using a compact binary encoding (CBOR).

The binary encoding of metadata values supports three simple types:

Integers in the range -(2^64 - 1) to 2^64 - 1

Strings (UTF-8 encoded)

Bytestrings

And two compound types:
Lists of metadata values
Mappings from metadata values to metadata values
It is possible to transform any JSON object into this schema.

However, according to your requirements, if your application uses floating-point values, they will need to be converted somehow. Likewise, for null or bool values. Also, when reading metadata from the chain, be aware that integers may exceed the programming language of choice numeric range and may need special bigint parsing.

Example metadata:

`{
    "0": {
        "string": "cardano"
    },
    "1": {
        "int": 14
    },
    "2": {
        "bytes": "0x2512a00e9653fe49a44a5886202e24d77eeb998f"
    },
    "3": {
        "list": [
            {
                "string": "test"
            }
        ]
    },
    "4": {
        "map": [
            {
                "k": {
                    "string": "key"
                },
                "v": {
                    "string": "value"
                }
            }
        ]
    }
}`


**This is equivalent to the normalized JSON version:**

`{
    "0": "cardano", // string
    "1": 14, // int
    "2": [53, 23, 53, 64, 23, 06], // bytes
    "3": ["test"], // list or array
    "4": { "key": "value" }  // Object
}`

**Explore**

We invite developers to experiment using Cardano Transaction Metadata and come up with new ideas. Next, we'll go over the various methods for creating a transaction that includes metadata.



Build with transaction metadata

## **How to create a metadata transaction using cardano-cli**

This guide assumes that you have a basic understanding of cardano-wallet and cardano-cli, how to use it and that you have installed it into your system. Otherwise, we recommend reading Installing cardano-node, Running cardano-node, and Exploring Cardano Wallets guides first.

This guide also assumes that you have cardano-node and cardano-wallet running in the background and connected to one of the testnet networks.

**Overview**

This article will explore how we can utilize the Transaction Metadata feature of the Cardano blockchain. More specifically, how we can insert and retrieve metadata that we have stored in the blockchain for a decentralized application using Transaction Metadata.

**Use case**

Let's imagine a decentralized To-Do List Application that stores and retrieve its metadata not from centralized servers or storage but instead from the Cardano blockchain. First, let's check the diagram below to see how something like this could theoretically work:

![](https://developers.cardano.org/assets/images/todo-list-app-45f9667e8173e1fe60c0ce49c5e5f679.png)

Here, we see a front-end application the user interacts with and is responsible for inserting and retrieving the metadata to/from the back-end server. The back-end server is responsible for communicating to the cardano-node by creating transactions and querying the blockchain for the metadata information required by the front-end.

The front-end application is not necessarily tied to the specific back-end API and could switch to another API as long as it ultimately communicates to the Cardano network.

How do you actually create transaction metadata in the Cardano blockchain, you ask? We'll let's get our hands dirty!

Setup
To create a transaction metadata using the cardano-cli, you must first create a payment key-pair and a wallet address if you haven't already.

**Create Payment Keys**

`cardano-cli address key-gen \
--verification-key-file payment.vkey \
--signing-key-file payment.skey`

**Create Wallet Address**
`cardano-cli address build \
--payment-verification-key-file payment.vkey \
--out-file payment.addr \
--testnet-magic 1097911063`

Now that you have a wallet address, you can now request some tAda funds from the Testnet Faucet.

Once you have some funds, we can now create the sample metadata that we want to store into the blockchain.

We start by creating a metadata.json file with the following content:

`{
    "1337": {
        "name": "hello world",
        "completed": 0
    }
}`

Based on our theoretical To-Do List application, this JSON shape could be a way to insert / update entries into our list. We choose an arbitrary number (1337) as the key; we are basically saying that all metadata that will be inserted with that key is related to the To-Do List application data. Although we don't have control over what will be inserted with that metadata key since Cardano is an open platform.

Now that we have our JSON data, we can create a transaction and embed the metadata into the transaction. Ultimately storing it into the Cardano blockchain forever.

**Query UTXO**

The next step is to query the available UTXO from our wallet address:

`cardano-cli query utxo --testnet-magic 1097911063 --address $(cat payment.addr)`

You should see something like this:

`                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
dfb99f8f103e56a856e04e087255dbaf402f3801acb71a6baf423a1054d3ccd5     0        1749651926 lovelace`

Here we can see that our wallet address contains some spendable lovelace with the TxHash: dfb99f8f103e56a856e04e087255dbaf402f3801acb71a6baf423a1054d3ccd5 and TxIndex: 0. We can then use it to pay for the transaction fee when we store our data on the blockchain.

**Submit to blockchain**

Next, we create a draft transaction with the metadata embedded into it using the TxHash and TxIndex result from our last query.

`cardano-cli conway transaction build-raw \
--tx-in dfb99f8f103e56a856e04e087255dbaf402f3801acb71a6baf423a1054d3ccd5#0 \
--tx-out $(cat payment.addr)+0 \
--metadata-json-file metadata.json \
--fee 0 \
--out-file tx.draft`

Then we calculate the transaction fee like so:

`cardano-cli conway transaction calculate-min-fee \
--tx-body-file tx.draft \
--tx-in-count 1 \
--tx-out-count 1 \
--witness-count 1 \
--byron-witness-count 0 \
--testnet-magic 1097911063 \
--protocol-params-file protocol.json`

You should see something like this:

`171793 Lovelace`

With that, We build the final transaction with the total amount of our wallet minus the calculated fee as the total output amount. 1749651926 - 171793 = 1749480133

`cardano-cli conway transaction build-raw \
--tx-in dfb99f8f103e56a856e04e087255dbaf402f3801acb71a6baf423a1054d3ccd5#0 \
--tx-out $(cat payment.addr)+1749480133 \
--metadata-json-file metadata.json \
--fee 171793 \
--out-file tx.draft`

We then sign the transaction using our payment signing key:

`cardano-cli conway transaction sign \             
--tx-body-file tx.draft \
--signing-key-file payment.skey \
--testnet-magic 1097911063 \
--out-file tx.signed `

Finally, we submit the signed transaction to the blockchain:

`cardano-cli conway transaction submit \
--tx-file tx.signed \    
--testnet-magic 1097911063`

Congratulations, you are now able to submit Cardano transactions with metadata embedded into them. 🎉🎉🎉

Up next, we discuss how to retrieve metadata that we have stored in the Cardano blockchain. @TODO


Create a metadata transaction

## **How to create a metadata transaction using cardano-wallet**

This guide assumes that you have a basic understanding of cardano-wallet and cardano-cli, how to use it and that you have installed it into your system. Otherwise, we recommend reading Installing cardano-node, Running cardano-node, and Exploring Cardano Wallets guides first.

This guide also assumes that you have cardano-node and cardano-wallet running in the background and connected to one of the testnet networks.

**Overview**

This article will explore how we can utilize the Transaction Metadata feature of the Cardano blockchain. More specifically, how we can insert and retrieve metadata that we have stored in the blockchain for a decentralized application using Transaction Metadata.

**Use case**

Let's imagine a decentralized To-Do List Application that stores and retrieve its metadata not from centralized servers or storage but instead from the Cardano blockchain. First, let's check the diagram below to see how something like this could theoretically work:

![](https://developers.cardano.org/assets/images/todo-list-app-45f9667e8173e1fe60c0ce49c5e5f679.png)

We see here that there is a front-end application the user interacts with and is responsible for inserting and retrieving the metadata to/from the back-end server. The back-end server is responsible for communicating to the cardano-node by creating transactions and querying the blockchain for the metadata information required by the front-end.

The front-end application is not necessarily tied to the specific back-end API and could switch to another API as long as it ultimately communicates to the Cardano network.

How do you actually create transaction metadata in the Cardano blockchain, you ask? We'll let's get our hands dirty!

**Setup**

To create a transaction metadata using the cardano-wallet, you must first create a wallet if you haven't already.

**Generate mnemonic seed**

`cardano-wallet recovery-phrase generate`

**Create Wallet with the generated mnemonic seed**

`curl --request POST \
  --url http://localhost:1337/v2/wallets \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "test_cf_1",
    "mnemonic_sentence": ["shift", "badge", "heavy", "action", "tube", "divide", "course", "quality", "capable", "velvet", "cart", "marriage", "vague", "aware", "maximum", "exist", "crime", "file", "analyst", "great", "cabbage", "course", "sad", "apology"],
    "passphrase": "test123456"
}' | jq`

Now that you have a wallet, we can now retrieve a wallet address:

`curl --request GET \
  --url 'http://localhost:1337/v2/wallets/5076b34c6949dbd150eb9c39039037543946bdce/addresses?state=unused' | jq '.[0]["id"]'`

Now that you have a wallet address, you can now request for some tAda funds from the Cardano Testnet Faucet.

Once you have some funds, we can now create the sample metadata that we want to store into the blockchain.

Now let's say that the JSON shape we decided on for our To-Do List application is the following:

`{
    "1337": {
        "name": "hello world",
        "completed": 0
    }
}`


Based on our theoretical To-Do List application, this JSON shape could be a way to insert / update entries into our list. We choose an arbitrary number (1337) as the key, and we are basically saying that all metadata that will be inserted with that key is related to the To-Do List application data. Although we don't have control over what will be inserted with that metadata key since Cardano is an open platform.

Now that we have our JSON data, we can create a transaction and embed the metadata into the transaction. Ultimately storing it into the Cardano blockchain forever.

JSON Format
cardano-wallet has special requirements in terms of the JSON format of the payload that it accepts. Here are some examples:

`{
    "0": {
        "string": "cardano"
    },
    "1": {
        "int": 14
    },
    "2": {
        "bytes": "2512a00e9653fe49a44a5886202e24d77eeb998f"
    },
    "3": {
        "list": [
            {
                "int": 14
            }
        ]
    },
    "4": {
        "map": [
            {
                "k": {
                    "string": "key"
                },
                "v": {
                    "string": "value"
                }
            }
        ]
    }
}`

So we will have to convert our JSON metadata payload to the format the cardano-wallet accepts:

`{
    "1337": {
        "map": [
            {
                "k": {
                    "string": "name"
                },
                "v": {
                    "string": "hello world"
                }
            },
            {
                "k": {
                    "string": "completed"
                },
                "v": {
                    "int": 0
                }
            }
        ]
    }
}`

**Submit to blockchain**

Once we have the accepted format, we can now finally submit the metadata to the blockchain.

First, let's retrieve another unused wallet address from our wallet:

`curl --request GET \
  --url 'http://localhost:1337/v2/wallets/5076b34c6949dbd150eb9c39039037543946bdce/addresses?state=unused' | jq '.[0]["id"]'`

Now we will send 1,000,000 lovelace to our own wallet while attaching the metadata in the transaction, ultimately storing it into the blockchain forever.

`curl --request POST \
  --url http://localhost:1337/v2/wallets/5076b34c6949dbd150eb9c39039037543946bdce/transactions \
  --header 'Content-Type: application/json' \
  --data '{
    "passphrase": "test123456",
    "payments": [
        {
            "address": "addr_test1qpg2eglv9gf2rksvdj53t6ajfgzkycaadlt2fatjyn4etpze0592agqpwraqajx2dsu2sxj64uese5s4qum293wuc00q6hnhqq",
            "amount": {
                "quantity": 1000000,
                "unit": "lovelace"
            }
        }
    ],
    "metadata": {
        "1337": {
            "map": [
                {
                    "k": {
                        "string": "name"
                    },
                    "v": {
                        "string": "hello world"
                    }
                },
                {
                    "k": {
                        "string": "completed"
                    },
                    "v": {
                        "int": 0
                    }
                }
            ]
        }
    }
}'`

Congratulations, you are now able to submit Cardano transactions with metadata embedded into them. 🎉🎉🎉

Up next, we discuss how to retrieve metadata that we have stored in the Cardano blockchain. @TODO

Create a metadata transaction (Wallet)

## **Retrieving your metadata**

**Overview**

There are many ways to retrieve metadata stored in the Cardano blockchain. This article discusses the different components and ways that can help us retrieve all kinds of blockchain data.

**Blockfrost**

Blockfrost provides an API to access the Cardano blockchain fast and easily.

To retrieve metadata using Blockfrost, we call a specific endpoint for transaction metadata that they provide.

**Query 1337 Metadata**

curl -H 'project_id: <api_key>' https://cardano-mainnet.blockfrost.io/api/v0/metadata/txs/labels/1337 | jq


You should see something like this:

`[
  {
    "tx_hash": "a54d000ad56cf5b4afe769b5d74b51a5817dc44102c7f8286887e28bf257a2fd",
    "json_metadata": "gimbalabs-poc"
  },
  {
    "tx_hash": "b26cc2323d6212a0396fa4ddb35578648853ef769e2e427d92019d50163f636a",
    "json_metadata": "go build"
  }
]`

In this example, we query the Cardano Mainnet for any metadata under the key 1337. We see a few of the many metadata that is already inserted into the Cardano blockchain under that key. It is now up to your implementation how you want to cache and sort through all the data that lives on-chain. Blockfrost provides paging and ordering parameters.

Please visit their official documentation to know more.

cardano-db-sync
@TODO

cardano-graphql
@TODO

cardano-wallet
note
This Section assumes that you have basic understanding of cardano-wallet, how to use it and that you have installed it into your system. Otherwise we recommend reading Installing cardano-node, Running cardano-node and Exploring Cardano Wallets guides first.

This guide also assumes that you have cardano-node and cardano-wallet running in the background and connected to one of the testnet networks.

To retrieve all the Metadata for the transactions of a selected Wallet you just need to query the wallet transactions, passing as filter '.[].metadata'

`curl --url 'http://localhost:1337/v2/wallets/41263958f6668e06190be661900f7129be78d583/transactions' | jq '.[].metadata'`

It is important to note that the 41263958f6668e06190be661900f7129be78d583 string is actually the wallet.id of a previously generated wallet.

The JSON returning all Wallet Transactions Metadata will have some format like below (considering the Metadata created for these transactions has these values):

`{
  "1337": {
    "map": [
      {
        "k": {
          "string": "name"
        },
        "v": {
          "string": "hello world"
        }
      },
      {
        "k": {
          "string": "completed"
        },
        "v": {
          "int": 0
        }
      }
    ]
  }
}`

A similar command may be used to retrieve the Metadata of a single transaction.

`curl --url 'http://localhost:1338/v2/wallets/41263958f6668e06190be661900f7129be78d583/transactions/fab2e2a42b465d0f86452521521a2853597a58d31c5b29663b7e615cd2b2eb47' | jq '.metadata'`

41263958f6668e06190be661900f7129be78d583 string is actually the wallet.id of a previously generated wallet.

fab2e2a42b465d0f86452521521a2853597a58d31c5b29663b7e615cd2b2eb47 string is the transaction.id.

The JSON returning the single Transaction Metadata will have some format like below (considering the Metadata created for these transactions has these values):

`{
  "1337": {
    "map": [
      {
        "k": {
          "string": "name"
        },
        "v": {
          "string": "hello world"
        }
      },
      {
        "k": {
          "string": "completed"
        },
        "v": {
          "int": 0
        }
      }
    ]
  }
}`

Ogmios
@TODO

Retrieving your metadata

Build with Transaction Metadata

The Cardano Transaction Metadata feature allows anyone to embed metadata into transactions, which is then stored in the blockchain. The following are the four most common uses of metadata:

Build with Transaction Metadata

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation