Improvements to paging via API

This FIP implements the following:

• Adds new API end points for fetching FIO Domains with support for paging
• Adds new API end points for fetching FIO Addresses with support for paging

Motivation

There are currently deficiencies in paging for certain API calls:

• /get_fio_names has no paging at all. If an account has more FIO Domains or FIO Addresses than can be returned before table read time out, only a partial results are returned without warning to the user or ability to retrieve the rest.

Provide ability to cancel a request for funds

This FIP implements the following:

• Adds new API end point and contract action for cancellation of a request for funds.
• Adds a new endpoint which will support paging that is called get_cancelled_requests.
• Adds new check to record obt action in the fio.request.obt contract to check that if the request id is specified, if there is a status of cancelled this is an error.

Motivation

Presently the FIO API does not provide any way for a user to cancel a request for funds they have made:

• It is foreseeable that users will have a desire to cancel newly made requests for funds
• When a user enters errant data (for amounts or memos)
• When events in the users world conspire to render the request irrelevant.
• When a users account has been “hacked” and they wish to cancel fraudulent requests for funds.
• Once we have an ability to cancel, it will be useful to have an api endpoint called get_cancelled_requests.
• Once we have the ability to cancel, we want to check on record obt if the status of the request is cancelled, this is an error, whenever a request id is specified.

Provide ability to remove pub address from the FIO protocol for a user

This FIP implements the following:

• Adds new API end point and contract action to remove selected pub addresses.
• Adds new API end point and contract action to remove all pub addresses.

Motivation

Presently the FIO API does not provide any way for a user to remove public address mappings for a user:

• It is foreseeable that users will have a need to remove pub address mappings
• When a certain token is no longer supported
• Whenever a user might desire to remove a certain mapping from state for privacy reasons.

Enhanced Privacy

Terminology

• Native Blockchain Public Address (NBPA) – this is the public address on a native blockchain that is needed to send funds and is associated to the FIO Address using /add_pub_address
• Payee – is the user receiving funds. In the Send scenario, this is the user who places NBPA on the FIO Chain and allows Payer to see it so that the Payer can send funds using this NBPA. In Request scenario, this is the user sending a FIO Request.
• Payer – is the user sending funds using FIO Address. In the Send scenario, Payer will type a FIO Address in wallet, that wallet will look up the corresponding NBPA on native blockchain and transaction will be executed. In Request scenario, Payer will respond to a FIO Request sent by Payee.
• Sender – is the user sending a transaction on the FIO Chain to another user (Receiver)
• Receiver – is the user receiving a transaction on the FIO Chain from another user (Sender)

Abstract

This FIP implements several new features to enhance privacy of the FIO Protocol:

• It extends the existing FIO Data encryption scheme to include NBPAs to optionally encrypt NBPAs placed on chain.
• It introduces a new way to exchange FIO Requests, FIO Data, and NBPAs, which obfuscates the fact that the users are interacting with each other.
• It consolidates record_obt_data and reject_funds_request into a single priv_record_send_action as to further obfuscate the action which was taken on a FIO Request.

The introduced actions will coexist with existing actions to ensure backwards compatibility.

Motivation

Even though contents of FIO Requests and OBT Records is already encrypted, there are two other areas where privacy of the FIO Protocol can be improved:

• Anytime a FIO Request or OBT Record is stored on chain, the FIO Addresses of both parties are stored unencrypted. This allows blockchain observers to:
  • Associate FIO Addresses transacting with each other, even though the details of those transactions are private.
• NBPAs mapped to FIO Addresses are stored on-chain unencrypted. This allows blockchain observers to:
  • Associate NBPAs to identifiable FIO Addresses.
  • Associate NBPAs on different blockchains belonging to a single individual/entity through a common FIO Address.

Transfer locked tokens

This FIP implements he ability to transfer tokens to a new account and lock those tokens on a pre-defined schedule.

Proposed new actions:

Modified actions:

Motivation

The FIO Protocol includes token locking functionality, which was built specifically to accommodate complex requirements for locking tokens minted at Mainnet. This functionality was not intended to be available post Mainnet.

The original use case was to allow the Foundation to grant or sell tokens with attached locks. During the design, the scope was extended to support the use case of allowing individuals to lock tokens for themselves as savings or for security reasons. However, supporting both use cases added unnecessary complexity and the FIP was scaled down to focus on the original use case. Individual users can still lock their own tokens using functionality developed for this FIP.

Provide ability to burn FIO Address

This FIP implements the ability for owners to burn their FIO Addresses.

Proposed new actions:

Motivation

