SACs should emit a balance event

[chowbao]

Proposal

SACs should emit a balance event any time an amount is transferred, created, burned, or clawbacked (any token amount movement).

Changes

Balance Event

The `event` event is emitted when an amount of the token is involved in any movement.

The event has topics:

- `Symbol` with value `"balance"`
- `Address` The address of the emitted balance
- `String` the sep0011_asset

The event has data:

- `i128` the balance amount.

Reasoning

Balances can currently be tracked through the existing events (transfer, mint, burn, and clawback). However to get the current balance (or historical balance) of a token for an address requires the need to know the full eventing history of the asset for that address. It would make downstream systems that only require the current balance at the given ledger/event much simpler if they didn't need to process and track all events and instead just tracked the balance event.

With a new event users can:

• Verify current balances are correct when compared to event history tracking (collection of transfer, mint, burn, clawback balances changes == balance event balance)
• Can choose to ignore transfer, mint, burn, and clawback events in favor of a single balance event
• Can choose to associate the balance event to a transfer, mint, burn, or clawback event as they see fit
• Can ignore the balance event

The balance event should provide more flexibility and theoretically more safety downstream

Alternative

Alternatively, instead of a new balance event, balance can be added to the existing events

[chowbao]

There was a large thread in the unified event discussion that seemed to warrant a separate discussion.

Ultimately it seemed like there was some interest in some kind of balance tracking on top of the existing events whether through a new balance event or adding balance to existing contract events.

cc: @JakeUrban @leighmcculloch @johncanneto

[dmkozh]

However to get the current balance (or historical balance) of a token for an address requires the need to know the full eventing history of the asset for that address.

While that's true, I'm not sure balance events simplify this much. Instead of the full history, one needs to ingest the latest event only, and the latest event may be arbitrarily old (and that's in the world where every balance movement has a corresponding event; that's not the world we'll be in).

Events are hashed into ledger and thus can't be 'backfilled'. Thus even if we were to implement this proposal in protocol N, protocols 20 to N would be missing the balance events, thus you'd need to distinguish between old and new balances. Trustlines make things even more complex, as trustline balances are the SAC balances of G-accounts, but the changes in these balances won't have a respective event, so for trustlines at least protocols 1 to N will be missing the balance events.

I don't think that introducing balance events is a good idea. They would introduce fragmentation into data model and won't generically solve the issue of getting the current balance. Even fragmentation aside, balance events don't seem to be the ultimate solution to the issue of getting the current balance (getters can be used for that). This seems to solve for a very particular setup that ingests all the events, but is also stateless and can't track the current balances off-chain. I'm not sure if this is a common or reasonable setup (also given that most of the blockchain ecosystems seem to do fine without the balance events).

Verify current balances are correct when compared to event history tracking (collection of transfer, mint, burn, clawback balances changes == balance event balance)

This is already possible, is it not?

Can choose to ignore transfer, mint, burn, and clawback events in favor of a single balance event

There won't be a single event, there would be up to 2 events for every respective balance movement (because of 2 parties involved). I'm not sure if that simplifies the things much.

Can choose to associate the balance event to a transfer, mint, burn, or clawback event as they see fit

That's a big footgun and I think it demonstrates why this proposal is not really feasible. There is currently no great way of 'linking' the events together. Leaving the interpretation up to the user is problematic - there should be only one 'correct' way to interpret the events.

[chowbao]

All good points. Some of the above would also apply to the alternative of adding balance to existing events as well

[JakeUrban]

I don't think we should add balance events, primarily because I'm not convinced it reduces complexity for the event consumer. Associating or linking the balance events to corresponding transfer events, in my opinion, is a necessity, and I agree with Dima that we shouldn't leave this to the event consumer to implement.

Thats why I believe if we want to emit balance data in events, we should add a balance value to existing transfer events. However, I'm not convinced this is necessary or worthwhile given the pain of updating contract and event consumer implementations. Event consumers, if they want to validate that they haven't missed or incorrectly processed any balance changes, can call getLedgerEntries to fetch each balance that was updated by the transfers they care about for each ledger closed.

[Shaptic]

Agreed with Jake here. If the goal is to provide consumers with a reliable source of truth, that source of truth already exists: it's the balance entry on the ledger.

[leighmcculloch]

Dune does balance tracking via tracking ERC20 transfer events:

• For ERC20: Analysis is based on token transfer events detailed in the tokens_ethereum_base_transfers. The address balance is updated based on the to/from addresses in the transfer events. If the token is a non-standard ERC20 token, the balance might not be updated until we detect a standard ERC20 transfer event. Known issues currently include ERC4626 tokens and rebasing tokens like stETH or $ampleforth. We are working on improving the range of balance changes that we detect.
• For ERC721 and ERC1155: Inspection of NFT transfer activities via the nft_ethereum_transfers, focusing on the to/from addresses.

Ref: docs.dune.com/data-catalog/curated/evm/asset-tracking/balances#balance-calculation-methodology

-- @leighmcculloch at #1553 (reply in thread)

Copying this info over from another thread where we had discussed how other ecosystems consume balance events.

Given there's evidence that other ecosystems get by without balance events, I'm interested in see how the ecosystem plays this out without them, at least initially, once there are transfer, mint, and burn events being published for all movements of value on Stellar. I think it's worth seeing how that plays out before adding balance events, which are an optimisation.

[chowbao]

It seems like the discussion has slowed down.

It seems like we are going to abandon emitting a balance event for now. This can be revisited if it is determined that the existing events do not satisfy the balance calculation/reporting