Account Storage Standard (formerly Account Registration)

[oysterpack]

Introduction

While designing the Fungible Token core standard, it became apparent for a need
to standardize account registration. This discussion is focused specifically on account registration, but that is a subset of the bigger problem domain of account management, which includes access control - we can save that for a separate discussion.

Account registration is a common use case for any multi-user contract. There are several benefits to require accounts to pre-register with the contract:

1. "There is no free lunch" - The biggest problem this solves is managing storage staking costs. In order for contracts to scale cost effectively, contracts may require accounts to pay for their own account storage. Account storage staking fees should be escrowed and refunded when the account is unregistered. An upfront storage staking fee is required, and depending on the contract, further storage staking fees may be required depending on the contract's specific use cases. Account storage fees should be pre-defined, predictable, and manageable as part of the contract interface.
2. Enhances security because accounts are required to explicitly register with the contract.
3. Contract can validate the account as part of registration process. For example, the account may register as a contract. In combination with a metadata standard interface, the contract can query the registering contract to ensure it supports a required interface.
4. Standardizing contract interface simplifies and lowers integration costs. It also enhances interoperability between contracts.

Lessons Learned from NEP-141 Discussion

• An approach that worked well and helped us to focus on the FT core standard interface, was defining the interface using the lowest common denominator, i.e., the JSON RPC API. I propose we continue to use the same approach to drive the discussion. Please post requirements as JSON RPC functions using the same format as in FT JSON API.
• Use a function name prefix to namespace the contract interface. I'll start by proposing acct_ , unless someone has a better one. We can sleep on it, and finalize the prefix at the end. Feel free to choose alternative names when proposing functions for the contract interface.

[robert-zaremba]

Proposal: Account Registration Interface

DEPRECATED. New design is presented in a discussion below: #145 (comment)
The rationale still holds.

pub trait AccountRegistrar {
    /// Registers an account for using smart-contract. Enough NEAR must be attach 
    /// to cover storage cost.
    /// Parameters:
    /// * `account_id` - an account to register. Anyone can register any other account.
    /// * `msg` - a transaction reference note for accounting.
    /// If the account is already registered then the function early returns and refunds the attached NEAR.
    /// MUST not panic if caller is already registered.
    /// Returns `false` iff account was already registered.
    /// Panics:
    /// * If not enough deposit was attached to pay for account storage
    #[payable]
    fn ar_register(&mut self, account_id: string, msg: string|null, msg: string|null) -> bool;

    /// Checks if the `account_id` is registered.
    fn ar_is_registered(&mut self, account_id: string) -> bool;

    /// Unregisters the caller for accepting token transfers and return the storage NEAR deposit back.
    /// If the caller is not registered, the function should early return without throwing exception.
    /// If `force=true` the function SHOULD ignore account balances (burn them) and close the account.
    ///     Otherwise,  MUST panic if caller has a positive registered balance (eg token holdings)
    /// MUST require exactly 1 yoctoNEAR attached balance to prevent restricted function-call access-key call 
    ///     (UX wallet security)
    /// Returns `false` iff account was not registered.
    #[payable]
    fn ar_unregister(&mut self, force: bool|null) -> bool;

    /// Returns a minimum amount of NEAR which must be attached for `ar_register`
    fn ar_registration_fee(&self) -> U128;
}

Rationale

Account registration

To simplify the interface we and make sure we send funds only to accounts which agree to receive token of a given type we introduce account registration concept. NEP-21 transfer (and approval) functions require payment to cover the potential storage fees.
With _account registration, an account must firstly to opt-in to a token, and only then it can receive tokens. This gives many benefits:

• protects account for receiving unwanted tokens (spamming, compliance)
• signals that a smart-contract can handle tokens

NOTE: Each method which calls a #payment method must be marked with #payment. This complicates the tools design - they will need to ask user to attach payment for every such transaction. However we decided to keep the payment requirement for security reasons related to wallet and transaction signing. Please look at NEP-141 (Fungible Token Core Standard) for details.

An account, once registered, can opt-out - with that, a storage deposit will be returned, and the account will stop accepting token transfers.

[robert-zaremba]

I've updated the comments. Thanks for suggestions @oysterpack

Re failures. register_account shouldn't panic / fail if the account is registered. It should return early and return the attached NEAR. Calling 2 times register_account is not a failure scenario. Same for unregister_account. Failure means that the whole transaction is reverted. I would rather interpret the function to "Assure that I'm registered".

[oysterpack]

Change Proposal: account registration fee query

function acct_registration_fee(msg: string|null): string

view method

Arguments:

• msg - optional msg that will be used to supply additional metadata or instructions when registering the account. Different storage fees may apply depending on how the account is registered

• Returns the registration account storage fee based on the msg.

  • Should be a positive number in decimal string representation.

Failures

• if msg is invalid

[oysterpack]

@robert-zaremba

I don't like the acct_register name. It doesn't sound legit.

