NEP 141 Standard

[mikedotexe]

THE STANDARD WAS MERGED: https://nomicon.io/Standards/FungibleToken/Core.html

Moving the comments discussion from #141 to here.

API

Function Token Core API

ft_transfer - Simple transfer

change method

Transfers positive amount of tokens from the env::predecessor_account_id to receiver_id.
Both accounts must be registered with the contract for transfer to succeed. (See #145)
This method must to be able to accept attached deposits, and must not panic on attached deposit. Exactly 1 yoctoNEAR must be attached. See the Security section of the standard.

Arguments:

• receiver_id - the account ID of the receiver.
• amount - the amount of tokens to transfer. Must be a positive number in decimal string representation.
• memo - an optional string field in a free form to associate a memo with this transfer.

function ft_transfer(receiver_id: string, amount: string, memo: string|null);

ft_transfer_call - Transfer to a contract with a callback.

change method

Transfers positive amount of tokens from the env::predecessor_account_id to receiver_id account. Then
calls ft_on_transfer method on receiver_id contract and attaches a callback to resolve this transfer.
ft_on_transfer method must return the amount of tokens unused by the receiver contract, the remaining tokens
must be refunded to the predecessor_account_id at the resolve transfer callback.

Token contract must pass all the remaining unused gas to the ft_on_transfer call.

Malicious or invalid behavior by the receiver's contract:

• If the receiver contract promise fails or returns invalid value, the full transfer amount must be refunded.
• If the receiver contract overspent the tokens, and the receiver_id balance is lower than the required refund
  amount, the remaining balance must be refunded. See the Security section of the standard.

Both accounts must be registered with the contract for transfer to succeed. (See #145)
This method must to be able to accept attached deposits, and must not panic on attached deposit. Exactly 1 yoctoNEAR must be attached. See the Security
section of the standard.

Arguments:

• receiver_id - the account ID of the receiver contract. This contract will be called.
• amount - the amount of tokens to transfer. Must be a positive number in a decimal string representation.
• msg - a string message that will be passed to ft_on_transfer contract call.
• memo - an optional string field in a free form to associate a memo with this transfer.

Returns a promise which will result in the amount of tokens withdrawn from sender's account.

function ft_transfer_call(
    receiver_id: string,
    amount: string,
    msg: string,
    memo: string|null,
): Promise;

ft_total_supply - Returns total supply

view method

Returns the total supply of the token in a decimal string representation.

function ft_total_supply(): string;

ft_balance_of - Returns account balance

view method

If the account doesn't exist must returns "0".

Arguments:

• account_id - the account ID to view the balance.

Returns the balance of the given account in a decimal string representation.

function ft_balance_of(account_id: string): string;

Transfer Receiver API

ft_on_transfer - Callback on transfer call

change method

Called by fungible token contract after ft_transfer_call was initiated by
sender_id of the given amount with the transfer message given in msg field.
The amount of tokens were already transferred to this contract account and ready to be used.

The method must return the amount of tokens that are not used/accepted by this contract from the transferred
amount. Examples:

• The transferred amount was 500, the contract completely takes it and must return 0.
• The transferred amount was 500, but this transfer call only needs 450 for the action passed in the msg
  field, then the method must return 50.
• The transferred amount was 500, but the action in msg field has expired and the transfer must be
  cancelled. The method must return 500 or panic.

Arguments:

• sender_id - the account ID that initiated the transfer.
• amount - the amount of tokens that were transferred to this account in a decimal string representation.
• msg - a string message that was passed with this transfer call.

Returns the amount of unused tokens that should be returned to sender, in a decimal string representation.

function ft_on_transfer(sender_id: string, amount: string, msg: string) -> string;

Notes

memo field is explained in details in #136
The goal is to associate some external information with the transfer on chain. It may be needed for compliance in some
jurisdictions.

Security

Requirement for accept attached deposits (#[payable])

Due to the nature of function-call permission access keys on NEAR protocol, the method that requires an attached deposit
can't be called by the restricted access key. If the token contract requires an attached deposit of at least 1
yoctoNEAR on transfer methods, then the function-call restricted access key will not be able to call them without going
through the wallet confirmation. This prevents some attacks like fishing through an authorization to a token contract.

This 1 yoctoNEAR is not enforced by this standard, but is encouraged to do. While ability to receive attached deposit
is enforced by this token.

Transfer Call Refunds

If the receiver contract is malicious or incorrectly implemented, then the receiver's promise result may be invalid and
the required balance may not be available on the receiver's account. In this case the refund can't be provided provided
to the sender. This is prevented by #122 standard that locks funds into a temporary
vault and prevents receiver from overspending the funds and later retuning invalid value.
But if this flaw exist in this standard, it's not an issue for the sender account. It only affects the transfer amount
and the receiver's account balance. The receiver can't overspend tokens from the sender outside of sent amount, so this
standard should be considered as safe as #122

Conceptual context

As discussed in the recorded call from January 18th, 2021, some context around gas usage and promises is helpful to add.

This standard mentions using promises to make a cross-contract call and then capture the result. With NEAR, each promises is given an amount of gas. Each promise can therefore have it's "own bucket" of gas separate from other promises. This means that if Contract A calls Contract B, and expects to analyze the result back in Contract A, it can allocate gas accordingly. Put another way, Contract B cannot run an infinite loop that drains all the gas and interfere with the callback on Contract A. This also means that assertions can be written into contracts like the one discussed here, ensuring that there will be enough gas attached to perform all the operations needed.

[TrevorJTClarke]

@mikedotexe looks like theres a duplicate ft_total_supply, which i think the second is intended to be ft_balance_of or similar.

Question -- where did the discussion end up on namespaced methods? Is that the path forward for other NEPs in the future?

[oysterpack]

Question -- where did the discussion end up on namespaced methods? Is that the path forward for other NEPs in the future?

Yes - that is the new standard naming convention going forward. At the WASM low level, all functions are effectively in the global namespace and function names must be unique (function overloading is not permitted). Using function prefix names is a trade-off. It enables global functions to be namespaced using a naming convention.

[mikedotexe]

Nice catch, Trevor, fixed it changing to ft_balance_of.

[robert-zaremba]

Why do you call it JSON API format? It's a documentation format. There is no JSON in the description. Zero.

[oysterpack]

good point - JSON implies implementation. We should keep the API decoupled from implementation (as much as possible).

@mikedotexe - Let's simply call it API

The idea is that we want to define the API in a format that is programming language neutral to keep the discussion focused on the API design (and not be distracted by the programming language). That being said ... since Rust is the de-facto supported programming language for writing smart contracts on NEAR, the standard should produce a Rust reference implementation for the API.

[oysterpack]

I am putting together a tutorial for NEP-141 and feedback would be appreciated: https://github.com/oysterpack/datahub-learn/blob/master/network-documentation/near/tutorials/stake/2-fungible-token.md

[mikedotexe]

I might suggest that the first time we mention NEP we have it like:

NEAR Enhancement Proposal (NEP)…

---

Looks like we need to add a space here:

There is a simple transferfunction

---

In this section we discuss how escrows aren't that great. I don't feel too strongly about the suggestion I'm about to give, but I'll give it anyway. Perhaps a small example of what an escrow is could help.

Alice wants to let Bob take up to X tokens from her. Alice has to pay for the storage of the data that indicates Bob is allowed to do this, then remember to remove that entry if it's no longer needed. This necessitates multiple transactions in order to accomplish a workflow that can be simplified…

---

"On NEAR, the contract is responsible to pay for its long term persistent storage."
I'd consider adding:

(To be clear: the state storage is paid for once; it is not state rent.)

---

In terms of the diagram, this is SUPER useful. I realize, now that I'm looking at it, that the arrows for the callback are a bit difficult to describe. It's almost like the callback should be from both the ft and the receiver, like this:

^ I'm not set on this, but workshopping ideas. what do you think?

[mikedotexe]

After this bullet point:
"Cross contract calls always require gas regardless whether the function call being invoked is a view method or change method"
We may consider adding that extra information about the individual "buckets" of gas used in promises. This is mentioned at the top of this page under "Conceptual context"

[mikedotexe]

Under the two view function definitions — function ft_total_supply(): string and function ft_balance_of(account_id: string): string — perhaps we can explain why it's returning a string. Perhaps linking here, or somewhere better: https://stackoverflow.com/a/9643650/711863

---

I think there's a typo here at "ft_on_transferl" (extra L)

[mikedotexe]

I wonder if we need to return a string or just leave this as void:
function ft_resolve_transfer_call(sender_id: string, receiver_id: string, amount: string): string

[mikedotexe]

Great stuff, Al. Last thing: I just noticed the final line says "NEP-41" instead of "NEP-141"

[oysterpack]

FYI - I implemented NEP-141 in my STAKE project:

Rust implementation

• FungibleToken interface
• FungibleToken implementation

and as a heads up when reading the code ... the "low level" API defined by NEP-141 uses string for all function argument and return types. My preference is to always model the domain in the code ...

The code is unit tested and functional. I did some simple manual ft_transfers on testnet. The only thing I haven't fully tested yet end-to-end is the transfer call flow.

[evgenykuzyakov]

Let's also move security notes here and the background as well.

[robert-zaremba]

Metadata #148

Last part of finalizing the Fungible Token standard is describing an interface for Metadata. Here is the discussion to find the right design: #148

[evgenykuzyakov]

(REJECTED) Change proposal

Rename ft_balance_of to ft_balance to be consistent with #145

[robert-zaremba]

In fact ft_balance_of sounds more correct, as I would updated #145 instead.

[luciotato]

@evgenykuzyakov is there an easy way to check if an account has a contract or not?
it will be nice to impede ft_transfer to contract accounts, because that normally means the tokens became locked and unrecoverable.

[chadoh]

From near-cli, near state [contract_name], check code_hash. From near-api-js, check await someAccount.state(). Not sure how from a contract.

[bowenwang1996]

No it is not possible to check that from within a contract.

[chadoh]

This 1 yoctoNEAR is not enforced by this standard, but is encouraged to do. While ability to receive attached deposit is enforced by this token.

Suggested rewrite:

This standard enforces that ft_transfer and ft_transfer_call endpoints be payable, which means they could accept deposits of any amount. Implementors are encouraged to check that attached deposits do not exceed 1 yoctoNEAR, but are not required to do so.

But is this accurate? Both core change methods say "exactly 1 yoctoNEAR must be attached." This makes it seem like the enforcement of "exactly 1 yoctoNEAR" is part of the standard.

[mikedotexe]

What is FCAK?

function-call access key

[vgrichina]

I think what we shouldn't do for sure is make it optional. Either make 1 yocto required or not. Otherwise any app like wallet would have no idea how much to attach to a given transfer.

Also note that it is super easy for wallet to have a list of methods like transfer which trigger confirmation by user, doesn't need to use this specific hack with 1 yoctoNEAR.

[luciotato]

@mikedotexe Thanks for the detailed explanation, all the FCAK details are more clear for me now.

The security problem is that the wallet, when asking for approval of a FCAK reads "xxxx cannot access your funds". So even if you need your FAK to add a FCAK, the message/idea is misleading, and can trick users into creating a FCAK for an unknown malicious contract believing their funds are safe because they trust the wallet.

without the 1 yocto hack, the attack vector to steal NEP-141 tokens or any other asset managed by smart contracts is too easy!... meaning the 1 yocto "hack" will become part of 95% of all pub fn's in DEFI smart contracts. The "hack" will become the "official implementation" and that's not good.

Attaching 1 yoctoⓃ, while a hack, does enforce this confirmation

Attaching 1 yoctoⓃ, while a hack, just disables FCAKs

[mikedotexe]

I think what we shouldn't do for sure is make it optional. Either make 1 yocto required or not. Otherwise any app like wallet would have no idea how much to attach to a given transfer.

Also note that it is super easy for wallet to have a list of methods like transfer which trigger confirmation by user, doesn't need to use this specific hack with 1 yoctoNEAR.

Great! This is news to me, how do I do this @vgrichina?

[mikedotexe]

So also I'm going to retract my statement about having 1 yoctoⓃ be optional. I should have thought more (or remembered the original intentions) regarding this. The real problem here is laid out in the scenario that I believe Lucio is mentioning.
For example:
A malicious site uses near-api-js and tells end users it's Candy Crush on the blockchain. The UI looks neat, so people log in with their NEAR accounts without properly reading the confirmation section when redirected to Wallet. Instead of using the CANDY tokens as they're led to believe, the user has unwittingly created a function-call access key for DAI. Now the frontend can transfer their DAI.
It sounds like Vlad knows something I don't know about wallet redirecting, so I'll wait to get updated on this.
I'll also say that certain fungible tokens (https://berryclub.io fungible tokens are a great example of this, where an FT is used every pixel you paint) would benefit from a user-initiated override on their own account for a "safe" vs "unsafe" mode. This would probably be useful in an example, and still abide by the standard. Modifications might look like this (without getting into all the implications like in storage and whatnot):

// would set safe_mode to true by default
pub struct AccountInfo {
    safe_mode: bool
}

#[near_bindgen]
#[derive(BorshDeserialize, BorshSerialize)]
pub struct Contract {
    pub accounts: LookupMap<AccountId, Balance>,
    pub total_supply: Balance,
    pub account_storage_usage: StorageUsage,
    pub metadata: FungibleTokenMetadata

    /// NEW PART AccountID -> Account details.
    pub account_info: LookupMap<AccountId, AccountInfo>,
}

…
// an extra impl
impl Contract {
    fn set_safe_mode(&mut self, is_safe: bool) {
        assert_self();
        let sender_account = env::predecessor_account_id();
        if let Some(sender_info) = self.account_info.get(&sender_account) {
            self.account_info.insert(&sender_account, &AccountInfo {
                safe_mode: is_safe,
            });
        } else {
            env::panic(b"User not registered");
        }
    }
}

…
#[near_bindgen]
impl FungibleTokenCore for Contract {
    #[payable]
    fn ft_transfer(&mut self, receiver_id: ValidAccountId, amount: U128, memo: Option<String>) {
        let sender_id = env::predecessor_account_id();
        if is_safe_mode(sender_id) {
          assert_one_yocto();
        }
        let amount = amount.into();
        self.internal_transfer(&sender_id, receiver_id.as_ref(), amount, memo);
    }
    …
}

Anyway, sorry for my back and forth on this issue. I think it's best to move this discussion into code and Nomicon, which is what I'm working on.

[chadoh]

Transfer Call Refunds: [slightly rewritten for clarity] If the receiver contract is malicious or incorrectly implemented, then the receiver's promise result may be invalid or the required balance may not be available on the receiver's account. In this case the refund can't be provided to the sender. This is prevented by Standard #122 which locks funds into a temporary vault and prevents receiver from overspending the funds and later returning invalid value. But if such a flaw exists in this standard, it's not an issue for the sender account. It only affects the transfer amount and the receiver's account balance. The receiver can't overspend tokens from the sender outside of sent amount, so this standard should be considered as safe as #122

NEP146 contracts are not required to use such a vault, correct? Is #122 worth mentioning here? I'd prefer we state the security properties without such a link, if possible.

As a newcomer to both NEP146 and NEP122, I don't actually understand the security properties here yet, and I'm hesitant to try to figure it out by reading all of the lengthy (and probably mostly irrelevant) discussion in #122.

The statement I just pasted seems to contradict an earlier statement in the ft_transfer_call description:

If the receiver contract overspent the tokens, and the receiver_id balance is lower than the required refund amount, the remaining balance must be refunded.

This implies the receiver contract can overspend the tokens. But the Security note says that it cannot. Which is it?

[chadoh]

Will we add a "Motivations" section, explaining the intended use of the various calls? Having started with this discussion, I don't understand the intended use-cases of ft_transfer_call, and I feel like there's probably something really cool that I'm missing. Without doing a lot more digging into other NEPs and recorded calls, I'm not sure how to think about the capabilities and limitations of the current proposal.

[chadoh]

Seems like @oysterpack covered it in great detail 🖤🖤

A TL;DR version of this on our canonical published standard would also be great

[jasperdg]

Playing around with the NEP-141 standard in our current code base. Problem I'm running into is that I would prefer for users not to have to "pre-pay" storage. I think the standard still holds true but it would be better if in the transfer_and_call method we'd allow for > 1 yocto and assume that all yocto attached would be used to fund storage on the target contract.

The implementation would be more similar to this:

        ext_fungible_token_receiver::ft_on_transfer(
            sender_id.clone(),
            amount.into(),
            msg,
            receiver_id.as_ref(),
            env::attached_deposit(),
            env::prepaid_gas() - GAS_FOR_FT_TRANSFER_CALL,
        )
        .then(ext_self::ft_resolve_transfer(
            sender_id,
            receiver_id.into(),
            amount.into(),
            &env::current_account_id(),
            NO_DEPOSIT,
            GAS_FOR_RESOLVE_TRANSFER,
        ))

I think the pre-paid model is a good fallback model but that it should be optional since it does require an extra step and will throw users / frontend devs off once storage runs out.

Maybe this would cause the same issue as we're trying to solve before where a user's deposit would get "stuck" in the token contract if the promise fails but I think this could be handled in resolve_transfer

[evgenykuzyakov]

The concern here is if the use didn't attach enough gas, then the attached deposit may be lost in the fungible token contract.

[jasperdg]

Wouldn't this implementation solve that? near/core-contracts#131

As long as we make sure there's enough gas to cover resolve, which is I think is being done by subtracting GAS_FOR_FT_TRANSFER_CALL from prepaid_gas

[jasperdg]

Hm no actually the way I propose in my pr won't work. It would allow attackers to drain all NEAR on te token contract.

There might be a way where if storage_deposit is larger than 1 we first call receiver_address::storage_deposit(sender, DEPOSIT_GAS, env::attached_deposit) or something of the sorts.