Proposal for Breaking Changes to FlowToken Events. Looking for feedback

Announcements Breaking Changes
1

As part of the Cadence 1.0 upgrade, many changes are coming to the Cadence fungible token standard. One of them is the addition of standard Withdrawn and Deposited events that get emitted for every fungible token implementation.

With the addition of these standard events, token implementations no longer need to emit their own events and they are in fact redundant because the standard events will get emitted either way with more metadata. Therefore all projects are encouraged to remove their existing withdraw, deposit, and burn events to reduce the event payload on any given transaction.

In accordance with these recommendations, the Flow team has a tentative plan to remove the TokensWithdrawn, TokensDeposited, and TokensBurned events from the FlowToken smart contract. This will not affect any on-chain code, but will be a breaking change for any event listeners who rely on FlowToken events to track balances off-chain.

This change is necessary because currently the epoch transitions emit large numbers of events and with the addition of the standard events, the number of emitted events will almost double. The large event payloads for these transactions sometimes make i it impossible for the access nodes to process properly. Removing the FlowToken events will avoid this problem and the problem of redundant events in every single transaction on Flow, since they are also emitted for regular transaction fees.

For event listeners, this change will be easy to adapt to. To start with, the Cadence 1.0 upgrade is bringing many breaking changes already, so project owners will already have to update their code to be compatible. This change to events is only a small edition to the work already required.

Projects will simply need to update their event listeners to look for the standard events instead of the existing events. For FlowToken in particular, these events will change from FlowToken.TokensDeposited() to FungibleToken.Deposited(type: "FlowToken.Vault", ...). More detailed event types are shown below:

A.0xf233dcee88fe0abe.FungibleToken.Deposited(type: String, amount: UFix64, to: Address?, toUUID: UInt64, depositedUUID: UInt64)
A.0xf233dcee88fe0abe.FungibleToken.Withdrawn(type: String, amount: UFix64, from: Address?, fromUUID: UInt64, withdrawnUUID: UInt64)
A.0xf233dcee88fe0abe.FungibleToken.Burned(type: String, amount: UFix64, fromUUID: UInt64)

where 0xf233dcee88fe0abe is the address of the FungibleToken contract interface on whatever network is being used. (in this case, mainnet)

These events can be found in the FungibleToken standard here.

Therefore, event listeners will need to listen for these events that have "0x1654653399040a61.FlowToken.Vault" as their type argument.

The change to the FlowToken contract as well as all the other core contracts that will be used for the upgrade can be found in this pull request. The changes are documented in the PR.

If you have any questions or feedback regarding these changes, please reply here, ask in the PR comments, or on the Flow Discord in the #protocol-builders channel.

2 Likes
2

For exchanges -

If you are using events to keep track of FLOW balance in accounts, you will have to make the following changes to your client code,

  1. Where you are listening for the deposited event,
    A.1654653399040a61.FlowToken.TokensDeposited(amount: UFix64, to: Address?)

    defined here

    Listen for the following event instead,
    A.0xf233dcee88fe0abe.FungibleToken.Deposited(type: String, amount: UFix64, to: Address?, toUUID: UInt64, depositedUUID: UInt64)

    defined here

    where type will be 0x1654653399040a61.FlowToken.Vault

  2. Similarly, where you are listening for the withdraw event,
    A.1654653399040a61.FlowToken.TokensWithdrawn(amount: UFix64, from: Address?)

    defined here

    Listen for the following event instead,
    A.0xf233dcee88fe0abe.FungibleToken.Withdrawn(type: String, id: UInt64, uuid: UInt64, from: Address?, providerUUID: UInt64)

    defined here

    where type again is 0x1654653399040a61.FlowToken.Vault

1 Like
3

I feel like this break change has a bigger impact than all the others.

Based on my personal experience, it is necessary to allow at least 2 months for the exchange to make a development schedule to ensure that the deposits and withdrawals of FlowToken can be correctly identified after Crescendo is updated.

If we confirm the implementation of this change, we will need to contact the major exchanges that support Flow deposits and withdrawals ASAP.

I think there are some compromises, such as keeping the original events for a while.

2 Likes
4

We still have a few months before Crescendo is updated on mainnet and Vishal is going to reach out to exchanges soon, so that should be enough time

1 Like
5

Can we have a public spreadsheet.
To track which exchanges have reached out, schedule changes, and complete updates?

This has a super huge impact, so it’s best to have information in this area publicly available, and the community can also help identify and fill in any gaps.
This ensures that most exchanges complete the updates.

2 Likes
6

yeah we can post the list here.

Also, I shared this potential transition plan in the discord thread we were using to discuss this:

One of the main reasons we are doing this is to not completely overwhelm access nodes with the huge event payload during epoch transition operations. If it turns out the exchanges aren’t going to be able to update in time, I think it would be fine to keep the flow token events, but just compromise and make it so the flow token events aren’t emitted from the staking account.

That way, it solves our epoch performance problem because then only FungibleToken events will be emitted. It also won’t be a problem that the staking account isn’t included in those events because 100% of relevant fungible token events still can be tracked with the default FungibleToken events, so it will encourage people to update without it being an immediate breaking change. then once everyone has updated, we can remove the FlowToken events

3 Likes
7

+1 on this one, exchanges might take longer than expected period to integrate with the new events.

If not communicated/done right, there might even be a glitched time window for several weeks that the network deposit/withdraw is suspended.

1 Like