XIP-21: On-chain transaction reference content type


This content type provides a reference to an on-chain transaction, such as a transaction hash or ID, sent as a message, thereby providing a direct link to on-chain activities.


The goal of the transaction reference content type is to provide transaction details in a message, facilitating the sharing of on-chain activities, such as token transfers, between users.


Content type

  authorityId: "xmtp.org",
  typeId: "transactionReference",
  versionMajor: 1,
  versionMinor: 0,

Transaction reference schema

type TransactionReference = {
   * The namespace for the networkId
  namespace?: string;
   * The networkId for the transaction, in decimal or hexidecimal format
  networkId: number | string;
   * The transaction hash
  reference: string;
   * Optional metadata object
  metadata?: {
    transactionType: string;
    currency: string;
    amount: number;
    decimals: number;
    fromAddress: string;
    toAddress: string;


The networkId provides details of the network used for the transaction, while the reference field contains the hash of the transaction on the network. These two fields should be enough to display a basic reference to the transaction. An optional namespace field can be used for a more human-readable description of the network.

In addition, optional metadata can be added to provide more details and a richer display of the transaction.

Backward Compatibility

To maintain backward compatibility, a content fallback is stored in the codec as text — ensuring that the intent of the transaction reference content type is conveyed even in non-supporting clients.

Test Cases

Test cases will validate the interpretation of schema type and effective use of a content fallback. These are essential for ensuring interoperability across XMTP platforms.

Reference Implementation

You can find a reference implementation of this transaction reference content type in the xmtp-js-content-types repo under the packages/content-type-transaction-reference directory.

Security Considerations

While there are no known negative security implications in the data of the on-chain transaction reference content type, clients could pass inaccurate or misleading values for these fields. In addition, clients could display inaccurate or misleading values for these fields and/or link to unrelated transactions.

All transactions should be confirmed on their respective blockchain.


Copyright and related rights waived via CC0.