Extend SEP-41 map-form event data to approve, burn, and clawback

[marcelosalloum]

SEP-41 v0.4.1 permits a map-form data payload with implementation-defined extra entries on transfer and mint, but restricts approve, burn, and clawback to scalar or tuple data. This asymmetry blocks real integrations — tokens that need to carry additional implementation-specific context.

This post proposes extending the same map-form pattern to those three events, fully backwards compatible. It follows up on an exchange in PR #1775, where @leighmcculloch and @dmkozh flagged the topic as worth a separate conversation.

Today's shape

Event	data	Map form?
transfer	i128 or Map { amount, to_muxed_id?, ... }	Yes
mint	i128 or Map { amount, to_muxed_id?, ... }	Yes
approve	[i128, u32]	No
burn	i128	No
clawback	i128	No

Motivating use case

Regulated-asset issuers need administrative events to carry extra context — for example, the actor that triggered a clawback or the compliance rule tied to a burn. The workaround today is emitting a parallel custom event per administrative action, which doubles emission cost on-chain and forces downstream indexers to correlate two events where one would do.

Proposal

Allow approve, burn, and clawback data to be either:

• the existing scalar/tuple form (unchanged), or
• a Map with Symbol keys where amount: i128 is required (plus live_until_ledger: u32 for approve), with "other entries allowed as defined by the implementation" — mirroring the language already used for transfer and mint.

Backwards compatibility

Although SAC is unaffected and topics are backwards compatible for emitters, existing off-chain consumers (indexers, wallets, explorers) that only handle the scalar/tuple form will need to be upgraded to process the map form once any custom token starts emitting it. That's the same situation we already accepted for transfer and mint in PR #1775, so it's not a new cost.

References

• SEP-41 v0.4.1
• PR #1775 — muxed address support

Cc @sydneynotthecity

[leighmcculloch]

+1 on extending the map form to approve, burn, and clawback. It's additive, doesn't break any existing on-chain contract, and only affects off-chain consumers, which is a cost they already have to pay for transfer and mint.

It's also worth noting that during CAP-67 we discussed this idea and while no consensus was stated explicitly it felt like there was general consensus with the only concern being the performance implication if everyone moved to maps even in the cases amounts were the only value. A few data points from that discussion:

• In PR CAP-0067 update after 02/27 protocol meeting #1667, @dmkozh raised that the spec should say "either i128 field with transfer amount, or a map that has at least amount(Symbol)->amount_value:i128 KV pair present."
• @sisuresh replied that his intention was for the data field to always be a map, even in the amount-only case (i.e. { amount: i128 } rather than a bare i128).
• @leighmcculloch pushed the same direction: "Emitting a map for all is a way to ensure all downstream systems see this change and aren't surprised by the first time they encounter the edge cases like muxed accounts."
• @dmkozh stated ("I can see some merit to using the map (almost) everywhere as well"), with the tradeoff being emission cost and the fact that consumers would have to handle both forms anyway.
• Later in PR SEP-41: Add muxed address support to token interface #1775, @dmkozh proposed an even more general extensibility model that aligns with this proposal: "Allow any value moving event to have a map field as data, with amount field representing the event amount ... Allow any map contain additional fields, specified either by the future SEP-41 changes, by separate SEPs, or even arbitrarily defined by the custom tokens."
• @leighmcculloch followed up suggesting a separate discussion to make that extensibility explicit across all SEP-41 events: "any event's data can be the single value (if currently defined as so), vec (if currently defined as so), or a map of named elements." This discussion is a good place to resolve that.

So I think the direction is consistent with prior consensus, and this proposal is a narrower, concrete form of it.

One correction on the backwards-compatibility framing:

Existing consumers that read the scalar/tuple form continue to work unchanged.

I don't think this is quite right. Existing on-chain consumers are fine, since no contract logic depends on the shape of event data. SAC is also unaffected since it wouldn't start emitting the map form. But existing off-chain consumers (indexers, wallets, explorers) that only handle the scalar/tuple form will need to be upgraded to process the map form once any custom token starts emitting it. That's the same situation we already accepted for transfer and mint in PR #1775, so it's not a new cost, but it's worth stating accurately.

[marcelosalloum]

existing off-chain consumers (indexers, wallets, explorers) that only handle the scalar/tuple form will need to be upgraded

Thanks for highlighting that. I've updated the proposal mentioning this on the (new) backwards compatibility section

[sydneynotthecity]

+1 on the change itself. I think we should keep approve/burn/transfer symmetric with transfer/mint events.

One orthogonal concern I want to flag here but not derail the thread on: SEP-41 has now accumulated several in-place interface/event changes since its inception (mint/clawback events, MuxedAddress support, etc). As @leighmcculloch mentioned, there is a cost to downstream data providers because they need to upgrade their service to support the new changes. It's becoming hard to track which revision a given deployed contract has targeted, as well as whether the off-chain consumer supports that given revision. A side effect we're seeing is that parsers are falling back to strict whole-interface conformance checks and dropping otherwise-legitimate tokens because one method signature or one event shape doesn't match the current spec.

Contract tokens are gaining popularity, and I think it's time to finalize SEP-41, and figure out better versioning (extend SEP-47) so that off-chain providers have an easier time dispatching changes. I'll open a separate discussion on SEP-41 lifecycle / versioning so we can work that out without blocking this proposal. Will link back once it's up