I am not a fan of function name prefixes, but it's a trade off since wasm does not support true namespaced interfaces - as we discussed in the FT standard

[oysterpack]

@robert-zaremba

Re failures. register_account shouldn't panic / fail if the account is registered. It should return early and return the attached NEAR.

Sounds good - in that case I changed the function to return bool to indicate whether or not account registration succeeded.

[robert-zaremba]

ar_registration_fee and ar_is_registered added.

[miohtama]

Enhances security because accounts are required to explicitly register with the contract

There also needs be a way to have "accept all" scenario where e.g. a smart contract receiving token does not need to register for receiving it beforehand.

[robert-zaremba]

someone has to pay for the storage.

[evgenykuzyakov]

Change proposal: Allow to burn existing token balances (e.g. for spam tokens), but you can still keep the registration fee.

Unregisters the caller for accepting token transfers and return the storage NEAR deposit back. If the caller is not registered, the
function MUST early return without throwing panic.

Arguments:

• force - Whether to force account unregistration. If true the account MUST be unregistered. If false the method MUST panic if the account has positive value (e.g. positive balance for a fungible token), otherwise it MUST unregister the account.

    function unregister_account(force: bool);

[oysterpack]

change suggestions:

1. rename force to burn_tokens and make it optional
2. since the function should be designed to never panic, then return a result back indicating what happened:
   • account was unregistered
   • account was unregistered and X tokens were burned
   • account unregistration failed with failure reason:
     • account balance is not zero
     • account is unknown

[evgenykuzyakov]

• for making it optional. false || null is fine.

But it's not only for tokens. It's possible to have this API for non-token contracts, e.g. your identity contract. So I disagree with renaming it to burn_tokens. force account unregistration is clear.

Panicking in case of unexpected transition is common for contracts, even with async NEAR environment. It's also cheaper to panic than to return something.

[oysterpack]

@evgenykuzyakov sounds good - can you please update the change proposal to specify force as optional

// if not specified, default value for `force` is false
function ar_unregister_account(force: bool|null);

[evgenykuzyakov]

Change proposal: Require 1 yoctoNEAR for unregister_account

unregister_account MUST require exactly 1 yoctoNEAR attached balance to prevent restricted function-call access-key call.

[evgenykuzyakov]

Change proposal: Introduce acct_registration_fee view method

view method

Returns the amount of tokens in yoctoNEAR required to register an account (e.g. to pay for storage). The value is in decimal string representation.

function acct_registration_fee(): string;

[oysterpack]

I added an optional msg arg to support multiple account types and setup - see my proposals above for acct_register and acct_registration_fee

[robert-zaremba]

If we want to use prefix, can we use something else than acct? It sounds more like an act, not an account. Few proposals:

• accreg_
• ar_
• account_reg_

[oysterpack]

ar_ acroynm caught my eye - it's short and simple like ft_

[evgenykuzyakov]

Let's use ar_. It will make methods names better. E.g.

• ar_register_account
• ar_unregister_account
• ar_account_exists instead of ar_is_registered or ar_account_registered
• ar_registration_fee

[robert-zaremba]

Good, except ar_account_exists - we are talking here about registration. ar_account_exists sounds if an account exists at all, not if it's registered. Hence I prefer ar_is_registered.

[oysterpack]

since the functions are namespaced we can remove account from the function names because it is redundant and assumed for the scope.

#[payable]
function ar_register(msg: string|null);

function ar_unregister(force: bool|null);

function ar_is_registered(account_id: string): bool;

function ar_registration_fee(msg: string|null): string;

regarding ar_register and ar_registration_fee

• what do folks think about the optional msg arg proposal ?

[jasperdg]

Are we sure we don't want to pass an account_id to ar_register_account? I really don't think spamming or compliance are a legit enough concern. I think the use-case of: "I want to send my friend some tokens" would really take a hit when he'd need to manually sign some tx in order to be able to receive said tokens.

I really dislike the idea of adding restrictive measures like these to token standards. It is really against the open-web ethos. With regards to spamming: let spammers pay the storage cost for registration.

[oysterpack]

this is a prime example where a live meeting would be beneficial and faster to discuss the topic - perhaps @evgenykuzyakov or @mikedotexe would organize a weekly online workshop to work through these issues - meeting minutes can be recorded and published to this discussion along with the video recording ... food for thought

[mikedotexe]

I completely agree, @oysterpack. Thank you. Eugene and I were talking about this. I'll get a Doodle going and send it to the standards channel at https://near.chat

[robert-zaremba]

I can send money to an invalid iban number, or the iban of the wrong person. This is something that should be safeguarded in layers above the baselayer (this is what near does when trying to transfer near through CLI to a non-existing account).

@jasperdg this is the wrong way of looking at it. You can send, but you can't create an IBAN for someone else without his consent.

[robert-zaremba]

I think in general the anyone for anyone registration is fine. If a smart contract will require a further limitation, it can always change it and require that env::preceeding_account==account_id or add additional registration step if it will require that.

[oysterpack]

