FIPs 36-40 Development Spec

Owned by Ed Rotthoff
Last updated: Feb 22, 2023
10 min read

 

FIP Summary

FIP 36 – changes to the fio repo were delivered. The changes are low risk and very testable.

FIP-37 – changes to the fio.contracts were delivered. The changes are low risk and very testable.

FIP-38 – there are new fees for this FIP. as well as a new ram bump.

we add a contract action to fio.system newfioacc

we add a new endpoint to the chain plugin new_fio_chain_account

Fee : the Fee for this new action will be set identically to the transfer_fio_pub_key call.

2 FIO will be used for dev and rollout. the present fee for transfer pub key is 1.76xxxx FIO, this value should be fine to use for rollout (bps will vote on the fee quickly)….

RAM Bump : the RAM bump will be 0. since we are making an account other than ourselves state use is none. a ram bump value of 0 and standard FIO ram bump logic will be added to permit easy adaptation should a ram bump be needed in the future for any reason for this call.

FIP-39 – this FIP proposes adding a key for the encryption and decryption of OBT content.

the following design approaches are being considered.

 

  1. mentioned in the FIP is the possible use of the token code, chain code, and pub key associated with a FIO address.

this approach has the advantage that it uses existing state structures, adding a new entry to an existing list of entries.

This approach has the following disadvantages

using the existing token code, we must make up a code to use within FIO, this code cannot collide with any token code in the crypto space. if a token comes out that matches our chosen code, then FIO must adapt to use another code instead of the one used.

the repurposing of token code, introduces a novel use of the FIO Public Key mapping which is not standard within the FIO system architecture. We will need to document this and also educate the community on this novel use of the token code.

the novel use of the token code violates best design practices of clearly naming elements within a data model. Since FIO is a usability protocol this novel use of token code seems to conflict with the mission statement of the protocol.

 

2. since this mapping is a new consideration of the FIO protocol providing the notion of an encryption key used by the obt request content, we might consider to add a table to the FIO protocol to hold this mapping going forward.

2a – create a generalized model of data to be associated with a fio address.

we might consider to make a table called handle info which holds data associated with a fio address/handle.

we might consider to have columns in this table address id, datadesc(a unique string descriptor for a data item), and datavalue(a string value for the descriptor). this will permit the FIOprotocol to manage data associated with an address easily (up to about 1k data items per address)

advantages of this approach-- it provides a quick way to lookup the encryption key.

this pattern of meta data describing the record allows the data model to be used flexibly going forward and provides a better ability to extend FIO with other data associated with an address.

the impacts to state are negligible.

add necessary logic to the integration of this approach so that if new data descriptors are added to the table they will not “break” the integration of the encryption key lookup.

 

2b – create a literal model of data to be associated with a fio address

we might consider to make a table called addrdata which holds data associated with a fio address.

we might consider to have literally defined columns in this table (address id, and encryption key.) this will permit the FIOprotocol to manage data associated with an address easily (up to about 1k data items per address)

advantages of this approach-- it provides a quick way to lookup the encryption key.

this pattern of using literal attributes for data describing the record allows the data model to be used flexibly going forward and provides an ability to extend the table by adding binary extensions for new attributes for any new fields to be added.

advantages – this data is much easier to understand and interpret.

disadvantages --

