[SEP-41] Update events to support extensions

[mootz12]

Summary

SEP-41 defines a handful of core token events that downstream services use to index data for tokens in the Stellar ecosystem. Today most of these events emit their data as a bare i128. The transfer and mint events already define an alternate form where the data is a Map with an amount: i128 entry plus an optional to_muxed_id entry.

This proposal generalizes the existing Map data format to all SEP-41 events. Any event may be extended with further keys by other token SEPs or implementations. Consumers must tolerate unknown keys on event data.

The existing data forms remain valid, and event consumers are required to support both the legacy form and the map form.

Why

As the token ecosystem grows, standards might want to emit additional data during events. Currently, for tokens to stay compliant with SEP-41 based indexers, they would need to define and emit additional events. These events will likely contain duplicate data or require downstream systems to match them with the SEP-41 event.

Further, the default data format for events in Soroban is a map. The #[contractevent] macro defaults to data_format = "map", so even a single data field event serializes its data as a Map rather than a bare value. Consider the following event definition:

#[contractevent]
pub struct Burn {
    /// The address from which tokens were burned
    #[topic]
    pub from: Address,
    /// The amount of tokens burned
    pub amount: i128,
}

While this event looks like it conforms to SEP-41, the data section would be a Map instead of an i128. This impacts the current compatibility of SEP-57's event definitions with SEP-41.

SEP-41 consumers already accept both the i128 and Map data forms for the transfer and mint events, so extending that handling to the remaining events should be a small change.

Change

PR: #1947

References

• SEP-41
• SEP-57

[leighmcculloch]

💯 It's time to do this. This idea has come up in past discussions and in every previous discussion the focus has been on keeping the changes minimal. But in hindsight the first time this came up we should have blanket changed the specification to allow contract developers to use maps for any of the event bodies and be extendable.

This has zero impact on chain to any existing contract, but does impact off-chain systems that index on-chain data, and require that they start are tolerant of the two different formats that each event can be represented with. Given that indexers already do this for the most prevalent events, transfer and mint, it seems very reasonable to expect it to be feasible for the other events.

[leighmcculloch]

Reviewing d385931:

In the linked change there is the phrase "original data format" used. Instead of naming the data format "original" can we call it by the name of the data format, which is "single-value" or "vec" depending on the event? "Original" creates a new term to navigate, define, relate to.

For example, say:

Events can be emitted by tokens in two formats, a single-value/vec data format, and a map data format.

[mootz12]

Agree. Fixed here 6ddff4f

[leighmcculloch]

These changes look 👨🏻‍🍳💋.

[marcelosalloum]

Cross-referencing https://github.com/orgs/stellar/discussions/1916 here. Both discussions are essentially the same, but this one goes further in pushing the map format to all events.

[mootz12]

Missed this - apologies for the duplication rather than feedback. Agreed these are very much the same.

I think I prefer taking the extra step to make all events the same. I think there is real concern with users creating contracts that "look" like they implement SEP-41 but don't due to the SDKs default map format.

[marcelosalloum]

I think I prefer taking the extra step to make all events the same. I think there is real concern with users creating contracts that "look" like they implement SEP-41 but don't due to the SDKs default map format.

Agreed!

[marcelosalloum]

In the PR #1947, the trait doc-comments are still showing only the old event formats. @mootz12: can you plz update them similarly to

stellar-protocol/ecosystem/sep-0041.md

Lines 107 to 108 in 6ddff4f

	/// - data - `amount: i128` or `{ amount: i128, to_muxed_id: Option<u64 | String | BytesN<32>> }`
	/// If the transfer involves a muxed address the address and muxed details

[mootz12]

Good catch, fixed here -> cacf287

[marcelosalloum]

Once we're aligned on SEP-41, we'll want to fan this update to SEP-57 as well.

[JakeUrban]

Just to confirm, there is no plan to update the format used for SAC events, right? So realistically applications will only need to update if they support contract tokens that use maps instead of the single-value approach?

[marcelosalloum]

Yup. The SAC format is untouched and still supported in this proposal.

The proposal aims at supporting expandable Maps as a more flexible and customizable event format

[mootz12]

Wanted to add some additional motivation for the change:

soroban-sdk uses maps by default

Most contracts define events using the #[contractevent] struct. By default, even for a single value, this will produce a map. E.g. someone defining Burn as:

/// Event emitted when tokens are burned.
#[contractevent]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Burn {
    #[topic]
    pub from: Address,
    pub amount: i128,
}

will actually not be following this SEP, as the data value is a map with { amount: i128 } not just a raw i128 value.

The update will ensure common patterns like above remain supported.

OpenZeppelin's fungible token library (v0.7.2)

When reviewing the OpenZeppelin funglible token implementation, some events use maps when SEP-41 requires raw values. Given lots of tokens might already be using this, we should ensure they are supported in the SEP.

Mint and Transfer already accept data values due to the earlier SEP-41 update, and the library emits both as data maps.

• Approve
  • Uses a map with amount and live_until_ledger, where the SEP currently expects a Vec ref
• Burn
  • Uses a map with amount, where the SEP currently expects a single i128 value ref

[mootz12]

cc @brozorec or @ozgunozerk - if you have any thoughts on the change to SEP-41 in the PR linked in the discussion.

[brozorec]

Thanks for the ping @mootz12 it looks fine on our end 👍

[leighmcculloch]

The feedback about this change is positive both today and in the past when discussed linked in other comments above, and it aligns SEP-41 document with implementations that have misinterpreted it in ways that make sense are is intuitive. The change is backwards compatible.

Let's merge the attached PR in 7 days, on July 27th, if there is no concerns raised.

[leighmcculloch]

The PR has been merged.

[orbitlens]

Looks nice. We'll add support for this right away to StellarExpert.