Skip to main content

​
Metadata labeling

Metadata labeling allows you to add custom labels to your wallets, accounts, addresses, and transaction outputs. These labels can be synchronized across devices using encrypted cloud storage, making it easy to organize and track your cryptocurrency holdings.
In the Trezor Suite interface, this feature is called “Labeling”. Technically, it’s implemented as an encrypted metadata system.

​
What is metadata?

Metadata is persistent data associated with your cryptocurrency wallets and transactions. It includes:
  • Wallet labels: Custom names for your wallets (including hidden wallets)
  • Account labels: Names for individual accounts
  • Address labels: Labels for receiving addresses
  • Output labels: Labels for transaction outputs (UTXOs)
All metadata is encrypted using AES-256-GCM before being stored in the cloud. Only your Trezor device can decrypt it.

​
Storage providers

Suite supports three storage providers for metadata synchronization:
Platform: All (Desktop, Web)Authentication: OAuth 2.0Features:
  • Permanent login (refresh token)
  • Automatic sync
  • Large storage capacity
Best for: Users who prefer Dropbox ecosystem
Google Drive on web requires re-authentication every hour due to security restrictions. For permanent login, use Suite Desktop.

​
Setting up metadata

1

Enable labeling

Navigate to Settings → Application and find the Labeling section.
2

Choose provider

Click Connect and select your preferred storage provider:
  • Dropbox
  • Google Drive
  • Local filesystem (desktop only)
3

Authorize access

Follow the OAuth flow to grant Suite access to your cloud storage. Suite only creates and accesses its own folder.
4

Generate encryption key

Your Trezor device generates a master encryption key. Confirm the operation on your device.
The encryption key is derived from your device using predefined constants. It’s unique to your device and seed.
5

Start labeling

Once connected, you can add labels throughout Suite. They’re automatically encrypted and synced.

​
Using labels

​
Where to add labels

Location: Wallet selection modalHow to add:
  1. Click wallet name in top navigation
  2. Hover over wallet and click edit icon
  3. Enter wallet label
Best practices: Use descriptive names like “Savings”, “Trading”, “Business”
Location: Account headerHow to add:
  1. Navigate to account
  2. Click edit icon next to account name
  3. Enter account label
Best practices: Describe the account purpose like “Emergency Fund”, “DCA Account”
Location: Receive tabHow to add:
  1. Go to Receive tab
  2. Click edit icon next to address
  3. Enter address label
Best practices: Note the source like “Coinbase Deposit”, “Salary March 2024”
Location: Send form, transaction history, coin controlHow to add:
  1. In send form: Label recipient as you send
  2. In transaction history: Edit outputs after transaction
  3. In coin control: Label individual UTXOs
Best practices: Describe the payment purpose like “Rent Payment”, “Purchase from Store X”

​
Label display behavior

In transaction history, Suite intelligently displays labels:
1

Check output label

If the output has a label, display it instead of the address.
2

Check address label

If the receiving address has a label, display the address label.
3

Check self-transfer

If the address belongs to the same account, display “Sent to myself”.
4

Check other accounts

If the address belongs to another discovered account or wallet, display that account’s label and wallet label.
5

Fallback to address

If none of the above, display the plain address.
Hover over a label in transaction history to see the actual address underneath.

​
Data structure

​
Current version (1.0.0)

Metadata is stored in encrypted JSON files:

​
Device metadata

{
  "version": "1.0.0",
  "walletLabel": "my hidden wallet label"
}

​
Account metadata

{
  "version": "1.0.0",
  "accountLabel": "my cool account label",
  "outputLabels": {
    "9f472739fa7034dfb9736fa4d98915f2e8ddf70a86ee5e0a9ac0634f8c1d0007": {
      "0": "transaction 1"
    }
  },
  "addressLabels": {
    "bc1qannfxke2tfd4l7vhepehpvt05y83v3qsf6nfkk": "my cool address label"
  }
}

​
Future version (2.0.0)

Planned improvements include timestamps for conflict resolution: 
{
  "version": "2.0.0",
  "accountLabel": {
    "value": "Updated label",
    "timestamp": 1678901234
  },
  "outputLabels": {
    "txid": {
      "0": {
        "value": "Payment to Bob",
        "timestamp": 1678901234
      }
    }
  }
}
Version 2.0.0 is not yet implemented but planned for future releases.

​
Encryption details

Metadata security is based on strong encryption:

​
Encryption algorithm

  • Cipher: AES-256-GCM
  • Key derivation: Device-specific master key
  • Authentication: Built-in with GCM mode

