Preamble

SEP: 0044
Title: Soroban Token Interface Extension: Memo
Authors: Leigh McCulloch <@leighmcculloch>
Status: Draft
Created: 2024-08-26
Updated: 2024-09-09
Version 0.2.1
Discussion: TBA

Simple Summary

This proposal defines a standard contract interface for tokens that support transfers to an address with an associated memo. The interface is an extension of the SEP-41 token interface.

Motivation

To define an unambiguous method by which contract wallets can transfer to custodial wallets that require a memo to be associated with the transfer that is populated through to events used to track transfers.

Specification

Interface

pub trait TokenExtMemoInterface {
    /// Transfer `amount` from `from` to `to`.
    ///
    /// The memo annotates the transfer event.
    ///
    /// # Arguments
    ///
    /// - `from` - The address holding the balance of tokens which will be
    /// withdrawn from.
    /// - `to` - The address which will receive the transferred tokens.
    /// - `amount` - The amount of tokens to be transferred.
    /// - `memo` - The memo associated with the transfer.
    ///
    /// # Events
    ///
    /// Emits an event with:
    /// - topics - `["transfer", from: Address, to: Address, _: _, memo: u64]`
    /// - data - `amount: i128`
    /// The events fourth topic is undefined. If the contract does not otherwise
    /// emit a value in the fourth topic field, it can emit `()`, the Void Val.
    fn transfer_memo(env: Env, from: Address, to: Address, amount: i128, memo: u64);
}

Events

Transfer Event

The transfer event is emitted much the same as a SEP-41 transfer event when an amount is transferred from one address to another, except that in the case that a memo is specified the invocation becomes an additional topic.

The event has topics:

• Symbol with value "transfer"
• Address the address holding the balance of tokens that was drawn from.
• Address the address that received the tokens.
• _ undefined and contracts should otherwise emit whatever they would normally emit for this field, or () / Void.
• u64 the memo.

The event has data:

• i128 the amount transferred.

Design Rationale

There are a variety of ways that memos could be introduced into either the Stellar protocol or the contract transfer protocol. Adding a new function that accepts the memo parameter is the least ambiguous.

Given that CAP-27 introduced muxed accounts for non-contract operations it is worth noting why support for muxed accounts are not being proposed. Memos, and muxed IDs, primarily exist to support offchain protocols, but adding support for a muxed account or address type to Soroban's Address type would make it extremely easy for existing contracts to store balances against the muxed account instead of the underlying account.

The memo is limited to the u64 type because previous research on the topic when CAP-27 was proposed found that most impactful non-advertising uses of memos were integers, or were compatible with integers. At anytime a future SEP could expand the types suppored by the memo field if that became necessary.

The SEP-41 transfer event is reused and extended rather than a new event introduced because SEP-41 uses the transfer event for all account to account transfers and while possible it seems best to continue to emit the same event in the new case which is really only an annotation. One challenge is that the CAP-46-6 implementation of SEP-41 already extended the transfer event topic list. For this reason the fourth field of the event topic list is assumed present with any value as defined by the token contract or other standards and this proposal leaves it undefined and has no opinion of its type and purpose. The memo is expected in the fifth field.

Changelog

• v0.2.1 - Minor edits to undefine the fourth event topic.
• v0.2.0 - Move memo into fifth event topic field in SEP-44 and CAP-61.
• v0.1.0 - Initial draft.

Implementations

• None