Presently the FIO Chain burns (removes from state) FIO Addresses after grace period following their expiration dates.

An owner should be able to burn their FIO Address ahead of expiration, if they no longer wish to use it and want to purge all associated data. There are many reasons why someone would want to burn their FIO Address:

• Business/Personal requirements
• Cost effectiveness
• Spam prevention

Public Address Request

This FIP implements the concept of Public Address Request, which allows Payer to request Public Address from Payee prior to send, and for Payee to release that Public Address to the Payer in an encrypted way. It further allows the Payer to allow that Public Address to be used in the future without the need for a Public Address Request for every send.

Proposed new actions:

Modified actions:

Terminology

• Public Address – this is the Public Address on a native blockchain that is needed to send funds and is associated to the FIO Address using /add_pub_address
• Payer – is the user sending funds using FIO Address. In the Send scenario, this is the user initiating payment.
• Payee – is the user receiving funds. In the Send scenario, this is the user who receives the payment.

Motivation

FIP-5 Enhanced privacy via friending proposes to improve FIO Protocol privacy in two areas:

1. Public Addresses mapped to FIO Addresses are stored on-chain unencrypted.
2. Anytime a FIO Request or OBT Record is stored on chain, the FIO Addresses of both parties are stored unencrypted.

The solution proposed in FIP-5 is arguably complex, both in terms of blockchain code, but, more importantly, in terms of wallet integration. This FIP proposes that issue #1 is the primary privacy concern that should be addressed and that issue #2 should not be addressed at this time to substantially reduce complexity.

Issue #1 could be solved by allowing Payer to first Request Public Address from Payee on-chain with optional encrypted metadata, and then allowing the Payee to Release Public Address on-chain, where the Public Address is encrypted for the Payer. There is no need for a Friend’s List or complex hashing to derive search indexes.

In addition, Public Address Request may have other useful applications. It may allow the Payee to withhold the release of the public address, preventing receipt of funds, until certain information is received. For example, a crypto exchange may not allow a deposit to occur until they have received information about the counter party, in order to comply with the Travel Rule.

Allow voting and proxying without a FIO Address

This FIP enables token holders to vote or proxy without requiring them to have a registered FIO Address.

Modified actions:

Motivation

In order to make voting/proxying “free” to users to encourage them to vote/proxy, the voteproducer and voteproxy actions require FIO Address, as FIO Address is needed to allow payment with bundled transactions instead of tokens. However, it introduced the requirement that the token holder have a FIO Address in order to vote/proxy. As recommended in Issue 47 it makes sense to also allow voting/proxying even when token holder does not have a FIO Address.

Redesign Fee Computations

This FIP implements a redesign of the fee voting and computation, and bundled transaction voting and computation in the FIO Protocol. Specifically:

• Fee computation will be removed from onblock and from setfeevote and setfeemult and attached to a dedicated action/endpoint.
• Top 42 block producers will be permitted to vote for fees and bundled transactions.
• A fee will be collected whenever a setfeevote, setfeemult is executed, and bundlevote
• Only votes of top 21 block producers will be used to compute the fees and bundled transactions.

Proposed new actions:

Modified actions:

Motivation

The FIO Protocol was designed to enable top 21 producers to vote on protocol fees and bundled transactions via setfeevote, and setfeemult.

The computation of fees occurs after every setfeevote or setfeemult. The fees are also recomputed in the onblock every 126 blocks.

It has been found that the processing required to compute fees is too large to be handled in onblock or attached to action of setting fees, especially if number of block producers allowed to vote is increased beyond top 21, which has been discussed in Issue 147 and now part of this FIP.

To address this issue, a new endpoint dedicated to fee computation should be implemented. This will follow the same approach as other areas of the FIO Protocol, such as burning of expired addresses, and claiming of rewards.

Ehnhance bundled transaction usability

This FIP implements enhancements to the way bundled transactions are acquired and used. Specifically:

• Adds ability to transfer FIO tokens using FIO Address and paying with bundled transactions.
• Adds ability to purchase multiple sets of bundled transactions in single action.

Proposed new actions:

Motivation

Bundled transactions make it easier for everyday users to interact with the FIO Protocol. Users pay a single annual fee for the FIO Address and get with it enough bundled transactions to cover an average amount of annual interaction with the FIO Chain.

There are a couple of improvements which can further enhanced the usability:

• FIO token transfer does not currently support the use of bundled transactions. This was primarily, because bundled transactions require a FIO Address and the base FIO token transfer action, trnsfiopubky, transfers tokens using public key. It could be enhanced to allow for optional FIO Address of sender, but in order to maintain backwards compatibility, a new action/end-point is a better option. In addition, it was always envisioned that ability to transfer FIO tokens using FIO Address and combining record_obt_data into the same call was a beneficial feature. Currently if a user wants to send FIO tokens to another user and attach a memo, they have to execute 2 transactions: trnsfiopubky and recordobt.
• Users who process more transaction than the annual amount of bundled transactions can either pay a per transaction fee for all additional transactions or renew their FIO Address early, which adds new bundle of transactions and extends FIO Address expiration date. However, heavy users will have to run multiple renewals in sequence. A better approach would be to allow ability to purchase multiple sets of bundled transactions in a single blockchain transaction.

Move action whitelisting into state

This FIP moves action whitelisting into state, so that new actions being added to the FIO Protocol do not require a coordinated FIO Chain software update.

Proposed new actions:

Motivation

This FIO protocol uses a whitelist of actions to prohibit unknown actions from spamming the network. The whitelist is implemented in the FIO Protocol core code. This means that any new action added to the FIO Protocol needs to be added to the whitelist and that requires a mandatory upgrade of the FIO Chain software. This is undesirable because it requires coordinated deployment of new software version to avoid hard fork. A better approach is to enable modifications to the whitelist via on-chain contract update performed by consensus of top 21 Block Producers.

Ability to retrive all public addresses for a FIO Address

This FIP implements ability to easily fetch all public address mapped to a provided FIO Address.

Proposed new actions:

Motivation

Currently, the /get_pub_address API method returns only the public address for specific chain and token code. This works great for a look-up of a specific token code, but it’s not practical for a wallet wanting to fetch and display all public address mappings to the owner of the FIO Address. Even though the mappings can be fetched using /get_table_rows, this call requires index computation, and therefore a native API method is desirable.

Ensuring API response data integrity.

Abstract

Pending

Motivation

Today, most integrators rely on a single API node (recommended to be hosted and secured by the integrator) to retrieve information from the FIO Chain. As with other chains that is acceptable for most data reads, but is risky when reading information which is then used to execute an irreversible transaction on another blockchain, such as payment public address. Specifically:

• get_pub_address returns public address for specific blockchain mapped to a FIO Address.
• get_pending_fio_requests returns public address for specific blockchain where Payee wants funds to be sent. Even though that information is encrypted, the public key required for decryption is sent along in the request.

It is desirable for payment public address to be returned to the wallet in a way, which can guarantee it has not been tempered with.

Specification

High-level definition of solution

Securely obtain and store list of known Block Producers (BPs)

• The integrator would hard-code a list of known (BPs) and would regularly update this list with new software releases and upgrades to the SDKs.
• The integrator would query a single API endpoint (new endpoint to be implemented as part of this FIP) to receive a list of BP schedule updates and corresponding block number of when they occurred.
• The integrator would fetch the corresponding block and its transactions as well as X blocks following that block and:
  • Verify that the block was part of chain signed by 2/3+1 of known BPs.
  • Add any new BP to list of known BPs.

Securely fetch data from FIO Chain

• BPs will post their API node address on-chain as part of BP registration
• The integrator would send API query to 2/3+1 BP API nodes.
• The API node would look-up the data, and return it signed with their BP signing key.
• Once the integrator receives content signed by 2/3+1 known BPs, the data is guaranteed by the consensus of the chain to not had been tampered with.

Chain and token code standard

Abstract

This FIP proposes a standard way to code chain and token codes as well as multi-level addressing parameters in FIO Protocol.

Motivation

Given the decentralized nature of blockchains, there is no standard on what code represent what blockchain or token on that blockchain. For example, Kraken crypto-exchange identifies Bitcoin as XBT, while most other exchanges use the code BTC. This creates a potential issue for users of FIO Protocol, because a wallet executing a send to another wallet using FIO Address does not know what coding convention the receiving wallet is using and therefore does not know what codes to specify in the get_pub_address method.

FIO Protocol does not validate token or chain codes against any list, nor should it. This makes FIO Protocol flexible enough to support any new chain or token code immediately after its creation. SLIP-44 has often been cited in FIO Protocol documentation as one of the industry standards to follow. Unfortunately SLIP-44 is primarily used for path derivation and hence mostly supports chains and not tokens.

In addition, FIO Protocol supports the use of Multi-level Addressing which allows for specification of additional attributes which may be required for send, such as memo or destination tags.

Wallets and exchanges integrating FIO Protocol have expressed interest in creating a master list of chain, token codes and multi-level addressing attributes that are being used by FIO Participants to ensure both sending and receiving wallets are using the same coding convention.