Skip to content

Commit

Permalink
update FLIP to final design
Browse files Browse the repository at this point in the history
  • Loading branch information
@joshuahannan
joshuahannan committed Jan 26, 2024
1 parent 4f1869b commit 2321538
Showing 1 changed file with 85 additions and 80 deletions.
165 changes: 85 additions & 80 deletions application/20221219-ft-v2.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,57 +3,61 @@ status: draft
flip: NNN (do not set)
authors: Joshua Hannan ([email protected])
sponsor: Joshua Hannan ([email protected])
updated: 2022-12-19
updated: 2024-01-26
---

# Fungible Token Standard V2

## Objective

This FLIP proposes multiple updates to the Flow Fungible Token Standard contracts,
primarily about encapsulating functionality within token resources instead of
with the contracts. There are other smaller quality of life changes to the token standard,
such as integration of metadata, improving error handling,
and including a transfer method and interface.
Some of these changes are dependent on other Cadence FLIPs being approved,
This FLIP proposes multiple updates to the Flow Fungible Token
Standard contracts as part of the Cadence 1.0 upgrade,
primarily about adding support for defining multiple token types
in one contract, adding standard events, integrating `ViewResolver`
and adding the `Burner` utility smart contract.

Some of these changes are dependent on other Cadence FLIPs that
made fundamental changes to the language
that have been approved and implemented,
primarily [interface inheritance](https://github.com/onflow/flips/pull/40),
removal of nested type requirements,
[removal of custom destructors](https://github.com/onflow/flips/blob/main/cadence/20230811-destructor-removal.md),
and [allowing interfaces to emit events](https://github.com/onflow/cadence/issues/2069).

Most of the changes proposed here would be breaking for all fungible token implementations
on the Flow blockchain, but should not be for third-party integrations such as
event listeners and apps that interface with the contracts.
The changes proposed here will be breaking for all fungible token implementations
on the Flow blockchain, as well as contracts that utilize tokens based on the standard,
third-party integrations such as event listeners, and apps that interface with the contracts.

## Motivation

The current fungible token standard for Flow
was designed in mid 2019, at a time when Cadence itself was still being designed.
The current standard, though functional, leaves much to be desired.

The current token standard uses contract interfaces.
They are designed in a way which requires each concrete contract
The current token standard uses contract interfaces and nested type requirements.
They are designed in a way that requires each concrete contract
to provide exactly one Vault type.
This means that any project that needs multiple tokens must deploy multiple contracts.
In the case of very simple tokens, this is a lot of complexity for very little value.

Related to this problem, functionality and metadata associated with some tokens,
such as paths, events, and empty vault creation methods,
such as paths and empty vault creation methods
is only accessible directly through the contract itself, when it should also
be accessible directly through an instance of a token resource and/or interface.

Many contracts also do not implement MetadataViews properly because
there is no requirement for it in the standard.

In the case of events, currently there is no way for the standard to ensure that
implementations are emitting standardized and correct events, which this upgrade will address.

Additionally, the usage of nested type requirements creates some confusing
interactions, which are not useful and make learning about
and interacting with token smart contracts more difficult.

## User Benefit

With these upgrades, users will now be able to:
* Define multiple tokens in a single contract
* Query all the data about a token directly through the token resource and core interfaces
* Have standard events emitted correctly for important operations
* Define multiple tokens in a single contract.
* Query all the data about a token directly through the contract as well as the `Vault` resource and core interfaces.
* Have standard events emitted correctly for important operations (`Withdrawn`, `Deposited`, and `Burned`)
* Define a `burnCallback()` method that effectively serves as a custom destructor if used in conjunction with the `Burner` contract.

## Design Proposal

Expand All @@ -63,40 +67,57 @@ A [pull request with the suggested code changes](https://github.com/onflow/flow-
is in the flow fungible token github repository.

The main code changes and their implications are described here.
The linked proposals provide more context.
The linked proposals provide more context, but the original forum post is somewhat out of date.

### Move Event Definitions and emissions to resource interfaces

Instead of requiring events to be defined in the token implementations contracts,
they will only be defined in the fungible token standard smart contract and will
be emitted in post-conditions from the correct methods
in the resource interfaces defined in the standard.

This feature is still being designed, so there is not a code sample yet.
See https://github.com/onflow/cadence/issues/2069 for potential examples
they will only be [defined in the fungible token standard smart contract](https://github.com/onflow/flow-ft/blob/v2-standard/contracts/FungibleToken.cdc#L50) and will
be [emitted in post-conditions](https://github.com/onflow/flow-ft/blob/v2-standard/contracts/FungibleToken.cdc#L100)
from the correct methods in the resource interfaces defined in the standard.

### Add Type and Metadata parameters to events
Ex:

Standard events contain more information about the FT that is being transferred,
such as the type of the FT and important metadata about the FT.
```cadence
access(all) contract interface FungibleToken {
/// The event that is emitted when tokens are withdrawn from a Vault
access(all) event Withdrawn(type: String, amount: UFix64, from: Address?, fromUUID: UInt64, withdrawnUUID: UInt64)
access(all) resource interface Provider {
access(Withdraw) fun withdraw(amount: UFix64): @{Vault} {
post {
// Emit directly in the interface instead of the implementation
emit Withdrawn(type: self.getType().identifier, amount: amount, from: self.owner?.address, fromUUID: self.uuid, withdrawnUUID: result.uuid)
}
}
}
}
```

Here is an example of what this could look like:
This means that the `FungibleToken` events will be the source of truth from now on,
though their types will still contain the name of the implementing contract
when they are emitted, such as:

```cadence
pub event TokensDeposited(amount: UFix64, to: Address?, type: Type, ftView: FungibleTokenMetadataViews.FTView)
A.0x1654653399040a61.FlowToken.Withdrawn
```

### Include Transferable Interface with transfer method
Therefore, all Fungible Token implementations can and probably should remove their
own `TokensWithdrawn` and `TokensDeposited` events, as they are now redundant.


### Add Type, Metadata, and UUID parameters to events

For managing simple transfers, tokens can now implement the transferable interface
and the transfer method.
Standard events contain more information about the FT that is being transferred,
such as the type of the FT and important metadata about the FT.
This includes UUIDs of the vaults involved in the token movements
in case this information is useful.

Here is an example of the proposal:

```cadence
pub resource interface Transferable {
/// Function for a direct transfer instead of having to do a deposit and withdrawal
///
pub fun transfer(amount: UFix64, recipient: Capability<&{FungibleToken.Receiver}>)
}
/// The event that is emitted when tokens are withdrawn from a Vault
access(all) event Withdrawn(type: String, amount: UFix64, from: Address?, fromUUID: UInt64, withdrawnUUID: UInt64)
```

### Add `getAcceptedTypes()` method to `Receiver` interface
Expand All @@ -107,36 +128,27 @@ it can accept.
```cadence
pub resource interface Receiver {
/// deposit takes a Vault and deposits it into the implementing resource type
///
pub fun deposit(from: @AnyResource{Vault})
/// getSupportedVaultTypes optionally returns a list of vault types that this receiver accepts
access(all) view fun getSupportedVaultTypes(): {Type: Bool}
/// getAcceptedTypes optionally returns a list of vault types that this receiver accepts
pub fun getAcceptedTypes(): {Type: Bool}
/// Returns whether or not the given type is accepted by the Receiver
/// A vault that can accept any type should just return true by default
access(all) view fun isSupportedVaultType(type: Type): Bool
}
```

### Remove the requirement for a `balance` field in `Vault`
### Add a requirement for a `isAvailableToWithdraw(): Bool` function in `Vault`

The requirement to include a `balance` field in Vault implementations is restrictive
because developers may want the vault balance to be a derived field.
This proposal replaces `balance` with a `getBalance()` method.
Vaults need a way to be able to say if a requested amount of tokens can be withdrawn.
Instead of checking the balance first or risking a panic on a failed withdrawal,
code can call `isAvailableToWithdraw()` to check first to be safe.

```cadence
pub resource interface Balance {
This is especially useful in Fungible Token provider implementations
that have the ability to withdraw from multiple different vaults
because it does not necessarily need to iterate through all the vaults
before finding out if the balance is withdrawable.

/// Method to get the balance
/// The balance could be a derived field,
/// so there is no need to require an explicit field
pub fun getBalance(): UFix64
}
```

This field removal may not be worth the change,
because it will break a lot of scripts and transactions that rely
on borrowing the balance interface capability and querying the `balance` field.

### Move `createEmptyVault()` to inside the Vault definition in addition to the contract
### Add `createEmptyVault()` inside the Vault definition in addition to the contract

It is useful to be able to create a new empty vault directly from a Vault object
instead of having to import the contract and call the method from the contract.
Expand All @@ -157,19 +169,11 @@ pub resource interface Vault {
### Add Metadata Views methods to the standard

Metadata Views for fungible tokens should be easily accessible
from interfaces defined by the standard. Unlike the NFT standard though,
there isn't an obvious interface to add the methods to.

The two options are:

1. Add the methods `getViews` and `resolveView` to a new metadata interface.
This would be more logical, but it would require all accounts to update their
linked public capabilities to include the metadata interface, which is cumbersome.

2. Add the methods `getViews` and `resolveView` to the `Balance` interface.
Calling it `Balance` would no longer be completely accurate, but it would not require
any users to update the links in their accounts. This is the option that seems the best.
from interfaces defined by the standard. This proposal enforces
all FungibleToken implementations to also implement `ViewResolver`
and for all Fungible Tokens to implement `ViewResolver.Resolver`.

This way, standard metadata views methods are enforced by default.

### Drawbacks

Expand All @@ -187,16 +191,17 @@ Please share any other drawbacks that you may discover with these changes.
1. Keep the standard the same:
* If nested type requirements are removed, this may not be possible
* This would avoid the breaking changes, which would be nice in the short term, but would not be setting up cadence developers for success in the long term.
2. Make `FungibleToken` a contract instead of an interface:
* This would allow the contract to have utility methods to have more fine-grained control
over how standard events are emitted, but would not allow the standard
to enforce that implementations use the `ViewResolver` interface
and have the `createEmptyVault(vaultType: Type)` function.

### Performance Implications

All of the methods in the fungible token interface are expected to be O(1),
so there is no performance requirements to enforce with the methods.

Adding metadata parameters to the standard events could cause event payloads
to be quite large if the metadata contained in the events is large.
We don't believe this will be a significant problem though.

### Dependencies

* Adds no new dependencies
Expand Down Expand Up @@ -231,7 +236,7 @@ having to update standard transactions if they aren't compatible.

### User Impact

* The upgrade will go out at the same time as stable cadence if approved
* The upgrade will go out at the same time as Cadence 1.0 (Crescendo) if approved.

## Related Issues

Expand Down

0 comments on commit 2321538

Please sign in to comment.