Attribute Plugin

The Attributes Plugin stores key-value pairs directly on-chain within Core Assets or Collections. Perfect for game stats, traits, and any data that on-chain programs need to read.

Summary

The Attributes Plugin is an Authority Managed plugin that stores key-value string pairs on-chain. Unlike off-chain metadata, these attributes are readable by Solana programs and indexed by DAS.

• Store any string key-value pairs on-chain
• Readable by on-chain programs via CPI
• Automatically indexed by DAS for fast queries
• Mutable by the update authority

Out of Scope

Off-chain metadata attributes (stored in JSON at URI), complex data types (only strings supported), and immutable attributes (all attributes are mutable).

Quick Start

Jump to: Add to Asset · Update Attributes

1. Add the Attributes plugin: addPlugin(umi, { asset, plugin: { type: 'Attributes', attributeList: [...] } })
2. Each attribute is a { key: string, value: string } pair
3. Update anytime with updatePlugin()
4. Query via DAS or fetch on-chain

Common Use Cases

• Game character stats: Health, XP, level, class - data that changes during gameplay
• Access control: Tier, role, permissions - data programs check for authorization
• Dynamic traits: Evolving NFTs where traits change based on actions
• Staking state: Track staking status, rewards earned, time staked
• Achievement tracking: Badges, milestones, completion status
• Rental/lending: Track rental periods, borrower info, return dates

Works With

Arguments

AttributeList

The attribute list consists of an Array[] then an object of key-value pairs {key: "value"} string value pairs.

const attributeList = [
  { key: 'key0', value: 'value0' },
  { key: 'key1', value: 'value1' },
]

Adding the Attributes Plugin to an Asset

import { publicKey } from '@metaplex-foundation/umi'
import { addPlugin } from '@metaplex-foundation/mpl-core'
const asset = publicKey('11111111111111111111111111111111')
await addPlugin(umi, {
  asset: asset.publicKey,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

Updating the Attributes Plugin on an Asset

import { publicKey } from '@metaplex-foundation/umi'
import { updatePlugin } from '@metaplex-foundation/mpl-core'
const assetAddress = publicKey('11111111111111111111111111111111')
await updatePlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

Common Errors

Authority mismatch

Only the plugin authority (usually update authority) can add or update attributes. Verify you're signing with the correct keypair.

String too long

Attribute keys and values are limited in size. Keep them concise.

Notes

• Authority Managed: update authority can add/update without owner signature
• All values are strings - convert numbers/booleans as needed
• Updating replaces the entire attribute list (no partial updates)
• Attributes increase account size and rent cost
• DAS indexes attributes for fast queries

Quick Reference

Minimum Code

import { addPlugin } from '@metaplex-foundation/mpl-core'
await addPlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'level', value: '5' },
      { key: 'class', value: 'warrior' },
    ],
  },
}).sendAndConfirm(umi)

Common Attribute Patterns

FAQ

What's the difference between on-chain attributes and off-chain metadata attributes?

On-chain attributes (this plugin) are stored on Solana and readable by programs. Off-chain attributes (in JSON at URI) are stored on Arweave/IPFS and only readable by clients.

Can on-chain programs read these attributes?

Yes. Use CPI to fetch the Asset account and deserialize the Attributes plugin data.

Are attributes indexed by DAS?

Yes. DAS automatically indexes attribute key-value pairs for fast queries.

Can I store numbers or booleans?

Values are strings only. Convert as needed: { key: 'level', value: '5' }, { key: 'active', value: 'true' }.

How do I update a single attribute?

You can't update individual attributes. Fetch the current list, modify it, and update with the full new list.

What's the size limit for attributes?

There's no hard limit, but larger attribute lists increase rent cost. Keep data concise.

Can the owner update attributes?

No. The Attributes plugin is Authority Managed, so only the update authority can modify it (not the owner).

Related Plugins

• Update Delegate - Grant others permission to update attributes
• ImmutableMetadata - Lock name/URI (attributes remain mutable)
• AddBlocker - Prevent adding new plugins

Glossary