​
Key generation

// Simplified key generation flow
const generateMetadataKey = async (device: TrezorDevice) => {
  // Device generates master key using internal seed
  const masterKey = await TrezorConnect.cipherKeyValue({
    device,
    key: 'Enable labeling?',
    value: Buffer.from(METADATA_LABELING_KEY).toString('hex'),
    encrypt: true,
    askOnEncrypt: true,
    askOnDecrypt: false,
  });
  
  return masterKey;
};

​
File encryption process

1

Generate metadata

Suite creates a JSON object with labels.
2

Encrypt

Data is encrypted using AES-256-GCM with the device-derived key.
3

Upload

Encrypted data is uploaded to the cloud provider.
4

Download & decrypt

On other devices, Suite downloads and your Trezor decrypts the data.
Cloud providers cannot read your metadata. Only your Trezor device with the correct seed can decrypt it.

​
Redux state structure

Metadata state is managed in Redux: 
// Settings state
interface MetadataState {
  enabled: boolean;
  initiating: boolean;
  provider: {
    isCloud: boolean;
    type: 'dropbox' | 'google' | 'fileSystem';
    tokens: {
      accessToken?: string;
      refreshToken?: string;
    };
    user: string; // Provider username/email
  };
}

// Device metadata
interface DeviceMetadata {
  status: 'disabled' | 'enabled' | 'cancelled';
  key: string;      // Encryption key
  fileName: string; // Storage file name
  aesKey: string;   // AES encryption key
  walletLabel: string;
}

// Account metadata
interface AccountMetadata {
  key: string;      // Account public key (xpub)
  fileName: string; // Storage file name
  aesKey: string;   // AES encryption key
  outputLabels: {
    [txid: string]: {
      [outputIndex: number]: string;
    };
  };
  addressLabels: {
    [address: string]: string;
  };
  accountLabel: string;
}

​
Metadata lifecycle

​
First-time user

1

Initial state

User opens Suite. Metadata is disabled. “Add label” buttons appear on hover.
2

First label attempt

User clicks “Add label” button.
3

Key generation

Device generates metadata master key. Account metadata keys are derived from master key.
4

Provider selection

Modal opens with provider options. User connects to Dropbox, Google Drive, or local filesystem.
5

Sync initialization

Suite fetches existing data (if any) and starts periodic sync.
6

Label activated

The input field becomes editable and the label is saved.

​
During account discovery

Metadata key generation is integrated with discovery:
  • Standard wallet: Device metadata key generated before discovery starts
  • Hidden wallet: Key generated after first non-empty account is found OR after passphrase confirmation
This optimization prevents unnecessary device confirmations when discovering empty wallets.

​
Managing metadata

​
Disconnecting provider

To disconnect a cloud provider:
  1. Go to Settings → Application → Labeling
  2. Click Disconnect
  3. This removes metadata values but keeps encryption keys
  4. You can reconnect later without regenerating keys

​
Disabling metadata entirely

To completely disable metadata:
  1. Go to Settings → Application → Labeling
  2. Toggle the switch to Off
  3. This:
    • Removes all metadata from devices and accounts
    • Removes encryption keys
    • Disconnects from provider
Disabling metadata permanently removes all labels from Suite. The encrypted files remain in cloud storage but become inaccessible without regenerating keys.

​
Troubleshooting

Check:
  • Provider connection status
  • Internet connectivity
  • Storage provider permissions
Solutions:
  • Disconnect and reconnect provider
  • Verify provider authorization hasn’t expired
  • Check Suite logs for sync errors
Cause: Metadata keys are regenerated after device recoverySolution:
  1. Recover device with same seed
  2. Reconnect metadata provider
  3. Labels should restore automatically
As long as you recover with the same seed, metadata keys will be identical.
Web only: This is expected behavior due to security restrictionsSolution:
  • Use Suite Desktop for permanent login
  • Or re-authenticate every hour on web
Device name is not part of metadata. It’s stored locally in device settings and doesn’t sync across Suite installations.

​
Best practices

Use descriptive labels that will make sense months later
Label addresses immediately when generating them
Enable metadata before creating multiple accounts
Regularly check provider connection status
Keep backup of recovery seed to ensure metadata access

Wallet management

Managing wallets and wallet labels

Transactions

How labels appear in transaction history

Send and receive

Labeling addresses while sending and receiving

Application settings

Configure metadata and other app settings

Build docs developers (and LLMs) love

Get started for freeTalk to us