Proposal for on-chain transaction reference content type

[yash-luna]

[PROPOSAL HAS BEEN UPDATES BASED ON THE LATEST DISCUSSION TO MOVE TOWARDS A GENERIC TRANSACTION REFERENCE CONTENT TYPE]

This is a proposal for on-chain transaction references in the context of chat conversations. A popular use-case is crypto token sends which enable users to easily send crypto inside the context of XMTP conversations without having to copy/paste long hex addresses.

Background

Bringing ease-of-use to referencing on-chain transactions, such as crypto payments, to empower users so they can leverage the trust and context built in conversations to split bills, settle up Splitwise balances, tip creators, or reference transactions for other purposes.

Specification

Proposed content type:

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

The encoded content can use a schema such as:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "transactionReference",
  "description": "XMTP transaction reference content type",
  "type": "object",

  "properties": {

    "namespace": {
      "description": "The namespace for the networkId",
      "type": "string"
    },

    "networkId": {
      "description": "The networkId for the transaction, in {decimal/hexidecimal} format",
      "type": "{integer/string}"
    },

    "reference": {
      "description": "The transaction hash",
      "type": "string"
    }
  },

  "required": ["networkId", "reference"],
}

Presentation

Clients that support transaction references content type SHOULD:

• Only send the message payload with the transactionReference to the network when the transaction has been confirmed. Till then the transaction reference card can be displayed in the message list with an in-progress indicator.
• Clearly display crucial information such as the chain, token, amount, link to a blockchain explorer, other relevant information, and whether the transaction is confirmed
• Surface a warning for if the reference and networkId data indicate that the transaction wasn't between the participants in the chat and that the message sending and receiving addresses match with the sending and receiving addresses for the transaction.

A link to the transaction can be created with the appropriate blockchain explorer using a list such as https://github.com/ethereum-lists/chains.

The details and format of the UI design for the transaction reference cards are client dependent and can take different forms.

[neekolas]

Given that the amount and tokenContract can't be verified on their own, I wonder if we just want to include the txnHash, chainId, and explorerLink (maybe not even that, since it could be an attack vector to include one txnHash and another explorer link). Since recipients are going to have to talk to the blockchain anyways to verify the data, why not just make that the source of truth?

[yash-luna]

I like that. My proposal started out that way but I added the other fields for convenience. Maybe safety trumps convenience here since verifying the info in the contentType with the blockchain explorer is still important.

If we were to only have txnHash and chainId:

• How would an app translate the chainId to a blockchain explorer link to verify the information?
• Is there a handy library or resolver that spits out the official explorer for a given chainId?

[neekolas]

You can build the appropriate link based on data from https://github.com/ethereum-lists/chains.

Would have to double check that the url format of all the block explorers is compatible. They're all heavily inspired by etherscan, so should be OK.

[yash-luna]

Awesome! Updated the discussion based on this chat and added that link as well.

[galligan]

@yash-luna This is a great proposal. I'm excited to see some payments going over XMTP, and this is a solid format to conform to.

When thinking about the UX here, one thing that I'm left feeling is that the fallback might not be as useful as we'd really like. With the current string formatted as:

[Crypto transaction] Use a blockchain explorer to learn more using the transaction hash: ${txSend.txnhash}

…you'd end up with a string that has both the prefix to the txn hash and the hash itself. Even a standard copy/paste (especially on mobile) would make for a lot of steps to go through before you could get to the result in a non-supporting client.

This is where I wonder if fallback text could occasionally be "opinionated" for the sake of a better user experience. Clients would still conform to a general format, but they could include text that might be more helpful to the recipient's experience.

Here's what I'm thinking:

Recommended fallback text for XIP:

[Crypto transaction] Use a blockchain explorer to learn more using the transaction hash: [Raw txn hash or block explorer URL]

Opinionated fallback text using above recommendation:

[Crypto transaction] Use a blockchain explorer to learn more using the transaction hash: https://etherscan.io/tx/0x71c1356016b2a599d713a7ca7303b7765a08f9407d280e80d01f1f58099406f2

In the above example, the client follows the recommended guideline for the fallback text, but chooses to be opinionated for the sake of the target recipient's user experience, including a block explorer URL.

Going further, in the case of a wallet or client app that has its own block explorer, this may be a desirable format.

Further considerations:

• An XIP cannot really mandate fallback text anyway, the best it can do is recommend a format for consistency's sake
• A URL in the fallback may not be ideal, but at the least it would be plaintext and would be harder to phish with, so long as the client is rendering it as-is

Just my $0.02. Would love your thoughts @yash-luna

[yash-luna]

I see how a blockchain explorer link in the fallback would be much nicer UX for clients without payment content type support. However, like you mention, it kinda negates the safety benefits we get from removing the blockchain explorer link - which @neekolas highlights can be an attack/spam vector.

In this tradeoff between safety and slightly better UX, I personally lean towards safety. Especially, considering our primary market and user base today, I envision a world widespread support for payment content type where the nicer UX for fallback text may not be as impactful.

[galligan]

@yash-luna Appreciate the feedback.

There's a key distinction between links in the fallback text, and links within content type…content, which is in how they'd be presented.

In your example, with the blockchain explorer link built into the content type, it's possible the link itself could be obfuscated by the sender, and the receiving client might optimistically render a link without considering that it might be a phishing link. In this particular case, recipient users nor their clients might be able to see when there is a phishing attempt.

A link within the feedback though wouldn't have the same specific risk. While someone could include a fraudulent URL, as it's not hidden behind anything, it's possible that the recipient may be able to recognize it more easily as not being a legitimate link. @neekolas curious how you see this as well.

[trebor-yatska]

