Skip to content

Latest commit

 

History

History
410 lines (387 loc) · 16.8 KB

fip-0040.md

File metadata and controls

410 lines (387 loc) · 16.8 KB
fip title status type author created updated
40
Enable specified accounts to register FIO Addresses on private FIO Domains
Accepted
Functionality
Pawel Mastalerz <[email protected]>
2022-02-08
2022-09-17

Abstract

The following FIP implements the ability to let domain owners allow specific accounts to register FIO Addresses on specific domains and pay corresponding registration fee.

New actions

Contract Action Endpoint Description
fio.access addperm /add_fio_permission Add new FIO permission.
fio.access remperms /remove_fio_permissions Remove FIO permission.

Modified actions

Contract Action Endpoint Description
fio.address regaddress /register_fio_address Allow FIO Addresses registrations on private FIO Domains, if domain permission was set.
fio.address burnexpired /burn_expired Burn all the associated domain permissions when FIO Domain is burned.
fio.address xferdomain /transfer_fio_domain Burn all the associated domain permissions when FIO Domain is transferred.

New getters

Endpoint Description
/get_grantee_permissions Returns all domain permissions for supplied grantee_account.
/get_actor_permissions Returns all domain permissions for supplied actor.
/get_object_permissions Returns all permissions for supplied object.

Motivation

FIO Chain allows only FIO Domain owner to register FIO Addresses on that domain and there is no way to create a custom permission which would allow another account to do it, assuming you:

  • Want to allow registrations only on a specific domain and not all domains that account owns OR
  • You want the registering account to pay the registration fee

This creates issues when the Foundation is offering to fund initial FIO Address registrations for an integration partner who wants to keep their FIO Domain private. There are several workarounds currently employed, but neither is solving the core problem. It is believed this enhancement would be desirable, not only for the Foundation, but also for any FIO Domain owners.

Specification

New actions

Add permissions

Add specific permission.

Contract: fio.access

New action: addperm

New end point: /add_fio_permission

New fee: add_fio_permission, not bundle-eligible, fee amount will be determined during development and updated here

RAM increase: To be determined during implementation

Request body

Parameter Required Format Definition
grantee_account Yes FIO Chain account Account receiving permission
object_type Yes String Custom name of permission type. Currently supported: regondomain.
object_name Yes String Name associated with object. Currently supported domain name owned by actor. Entering * is allowed and will permit registrations on all current and future domains owned by the signing account.
aux_info Yes String Future use, leave blank.
max_fee Yes Positive Int Maximum amount of SUFs the user is willing to pay for fee. Should be preceded by /get_fee for correct value.
tpid Yes FIO Address FIO Address of the entity which generates this transaction. TPID rewards will be paid to this address. Set to empty if not known.
actor Yes 12 character string Valid actor of signer
Example
{
	"grantee_account": "deshputyz",
	"object_type": "regondomain",
	"object_name": "alice",
	"aux_info": "",
	"max_fee": 0,
	"tpid": "rewards@wallet",
	"actor": "aftyershcu22"
}

Processing

  • Request is validated per Exception handling.
  • add_fio_permission fee is collected.
  • RAM of signer is increased.
  • Check for maximum FIO transaction size is applied.
  • Permission is stored in state.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid Grantee Account Grantee account is invalid or does not exist. 400 "grantee_account" Value sent in, i.e. "123" "Account is invalid or does not exist."
Invalid Object Type Object Type is not regondomain. 400 "object_type" Value sent in, i.e. "123" "Object Type is invalid."
Invalid Object Name Object Name is not a valid domain or *. 400 "object_name" Value sent in, i.e. "123" "Object Name is invalid."
Invalid Aux Info Object Aux Info is not empty. 400 "aux_info" Value sent in, i.e. "123" "Aux Info is invalid."
Fee exceeds maximum Actual fee is greater than supplied max_fee 400 "max_fee" Value sent in, e.g. "1000000000" "Fee exceeds supplied maximum"
Insufficient balance Available balance is less than chain fee 400 "max_fee" Value sent in, e.g. "100000000000" "Insufficient balance"
Invalid TPID tpid format is not valid 400 "tpid" Value sent in, e.g. "notvalidfioaddress" "TPID must be empty or valid FIO address"
Signer not actor Signer not actor 403 Type: invalid_signature

Response body

Parameter Format Definition
status String OK if successful
fee_collected Int Amount of SUFs collected as fee
Example
{
  "status": "OK",
  "fee_collected": 1000000000
}

Remove permission

Remove specific.

Contract: fio.access

New action: remperm

New end point: /remove_fio_permissions