As a general comment to keep in mind ... the Open Web derives its power from being decentralized and open. The key word here is power. Unfortunately we don't live in a perfect world where there is all good and no evil. Power, regardless whether it is centralized or decentralized, will attract people that will exploit the power to exploit others. Centralized power has failed the people, and thus it has led us here onto to the path of decentralization. As we build the new decentralized and open world for the future, we must not compromise security because it adds complexity. That is the whole point of security, otherwise the system would be too simple to exploit. We must all bear the cost of security in order to protect everyone from everyone else. The network will always be under constant attack, and that means the network must always be defending and countering. It's the reality we live in.

[robert-zaremba]

LAST CALL 2021-02-01

We are planning to finalize this standard on Monday, 2021-02-01 if we won't get other critical comment by that time.

[oysterpack]

before we can finalize, a draft of the final version needs to be published for final review

[oysterpack]

since I licked off this discussion, I'll write it up based on consensus from yesterday's meeting ... for Monday to have folks to collect feedback from the community. Based on feedback we can decide on next Friday's meeting on finalizing the standard.

[robert-zaremba]

I already did - In the updated post with the interface.

[robert-zaremba]

Reimbursing

Account can be updated, or a fees can change on a protocol level. In that case it's recommended that the service provider will reimburse users by sending back NEAR for them (minus tx cost).

We don't need to have a standard method for that, because it's only in an interest of the service provider, not a general inter-smart contract communication. Instead we recommend few methods how to do that:

1. Use off-chain indexer to trace the deposit fees. After the change, service provider will send multiple simple NEAR transfers (minus tx fee) to reimburse the users.
   • as a modification, NEAR can be sent in batch to multiple users in a single transaction
2. Fee tracing can be done in smart contract. This, however, increase storage fees. Users can always check their storage deposit, compare it with a minimum required deposit and withdraw.

Note: a fully decentralized smart contract can just ignore that -- if a user will will like to get back his allowance, he will unregister and register himself back.

[oysterpack]

Account Registration API

The primary use case for account registration is to address storage staking costs. This is an issue that needs
to be addressed by any multi-user contract that allocates storage for the user on the blockchain. Storage staking costs
are the most expensive costs to consider for the contract on NEAR. If storage costs are not managed properly, then they
can break the bank for the contract.

On NEAR, the contract is responsible to pay for its long term persistent storage. Thus, multi-user contracts should be
designed to pass on storage costs to its user accounts. Contracts should require accounts to pay for their own account storage
when the account registers with the contract. How the contract handles the account storage will not be defined by this standard.
It is left up to the individual contracts to choose what works best for its use case.

Additional benefits provided by account registration are:

1. Enhances security because accounts are required to explicitly register with the contract.
2. Contract can validate the account as part of registration process. For example, the account may register as a contract.
   In combination with a metadata standard interface, the contract can query the registering contract to ensure it
   supports a required interface.
3. Standardizing contract interface simplifies and lowers integration costs. It also enhances interoperability between contracts.

The API specifies 4 functions:

#[payable]
function ar_register(account_id: string|null): bool;

#[payable]
function ar_unregister(force: bool|null): bool;

function ar_is_registered(account_id: string): bool;

function ar_registration_fee(): string;

• see below for details

---

Function

#[payable]
function ar_register(account_id: string|null): bool;

change method

Used for accounts to register with a contract. This function supports 2 modes of account registration:

1. self registration (account_id is not specified): the function caller (predecessor account) will be registered
2. third party registration (account_id is valid NEAR account ID): the function caller is registering the specified
   account_id and paying the account registration fee on the account's behalf

Account registration fee is required and must be attached to the function all.

• The main purpose for the registration fee is to pay for account storage allocation, however additional fees may apply
  that are specific to the contract's business use case. The account registration fee can be looked up on the contract
  via ar_registration_fee(). Account registration fee overpayment will be refunded back to the predecessor account
  that invoked the function.
• If the account_id is specified, then the predecessor account will be responsible for paying the registration fee on
  behalf of the account being registered.

Arguments

• account_id - optional NEAR account ID to register. If not specified, then predecessor account ID will be registered

Returns

• true if the account was successfully registered.
• false if the account was already registered, and the attached deposit will be refunded.

Panics

• If the attached deposit cannot cover the registration fee
• If account_id is not a valid NEAR account ID

---

Function

#[payable]
function ar_unregister(force: bool|null): bool;

Used to unregister the predecessor account that invoked the the function. Unregistration supports 2 modes:

1. normal mode (force=false|null): contract will apply business rules to determine if the account may be closed. If business rules prevent
   the account to be closed, then the function call will fail.
   • Using fungible token contracts as an example, account unregistration will fail if the account's balances are non-zero.
2. force mode (force=true): contract will apply alternate business rules and must close the account
   • Using fungible token contracts as an example, account balance will be ignored and tokens are effectively burned.

If the account is not registered, then the function is a no-op, i.e., simply returns false.

