Stellar Memo Convention

[jedmccaleb]

Motivation

Often you need to include more info with a transaction than will fit into the 32 bytes available for memos in a Stellar transaction. You can do this by including the just the hash of the longer message in the Stellar transaction using MEMO_HASH and then providing some way for recipients to retrieve the preimage of the hash. See message server.

Memos are used for things like:

• further credit to a given recipient
• transfer KYC info
• User and use case specific things

Although you can technically put anything in the hash preimage, these messages are intended to be understood by other clients. Therefore it is helpful to follow the Stellar Memo Convention.

Stellar Memo Convention

Memos are in JSON format. They are parsed in two passes. The first pass decrypts the encrypted parts of the memo. This pass generates a new JSON object that can then be parsed by the application.

First pass

Fields with $str_ are reserved.
encrypt_v1 is https://download.libsodium.org/doc/public-key_cryptography/sealed_boxes.html
Any JSON field can have either a normal JSON value or an encrypted object of this format:

field	description
$str_type	Currently only encrypt_v1 is supported.
$str_for	(optional) hint of what public encryption key can decrypt this message.
$str_value	The encrypted message in base64.

{
      "$str_type": "encrypt_v1",
      "$str_for": "G56789",
      "$str_value": "AAAAZ2VsbG8="
}

When an encrypted object is found the $str_value field is decrypted and the JSON is changed to just the decrypted value.

Examples

empty:
  packed: 
    {}
  unpacked: 
    {}

no_blocks:
  packed: 
    {"foo": 1234 }
  unpacked: 
    {"foo": 1234 }

top_encrypted:
  packed: 
    {
       "$str_type": "encrypt_v1",
      "$str_for": "G56789",
      "$str_value": "AAAAZ2VsbG8="
    }
  unpacked: 
    {"foo": 1234 }

child_encrypted:
  packed: 
    {
      "foo": {
          "$str_type": "encrypt_v1",
          "$str_for": "G56789",
          "$str_value": "AAAAZ2VsbG8="
      }
    }
  unpacked: 
    {"foo": 1234 }
arrays:
  packed: 
    {
      "foo": [
        "simple",
        {
         "$str_type": "encrypt_v1",
          "$str_for": "G56789",
          "$str_value": "AAAAZ2VsbG8="
        }
      ]
    }
  unpacked: 
    {"foo": ["simple", 1234] }

Second Pass

After the JSON is decrypted it can be sent to the application for further processing. The following are common fields but applications are free to use their own

field	description
operations[]	Array of info specific to each operation.
note	Arbitrary text attached to this transaction or operation intended to be displayed to the recipient.
sender_info	Compliance info for the sender. See below.
route	Gateway specific routing info for the recipient. (accountID, or username, etc)

Sender info

field	description
name	Full name of sender
address	Mailing address of sender
stellar	Payment address of sender (bob*kraken.com)
DOB	Date of Birth

Examples

Simple route with message

{
    "note": "Hey thanks for all the Kelp."
    "route": "6387622"
}

Half-Encrypted message

{ 
    "note" : "You can read this but there is secret stuff below."
    "route": {
            $str_type: "encrypt_v1",
            value: E( "127682" )
        }
}

Transaction with 3 payments that each need route info and two of the routes are encrypted.

{
    operations: [{

            "route": "bob"
        }, {
            "route": "127682"
        }, {
            $str_type: "encrypt_v1",
            value: E("route : 127682")
        }
    }]

}

[jedmccaleb]

Someone needs to turn this into a SEP