New fee: remove_fio_permissions, not bundle-eligible, fee amount will be determined during development and updated here

RAM increase: To be determined during implementation

Request body

Parameter Required Format Definition
grantee_account Yes FIO Chain account Account receiving permission. May be left blank for all accounts in actor permission set.
object_type Yes String Custom name of permission type. May be left blank for all accounts in actor permission set.
object_name Yes String Name associated with object. May be left blank for all accounts in actor permission set.
aux_info Yes String Future use, leave blank.
max_fee Yes Positive Int Maximum amount of SUFs the user is willing to pay for fee. Should be preceded by /get_fee for correct value.
tpid Yes FIO Address FIO Address of the entity which generates this transaction. TPID rewards will be paid to this address. Set to empty if not known.
actor Yes 12 character string Valid actor of signer
Example
{
	"grantee_account": "deshputyz",
	"object_type": "regondomain",
	"object_name": "alice",
	"max_fee": 0,
	"tpid": "rewards@wallet",
	"actor": "aftyershcu22"
}

Processing

  • Request is validated per Exception handling.
  • remove_fio_permission fee is collected.
  • RAM of signer is increased.
  • Check for maximum FIO transaction size is applied.
  • Permissions are removed from state, if all values match: grantee_account, object_type, object_name, actor.
    • * will remove only the permission with object_name = *
    • Leaving a value blank will act as wildcard and remove all permissions with any value as the blank. See examples below.

Wildcard examples

grantee_account object_type object_name what to remove
deshputyz regondomain alice Only this specific permission: ability for deshputyz to regondomain alice granted by actor.
regondomain alice All permissions on domain alice granted by actor.
All permissions by actor.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Fee exceeds maximum Actual fee is greater than supplied max_fee 400 "max_fee" Value sent in, e.g. "1000000000" "Fee exceeds supplied maximum"
Insufficient balance Available balance is less than chain fee 400 "max_fee" Value sent in, e.g. "100000000000" "Insufficient balance"
Invalid TPID tpid format is not valid 400 "tpid" Value sent in, e.g. "notvalidfioaddress" "TPID must be empty or valid FIO address"
Invalid number of accounts More than X items in permissions array 400 "accounts" "Min 1, Max X accounts are allowed"
Signer not actor Signer not actor 403 Type: invalid_signature
Permission not found Supplied cobination for grantee_account, object_type, object_name, actor does not exist, aka nothing to delete. 404 "Permission not found."

Response body

Parameter Format Definition
status String OK if successful
fee_collected Int Amount of SUFs collected as fee
Example
{
  "status": "OK",
  "fee_collected": 1000000000
}

Modified actions

Register Address

Allow FIO Addresses registrations on private FIO Domains, if domain permission was set.

Contract: fio.address

Action: regaddress

End point: /register_fio_address

Request

Unchanged

Processing

  • Allow FIO Address registration, if domain of FIO Address being registered is set to private and the following permission exists:
    • grantee_account is account registering FIO Address
    • object_type is regondomain
    • object_name is domain of registered FIO Address or *

Response

Unchanged

Burn Expired

Burn all the associated domain permissions when FIO Domain is burned.

Contract: fio.address

Action: burnexpired

End point: /burn_expired

Request

Unchanged

Processing

  • Burn all the associated domain permissions when FIO Domain is burned.
    • object_type is regondomain
    • object_name is domain being burned

Response

Unchanged

Transfer Domain

Burn all the associated domain permissions when FIO Domain is transferred.

Contract: fio.address

Action: xferdomain

End point: /transfer_fio_domain

Request

Unchanged

Processing

  • Burn all the associated domain permissions when FIO Domain is transferred.
    • object_type is regondomain
    • object_name is domain being transferred

Response

Unchanged

New getters

Get grantee permissions

Returns all domain permissions for supplied grantee_account.

New end point: /get_grantee_permissions

Request

Parameter Required Format Definition
grantee_account Yes FIO Chain account Account receiving permission.
limit No Positive Int Number of records to return. If omitted, all records will be returned. Due to table read timeout, a value of less than 1,000 is recommended.
offset No Positive Int First record from list to return. If omitted, 0 is assumed.
Example
{
	"grantee_account": "deshputyz"
}

Processing

  • Request is validated per Exception handling
  • FIO permissions are returned where grantee_account matches the supplied grantee_account

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid Grantee Account Format of Grantee Account is not valid. 400 "grantee_account" Value sent in, i.e. "-123" "Invalid account."
No permissions No permission exists for supplied grantee_account. 404 "Permissions not found."

Response