Sender account is required to attach exactly 1 yoctoNEAR to the function call to prevent restricted function-call access-key call.

Arguments

• force - if true, it is used to override contract business rules and apply alternate business logic to forcibly close the account

Returns

• true if the account was successfully closed
• false if the account is not registered

Panics

• If the attached deposit does not equal 1 yoctoNEAR
• If the account is registered but business logic prevents the account from being closed

Notes

How refunds are handled is out of scope for account registration standard. Refund business logic is contract specific.
That being said, ar_unregister() is a logical place for the contract to apply appropriate refunds per its use case.

---

Function

function ar_is_registered(account_id: string): bool;

view method

Used to check if the account is registered with the contract.

Arguments

• account_id - valid NEAR account ID

Returns

• true if the specified account_id is registered with the contract.
• false if the specified account_id is not registered with the contract.

Panics

• If account_id is not a valid NEAR account ID

---

Function

function ar_registration_fee(): string;

view method

Used to lookup the account registration fee that is required for registering an account with the contract.

Returns

the account registration fee amount in yoctoNEAR as an unsigned integer in string representation.

---

Account Registration Standard Review Meeting - 2021-01-29

[oysterpack]

Let's use Panics as a subsection header rather t

done

[mikedotexe]

Awesome progress here, thank you gents. Eugene and I were talking about how both ar_register and ar_unregister don't need to return anything. At first blush it seems like a bool makes sense to see if there's success or failure, but I believe if there's a failure to register or unregister, it should simply panic. If it panics, it reverts everything. This would revert the deposit (for the payable part) which is also nice. If someone underpaid for a call to ar_register we'd simply assert their payment, panic if it's not enough, instead of transferring their money back to them. Thoughts?

[robert-zaremba]

@mikedotexe - the intention is to make ar_register idempotent, so returning false if account is already registered instead of panicing. IMHO this is better, because it's more declarative. with ar_register I request to register some account and panic only if it can't make it.

[mikedotexe]

I don't think I agree on this one. I think these two articles from MDN (in regards to HTTP methods) are what I'm looking at:
Idempotence
https://developer.mozilla.org/en-US/docs/Glossary/Idempotent

PUT request method specifically:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT

I feel like ar_register is essentially a PUT, and ar_unregister is a DELETE. At the bottom of the first link, it shows how DELETE will reliably return 404, which is an error, if the item is not found. I think that's quite parallel to panicking.

[robert-zaremba]

well, the PUT is idempotent - and the the link you shared confirms that.

[evgenykuzyakov]

[OPTIONAL] Change proposal: Generic storage accounting

I've reviewed Flux AMM contract and spotted a problem where they need to increase/refund storage in the ft_transfer_call callback. We can't accept attached deposit and proxy it to ft_on_transfer, because the callback can't handle refund properly. So they have to implement variable storage per user's account. This creates a demand for another standard that we have briefly touched in this discussion to have variable storage allocation per user.

It made me think that we potentially should generalize this standard to support variable storage amounts. I know I made the argument against this to simplify fungible token standard, but let's still consider it.

APIs

• as_deposit(account_id: string|null) - deposits attached NEAR to account's storage balance
• as_withdraw(amount: string) - allows to withdraw NEAR from the account's storage balance for unused storage. Need to decide how to force withdrawal, e.g. with storage cleanup.
• as_balance_of(account_id: string): string - returns the account's storage balance in NEAR
• as_used_balance_of(account_id: string): string - returns the account's storage balance in NEAR locked for account's storage
• as_minimum_balance(): string - minimum storage balance required to have an account.

Notes:

• prefix is account storage
• we may also need to support as_withdraw_all that forces account storage deletion.

Fixed size account storage contracts

E.g. current proposal can be migrated using the following:

• ar_register - is one time call to as_deposit
• ar_unregister - is as_withdraw, but without force option
• ar_is_registered - is as_balance_of, so long as value is not 0
• ar_registration_fee is as_minimum_balance.

[robert-zaremba]

I would also prefer to not use null

[robert-zaremba]

Usually as_available_balance is what matters for doing checks. So if we have that one, then probably we don't need as_locked_balance -- because dapp will only like to check the available balance.

[evgenykuzyakov]

ok - I missed the view functions aspect. However, I still still think returning null if the account is not registered provides is direct. Returning 0 to indicate that the account is not registered implies semantics. The API should not imply any semantics. And returning 0 for as_available_balance won't work because it is ambiguous - does it mean that the entire balance is locked or there is no balance, which implies the account is not registered.

I don't like this pattern because it returns information that is not reflecting the true state and can be misleading.

The argument to this is the account registration doesn't have to be explicit anymore. We only care about the storage balance the account has and not necessary implementation. So whether the account is registered or not registered can be implied from as_balance returning positive balance.

We can also change the return type of as_balance to return an object | null and remove as_locked_balance and as_available_balance:

{
  "balance": "1000",
  "available_balance": "0",
}