binary extensions have increased complexity of deployment and migration issues as fields are added. (because it changes the get table results and fio users need to understand this and integrate appropriately….

each new item causes a mandatory increase to state size as each record WILL contain the new data field (so state use increases each time a new field is added.

the impacts to state are whenever a new piece of data is added associated with an address then FIO state size will increase by N where N= (number of records in the table * the size of the new attribute).

recommendation --

implement the meta data model and integrate this into the necessary locations.

These options were reviewed with Eric and pawel, and further discussion is welcome,

chosen design and implementation --

the chosen path is 2A

 

FIP-40

this FIP identifies the need for a permission scheme associated with domains. When we consider to design a permission scheme the question becomes, what level of flexibility is desirable for this permission scheme at this moment, in light of the present needs of FIP-40, and in light of the foreseeable needs of the FIO protocol. We can put a large amount of resources and time on the design of these permissions and try to design something very powerful and generic. We can try to analyze existing EOSIO permission schemes and use these. The design phase of the permissions, and the choice we make regarding the design to pursue will impact the timeline of this project by extending it while this is evaluated and implemented. Once its evaluated and implemented, we must test the resulting changes. A more generic design takes more testing, documentation, and time to develop, so this impacts the schedule by extending these areas of the FIP-40 delivery.

 

I had a meeting with pawel, and discussed this. He mentioned that he did analysis on the protocol needs with respect to permissions. He does not personally presently foresee any other needs for this permission scheme. However, since we are putting a scheme into place it will be useful to help to ensure that the design of these permissions is extensible (meaning new permissions can be added if necessary with reasonable effort) and most importantly that these permissions be re-usable in other areas of the FIO protocol for possibly not yet understood purposes.

based on this we will consider design solutions that provide a loose coupling between the permissions and surrounding state information/concepts (domains, fio handles, etc).

details of any approaches will be added here.

 

Design approaches considered.

 

Approach A – design/define a new meta data driven permissions scheme.

 

We can create a new table in the state model called perms. We can identify the attributes of this scheme that may become useful.

Example

table name – perms

table attributes --

uint64 id – the unique id of the permission.

name grantingaccount – the account that is granting the permission.

name assignee account – the account that is being granted the permission.

string name – the name of the permission.

string value – the value of the permission (could become a complex json structure for more complex or hierarchical permissions in the future)

(EX: for register fio handles on domain it might be the domains state table id of the target domain and look like “197654324”, or “*” for all domains)

uint128 grantingassigneenamehash – the 128 bit hash of the granting account (as a string), and the assignee account combined with the permission name.

 

 

indexes.

primary index – id.

secondary indexes

by account – allow retrieval of permissions by account. this permits perhaps up to 1k permissions to be processed per account…

by (granting, assignee) account names and permission – allow retrieval by the 128 bit hash value resulting from hashing of grantingaccount.to_string() + assignee account.to_string()+permission name.

 

 

another table perm names can be made to hold the permitted permissions that can be used.

table – permnames – a table holding the list of premised permission names.

attributes

uint64_t id – unique id for each row (primary key).

string permname – the permission name string.

string description – a description of the permission.

uint128 permnamehash – 128 bit hash of the permission name (secondary key)..

 

example use of info for add domain accounts (this action adds the ability of the specified accounts to register fio names on the specified domains)

{ "fio_domain": "alice", "permissions": [ { "account": "5j1a2jaszjef" }, { "account": "nqvzlysw1bvd" } ], "max_fee": 0, "tpid": "rewards@wallet", "actor": "aftyershcu22" }

 

For this example, the FIO protocol BPs would first add a new permission to the perms called “domainsregisterfionames”, to the permnames talble IE allow this permission to be used in the protocol.

permission name : domainregfiohandle

permission description : “ this permission permits specified accounts to register handles on a domain owned by another account”

 

add domain accounts would verify the ownership of the domain, then add rows into the perms table as necessary, for this example 2 rows would be added.

when one of the assignee accounts calls register fio address, the action will call hasAccess with the permission name and the accounts in question, along with the permission name, the permission name will be verified, then if it is verified then the permission will be checked using the indexing specified above

 

 

Approach B – no permnames table.

in this approach we do everything same as approach A, but we leave out the permnames….

in this approach for our example

the developer would add strings to the contracts…and document them for the new permission names.

the dev hub will be updated to contain detailed info on the new perm and its uses.

 

when one of the assignee accounts calls register fio address, the action will call hasAccess with the permission name and the accounts in question, along with the permission name, the permission name will be verified against a hardcoded string for the permissions that apply (saving a table read!), then if it is verified then the permission will be checked using the indexing specified above

 

 

Approach c

please see the FIP-40 design breakout.

FIP-40 design breakout

 

Links

 

 

Development Branches and PRs

fio.contracts – feature/FIPs36-40-fiocontracts-develop-07202022

fio – feature/FIPS36-40-FIO-DEVELOP-07182022

fio.devtools. – feature/FIPS-36-40-fiodevtools-develop-07252022

fio.test – feature/FIP-36-40-fiotest-develop-07202022

Development testing Procedures and findings

a new test was added to fio.test in the above branch….see this file for dev testing details.

 

 

Design

 

 

Summary of changes to fio and fio.contracts

  • FIP 36.

  • a new getter will be made that implements the following logic.

    • lookup the specified account in the account.

    • please see PR referenced above.

  • FIP 37.

    • the code in the updateauth contract, specifically the include file for the fio.system contract (native.hpp) was modified to remove the checks limiting the number of keys.

  • FIP-38

    • please refer to the PR above, all changes for FIP-38 are delimited with //FIP-38 begin and //FIP-38 end

  • FIP-39 please refer to PR comments delineate changes using FIP-39

    • RAM bump set at same as register address.

Actions and Endpoints

  • please see PR referenced above

Structs and ABIs

  • please see PR referenced above.

Tables

  • FIP-39

    • a new table will be created in the fio.address contract called handleinfo.

      • this table will hold data associated with a fio handle (IE a fio name in the existing data structures).

      • this table will contain the following data attributes

        • ID – uint64 the unique id of the record.

        • fionameid – uint64 this is the id of the handle in the fionames table for which data is to be associated.

        • datadesc – string this is the data descriptor for the data to be associated with the fio handle.

          • values of datadesc – the values allowed in this field will be enforced within the fio.address contract. one value will be permitted “FIO_REQUEST_CONTENT_ENCRYPTION_PUB_KEY”

        • value - string this is the value of the data to be used,

          • the contents of the value attribute will be the public key to use for encryption and decryption of the obt request content.

      • the table will have the following indexes.

        • primary index – id

        • secondary index – fionameid

Risks

  • list the risks of this project.

SDK Requirements

  • list SDK impacts of this project

Performance Testing

  • FIP 36 – no ram impacts of getter.

  • ram use analysis <link to ram usage doc in wiki>

  • please refer to the dev testing plan as it will contain performance testing considerations and tests performed. <link to dev testing guide in wiki>

Fork Testing plan

  • list any fork testing considerations or why these are not in scope.

  • please refer to the testing and integration plan and deployment rollout guides for the project.

  • <add link to testing and rollout plan> <add link to deployment rollout guide>

  • Contract Rollout testing

  • please refer to testing and rollout plan and deployment rollout guides referenced above.

Rollout/Release plan

  • please refer to testing and rollout plan and deployment rollout guides referenced above.

Rollout/Release verification plan

  • please refer to testing and rollout plan and deployment rollout guides referenced above.