Inconsistencies between the SAC and SEP-41

[JakeUrban]

This discussion aims to cover the full scope of inconsistencies between the interface and behavior of Stellar asset contracts (SAC's) and SEP-41, or inconsistencies within their own interfaces, with the intention of identifying resolutions to those inconsistencies.

It is likely that this discussion will result in new discussions that are more narrowly defined. This discussion should be focused on identifying the full set of inconsistencies and the relationships between them, at which point we can continue to discuss interconnected issues here or create separate discussions for inconsistencies that are independent of the others.

The inconsistencies that we've identified through prior discussion are:

1. The SAC's transfer function emits mint events when from is the asset's issuer account, but SEP-41 states that transfer functions should only emit transfer events.
2. The mint function on the SAC does not accept muxed info, but the mint event will emit muxed info
3. The data value for transfer and mint events will be a i128 if muxed info is not provided, and a map if muxed info is provided

All of these pose challenges for developers looking to integrate tokens on Stellar.

1. Developers may understandably not expect mint events to be emitted as a result of transfer invocations if they're only familiar with SEP-41 and not the SAC. Similarly, developers may expect mint events from transfer invocations of contract tokens if they are familiar with the SAC.
2. Developers cannot mint to a muxed address using the mint function. If its possible through the transfer function, I don't see why we'd prohibit doing so in the mint function.
3. Developers may not expect the data value of mint and transfer events to be a map given that the case where data is a i128 is likely to be much more common and was the only possible type before v23 of stellar-core.

[dmkozh]

Re 1:

The SAC's transfer function emits mint events when from is the asset's issuer account, but SEP-41 states that transfer functions should only emit transfer events.

I don't see too many options for addressing this incosistencies besides relaxing the SEP-41 phrasing and basically decoupling the events from the functions. I think this is going to be generally beneficial, as it opens doors for more compatible implementations. I don't see much harm in that for the consumers as well, as consumers are going to consume events, not transactions, so it doesn't really matter which functions produce which events. Are there any other options that I'm missing?

Re 2:

The mint function on the SAC does not accept muxed info, but the mint event will emit muxed info

Sorry for being pedantic here, but SEP-41 does not define the mint function interface so I guess this is rather internal SAC inconsistency and not SEP-41<->SAC inconsistency (beyond point 1, of course). #1775 updates the mint event specification, so at least the consumers have the necessary information to ingest these events. But I'm not sure if the interface inconsistency is particularly problematic.

Developers cannot mint to a muxed address using the mint function. If its possible through the transfer function, I don't see why we'd prohibit doing so in the mint function.

The same argument can be made for transfer_from as well, as it does emit transfer events, but these can't have a muxed destination (unless the token implementation chooses to support it as well, that is). I'd like to come back to my previous point - I think if we decouple events from functions, then we'll remove most of the issues with inconsistencies. Token interface will specify what contract clients and wallets are expected to call. Events will specify when to emit them and how to consume them for the value tracking. This way we don't need to try to reflect all the intricacies of SAC/classic events in the token interface, and we also allow for more flexible token semantics that don't break anyone.

To add some context, the decision to minimize the use of MuxedAddress in token interface has been conscious and is based on the following 2 requirements:

• Support the main use case for the account multiplexing, specifically add a way to make deposits to the custodial wallets.
• Reduce 'leaking' of MuxedAddress into token interface. This is valuable because MuxedAddress isn't really necessary most of the time, besides a specific use case above. We don't want to make every token more complex in several places, even though it's necessary in one specific place.

The second requirement can indeed be challenged. But I'd like to see some strong arguments for it, because so far I haven't seen evidence that muxed destinations are useful elsewhere beyond direct transfers.

Re 3:

I agree this might be a footgun for unaware event consumers. But I'm also not sure if there is a good solution on the SAC/Core side. We could add another optional backfill flag that massages all SAC transfers into the map format, but we can't do the same for the custom tokens. Maybe that's still ok for most of consumers, but I'm generally not a huge fan of adjusting the events post-factum, and this seems like a pretty bad precedent to set.
Maybe there is something we could do on the tooling side, like provide some libraries for parsing the events and abstracting away their internal structure?

[dmkozh]

but needing to send to muxed destinations is not exclusive to transfer use cases.

Would you mind expanding this point, i.e. what are these use cases? Please correct me if I'm wrong, but the exchange deposit operation is pretty narrowly defined.

MuxedAddresses are pretty 'contagious' which is why we wanted to keep them restricted to the use cases that we are certain about. While mint support probably could work (even though it's likely not necessary for SAC, given that distribution accounts are considered the best practice for token issuance), transfer_from change would be really invasive. MuxedAddress would then need to be supported in approve as well and then stored on chain. The last part is the most concerning, because the point of address multiplexing is to add an identifier that is only interpreted off-chain. We don't even allow simply storing multiplexed addresses, as this is likely a programming mistake. Basically, any additional function accepting MuxedAddress comes with a lot of technical complexity and friction. The fact that users could potentially use that, doesn't meant that will, but the complexity cost is very tangible.

Secondarily, the less times we change the interface, the better.

I don't disagree, but mint interface is not a part of SEP-41. If we ever allow SAC to mint to a muxed address via mint function nothing will need to be changed about SEP-41, and event consumers also will not need to make any changes. As for transfer_from, the additional complexity this introduces is very likely to not be worth the potential benefits.

[JakeUrban]

transfer_from change would be really invasive. MuxedAddress would then need to be supported in approve as well and then stored on chain. The last part is the most concerning, because the point of address multiplexing is to add an identifier that is only interpreted off-chain.

Ok, this is definitely a fair argument to not support it for transfer_from.

Would you mind expanding this point, i.e. what are these use cases [for muxed info in mint]? Please correct me if I'm wrong, but the exchange deposit operation is pretty narrowly defined.

Well first, "exchange" should be substituted for "custodian". Any organization that custodies user funds using the omnibus account approach would be relevant here.

But either way, one example could be a token issuer selling their token directly to individuals. If I can buy 1M PYUSD directly from Paxos, I may want that PYUSD sent to my coinbase or anchorage account. Ideally, Paxos could call mint to my muxed address, rather than calling transfer.

[dmkozh]

Well first, "exchange" should be substituted for "custodian".

Sure, I assume the requirements are generally similar.

If I can buy 1M PYUSD directly from Paxos, I may want that PYUSD sent to my coinbase or anchorage account. Ideally, Paxos could call mint to my muxed address, rather than calling transfer.

That's a fair point and I understand that this is a potentially a valid scenario (though them supporting selling directly to custodian accounts might require quite a bit of heavy lifting). However, I would hope that most of the assets that have some (any) value use the best security practices and don't mint tokens to any users besides the distribution account(s) (https://developers.stellar.org/docs/tokens/control-asset-access). I realize this doesn't comprehensively cover every possible case out there and some issuers might not follow the security recommendations, but I think a case can be made that it is more beneficial to adopt for the issuer to adopt the best practice instead of adjusting the token interface.

I don't think SAC mint update is completely out of the question, but I'd like to have some issuer directly requesting this functionality instead of relying on our assumptions about what they might potentially want to do.

[leighmcculloch]

use the best security practices and don't mint tokens to any users besides the distribution account(s) (developers.stellar.org/docs/tokens/control-asset-access)

@JakeUrban Do you know if that practice described in the doc is actually followed? I'm not certain but thought it was only used in cases where having a distribution account is actually useful and in practice institutions do in fact mint directly to consumers, because minting for each user keeps the circulating asset on chain equal to the amount actually being held off chain for consumers.

It does seem feasible and a pretty low-lift low-impact change to make to make minting support a muxed destination, so it does seem like a reasonable ask to put in the queue and prioritise based on institutional need.

[JakeUrban]

@leighmcculloch that is accurate, Circle for example does not have a distribution account and mints directly to customers.

Personally, I don't see the benefit in waiting for an issuer to ask for this if we can already see the possibility of this use case. I'd rather not have to tell a partner they need to wait for the next protocol release for what they're going to assume is already possible.

[leighmcculloch]

Re 1: +1 what @dmkozh said in https://github.com/orgs/stellar/discussions/1776#discussioncomment-14250403.

Events are intended to be emitted for off-chain systems when the event occurs, and don't / shouldn't be tied to specific functions. We included comments about events on the transactions because there is some general expectation that folks implementing a token will probably want to emit the event during those functions. But they might emit additional events, or multiple events, or events at other times and that's fine. Function calls are not designed to be consumed off chain, and integrators should avoid looking at function calls as a way to understand the movement of value. Integrators should use events only.

@JakeUrban Do you see any issue with this approach? What problem are you trying to solve by linking functions to events concretely?

[fazzatti]

+1 On events being agnostic to the underlying functions that emitted them.

Even though on simpler implementations you might see an almost 1:1 relationship between events and the underlying functions, we should expect custom implementations and more complex scenarios as @leighmcculloch mentioned.

I see the purpose of the Events as providing key information about the execution to off-chain observers. As long as you know what to expect by ingesting mint events and can use those to consistently track the increase in supply, it shouldn't matter if it was issued during an explicit mint function call or transfer function call or even a custom one.

As long as the integration of the standard-compliant assets is not affected, it should be fine. On the other hand if this could introduce a common ambiguity that would add friction to integrations, then I would revisit the standard.

It sounds to me that if a use case requires this 1:1 tie between the event and a function, this would be the outlier and therefore a different standard than a common token interface.

[JakeUrban]

I see the rationale and the benefits, but I'm not convinced that we should decouple events from functions. I don't think we can ignore the cause-and-effect relationship between function invocations and events emitted.

For those that call third-party token contracts on behalf of users (ex. dapps), they need to be able to make accurate assumptions in order to offer an acceptable user experience. If my user inputs a swap for 50 TokenA for 10 TokenB, then I as the dapp developer am going to assume that calling transfer(env, user_address, pool_address, 50) is going to result in a debit of 50 TokenA.

If we decouple events from functions, then it makes these kinds of very necessary assumptions impossible to make, and without them, I can't offer an acceptable user experience. Sure, I could add a disclaimer, but then users either don't use my product or still expect me to "fix" these things in practice. Ultimately users will not find this kind of experience acceptable.

Now I recognize the challenge here is that there is no way for contracts or offchain clients to verify if a token implementation adhere's to these assumptions, and that the only thing that is verifiable is the contract's function signatures, but I think we should make a best-effort push to get the ecosystem to adhere. We can do this by offering a different SEP with the same interface but with different assumptions, and then encourage the use of SEP-47 to tell clients the assumptions they should have.

[dmkozh]

I as the dapp developer am going to assume that calling transfer(env, user_address, pool_address, 50) is going to result in a debit of 50 TokenA.

I think we are talking about a bit different things here. The invariant of the transfer function is that value is moved from one address to another, i.e. the spender is credited and the receiver is debited. It is fair for the SEP to require implementation to follow that invariant. But satisfying the invariant doesn't mean that the function should limit the value movements to just what invariant requires, or should limit the implementation details of debits and credits. Two examples here:

• SAC transfer from issuer: the receiver is credited as expected, the sender is credited, but that doesn't result in the spender balance change, which is why mint event is emitted instead of transfer. Dapp assumptions are safe (their contract has received the transfer), while downstream consumers can understand the value movement properly.
• Token that implements some sort of commission, say, for every transfer debit an additional 0.01% of the transfer amount from receiver to some special address. Two transfer events will be emitted in this case: the transfer between the spender and the original receiver, and the commission transfer event from spender to the special address. Dapp assumptions are safe because it still receives its transfer value, and downstream consumers can still understand the value movement and track balances.

Token can easily violate the invariant by emitting a single transfer event with the right amount, but not adjusting the balances properly. This way it will break both dapp, and the downstream consumers. Which is why it's important to respect the invariant, but not necessarily the event mapping.

[JakeUrban]

The invariant of the transfer function is that value is moved from one address to another, i.e. the spender is credited and the receiver is debited.

Where is this invariant defined? If its not defined in the SEP, than I'd argue its not an invariant, or at least not one that clients can safely assume. I'd love to explicitly define invariants for all SEP41 so clients can know what is safe and not safe to assume.

Lets say clients can safely assume that transfer(env, user_address, pool_address, 50) will result in user_address being debited and pool_address being credited, but there are no guarantees other than that. This is still a better situation than the current one, because clients right now could understandably assume more than this, resulting in a poor or even broken UX.

And since the invariants of each function are not currently defined, we should solicit input from the ecosystem before we define these invariants. As a community we could decide to define more invariants than the one you mention.

[dmkozh]

Where is this invariant defined? If its not defined in the SEP, than I'd argue its not an invariant, or at least not one that clients can safely assume. I'd love to explicitly define invariants for all SEP41 so clients can know what is safe and not safe to assume.

I think we're on the same page here - that's poorly specified currently and I'm suggesting to update SEP-41 in such a way that the contract interface defines the invariants (but not the events) and events define the semantics of balance updates (but not the exact functions they should be emitted from). We could of course provide some 'common sense' linking with a caveat that it's not always followed.

As a community we could decide to define more invariants than the one you mention.

Sure, I don't suggest to limit the update to just the transfer, but to all the functions. Hopefully, it shouldn't be too hard and I don't expect anyone breaking these invariants in any reasonable token implementation.

[leighmcculloch]

Re 3: I don't think the inconsistency for consumers is a big concern, especially once SDKs can code generate event parsers. I understand it is a surprise today that the events take several shapes. Once you can generate an event ingestor and you just get given the concrete types you need to handle, I think the issues discussed will be small and mostly insignificant. See #1765 for that initiative. At the very least I think it's worth waiting to see if the issues disappear as a result of that.

I do think there could be value to update the SAC to emit data events for a different reason: to set a good example of how to create extendable events. I understand we went with i128 data to reduce data, but is that data saving worth encouraging others to hyperoptimise by producing a variety of event shapes? If the optimisation is worthwhile for the SAC, then it's worthwhile for everyone.

If we switch to in the future emitting map data, I also don't think we necessarily need to provide a backfill facility. It can just be a from now on thing.

[JakeUrban]

I'm not sure I understand how event parsers make this less of a footgun. They may provide you the types, but for languages that don't require exhaustive case handling it would still be easy not to realize the data value has two different shapes right?

Either way, I agree with you on setting a good example and defaulting to using maps to ensure extensibility.