Native fungible token standard (FRC-0046)

[anorth]

See https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0046.md

[Edit 2022-08-02: built-in multisig should also implement receiver hook]

This is a proposal for a fungible token standard for native actors. It’s a collaborative effort with @jsuresh and @alexytsu.

Motivation

The concept of a fungible token is widely established in other blockchains. As in those ecosystems, the Filecoin actor ecosystem will benefit from a standard API implemented by most tokens. A standard permits easy building of UIs, wallets, tools, and higher level applications on top of a variety of tokens representing different quantities.

Early token APIs like ERC-20 were developed before many applications had been built, and so fall short in a number of ways. Network effects have led to significant adoption and lock-in, but even the authors acknowledge that they’d do it differently if starting over. Filecoin has a unique opportunity to benefit from the learnings of other ecosystems and, at least for native actors, establish more powerful and flexible fundamental building blocks.

Goals

This proposal aims to:

• Establish a token API conceptually similar to prior art, including support for delegated control of tokens
• Reduce user interface complexity and gas costs of transferring tokens to contracts
• Prevent losses associated with accidental transfer to addresses unable to process tokens
• Satisfy the above goals in the simplest and safest possible manner

Proposal

This proposal is inspired significantly by ERC-777, an improved token standard for Ethereum. The Filecoin proposal is unencumbered by backward compatibility concerns.

The highlights are:

• Standard token name/symbol/supply/balances, with a fixed decimal precision of 18
• Standard allowance protocol for delegated control, but with an API robust to front-running
• Receiver hooks informing receiving actors of incoming tokens (mandatory)

API specification

Methods and types are described with a Rust-like pseudocode. All parameters and return types are IPLD types in a CBOR tuple encoding. The spec below is not exhaustive with respect to all possible inputs and states; a FIP to be drafted after discussion of these ideas should fill all the gaps.

Methods are to be presented according to the calling convention such as that discussed in #382, so this recommendation depends on that.

Interface FRC-XXX

type TokenAmount = BigInt

/// Returns the name of the token.
/// Must not be empty.
fn name() -> String

/// Returns the ticker symbol of the token.
/// Must not be empty. Should be a short string of uppercase.
fn symbol() -> String

/// Returns the total amount of the token in existence.
/// Must be non-negative.
/// The total supply must equal the balances of all addresses.
/// The total supply must equal the sum of all minted tokens
/// less the sum of all burnt tokens.
fn total_supply() -> TokenAmount

/// Returns the balance of an address.
/// Must be non-negative.
fn balance_of(owner: Address) -> TokenAmount

/// Transfers tokens from caller to another address.
/// Amount must be non-negative (but can be zero).
/// Transferring to the caller must be treated as a normal transfer.
/// Fails (aborts) if invoking the receiver hook on the
/// to address aborts.
fn transfer({to: Address, amount: TokenAmount, data: Bytes})

/// Transfers tokens from one address to another.
/// The caller must have previously been approved to control
/// at least the sent amount.
fn transfer_from({from: Address, to: Address, amount: TokenAmount, data: Bytes})

/// Atomically increases the amount that a spender can transfer
/// from the caller’s balance.
/// The increase must be non-negative.
///
/// Returns the new total allowance of the spender for the owner.
fn increase_allowance({spender: Address, increase: TokenAmount}) -> TokenAmount

/// Atomically decreases the amount that a spender can transfer
/// from the caller’s balance.
/// The decrease must be non-negative.
///
/// Sets the remaining allowance to zero if the decrease is
/// more than the current allowance.
fn decrease_allowance({spender: Address, decrease: TokenAmount}) -> TokenAmount

/// Sets the allowance a spender can transfer from the caller’s
/// balance to zero.
fn revoke_allowance(spender: Address)

/// Returns the allowance of a spender for an owner.
///
/// The spender can burn or transfer the allowance amount
/// out of the owner's address.
fn allowance({owner: Address, spender: Address}) -> TokenAmount

/// Burns tokens from the caller’s balance, decreasing the
/// total supply.
fn burn(amount: TokenAmount)

/// Burns tokens from an address’s balance.
/// The caller must have previously been approved to control
/// at least the burnt amount.
fn burnFrom({owner: Address, amount: TokenAmount})

Interface FRCXXXTokenReceiver