Is the primary purpose of this content type to be able to request crypto within a chat? If so, could it have multiple recipients (e.g., I'm requesting 5 USDC from each person in a group chat)?

[galligan]

@trebor-yatska In this case it's basically just a receipt of funds having already been sent, with a confirmed transaction as part of it.

I like what you're thinking about, but requests would have a different set of needs and likely need to be fulfilled by a different content type.

[nakajima]

I sort of feel like "payments" is actually a couple things. Off the top of my head it seems like we should have two different content types for requests and confirmations.

I'm also a bit wary of conflating "payments" with "crypto" payments. It'd be nice to have a system that can accommodate multiple types of payments (but still supports crypto as a first class concept).

Here's sort of what I've been thinking payments could look like:

type PaymentRequest = {
  // A random UUID for matching a request with a confirmation
  requestID: string 

  // The address of the user who should be sending the payment
  payer: string

  // The address of the user who should be receiving the payment
  payee: string

  // The way this payment should be fulfilled (eth, cash app, etc)
  fulfillmentMethod: FulfillmentMethod
}

type PaymentConfirmation = {
  // The requestID of a PaymentRequest if there was one
  requestID: string | undefined;

  // The address of the user who sent the payment
  payer: string;

  // The address of the user who received the payment
  payee: string;

  // The way this payment was fulfilled (eth, cash app, etc)
  fulfillmentMethod: FulfillmentMethod;
}

type FulfillmentMethod = {
  // The name of the method for display in an app
  name: string

  // The amount of the payment
  amount: number

  // The units of the payment (cents, eth, etc)
  units: string

  // Any additional information needed to process the payment
  metadata: { [key: string]: [value: string] }
}

For a concrete example, here's how it'd work for an ETH transaction.

Bob owes Alice 0.1 ETH. Alice sends Bob a PaymentRequest message that looks like this:

const id = randomUUID()
const paymentRequest = {
  requestID: id,
  payer: bob.address,
  payee: alice.address,
  fulfillmentMethod: {
    name: "Crypto Currency",
    amount: 0.1,
    units: "ETH",
  }
}

await aliceConversation.send(paymentRequest, {
  contentType: ContentTypePaymentRequest,
  contentFallback: "Can u send me 0.1 ETH pls"
})

Bob's client sees the PaymentRequest message and understands how to fulfill a "Crypto Currency" payment request so it pops a modal with a payment confirmation screen or bounces to an external wallet app (or does something else). Once that payment goes through, Bob's client can send back a payment confirmation message:

const paymentConfirmation = {
  requestID: requestID, // The request ID sent with the payment request
  payer: bob.address,
  payee: alice.address,
  fulfillmentMethod: {
    name: "Crypto Currency",
    amount: 0.1,
    units: "ETH",
    metadata: {
      transactionHash: "...",
      chainId: 123
    }
  }
}

await bobConversation.send(paymentConfirmation, {
  contentType: ContentTypePaymentConfirmation,
  contentFallback: "I just sent u 0.1 ETH"
})

Fulfillment strategies should be standardized so that their metadata is well defined. This should let clients receiving a payment confirmation do independent verification that the payment was actually received.

This approach gives clients enough information to allow their users to perform payments without being too descriptive about the mechanism by which that gets done.

Thoughts?

[yash-luna]

Thanks for the awesome comment @nakajima! Couple questions:

• Why add payer, payee metadata to this contentType when XMTP messages cryptographically determine who the sender is (and by extension who the receiver is) in 1-1 DMs? It seems redundant and could be a potential attack vector.
• You have a great point about not conflating 'payments' and 'crypto payments'. Based on our conversation last week, I updated the discussion title and content to specify that this is a 'cryptoTokenSend' contentType. To be even more specific, this contentType captures the receipt for token transactions and sends that info in-chat - this limits scope, simplifies the implementation, and minimizes attack vectors. Wondering if we can work on this 'cryptoTokenSend' proposal without increasing scope and start a new discussion (or even discussions perhaps) for other related contentType(s) that support different fulfillment methods as well as payment requests.

[nakajima]

Why add payer, payee metadata to this contentType when XMTP messages cryptographically determine who the sender is (and by extension who the receiver is) in 1-1 DMs? It seems redundant and could be a potential attack vector.

Payer/Payee is different than who is sending the message. If you're requesting payment from me, you would be the sender of the message, but the payer would be me.

Wondering if we can work on this 'cryptoTokenSend' proposal without increasing scope and start a new discussion (or even discussions perhaps) for other related contentType(s) that support different fulfillment methods as well as payment requests.

I think if we renamed this to something like cryptoTokenReceipt that could solve some of my "payment" related concerns, though I do worry a bit about having two different concepts if we decide to introduce a more holistic approach.

[yash-luna]

PaymentConfirmation vs PaymentRequest can determine the direction of transaction without the need for to and from addresses. If I initiate a PaymentConfirmation in our chat, I'm the payer and you're the payee. The opposite is true if I initiate a PaymentRequest.

I'm down to rename to cryptoTokenReceipt to scope this contentType to the most impactful, least risky implementation & use-case combo today. If there is a holistic approach down the line that addresses the potential risks with non-confirmed transactions, apps can support that over this one.

[polmaire]

Sounds like a very exciting proposal @yash-luna !

Here are questions / comments:

1. which kind of token are we talking about? only erc-20? it would be interesting at least to recommend the types of tokens that should be sent because it's not the same in terms of UI for clients. see what i mean?
2. about the fallback: I would also say that security is more important in this case @galligan
3. wondering if non-EVM chains would work with your proposition ; thinking about a potential future where chains like starknet are integrated

thank you!

[galligan]

Wanted to hop in and propose that, along the lines of what @nakajima recommended, this content type might get scoped to just registering an onchain event, specifically a transaction.

Transaction Reference

With the recent launch of Coinbase Wallet messaging, powered by XMTP, they've introduced the concept of a payment that takes place in the context of a conversation. The payment itself is still happening by way of an onchain transaction, and the record of the tx is being displayed in the chat. CBW already supports sending crypto assets via different chains, so not just Ethereum mainnet. For instance, I can send $1 USDC to another address via Polygon, and CBW actually provides the gas for that tx. Here's an example transaction.

But this is where things get a little bit challenging in that not all transfers, certainly not all transactions, are created equal. If you look at the transaction mentioned above you'll see a "From" and a "To". The "From" happens to be my wallet, 0x2b…45ef. The "To" is 0x3e…f9ed but that's the USDC contract on Polygon, not the recipient I was sending USDC to. That can only be seen in the deeper tx log detail, because Coinbase Wallet does some special things with USDC on Polygon, and pays for the gas on behalf of the user.

All of this means that the actual logic of parsing a transaction could actually be a lot of work, and it may be hard to account for the various ways that could be done. But standardizing around a way to have a transaction record type could be really valuable—in the case of Coinbase Wallet they've already got one, it's just not standardized yet.

So it's with that context that I thought I'd contribute a few more resources to the mix. First is EIP-155, which established Chain IDs for EVM networks. Another is CAIP-2 (Chain Agnostic Improvement Proposal) which proposes a human and machine-readable way to identify a chain. The last is Chainlist, which is a resource for identifying the different Network IDs present in the EVM space. All of this is to say that there still isn't a specific consensus or standard convention around how to identify the network/chain IDs alongside a transaction hash. We can try and settle on something that works for us for now, and revise as things solidify.

Currently the proposal above suggests the following format:

{
  chainId: int,
  txnHash: hex
}

chainId is listed as an integer, such as 137, which would designate Polygon mainnet. In some cases a hex is preferred, which would be 0x89 for the same value. It would be useful to clarify which would be better to adopt for this proposal—I just don't have a specific recommendation.

I do like how CAIP-2 also adds the designation eip155 as the prefix for the chain ID as it opens up the namespace to include non-EVM specific examples. While XMTP currently only supports EVM use cases, it might make sense to future-proof this with the eip155 prefix and decide on others later.

One additional consideration is that "chainId" might be better described as "networkId" to better accommodate L2's and other constructs.

With these considerations, what do we think about this update?

Content Type: Transaction Reference

Note the name "transactionReference" which intends to be a bit more literal as to what it is. We could build on this type, to enable specific examples like payment or request, as @nakajima recommends elsewhere.

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

Schema could be:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "transactionReference",
  "description": "XMTP transaction reference content type",
  "type": "object",

  "properties": {

    "namespace": {
      "description": "The namespace for the networkId",
      "type": "string"
    },

    "networkId": {
      "description": "The networkId for the transaction, in {decimal/hexidecimal} format",
      "type": "{integer/string}"
    },

    "reference": {
      "description": "The transaction hash",
      "type": "string"
    }
  },

  "required": ["networkId", "reference"],
}

