Memo Format for User Agents

[jonathanlei]

Memo Format for User Agents

Purpose and Scope

The purpose of this standard is to define a format for on-chain analytics information on XRP Ledger transactions. The memo field can be used for various applications, including but not limited to adding on-chain analytics information for a transaction. This standard is intended to be used by client libraries (and other user agents) across various applications.

This document covers the general format for memos and includes a specific subsection for the fundWallet function in client libraries for Testnet transactions.

Data Structure and Format

The memo object should be an object with the following properties:

• data: An optional string that represents the data.
• type: A required string that represents the user agent or client (i.e. application name and version number).
• format: An optional string that represents the format of the data.

The type field should follow existing standards for user agent identification. The type field should specify the identification data.

The format field, if present, should follow the format of standard MIME types.

Example Template

{
  "data": "Some data",
  "type": "Application Name/Version Number",
  "format": "text/plain"
}

Specific Example

{
  "data": "fundWallet",
  "type": "xrpl.js/2.8.0-beta.1",
  "format": "text/plain"
}

Validation Rules

To ensure that the memo field is consistent with the standard and can be read by compatible software, the following validation rules should be followed:

• The data, type, and format fields, if present, should be strings.
• The data field is optional.
• The format field is optional.
• If the format field is present, it should follow the format of standard MIME types.

Best Practices

To ensure that the memo field is easy to read and consistent across different user agents, the following best practices are recommended:

• All strings should be simple ASCII.
• Use standard formats for the type and format fields.
• Use a concise and descriptive type field.
• Use a standard format for the format field, such as MIME types.
• Use the data field only when necessary.

fundWallet Function (Testnet)

For the fundWallet function used in Testnet transactions from client libraries, the memo field is used to add on-chain analytics information for a transaction. This tracking is only done for Testnet transactions and is not applicable to Mainnet usage.

References

• MIME Types
• Content Types
• Memo Format on xrpl.org
• User Agent Format

[WietseWind]

Isn't this a duplicate of #103?

I added a comment & elaboration in #103 regarding adding user agents to transactions probably being a bad idea (besides a waste of storage space for analytics purposes, to be honest: Full History node operators will have even more data to store for every transaction).

Regarding User Agents with transactions: "application/version" could be a bad idea to use as an example, as including app name and version in Memos could give away extra attack/scam surface: it could help to provide an easy to use attack vector when a user is already identified by r-address.

1. You know how to reach rABCDwhatever123 (account address) per mail / text / ...
2. You know their application based on the memo (if you know the r-address you can see the tx history)
3. You can craft a phising mail in the branding of wallet app from point 2
4. It's extra convincing because that is indeed the client the user is using

TL;DR:

• all full history nodes have to store even more data with every transaction ("no incentive" discussion)
• all users get an extra scam attack vector

[alloynetworks]

Completely against this proposal for exactly the reasons above.

[intelliot]

Isn't this a duplicate of #103?

The proposal was edited to reduce the scope to user agents and analytics, not memos in general.

I added a comment & elaboration in #103 regarding adding user agents to transactions probably being a bad idea (besides a waste of storage space for analytics purposes, to be honest: Full History node operators will have even more data to store for every transaction).

Thank you. This standard will only be used on test networks, such as the Ripple-maintained Testnet and Devnet. Given that the memos will never be used on Mainnet, do you still have concerns?

Regarding User Agents with transactions: "application/version" could be a bad idea to use as an example, as including app name and version in Memos could give away extra attack/scam surface: it could help to provide an easy to use attack vector when a user is already identified by r-address.

Understood.

The goal is to track the sources of Testnet accounts, and break out (distinguish) ones created by client libraries, such as xrpl.js, xrpl-py. As mentioned, it will only be used on test networks.

I'll request for the proposal to be updated to clarify the above.

[WietseWind]

@intelliot

Re: scope: clear, thanks.

Regarding only devnet/testnet: the concern is still relevant, as one can look for the same account being used on mainnet and the same information will apply.

If it's specifically about the origin of the Testnet/Devnet account: why not add a required HTTP Header / POST value to the faucet endpoint, and collect the data there, off ledger?

[intelliot]

Regarding only devnet/testnet: the concern is still relevant, as one can look for the same account being used on mainnet and the same information will apply.

It has always been recommended not to use the same keys on multiple networks. That said, I know it does happen, so your point stands.

If it's specifically about the origin of the Testnet/Devnet account: why not add a required HTTP Header / POST value to the faucet endpoint, and collect the data there, off ledger?

That has been discussed internally; one downside is that the Memo work is already done (without a standard; there are tutorials that create test transactions with analytics memos). On the other hand, there is no pre-existing mechanism or infrastructure for collecting analytics off-ledger. However, from a technical perspective, it is possible - of course.

We'll debate this, and close this Discussion if this proposal isn't necessary.