See also the universal receiver hook idea, below.

/// Invoked by a token contract after transfer of tokens to the
/// receiver’s address.
/// The token state must be persisted such that the hook receiver
/// will observe the new balances.
/// Amount must be non-negative (but may be zero).
/// Aborts if the receiver refuses the transfer.
fn token_received({from: Address, amount: TokenAmount, data: Bytes})

Behaviour

A token may implement other methods for transferring tokens and managing allowances. These must maintain the invariants about supply and balances.

Transferring tokens

This standard requires the actor receiving tokens to implement a receiver hook to accept the transfer. This mechanism achieves two significant outcomes:

• Prevents loss-of-value from transferring tokens to actors that cannot use them
• Notifies receiving actors so they can perform internal logic in response

Because receiving tokens becomes an opt-in capability, it’s expected that most actors not designed to receive tokens will not implement a receiver. Invoking that method will thus abort (e.g. with a USR_UNHANDLED_MESSAGE code) and cancel the transfer. This will prevent common cases of error such as transferring to the token actor itself, an exchange router, etc.

A receiver hook significantly simplifies the common flow of depositing tokens into some actor (e.g. an investment vault) that needs to perform some internal accounting in response.

• Without hooks, the typical flow is for the depositor to first approve the receiving contract (often for an infinite allowance), wait for that approval, then call a method on the contract which internally invokes transferFrom() to pull the tokens, and then update internal records.
• With hooks, the depositor simply calls transfer(), perhaps with some attached metadata. If the receiving contract accepts the deposit, it can update internal state; or it can reject the deposit by aborting.

Receiver hooks thus use less gas, provide a simpler UX, and prevent a large class of user errors.

Minting

API methods for minting are left unspecified. However, minting tokens to an address must invoke the receiver hook, and fail if it aborts.

Addresses

Addresses for receivers and spenders of tokens must be resolvable to an actor ID. See discussion about built-in account actor support, but some implications:

• An uninitialised pubkey address can receive tokens (because receiver hook will initialise it), but cannot be authorized as a spender
• An uninitialised actor address cannot receive tokens or be authorized as a spender

We might wish to re-evaluate some of these implications, but any alternative policy will involve more complexity in token implementations.

Discussion

Decimals

There is no decimals() function. All tokens are assumed to have a precision of 18 decimal places, matching that of the native Filecoin token.

Tokens that should logically have a lesser precision (e.g. in-game asset units) should enforce balances conform to their desired precision internally (e.g. rejecting attempts to transfer or mint fractional tokens).

Approvals and allowances

The approval mechanism is retained in order to handle asynchronous workflows, where tokens are pulled some time after the approval, or as part of more complicated transactions.

Reentrancy

Receiver hooks introduce the possibility of complex call flows, the most concerning of which might be a malicious receiver that calls back to a token actor in an attempt to exploit a re-entrancy bug. We expect that one or more high quality reference implementations of the token state and logic will keep the vast majority of token actors safe. We judge the risk to more complex actors as lesser than the aggregate risk of losses due to misdirected transfers and infinite approvals.

Built-in actor support