Group Parameter Format Definition
permissions JSON Array Array of domain permissions
permissions grantee_account Yes FIO Chain account
permissions object_type Yes String
permissions object_name Yes String
permissions aux_info Yes String
permissions actor Yes 12 character string
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"object_type": "regondomain",
			"object_name": "alice",
			"aux_info": "",
			"actor": "aftyershcu22"
		},
		{
			"grantee_account": "deshputyz",
			"object_type": "regondomain",
			"object_name": "bob",
			"aux_info": "",
			"actor": "aftyershcu22"
		}
	],
	"more": 0
}

Get actor permissions

Returns all domain permissions for supplied actor.

New end point: /get_actor_permissions

Request

Parameter Required Format Definition
actor Yes FIO Chain account Account granting permission.
limit No Positive Int Number of records to return. If omitted, all records will be returned. Due to table read timeout, a value of less than 1,000 is recommended.
offset No Positive Int First record from list to return. If omitted, 0 is assumed.
Example
{
	"actor": "aftyershcu22"
}

Processing

  • Request is validated per Exception handling
  • FIO permissions are returned where actor matches the supplied actor

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid actor Format of actor is not valid. 400 "actor" Value sent in, i.e. "-123" "Invalid actor."
No permissions No permission exists for supplied actor. 404 "Permissions not found."

Response

Group Parameter Format Definition
permissions JSON Array Array of domain permissions
permissions JSON Array Array of domain permissions
permissions grantee_account Yes FIO Chain account
permissions object_type Yes String
permissions object_name Yes String
permissions aux_info Yes String
permissions actor Yes 12 character string
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"object_type": "regondomain",
			"object_name": "alice",
			"aux_info": "",
			"actor": "aftyershcu22"
		},
		{
			"grantee_account": "deshputyz",
			"object_type": "regondomain",
			"object_name": "bob",
			"aux_info": "",
			"actor": "aftyershcu22"
		}
	],
	"more": 0
}

Get object permissions

Returns all permissions for supplied object.

New end point: /get_object_permissions

Request

Parameter Required Format Definition
object_type Yes String Custom name of permission type. Currently supported: regondomain.
object_name Yes String Name associated with object. Currently supported domain name owned by actor. Entering * is not allowed.
limit No Positive Int Number of records to return. If omitted, all records will be returned. Due to table read timeout, a value of less than 1,000 is recommended.
offset No Positive Int First record from list to return. If omitted, 0 is assumed.
Example
{
	"object_type": "regondomain",
	"object_name": "alice"
}

Processing

  • Request is validated per Exception handling
  • FIO permissions are returned where object_type matches the supplied object_type and object_name matches supplied object_name or *.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid Object Type Object Type is not regondomain. 400 "object_type" Value sent in, i.e. "123" "Object Type is invalid."
Invalid Object Name Object Name is not a valid domain or *. 400 "object_name" Value sent in, i.e. "123" "Object Name is invalid."
No permissions No permission exists for supplied actor. 404 "Permissions not found."

Response

Group Parameter Format Definition
permissions JSON Array Array of domain permissions
permissions JSON Array Array of domain permissions
permissions grantee_account Yes FIO Chain account
permissions object_type Yes String
permissions object_name Yes String
permissions aux_info Yes String
permissions actor Yes 12 character string
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"object_type": "regondomain",
			"object_name": "alice",
			"aux_info": "",
			"actor": "aftyershcu22"
		},
		{
			"grantee_account": "asdftredg",
			"object_type": "regondomain",
			"object_name": "alice",
			"aux_info": "",
			"actor": "aftyershcu22"
		}
	],
	"more": 0
}

Rationale

Two other approaches were considered:

  • Create an action to specifically enable FIO Address registrations on private FIO Domain since that is the only need now. However, during design a more generic implementation made more sense as it did not introduce significant overhead and will create a frame.
  • Current EOSIO permissions hack to allow the owner of a Domain to specify permission using updateauth and have regaddress action inspect that permission when someone is trying to register a domain. It was not selected due to its "hacky nature". Example:
    • Account A owns Domain D
    • Account A wants to let Account B register (and pay for) FIO Address on Domain D
    • Account A executes updateauth with
      • permission: readdress-DomainD
      • actor: AccountB
    • Account B executes regaddress on DomainD (using its own standard permissions) and regaddress checks standard EOSIO permissions to see if above entry is present for Domain D and allows the registration even though domain is private

Implementation

TBD

Backwards Compatibility

No changes to requests/responses in existing actions or getters.

Future considerations

None

Discussion link

https://fioprotocol.atlassian.net/wiki/spaces/FC/pages/473104421/Enhanced+permissions