So, in total the recommendations would be a minor change the proposal from @yash-luna, but it felt worthwhile to add the additional context and explanation.

There is still additional work that will need to go into how best to display these, as none of the reference type describes what's going on with the transaction at all. I'm intentionally leaving that out for now, as it could be added here to this type, or future types that extend from this one.

[yash-luna]

Updated the original post based on your proposed changes @galligan.

What would an example of the schema like for an instance of the content type used for sending tokens similar to the functionality in CBW? Based on that, what could a template for the standard fallback text that can be included in the codec?

[nmalzieu]

The Content Type: "Transaction Reference" proposed by @galligan in the last post looks pretty good.

Currently, Coinbase Wallet uses its own content-type for 2 subtypes of transactions (see doc):

• Regular Payments (token transfers), which could easily be represented by the “Transaction Reference” content type above
• Coinbase Sponsored Payments, which will not be easily represented by the “Transaction Reference” content type above because the message is sent in XMTP before the transaction hash is known.

Coinbase Wallet is ready to move regular payments to the “Transaction Reference” content type above, and Converse would love to integrate it as well, paving the way for future wallets that would integrate XMTP to show transactions in a unified way.

However, it would be useful - and necessary for Coinbase Wallet to keep offering the same level of experience - to add a field to that content type. We could call it metadata and it would be a way for the sending client to give more information on the transaction, specifically while the transaction is still pending

Indeed, while the transaction is pending, there is no way to decode the transaction and see the state changes it produces. During that time, it is nice for clients to have some more information on the intent of the user (for instance, “a USDC transfer on Base”). This would be especially useful on blockchains with a longer block times.

Clients would know to rely on that metadata only while the transaction is still pending, as of course this data could be fake.

This new field would be a key-value dict and wallets & inboxes could agree together on fields they want to put in there.

One example of full content-type could be

{
    "namespace": "eip155",
    "networkId": 8453,
    "reference": "0x2f266433b146661b842f0365828ed22ea6615539830a4ae7bb9e980a2f0c4e77",
    "metadata": {
        "transactionType": "transfer",
        "currency": "USDC",
        "amount": 2,
        "fromAddress": "0xc50e761c35e731d3a475eeb1e30cb917edafe187",
        "toAddress": "0xdeb70b622b32cc3a781bc00910c385cb00574a8a"
    }
}

[nplasterer]

We looked over this as a team today and think it looks good! Just a note that it would be nice to do this in the https://github.com/xmtp/xmtp-js-content-types/ repo so others can easily consume the type as well.

[lourou]

I've just opened a pull request with a proposed implementation of the "Transaction Reference" content type: xmtp/xmtp-js-content-types#50