For this proposal to be adopted as standard, we would need the built-in account and multisig actors to implement the receiver hook (as a no-op). This implies adoption of the associated calling convention, too (more discussion in #401). This should also support transfer of tokens to uninitialised public-key-addressed actors (that have never sent a message), as the VM will install a built-in account actor at the address during the process of invoking the hook.

This would not automatically support transfer to uninitialised non-public-key addresses, such as those deterministically generated for future actor installation (#379). Support could be added by treating the NotFound syscall error as success. This would however create potential for lost tokens transferred to such addresses. We should decide and specify this behaviour.

EVM support

We need to see more detail of proposals for FVM/EVM (and other hosted VM) integration in order to design smooth compatibility. Pending such details, a few paths for token integration present themselves:

• Token contracts are free to implement additional methods, including the ERC-20 standard for direct calls from existing EVM contracts. It’s likely not too hard to decode EVM ABI messages in native actors to support direct calls.
• A bridge actor could mediate token balances between two environments. This would function much like existing cross-chain or layer-two bridges.

Depending again on details about EVM account actors, it may be possible to transfer native tokens to EVM addresses directly if they implement the receiver hook. If not, the fact that EVM account actors would not implement the token receiver hook would likely save many people from an otherwise easy error of confusing the address types or considering such transfer valid.

If bridging, the bridge actor would implement the hook but may not be able to confirm the receiving EVM contract can in fact handle the tokens. This is a necessary loss of functionality if “downgrading” to ERC-20 semantics.

Extension - universal receiver

The Lukso blockchain (from ERC-20 author @frozeman) generalises the token receiver hook to a universal receiver. This is a single receiver hook that accepts an additional “type” parameter identifying the type of asset being received. This permits a single hook to respond to all kinds of asset transfers (e.g. non-fungible tokens), including those which have not yet been specified!

/// Universal receiver hook.
/// The data bytes should be decoded according to the asset type.
fn asset_received({type: String, data: Bytes})

We already intend to specify a non-fungible token API as companion to this one, with its own receiver hook if necessary. But the flexibility to support future standards is very attractive. For example, if we implement a universal receiver in the built-in account actor, future standards can emerge easily. Without that, developing a new standard would require large-scale community buy-in before it could be realistically tried out.

Extension - sender hooks

ERC-777 also specifies a token sender hook. This calls a hook in the owner account whenever tokens are transferred, and similarly permits cancelling the transfer. We might consider whether such mechanism is worthwhile to establish from the beginning for Filecoin.

[Tom-OriginStorage]

Not much comments on Fungible Token Standards, do have a lot to say on Non Fungible Token Standards. But I do notice many new chains are using u128/u64 over BigInt, simply because they are primitives and more than sufficient to cover all use cases.

[Stebalien]

• i128 is enough for all practical purposes (although i64 likely isn't). However, it's important to consider signed integers when talking about tokens/money.
• There are probably better ways to serialize, honestly (e.g., ways to avoid trailing zeros when storing values in attoFIL). But BigInt is usually "good enough".

[Tom-OriginStorage]

Why the need to consider signed integers? My understanding is unsigned integers should be used as we don't deal with negative money in the real world. It doesn't make sense to continue spending money when your balance is zero, it defeats the whole purpose of earning money in a meritocratic society.

I was actually thinking the other way round, that BigInt is an overkill. And favoring primitive over BigInt.

[Kubuxu]

Why the need to consider signed integers?

When doing arithmetic over tokens you might need to represent negative values. For storage, you are primarily interested in positive values although, for example, someone might decide to represent and store deficits as negative.

[hunjixin]

agree to represent negative value for temp value in arithmetic. not need to consider underflow

[anorth]

Since the spec is mostly about serialization here, I can see the point that we're wasting a byte for the sign of these values, because none of them in the specified messages can be negative. But the same could be said for the native token, and I think it's far more valuable to match that behaviour that optimise those bytes.

I am also fully on board with the arguments why, when instantiated, one should use signed values to avoid underflow. So its simpler all round to use a signed value everywhere.

[anorth]

One design question is whether the token receiver hook should receive addresses as Address type or ActorID type.

• If an Address it must always be an ID-type address, following the behaviour of the syscalls
• Using ActorID is thus very explicit, saves receivers from unpacking the actor ID and the associated error handling code
• ActorID is marginally smaller
• But convention from the runtime/syscalls and built-in actors is to always pass addresses

Not sure how to resolve this tension between convention and a probably-superior approach.

[Tom-OriginStorage]

Personally I think ActorID type would be better in terms of user experience. As you have highlighted, it saves receivers from writing boilerplate code and is more compact.

And as mentioned before, developers who are familiar with the EVM conventions is unlikely to touch the Rust SDK, they would be using Solidity and these details will be abstracted and irrelevant for them.

[anorth]

Thanks, I agree, and this works reasonably in implementation.

[anorth]

Moving discussion about granularity out from PR

@Kubuxu

I see that decimals() was discarded. Should we provide something like granularity() from EIP-777. While rejecting transactions internally is the correct thing to do, I can see a need for knowing what is the granularity of a given token. For example a generic wallet application and users wanting to transfer half of their tokens.

@jsuresh

I understood the purpose of granularity differently. Love a few more examples from you as I may have missed important use cases.

my understanding is everything has 18 DP as this being different is an endless source of client bugs. However, in certain use cases it doesn’t make sense to hold or transact partial tokens.

my goto example is games. Eg. Rupees in Zelda have to be ‘whole’ for use in game and therefore trading.

My assumption was in filecoin this kind of use case would be rare. However, would love to hear other motivations/examples of ways you think this would come in handy.

[anorth]

I don't think we can say much about the kind of use cases to expect, but the class that want whole units only definitely exists.

In fact, my first use of this to represent verified registry datacap as a token has a granularity of whole units only (in bytes).

[Kubuxu]

Rupees in Zelda have to be ‘whole’ for use in game and therefore trading

Exactly, it comes into consideration every time something has a defined usable fraction (or lack of thereof).
For example, it doesn't make sense to work on fractions of a byte in the case of a data cap, which is a use case that we are implementing right now.

The built-in internal precision is 18 decimal digits, so if someone wants their token presented as "5 TICKER", they need to specify 5e18 "token amount". Granularity is then additional information for users of the token of "transactive unit" of the token (important part is that some users of the token standard are generic, as in work over a multitude of different tokens, not giving any special treatment to any of them).

As in my initial example this really comes into in play whenever you want to do any divisions of the token. If the contract has embedded granularity (as in transfers with incorrect granularity fail), without that Granularity property exposed, there is no way for a generic contract to be able to for example to share out profits from some endeavour proportional to investor shares. In general, if the contract has embedded granularity and it is not exposed, then transfers of divisions of the token amount are likely to fail.

[hunjixin]

@anorth

I think TokenAmount needs to be strictly defined.

1. This protocol may need to be implemented on different platforms.
2. If there are differences in tokenAmount (including serialize) implementation may have impact on data analysis or actor interaction

In the draft, mentioned that tokenAmount uses var-int serialization, does this mean that can't use big.Int directly in golang. If not, can use the (uint64, uint64) scheme? var-int does not seem to work in the case of large numbers.

[Kubuxu]

It is BigInt serialisation, which isn't strictly varint by normal definition. I think @anorth meant that as variable length encoded int, as bigint is encoded byte by byte on the need basis.

[anorth]

I'll clarify a bit in the text saying it's the same type as the built-in native token.

[alexytsu]

A design question to consider is whether the tokens_received hook should accept arbitrary byte data from both the operator and the token-actor itself - and whether this should be encoding/schema specific or defined in our interface.

ERC-777 specifies separate fields for data and operatorData which I'm inclined to follow.

[anorth]

It's very cheap to add in both, so I'm inclined to agree. Can we qualify both names, e.g. operatorData and tokenData?

[anorth]

Now done in the draft

[anorth]

A thread about universal receiver hook. Quoting FRC:

This is a single receiver hook that accepts an additional “type” parameter identifying the type of asset being received.
This permits a single hook to respond to all kinds of asset transfers (e.g. non-fungible tokens),
including those which have not yet been specified!

/// Universal receiver hook.
/// The data bytes should be decoded according to the asset type.
fn asset_received({type: String, data: Bytes, operatorData: Bytes})

We already intend to specify a non-fungible token API as companion to this one, with its own receiver hook if necessary.
But the flexibility to support future standards is very attractive.
For example, if we implement a universal receiver in the built-in account actor (that returns true), future standards can emerge easily.
Without that, developing a new standard would require large-scale community buy-in before it could be realistically tried out.

[alexytsu]

Without universal receivers, even just the addition of an NFT standard would require a new hook to be added on the built-in account actor.

I think the flexibility of a universal receiver will be beneficial going forward.

[Kubuxu]

How do we handle the assignment of the type enum? One option would be to prefix namespace it, FRCxxxx prefix for FRCs and x- for experiments/new standards similar to HTTP.

[anorth]

Yes I think namespacing should work pretty well

[anorth]

Ah, and rather than a string for type, we can use FRC-42 hash(string).

[anorth]

I think we should consider naming all the methods with an FRC46 prefix, to avoid possible collision with any other standards. We're claiming some very generic terms here.

[anorth]

I'm torn about this. Prefixing will avoid collisions, but (a) how much is that a real problem, and (b) maybe we want some collisions sometimes?

Colliding names only matters if one actor wants to implement two different standards that use the same name but to mean different things. I'm not aware of this being a practical problem yet in other ecosystems, but of course we are still in very early days. It's not a problem for standards to overlap in names if no actor wants to implement both at once.

But sometimes we might want collisions. An example would be extracting a subset of a standard into a new one. Or it would be quite reasonable for fungible and non-fungible tokens to overlap in name for conceptually similar things like name, symbol, total supply. Should you have to know the FRC being implemented in order to write a method name for something simple like that?

What about when one standard extends another. E.g. imagine FRC-101 is an extended version of FRC-100, and in practise everyone uses the extension. Actors implementing FRC-101 will have some methods prefixed with FRC-100. And you have to get the names exactly right for it to work.

[Kubuxu]

If the handlers are functionally the same, we can accept calls from both FRC100_transfer and FRC101_transfer into the same underlying method although that gets into a bit of a different mess where you start asking what should the callers use.

[anorth]

One new thought prompted by exploration of NFT APIs. There is currently no standard method to enumerate the balances (or allowances) of a token. Contrast with something like ERC-721 that at least specifies an optional method for enumeration. I think we should add enumeration to FRC-0046, at least as optional but preferably as a required part of the standard.

One might claim that the kind of users that need to enumerate are off-chain and can use direct state inspection, but (a) the kind of users that we know about are off-chain today because ERC-20 doesn't support enumeration, and (b) that's a very rough solution anyway. The easiest way for actor introspection off-chain is to invoke read-only methods on the actor/contract anyway (e.g. over RPC to a node). Direct state inspection more-or-less requires the node to implement an understanding of the state of individual actors, which is not reasonable for most user-programmed actors. Even though we have a reference implementation, tokens might embed that state in other actor state (as the Datacap actor does), or are free to use a different representation too. Actor authors should be able to fully abstract their state representation without suffering reduced amenity to tooling, explorers etc, and do so via an API they define. See also #383

So

• Actors generally should implement methods for all relevant state introspection
• Token actors are no exception
• We should standardise the methods used for similar reasons we standardise the rest of the API

I propose we add methods to enumerate the balance and allowance tables.

Note: The built-in Datacap actor (FIP-0045 in nv17) doesn't yet implement such methods, but it'll be easy to add them so it conforms to an updated standard.

@alexytsu @jsuresh

[Kubuxu]

I agree that enumerating method is a good idea for introspection, but generally, we should not rely on them to run on-chain, and it is possible that for some implementations they might be very expensive.

A counterpoint would be that they should be made optional/explicitly state that results might be incomplete or invalid.
The basic implementation where enumeration is unfeasible is zero-knowledge tokens or off-state token accounts.
The latter has quite a bit of a use case in airdrops, where the Merkle tree can be used to set the initial distribution of tokens, which then can be claimed, this mechanism can also be used for things better than airdrops.

[raulk]

Agree that it's useful for actors to expose getters. This is the principle of good encapsulation. Some form of yield would be great for large enumerations, but I don't think that's easily doable.

Agree that this method is useful, yet not all implementations will be able to satisfy it, so it should be optional and error with ErrNotSupported when unavailable.

Agree that it should only be allowed off-chain. There's precedent in the EVM actor, where GetStorageAt checks that the caller is 0 to prohibit on-chain calls.

[anorth]

Ok, I'm down with optional enumeration methods, thanks for the motivating examples.

I disagree that we should specify that enumeration methods must be unavailable on-chain, or even that it's a good idea for many actors to decide to enforce that. The possibility of being expensive is not a good reason to blanket deny functionality. An actor programmer isn't in a position to make a cost/benefit analysis on behalf of a hypothetical caller. Let the caller make that decision. There could be many cases where expensive is better than not at all.

[Kubuxu]

From my perspective: let's say, actor A calls actor's B enumerating method, because the B::Method is enumerating there might be a possibility for an adversary to cause it to use more gas than BlockGasLimit, it now becomes an issue for actor A which might have based a core functionality on that B::Method and is unable to proceed. From the perspective of actor A, it is a denial of service attack, from the perspective of actor B, it is an enumerating method that "wasn't supposed to be called on chain.

[Kubuxu]

For example, we are discussing an enumeration of all token holders in this case, I would argue that there is a very good reason to make the enumeration off-chain only as there is nothing which would prevent such a token contract to be susceptible to the above attack.
If the token is wrapped in specialised code, which would prevent the above, then it can re-expose the enumeration on-chain.