Transaction Metadata
How Cardano enables custom on-chain data storage and certification using structured CBOR metadata.
Attaching Context to Value
A standard blockchain transaction moves a native coin from address A to address B. While this transfers value, it doesn't explain why the transfer occurred. To support real-world commerce, identity, and applications, Cardano allows users to attach custom structured data, called Transaction Metadata, directly to any transaction.
How Metadata is Structured
To keep the ledger efficient and secure, transaction metadata on Cardano must adhere to strict formatting guidelines defined by the protocol:
- Top-Level Integer Keys: Unlike a standard JSON object which uses arbitrary string keys, the top-level keys of Cardano metadata must be unsigned integers between
0and2^64 - 1. Specific keys are reserved for community standards (e.g., key721is reserved for NFT metadata). - 64-Byte String Limit: Within the data structures, individual text strings or byte arrays cannot exceed 64 bytes. To store longer text, developers split the content into arrays of 64-byte strings. This prevents illegal, oversized, or malicious content from being stored as single monolithic blocks.
- CBOR Encoding: While developers write metadata in a JSON-like format, it is converted and stored on-chain using CBOR (Concise Binary Object Representation), minimizing the byte-size of the transaction.
Fee Implications
Cardano does not charge an arbitrary "gas premium" for metadata. However, since fees are strictly calculated based on the total transaction size in bytes, adding large metadata will increase the transaction fee slightly. This provides a natural, deterministic economic barrier against blockchain bloat.
Real-World Use Cases
- CIP-25 & CIP-68 (NFT Metadata): Every Cardano NFT uses transaction metadata (or reference UTXO metadata under CIP-68) to specify the token's name, description, media link, and custom attributes.
- Supply Chain & Logistics: Scanning a physical item's QR code can link it to an immutable, timestamped Cardano metadata record proving its origin, temperature history, and ownership transition.
- Transaction Messages (CIP-20): Wallets can attach encrypted or plaintext payment references, invoice numbers, or memos so both parties understand the transaction's purpose.