Still this makes it challenging for the front-end to know whether a given operation will succeed of fail based on the available_balance being 0. It can succeed if you don't change the storage or release the storage, but can fail you try to increase the storage. But it's still better than requesting attached deposit for every operation.

[robert-zaremba]

I like an idea of one function: as_available_balance returning a structure.

[oysterpack]

I also favor the single balance function:

function as_balance(account_id: string): AccountStorageBalance|null;

class AccountStorageBalance {
  total: string;
  available: string;
}

[oysterpack]

2021-02-05 Standards Meeting Agenda

Meeting Time: 11 AM - 12 PM ET
Meeting Zoom URL: https://near-org.zoom.us/j/87544657114

NOTE: Please reply to this post to submit questions and discussion items prior to the meeting

1. Review new Account Storage API

/// may be used to deposit funds for caller (predecessor account) or for specified account
///
/// Returns updated balance
///
/// PANICS
/// - if deposit is less than minimum balance
#[payable]
function storage_deposit(account_id: string|null): string;

/// requires 1 yoctoNEAR attached, which is refunded along with withdrawal
///
/// Returns updated balance
///
/// PANICS
/// - if withdrawal results in account balance below minimum balanace
#[payable] 
function storage_withdraw(amount: string): string

/// minimum balance that is required in order for the account to use the contract
function storage_minimum_balance(): string;

function storage_balance(account_id: string): AccountStorageBalance|null;

class AccountStorageBalance {
  total: string;
  available: string;
}

Replaces the need for account registration API because the main problem that account registration was trying to solve was account storage staking cost management. Storage staking costs is a problem for any multi-user contract and is not specific for token contracts.

Questions and Discussion Items

1. How to best handle failures to enable the user to easily recover? If the account performs an action that fails because the available balance was insufficient to cover storage allocation, then the failure should provide enough information to the user to make an informed decision on how to recover? User should know why the action failed. If the action fails because the available balance was insufficient to cover storage staking costs then the user should be provided with the following information:
   • how much storage the action tried to allocate - user may decide to clean up storage as the recovery action
   • how much more funds are required to cover the storage costs
2. Storage prices will change over time - should decrease over time. As storage price decreases, then this should be reflected in available balance.
   • Can storage price be provided by the NEAR runtime environment? Otherwise, it's up to the contract to build in support to adjust storage prices within the contract.
3. The assumption is that storage prices will never increase over time, i.e., it is expected that storage prices will only ever decrease over time. If storage prices were to increase then this would impact the user experience.
4. Contracts may choose to impose stricter restrictions to control access to the account storage API. For example, contracts may require that accounts must be registered to be able to deposit and withdraw funds via the account storage API.

[jasperdg]

What api entry point is used for balancing available? I think some sort of private set_available fn to lock up part of the storage in usage would be a good addition.

[jasperdg]

Would it make sense to do a whiteboard type session where we walk through some examples where we do some cross contract storage accounting. I was just doing some on a whiteboard here and it seems pretty helpful for my understanding.

[oysterpack]

Absolutely - It would be a great way to validate the API design ... especially after the Flux AMM use case exposed problems with the initial account registration API design. We would definitely need at least @evgenykuzyakov and @mikedotexe from the NEAR team for their input.

[oysterpack]

2021-02-05 Standards Review Meeting Meeting Minutes:

• rationale for shifting scope from account registration to account storage standard was discussed
  • account storage staking balance may be variable and accounts may be required to deposit additional funds depending on contract use case, e.g., Flux AMM contract
  • provide ability for accounts to withdraw available balance
• API function prefix name was renamed from as to storage
• consensus was reached on the Account Storage Standard API - see below - please review
• briefly discussed Token Metadata standard open issues:
  • add icon URL
  • remove granularity
  • need for reference hash was raised - still requires further discussion
• ran out of time to discuss questions and issues raised on above agenda - community feedback and thoughts would be appreciated

Account Storage API

Storage staking is an issue that needs to be addressed by any multi-user contract that allocates storage for the
user on the blockchain. Storage staking costs are the most expensive costs to consider for the contract on NEAR. If storage
costs are not managed properly, then they can break the bank for the contract.

On NEAR, the contract is responsible to pay for its long term persistent storage. Thus, multi-user contracts should be
designed to pass on storage costs to its user accounts. The account storage API provides the following:

1. It enables accounts to lookup the minimum required account storage balance for the initial deposit in order to be able
   to use the contract.
2. It enables accounts to deposit NEAR funds into the contract to pay for storage for either itself or on behalf of another
   account. The initial deposit for the account must be at least the minimum amount required by the contract.
3. Account storage total and available balance can be looked up. The amount required to pay for the account's storage usage
   will be locked up in the contract. Any storage balance above storage staking costs is available for withdrawal.

Out of Scope

• Managing funds for purposes other than account storage is outside the scope of this API.
• The contract should account for changes in price for storage on the NEAR blockchain over time. However, how it does so is outside the scope of this contract.

Quick API Overview

