Custom Tokens should emit a mint event when the token is minted

[chowbao]

Preamble

SEP: To Be Assigned
Title: Custom Token Mint Event
Author: Simon Chow <@chowbao>
Track: Standard
Status: Draft
Created: 2024-12-5
Updated: 2024-12-5
Version: 0.0.1
Discussion: <TBD>

Simple Summary

Custom smart contract tokens should be required to send a mint contract event when the new token is minted/initialized. Same as the SAC token minting.

Dependencies

Related to

• CAP-46-06
• SEP-41

Motivation

Currently custom smart contract tokens have a token interface defined in SEP-41. This interface defines the standard for functions such as transferring and burning the token but does not define a function nor set a standard for minting the token. There is currently no requirement to emit the mint event like how SACs do. This means that a contract can create a token without a definitive "source" contract event. Without this event it becomes difficult to track the full history of the custom tokens movement as well as the initial amount of the token.

The only events required are transfer and burn from SEP-41

contract: asset, topics: ["transfer", from:Address, to:Address, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["burn", from:Address, sep0011_asset:String], data: amount:i128

Without the mint event there would be no guaranteed way to know the initial balance of the minted token in the address

contract: asset, topics: ["mint", admin:Address, to:Address, sep0011_asset:String], data: amount:i128

It is possible to look up the to:Address through the contract data entries but it is not guaranteed that entry amount without invoking the balance() function. This is problematic because balance() may have never been called and the way the balance is stored in the contract data entry is not standardized.

With the mint event it is easy to track the full history of custom token balances from inception. This would be similar to how Ethereum ERC20 balances are tracked with traces (Dune's balance calculation methodology).

The end goal is to have a history of events like so:

contract: asset, topics: ["mint", admin:AdminAddress, to:Address1, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["transfer", from:Address1, to:Address2, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["burn", from:Address1, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["transfer", from:Address1, to:Address3, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["transfer", from:Address1, to:Address4, sep0011_asset:String], data: amount:i128
...

With these events you can clearly track the custom token balance for Address1, Address2, Address3, and Address4.

Abstract

Enable balance tracking of smart contract custom tokens through contract events by requiring mint events on custom token mint wherever the contract decides to do the minting (this SEP does not define a new interface function for minting).

Specification

The mint event is unchanged and follows the same format as currently defined:

contract: asset, topics: ["mint", admin:Address, to:Address, sep0011_asset:String], data: amount:i128

The mint event must be emitted when the custom token is minted/initialized. Similarly to how the mint() function from cap-46-06 emits the event

Design Rationale

This SEP has purposely not added an mint() nor init_asset() function to give contracts more flexibility. The theory is that a contract should be free to define how they want to mint a new custom token. There doesn't need to be an standard single initialization function. There are existing contracts that have an initialize() function that does emit the mint event. By not adding a minting function to the interface, these existing contracts with be compliant with this SEP without changes.

Alternatively this SEP can propose a mint() or some initialization function. Or this can be proposed in a future SEP when a clear need is found.

Security Concerns

N/A

Changelog

• v0.1.0: Initial draft.

[chowbao]

Should we define a new mint() function for the custom token interface?

Currently the SEP proposes we only require the mint event without defining a mint() function

[sreuland]

does 'custom token interface' infer TokenInterface? That has some docs which mention intentionally avoiding themint function and deferring it to StellarAssetInterface which also includes clawback, and is an optional interface which a custom token could choose to implement and thereby emit the desired event.

Do you know if existing event requirements which are mentioned on the other method docs on TokenInterface are enforced during invocation by Soroban? i.e. if a custom token contract transfer implementation doesn't emit an event, will that be detected?

[chowbao]

does 'custom token interface' infer TokenInterface?

Yes I believe it infers the TokenInterface as also defined in SEP-41.

Yes the mint() or initialization function can be outside the TokenInterface. StellarAssetInterface is for SACs and I don't believe is a sep requiring the usage of that interface for non SAC custom tokens. That's why I felt generally it'd be better to propose non SAC custom tokens just requiring a mint contract event instead of a specific new interface function.

Regarding clawback events, I wanted to propose in a separate SEP to lower the scope and friction of agreeing on mint events first.

Do you know if existing event requirements which are mentioned on the other method docs on TokenInterface are enforced during invocation by Soroban? i.e. if a custom token contract transfer implementation doesn't emit an event, will that be detected?

I don't know. I would guess not because I don't think SEPs do any enforcement and I don't know how the ecosystem currently checks for SEP compliance

[sreuland]

in that case of any events being best effort/optional from non-SAC token contracts, adding mint event doesn't further guarantee downstream consumers can rely on a single consistent sequenced representation of token movements, since they could be skipping other events like transfer/burn, etc. It appears like downstream consumers need to know specifics per each custom token contract eventing behavior to parse their respective token movements, and for SAC can rely on TokenInterface and StellarAssetInterface events.

[leighmcculloch]

The only events required are transfer and burn from SEP-41

contract: asset, topics: ["transfer", from:Address, to:Address, sep0011_asset:String], data: amount:i128
contract: asset, topics: ["burn", from:Address, sep0011_asset:String], data: amount:i128

In the proposal it states that SEP-41 Tokens include a sep0011_asset:String, however that is not part of SEP-41, but is a bespoke part of CAP-46-6 that is specific to SAC tokens.

I think this proposal should remove the sep0011_asset from what's required in the mint function. The SAC may add additional Stellar Asset specific details to the mint function as it does today, but tokens shouldn't be required to provide it just as they are not required to provide it for transfer and burn events.

[chowbao]

That sounds reasonable. Is it preferred for me to update that in the proposal above (sep0011_asset --> asset)? But would that lose versioning history because this is a discussion and not a PR

[leighmcculloch]

I think the field can be removed rather than renamed.

[chowbao]

After doing some research I've found that all non SAC custom tokens currently do emit the mint event when a token is minted/initialized. It would be better suited to updating SEP-41 rather than creating a new SEP at this time.

PR updating SEP-41

[dmkozh]

SEP-41 purposefully doesn't specify the admin interface. Adding the mint event to it is currently meaningless, as it doesn't define the mint function in the first place.

If we want to go for the admin-driven interface, it should probably be specified in a new SEP, with all the functions and events. That said, please do keep in mind that not every token can/will implement it - e.g. a token can be minted automatically based on certain conditions (e.g. mint NFT once on initialization), or require a quorum of admins to mint it etc. This is the reason for why minting is not a part of SEP-41.

In the hindsight it seems like it might have been better to not have admin in the mint event at all. That would make it compatible with pretty much any minting procedure. But I'm not sure if we can fix this now.

[chowbao]

That's fair. It was recommended to me to update the original SEP rather than creating a new SEP. IMO a new SEP would have made more sense instead of updating a finalized and active SEP but because all current SEP-41 compliant custom tokens emit the mint event it seemed reasonable to update in place.

This is more a process issue than idea issue. To confirm are you in favor of the mint event though?

[dmkozh]

Sure, if there is a standardized interface, it makes sense to have a standardized event. We also can be a bit more creative and define a SEP for the 'admin' action semantics and the corresponding events, without specifying the exact admin interface. This way we can standardize the mint and clawback events without restricting the admin interface. We'd need to drop the admin from them in that case, or at least make it optional.

[sreuland]

If the mint event is included as a recommended standard event for token contract and regardless of whether it has a corresponding token interface method..does it seem worthwhile to start thinking about more deterministic event cataloging which is not related to interfaces, how will off-chain apps understand what events a contract is capable and therefore know its event stream can be parsed reliably to a SEP compliance level such as SEP-41?

Is it worthwhile to spin up a discussion on extending language of CAP-0046-08 to allow contracts to assert their event publishing profile, by registering event names they intend to publish(and unregister), perhaps a new host fn like contract_register_events which could be used during contract lifecycle, constructor or later, and stored/retrieved as an scvec attrib in contract code or data ledger entry. Then apps could query deployed contract for its list of events and if intersects with all event names required by higher level spec/protocols like a SEP-41, then app knows it can reliably parse events from contract as that type.

[leighmcculloch]

I agree that the mint function is an admin functionality in the Stellar Access Contract, and it's admin functionality I don't think we have sufficient evidence needs standardizing.

However, I think the mint event is not admin functionality. The mint event is critical to understanding user balances. It should be emitted by SEP-41 tokens because systems should be able to signal when new tokens are received by an account without having existed anywhere else. Without the mint event it is impossible to truly measure balances via events, unless all mints happen into some distribution account first then get transferred.

It's a similar problem that @MonsieurNicolas highlighted about clawback events here: https://stellarfoundation.slack.com/archives/C02B04RMK/p1733531292589449?thread_ts=1733502333.026599&cid=C02B04RMK.

As @chowbao points out, most contracts are already emitting mint events anyway.

[leighmcculloch]

I'm good with removing the admin from the mint event in this case.

I think it's critical the admin Address is not emitted in the mint event for SEP-41.

The fact that CAP-46-6 emits the admin address in the mint event is unnecessary, and unfortunate, and I think worth breaking in a protocol change to remove so that it can be consistent with SEP-41.

cc @sisuresh @MonsieurNicolas

[orbitlens]

StellarExpert currently supports mint event alongside with transfer and burn for token balances tracking for custom token contracts, but only if they were generated by calling a contract function that adheres to the reference conventional token implementation. E.g. mint should be generated by the function mint matching the reference func signature. We have to match the generated event with the function signature and match arguments as well. So, for example, if a call mint('G..', 1000) generates event [mint, 2000] -- we ignore this because the "minted" amount doesn't match the amount provided in the argument.

We tried rely purely on events for balances calculation, but it proved to be a bad idea -- people tend to generate whatever events they like, disregarding the internal logic. This leads to negative balances or some impossible numbers, not fitting into u256.

[leighmcculloch]

Could you share examples of mainnet deployed token implementations that are emitting incorrect events for minting, transferring, or burning?

This problem may have been exacerbated by the fact that SEP-41 didn't document the mint event (or clawback event).

This proposal explicitly leaves out the mint function because contracts may mint other ways.

Do you think once the mint event is standardised it would be possible to rely more on events, like how Ethereum products do, and not the function calls? Or do you think explorers will always need to track via functions too?

Do you think it'd be realistic to use simulation to get balances in real time? Simulation is how wallets are getting balances (e.g. Freighter) and mean that wallets display the correct balance for tokens with calculated balances that can't be tracked by data, or maybe even not events.

[orbitlens]

Here are few contracts that mess up with balances, resulting in negative balances (according to our event tracking logic):

• CAVK...NMOZ
• Comet pool

Do you think once the mint event is standardised it would be possible to rely more on events, like how Ethereum products do, and not the function calls?

We tried and it didn't work for us for the reasons I described above. But if people come up with the ecosystem standard for all events for custom tokens, we'll update our parsing logic accordingly to the standard, so our implementation will match it exactly.

Do you think it'd be realistic to use simulation to get balances in real time?

For cline-side apps fetching current balances -- yes, don't see any problems with this. For server-side apps that potentially deal with huge amount of data it might be difficult. For example, we cannot afford making async calls to RPC during ingestion due to the significant amount of data we need to process every few seconds. And it's not always possible for historical data as there is no guarantees that currently deployed contract has the same WASM code as the contract at the time of transaction execution (let's say a month ago).

[chowbao]

We tried and it didn't work for us for the reasons I described above. But if people come up with the ecosystem standard for all events for custom tokens, we'll update our parsing logic accordingly to the standard, so our implementation will match it exactly.

+1 hopefully adding all types of contract events and clear definitions of when they are supposed to be emitted will allow everyone to use the same standard for tracking balances.

And it's not always possible for historical data

+1 balance() has no historical context. Contract events should be the de facto only way to get historical balances accurately

[sydneynotthecity]

Do you think once the mint event is standardised it would be possible to rely more on events, like how Ethereum products do, and not the function calls?

I think this highlights why we need to get this standardization right and can validate that account balances reproduced from events match the expected balance. Like @orbitlens said, if parsing events match exactly, we can tell the ecosystem events are the source of truth for balances, and this will decrease the risk of different data providers reporting different balances, which we are seeing in our providers today. We track balances via contract_data entries, so we don't even align with Stellar Expert, which is not good for reconciliation and verifiability.

[sreuland]

We tried rely purely on events for balances calculation, but it proved to be a bad idea -- people tend to generate whatever events they like, disregarding the internal logic.

that is a good insight on current day challenge for downstream ingestion to accurately process contract events, as downstream ingestion depends on contracts adhering to the larger expected event lifecycle of an app protocol, otherwise the events are less valuable.

But if people come up with the ecosystem standard for all events for custom tokens, we'll update our parsing logic accordingly to the standard, so our implementation will match it exactly.

As contract growth takes place, more of these events are coming, exacerbating the challenge for application ingestion to understand how to parse them accurately. There is a separate CAP discussion #1596, would be great if you have chance to review/share insights further. It is exploring ideas for how contract code can assert the app protocol(s) it implements by Specing a catalog of the events, functions, and protocols it supports, the outcome being that it drives contract authors a bit further to make sure the implementation(including events) matches the protocol catalog and in tandem, downstream ingestion could be able to leverage this catalog to dynamically determine if it can parse events from a specific contract per an app protocol.

[chowbao]

I agree that there should be a catalog (or whatever we end up calling it) but I will say that no matter what events are added for a protocol that the 4 events (transfer, mint, burn, clawback) must be present and used for any balance movement.

If I'm interpreting your message correctly I would say that yes a protocol can define and list their events and how they should be used but we would need to make it clear that they should emit a mint event along with a my_custom_created_token event if they chose to define a new event

[chowbao]

It seems like the discussion has slowed down.

Are we in favor of adding a mint event requirement to SEP-41?
This does NOT define a mint() function but rather requires the SEP-41 compliant contracts to emit a mint event whenever a token is minted

contract: asset, topics: ["mint", to:Address], data: amount:i128

[janewang]

mint event should be a part of SEP-41.

Each token standard should define its own set of events. If SEP-41 doesn't have an event w.r.t. mint, then it seems like a gap in SEP-41. That mint event should be described or added in SEP-41.