Support onchain transaction references with your agent built with XMTP

This package provides an XMTP content type to support onchain transaction references. It is a reference to an onchain transaction sent as a message. This content type facilitates sharing transaction hashes or IDs, thereby providing a direct link to onchain activities. Transaction references serve to display transaction details, facilitating the sharing of onchain activities, such as token transfers, between users.

For an example of an agent that implements the transaction reference content type, see the Transaction example in the xmtp-agent-examples repo.

Install the package

npm

npm i @xmtp/content-type-transaction-reference

Configure the content type

After importing the package, you can register the codec.

Node

import {
  ContentTypeTransactionReference,
  TransactionReferenceCodec,
} from "@xmtp/content-type-transaction-reference";
// Create the XMTP client
const xmtp = await Client.create(signer, {
  env: "dev",
  codecs: [new TransactionReferenceCodec()],
});

Send a transaction reference

With XMTP, a transaction reference is represented as an object with the following keys:

Node

const transactionReference: TransactionReference = {
  /**
   * Optional namespace for the networkId
   */
  namespace: "eip155",
  /**
   * The networkId for the transaction, in decimal or hexadecimal format
   */
  networkId: 1;
  /**
   * The transaction hash
   */
  reference: "0x123...abc";
  /**
   * Optional metadata object
   */
  metadata: {
    transactionType: "transfer",
    currency: "USDC",
    amount: 100000, // In integer format, this represents 1 USDC (100000/10^6)
    decimals: 6, // Specifies that the currency uses 6 decimal places
    fromAddress: "0x456...def",
    toAddress: "0x789...ghi"
  };
};

Once you have a transaction reference, you can send it as part of your conversation:

Node

await conversation.messages.send(transactionReference, {
  contentType: ContentTypeTransactionReference,
});

Receive a transaction reference

To receive and process a transaction reference, you can use the following code samples.

Node

// Assume `loadLastMessage` is a thing you have
const message: DecodedMessage = await loadLastMessage();
 
if (!message.contentType.sameAs(ContentTypeTransactionReference)) {
  // Handle non-transaction reference message
  return;
}
 
const transactionRef: TransactionReference = message.content;
// Process the transaction reference here

Display the transaction reference

Displaying a transaction reference typically involves rendering details such as the transaction hash, network ID, and any relevant metadata. Because the exact UI representation can vary based on an app's design, you might want to fetch onchain data before showing it to the user.