// Deposit funds to pay for account storage for the specified `account_id`.
// If the `account_id` is not specified, then it defaults to the `predecessor_id`.
//
// Returns the account's updated balance
#[payable]
function storage_deposit(account_id: string|null): AccountStorageBalance;

// Withdraw the specified amount from the `predecessor_id` available storage balance.
// If no `amount` is specified, then all of the account's available storage balance is withdrawn.
//
// Returns the account's updated balance
#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

function storage_minimum_balance(): string;

function storage_balance_of(account_id: string): AccountStorageBalance;

class AccountStorageBalance {
    total: string;
    available: string;
}

See below for details.

---

Domain Model

class AccountStorageBalance {
    total: string;
    available: string;
}

• total represents the account's total storage balance in yoctoNEAR (in string representation)
• available represents portion of the account's total balance that is available for withdrawal

---

Function

#[payable]
function storage_deposit(account_id: string|null): AccountStorageBalance;

change method

Used by accounts to deposit funds to pay for account storage staking fees. This function supports 2 deposit modes:

1. self deposit (account_id is not specified): predecessor account is used as the account
2. third party deposit (account_id is valid NEAR account ID): the function caller is depositing NEAR funds for the
   specified account_id

If this is the initial deposit for the account, then the deposit must be enough to cover the minimum required balance.
If the attached deposit is more than the required minimum balance, then the funds are credited to the account storage
available balance.

Example Use Cases

1. In order for the account to hold tokens, the account must first have enough NEAR funds deposited into the token contract to pay for the account's storage staking fees. The account can deposit NEAR funds for itself into the token contract, or another contract might have deposited NEAR funds into the token contract on the account's behalf to pay for the account's storage staking fees.
2. Account's may use the blockchain to store data that grows over time. The account can use this API to deposit additional funds to pay for additional account storage usage growth.

Arguments

• account_id - optional NEAR account ID. If not specified, then predecessor account ID will be used.

Returns

The account's updated storage balance.

Panics

• If the attached deposit is less than the minimum required account storage fee on the initial deposit.
• If account_id is not a valid NEAR account ID

---

Function

#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

change method

Used to withdraw NEAR from the predecessor account's storage available balance. If amount is not specified, then all of the account's storage available balance will be withdrawn.

The attached yoctoNEAR will be refunded with the withdrawal transfer.

The account is required to attach exactly 1 yoctoNEAR to the function call to prevent restricted function-call access-key call.

Arguments

• amount - the amount to withdraw from the account's storage available balance expressed in yoctoNEAR (in string representation)

Returns

The account's updated storage balance.

Panics

• If the attached deposit does not equal 1 yoctoNEAR
• If the specified withdrawal amount is greater than the account's available storage balance

---

Function

function storage_minimum_balance(): string;

view method

Used to look up the minimum balance required for the initial deposit.

Returns

Amount in yoctoNEAR (in string representation)

---

Function

function storage_balance_of(account_id: string): AccountStorageBalance;

view method

Used to lookup the account storage balance for the specified account. If the account is unknown to the contract then the total
account storage balance returned will be zero.

Panics

• If account_id is not a valid NEAR account ID

---

[oysterpack]

To be hones, I don't think storage_balance should return null. Zero value: (0, 0) is correct here. In general I try to avoid null values whenever possible - they are dangerous and require additional check.

I don't like null as well, but either way checks are required. At the same time I dislike even more returning a zero value to indicate the absence of a value. In this context, we are saying that the return value is optional. In modern programming languages this is encoded into the type system, e.g., in Rust, we use Option.

AccountStorageBalance|null would be represented as Option<AccountStorageBalance> in Rust. The problem is we are using JavaScript to define the standard API, which ties our hands. We could introduce a wrapper sum type but the tradeoff is more overhead. I think we should define the API to be as efficient as possible. Higher level client libraries can be layered on top of the lower level standard API protocol to make it easier and safer to work with, e.g., providing optional types.

[robert-zaremba]

I dislike even more returning a zero value to indicate the absence of a value

In this case it doesn't indicate an absence of value. It says that you don't have any storage balance. Which is perfect for the use-case.

[robert-zaremba]

BTW: I'm talking here about storage_ functions.

[oysterpack]

