Skip to content

Latest commit

 

History

History
404 lines (379 loc) · 17.4 KB

fip-0040.md

File metadata and controls

404 lines (379 loc) · 17.4 KB
fip title status type author created updated
40
Enable specified accounts to register FIO Addresses on private FIO Domains
Final
Functionality
Pawel Mastalerz <[email protected]>
2022-02-08
2024-01-19

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.perms addperm /add_fio_permission Add new FIO permission.
fio.perms remperm /remove_fio_permission 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_grantor_permissions Returns all domain permissions for supplied account.
/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 permission

Add specific permission.

Contract: fio.perms

New action: addperm

New end point: /add_fio_permission

New fee: add_fio_permission, not bundle-eligible, fee amount will be 3 FIO

RAM increase: To be determined during implementation

Request body

Parameter Required Format Definition
grantee_account Yes FIO Chain account Account that is granted and using the permission
permission_name Yes String Custom name of permission. Currently supported: register_address_on_domain.
permission_info Yes String Permission detailed info. This is an optional json string containing specific settings associated with a given permission. For register_address_on_domain this is not set since the existence of the granted permission means to "allow" address creation.
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.
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",
	"permission_name": "register_address_on_domain",
	"permission_info":"",
	"object_name": "alice",
	"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 Permission Name Permission name is not register_address_on_domain. 400 "permission_name" Value sent in, i.e. "123" "Permission name 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 Permission Info Permission Info is not empty. 400 "permission_info" Value sent in, i.e. "123" "Permission 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.perms

New action: remperm

New end point: /remove_fio_permission

New fee: remove_fio_permission, not bundle-eligible, fee amount will be 1 FIO

RAM increase: To be determined during implementation

Request body

Parameter Required Format Definition
grantee_account Yes FIO Chain account Account granted and using the permission.
permission_name Yes String The name of permission. supported register_address_on_domain
object_name Yes String Name associated with object.
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",
	"permission_name": "register_address_on_domain",
	"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, permission_name, object_name, actor.
    • * will remove only the permission with object_name = *

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 Permission Name Permission name is not register_address_on_domain. 400 "permission_name" Value sent in, i.e. "123" "Permission name 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."
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
Permission not found Supplied combination 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 string FIO Chain account. Account receiving permission.
permissions permission_name String Custom name of permission.
permissions object_name String Name associated with object.
permissions permission_info String optional for a permission so this may be blank, detailed permission settings json.
permissions grantor_account 12 character string grantor account
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "alice",
			"grantor_account": "aftyershcu22"
		},
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "bob",
			"grantor_account": "aftyershcu22"
		}
	],
	"more": 0
}

Get grantor permissions

Returns all domain permissions for supplied grantor_account.

New end point: /get_grantor_permissions

Request

Parameter Required Format Definition
grantor_account 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
{
	"grantor_account": "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 grantor account Format of grantor account is not valid. 400 "grantor_account" Value sent in, i.e. "-123" "Invalid grantor account."
No permissions No permission exists for supplied grantor_account. 404 "Permissions not found."

Response

Group Parameter Format Definition
permissions JSON Array Array of domain permissions
permissions grantee_account string FIO Chain account. Account receiving permission.
permissions permission_name String Custom name of permission.
permissions object_name String Name associated with object.
permissions permission_info String optional for a permission so this may be blank, detailed permission settings json.
permissions grantor_account 12 character string Valid grantor account
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "alice",
			"grantor_account": "aftyershcu22"
		},
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "bob",
			"grantor_account": "aftyershcu22"
		}
	],
	"more": 0
}

Get object permissions

Returns all permissions for supplied object.

New end point: /get_object_permissions

Request

Parameter Required Format Definition
permission_name Yes String The name of permission type. Currently supported: register_address_on_domain.
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
{
	"permission_name": "register_domain_on_address",
	"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 Name Object name must be longer than 0. 400 "object_name" Value sent in, i.e. "123" "Object Name is invalid."
Invalid Permission Name Permission name is not a valid permission name. 400 "permission_name" Value sent in, i.e. "123" "Permission Name is invalid."
No permissions No permission exists for supplied object and permission name. 404 "Permissions not found."

Response

Group Parameter Format Definition
permissions JSON Array Array of domain permissions
permissions grantee_account string FIO Chain account. Account receiving permission.
permissions permission_name String Custom name of permission.
permissions object_name String Name associated with object.
permissions permission_info String optional for a permission so this may be blank, detailed permission settings json.
permissions grantor_account 12 character string Valid grantor account
more Int Number of remaining results
Example
{
	"permissions": [
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "alice",
			"grantor_account": "aftyershcu22"
		},
		{
			"grantee_account": "deshputyz",
			"permission_name": "register_address_on_domain",
			"permission_info":"",
			"object_name": "bob",
			"grantor_account": "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

please see the project artifacts including the development specification at https://fioprotocol.atlassian.net/wiki/spaces/FD/pages/555253761/FIP-40+Register+addresses+on+private+domains+access+control

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