your are right - returning zero total storage balance works here if we make no other assumptions (which we shouldn't). I'll update the account storage API

In our last meeting, we discussed using a zero total storage balance to imply that the account is not registered with the contract. That may be a valid assumption, but I don't like making assumptions, especially when I don't have to. The point I am trying to make is that this makes me feel even stronger about having an explicit account registration standard to keep it clean. In order to check if an account is registered, I would prefer to have a direct ar_is_registered(account_id). Using the storage_balance_of(account_id) to check if the account is registered with the contract seems hacky to me.

[robert-zaremba]

So, we need to have ar_unregister and ar_register anyway. We can have ar_is_registered as well.

[robert-zaremba]

Change proposal

Rename storage_balance to storage_balance_of to be consistent with #146

[oysterpack]

Done

[evgenykuzyakov]

Please also update in Quick API Overview

[oysterpack]

Done

[evgenykuzyakov]

I've attempted to use this standard for fixed-size fungible token storage. It somewhat works with limitations. E.g. I require that you deposit only the exact minimum balance and you can withdraw only the exact minimum balance. See https://github.com/near/core-contracts/pull/128/files#diff-1f33dbff2263c13dc7cea606765b6a2326c6c355a6b659f7f22be1262cd3ea70

[evgenykuzyakov]

We can make amount optional, that will be equivalent to withdraw all available.

#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

As we discussed before, we probably DON'T want to have forcing method as part of the standard that erases storage.

[oysterpack]

yes - having optional amount works as well

[oysterpack]

As we discussed before, we probably DON'T want to have forcing method as part of the standard that erases storage.

It sounds like we are talking about 2 different things. Let me clarify what I am trying to say:

#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

• should only be used to withdraw from the account's storage available balance
• there should be no other side effects, i.e., account state should not be deleted from storage as a side effect as a way to "close" or "unregister" the account
• and if you are saying there should be no force option here, then I agree - force is not applicable here

#[payable]
function ar_unregister(force: bool|null);

• is used to unregister the account with the contract
• if force is true, then it overrides normal business rules and the contract is being told to do whatever it takes to unregister the account, even though it may mean that the account may lose some assets.
• when the account is unregistered, the contract deletes the account state from contract storage, refunds escrowed account storage fees, and applies any other contract specific business logic

Do you differ with any of the above or am I missing something?

[robert-zaremba]

I think an app developer can decide to include "unregister" functionality in storage_withdraw(null). It's perfectly fine to do it, because in many cases this is what we will expect and there is no need to make a second transaction. Of course each smart contract will have to document that.

[evgenykuzyakov]

No. As long as storage_withdraw(null) is not the same as account_unregister(force=true). As a user, you shouldn't expect to lose funds (e.g. from the fungible token) when you call storage_withdraw(null).

[oysterpack]

2021-02-12 Standards Review Meeting Agenda

NOTE: Meeting is shortened to 30 minutes for tomorrow due to ETHDenver constraints

1. Review and finalize Account Storage API
2. Fungible Token Metadata API

Please vote on the 2 above APIs with a thumbs up to approve or thumbs down to reject.
If you vote thumbs down, please post a comment to explain the rationale.

---

Account Storage API

Storage staking is an issue that needs to be addressed by any multi-user contract that allocates storage for the
user on the blockchain. Storage staking costs are the most expensive costs to consider for the contract on NEAR. If storage
costs are not managed properly, then they can break the bank for the contract.

On NEAR, the contract is responsible to pay for its long term persistent storage. Thus, multi-user contracts should be
designed to pass on storage costs to its user accounts. The account storage API provides the following:

1. It enables accounts to lookup the minimum required account storage balance for the initial deposit in order to be able
   to use the contract.
2. It enables accounts to deposit NEAR funds into the contract to pay for storage for either itself or on behalf of another
   account. The initial deposit for the account must be at least the minimum amount required by the contract.
3. Account storage total and available balance can be looked up. The amount required to pay for the account's storage usage
   will be locked up in the contract. Any storage balance above storage staking costs is available for withdrawal.

Out of Scope

• Managing funds for purposes other than account storage is outside the scope of this API.
• The contract should account for changes in price for storage on the NEAR blockchain over time. However, how it does so is outside the scope of this contract.

Quick API Overview

// Deposit funds to pay for account storage for the specified `account_id`.
// If the `account_id` is not specified, then it defaults to the `predecessor_id`.
//
// Returns the account's updated balance
#[payable]
function storage_deposit(account_id: string|null): AccountStorageBalance;

// Withdraw the specified amount from the `predecessor_id` available storage balance.
// If no `amount` is specified, then all of the account's available storage balance is withdrawn.
//
// Returns the account's updated balance
#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

function storage_minimum_balance(): string;

function storage_balance_of(account_id: string): AccountStorageBalance;

class AccountStorageBalance {
    total: string;
    available: string;
}

See below for details.

---

Domain Model

class AccountStorageBalance {
    total: string;
    available: string;
}

• total represents the account's total storage balance in yoctoNEAR (in string representation)
• available represents portion of the account's total balance that is available for withdrawal

---

Function

#[payable]
function storage_deposit(account_id: string|null): AccountStorageBalance;

change method

Used by accounts to deposit funds to pay for account storage staking fees. This function supports 2 deposit modes:

1. self deposit (account_id is not specified): predecessor account is used as the account
2. third party deposit (account_id is valid NEAR account ID): the function caller is depositing NEAR funds for the
   specified account_id

If this is the initial deposit for the account, then the deposit must be enough to cover the minimum required balance.
If the attached deposit is more than the required minimum balance, then the funds are credited to the account storage
available balance.

Example Use Cases

1. In order for the account to hold tokens, the account must first have enough NEAR funds deposited into the token contract to pay for the account's storage staking fees. The account can deposit NEAR funds for itself into the token contract, or another contract might have deposited NEAR funds into the token contract on the account's behalf to pay for the account's storage staking fees.
2. Account's may use the blockchain to store data that grows over time. The account can use this API to deposit additional funds to pay for additional account storage usage growth.

Arguments

• account_id - optional NEAR account ID. If not specified, then predecessor account ID will be used.

Returns

The account's updated storage balance.

Panics

• If the attached deposit is less than the minimum required account storage fee on the initial deposit.
• If account_id is not a valid NEAR account ID

---

Function

#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;

change method

Used to withdraw NEAR from the predecessor account's storage available balance. If amount is not specified, then all of the account's storage available balance will be withdrawn.

The attached yoctoNEAR will be refunded with the withdrawal transfer.

The account is required to attach exactly 1 yoctoNEAR to the function call to prevent restricted function-call access-key call.

Arguments

• amount - the amount to withdraw from the account's storage available balance expressed in yoctoNEAR (in string representation)

Returns

The account's updated storage balance.

Panics

• If the attached deposit does not equal 1 yoctoNEAR
• If the account is not registered
• If the specified withdrawal amount is greater than the account's available storage balance

---

Function

function storage_minimum_balance(): string;

view method

Used to look up the minimum balance required for the initial deposit.

Returns

Amount in yoctoNEAR (in string representation)

---

Function

function storage_balance_of(account_id: string): AccountStorageBalance;

view method

Used to lookup the account storage balance for the specified account. If the account is unknown to the contract then the total
account storage balance returned will be zero.

Panics

• If account_id is not a valid NEAR account ID

---

[oysterpack]

2021-02-12 Meeting Minutes

• Account Storage Standard has reached consensus and is considered finalized
• [Fungible Token Metadata Standard2 discussion outcomes
  • FT metadata stored on-chain should be kept minimal and only include medata that is required by smart contracts
  • FT metadata that is required for dApps should be kept off-chain - the reference URL and reference content hash will be stored on-chain
  • reference hash is being stored on chain because the content retrieved from the reference URL cannot be trusted - this provides dApps the option to verify the reference content
  • FOLLOW UP: reference content will require schema to be standardized

Action Items

1. @mikedotexe will pull together Fungible Token standard into a single PR for https://nomicon.io/Standards/Tokens/FungibleToken.html, which is composed using the following of standards:
   • Fungible Token Core Standard
   • Account Storage Standard
   • Fungible Token Metadata Standard defined below
2. @robert-zaremba will publish FT standard to new DeFi Guild repo

Fungible Token Metadata API

class FungibleTokenMetadata {
  name: string,  
  decimals: number,
  reference: string, 
  reference_hash: string, // base64 encoded hash bytes
}

---

Function

function ft_metadata(): FungibleTokenMetadata;

view method

---

[robert-zaremba]

Yes, reference is optional. It's not meant to be uses by a smart contract.

If it's omitted, consumers can assume that reference_hash contains an IPFS content address.

Not at all. Reference might be a resource itself (document string), or a link to external resource- which can be anything: github file, IPFS, S3 ....

We don't and shouldn't make assumptions that the link is IPFS.

[luciotato]

class FungibleTokenMetadata {
  name: string,  
  image: string,  // URL | SVG | IPFS .- useful for wallets
  decimals: number,
  reference: string, 
  reference_hash: string, // base64 encoded hash bytes
}

[oysterpack]

Is reference optional? If it's omitted, consumers can assume that reference_hash contains an IPFS content address. No need for duplicate fields.

What happened with the icon/image field?
a String will be useful. It could be a URL, or a svg, ir IPFS

Reference must not be optional. The whole point of reference was to keep the on-chain metadata minimal to what smart contracts need. However, applications (especially wallets) will require more metadata in order to integrate fungible tokens consistently. The goal is to make it as simple as possible for applications to integrate and use fungible tokens. We can't have 10000 ways to get FT metadata - we need a standard way.

I envision there would be FT client libraries what would make it easy for any app to plugin in the library and work with any FT that is compliant with the standard. It would be a maintenance nightmare for apps and wallets to be able to handle metadata differently for each FT.

The rationale to keep FT metadata off-chain is:

• to enable the metadata schema to evolve overtime in a standard versioned manner
• to offload the metadata storage to off-chain
• to offload the metadata lookup to off-chain

FOLLOW UP: reference content will require schema to be standardized

NOTE: a FOLLOW UP was specified because we need to standardize the reference metadata schema - outside the scope of this standard.

Standardizing the FT metadata schema will enable libraries to be created and solve the problem universally for apps and wallets

[oysterpack]

... how FungibleTokenMetadata::reference and FungibleTokenMetadata::reference_hash is maintained, i.e., updated, on-chain in the FT contract is outside the scope of this standard.

Proper access control needs to be put in place to secure and restrict changes ... access control standards should be a high priority and concern for the community

[luciotato]

FT Metadata is being discussed here: #148