fio.oracle Design
Archived. Refer to FIP for final design decisions: https://github.com/fioprotocol/fips/blob/master/fip-0017.md
Links
https://fioprotocol.atlassian.net/wiki/spaces/WP/pages/7012357/Enable+FIO+Token+and+Domain+NFT+wrapping
Tasks
wraptokens
Transfers FIO Tokens to designated FIO account for the purpose of wrapping.
Implementation
Contract: fio.wrapping
New action: wraptokens
New end point: /wrap_fio_tokens
New fee: wrap_fio_tokens, not bundle-eligible
RAM increase: To be determined during implementation
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
amount | Yes | Positive Int | Amount of SUFs to wrap. |
chain_code | Yes | String | Chain code of destination blockchain. |
public_address | Yes | String | Public address on destination blockchain where wrapped token should be delivered. |
max_oracle_fee | Yes | Positive Int | Maximum amount of SUFs the user is willing to pay as Oracle fee. Should be preceded by /get_oracle_fees |
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
{
"amount": 100000000000,
"chain_code": "ETH",
"public_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
"max_oracle_fee": 1000000000,
"max_fee": 1000000000,
"tpid": "rewards@wallet",
"actor": "aftyershcu22"
}
Processing
Request is validated per Exception handling.
Oracle fee is transferred from actor account to all registered oracles in even amount.
Chain wrap_fio_token fee is collected.
RAM of signer is increased
Tokens are transferred to fio.wrapping.
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid amount | Transfer amount is not valid. | 400 | "amount" | Value sent in, e.g. "-1" | "Invalid amount" |
Insufficient balance | Balance is less than amount + oracle fee + chain fee | 400 | "amount" | Value sent in, e.g. "100000000000" | "Insufficient balance" |
Invalid oracle fee value | max_oracle_fee format is not valid | 400 | "max_oracle_fee" | Value sent in, e.g. "-100" | "Invalid oracle fee value" |
Oracle fee exceeds maximum | Actual oracle fee is greater than supplied max_oracle_fee | 400 | "max_oracle_fee" | Value sent in, e.g. "1000000000" | "Oracle fee exceeds supplied maximum" |
Invalid fee value | max_fee format is not valid | 400 | "max_fee" | Value sent in, e.g. "-100" | "Invalid fee value" |
Fee exceeds maximum | Actual fee is greater than supplied max_fee | 400 | "max_fee" | Value sent in, e.g. "1000000000" | "Fee exceeds supplied maximum" |
Invalid TPID | tpid format is not valid | 400 | "tpid" | Value sent in, e.g. "notvalidfioaddress" | "TPID must be empty or valid FIO address" |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
oracle_fee_collected | Int | Amount of SUFs collected as Oracle fee |
fee_collected | Int | Amount of SUFs collected as fee |
Example
{
"status": "OK",
"oracle_fee_collected": 2000000000,
"fee_collected": 2000000000
}
unwraptokens
Transfers FIO Tokens from fio.wrapping to designated FIO account.
Implementation
Contract: fio.wrapping
New action: unwraptokens
Fee: none
RAM increase: To be determined during implementation
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
amount | Yes | Positive Int | Amount of SUFs to unwrap. |
obt_id | Yes | String | Other Blockchain Transaction ID to identify specific transaction which triggers the unwrap. |
fio_address | Yes | String | FIO Address where domain should be delivered. |
actor | Yes | 12 character string | Valid actor of signer |
Example
{
"amount": 100000000000,
"obt_id": "0x399b9129571fee35d450d60fffe3652433b5295b0161e622d2d27b18b04784fe",
"fio_address": "alice@wallet",
"actor": "aftyershcu22"
}
Processing
Request is validated per Exception handling.
If all other Oracles have alreday called unwraptokens for supplied obt_id, amount is transferred from fio.wrapping to account which hashes down from FIO Public Key mapped to supplied FIO Address. If does not exist, it is created.
RAM of signer is increased
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid amount | Transfer amount is not valid. | 400 | "amount" | Value sent in, e.g. "-1" | "Invalid amount" |
Invalid FIO Address | FIO Address is invalid or does not exist | 400 | "fio_address" | Value sent in, e.g. "alice@wallet" | "Invalid FIO Address" |
Insufficient balance | Balance is less than amount | 400 | "amount" | Value sent in, e.g. "100000000000" | "Insufficient balance" |
Not an Oracle | actor is not a registered Oracle | 400 | "actor" | Value sent in, e.g. "aftyershcu22" | "Not a registered Oracle" |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
Example
regoracle
Register Oracle.
Registering oracles
Each Oracle is registered using regoracle action. Only top 21 BPs can register Oracles via an msig.
Implementation
Contract: fio.wrapping
New action: regoracle
Fee: none
RAM increase: none
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
oracle_actor | Yes | 12 character string | Valid actor (account) of oracle. |
actor | Yes | 12 character string | Valid actor of signer |
Example
Processing
Request is validated per Exception handling.
Only top 21 BPs via msig (eosio authority) can register an oracle
oracle_actor is added
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid oracle | Oracle is not valid or does not exist | 400 | "oracle_actor" | Value sent in, e.g. "alice" | "Invalid oracle" |
No authority | The signer does not have authority to register oracles | 403 |
|
| Type: invalid_signature |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
Example
unregoracle
Unregister Oracle.
Implementation
Contract: fio.wrapping
New action: unregoracle
Fee: none
RAM increase: none
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
oracle_actor | Yes | 12 character string | Valid actor (account) of oracle. |
actor | Yes | 12 character string | Valid actor of signer |
Example
Processing
Request is validated per Exception handling.
Only top 21 BPs via msig (eosio authority) can unregister an oracle
oracle_actor is removed
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid oracle | Oracle is not registered | 400 | "oracle_actor" | Value sent in, e.g. "alice" | "Invalid oracle" |
No authority | The signer does not have authority to register oracles | 403 |
|
| Type: invalid_signature |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
Example
setoraclefee
Allows Oracle to set a fee they desire for wrapping.
Implementation
Contract: fio.wrapping
New action: setoraclefee
No fee
RAM increase: To be determined during implementation
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
wrap_fio_domain | Yes | Positive Int | Amount of SUFs the oracle is requesting for wrapping FIO Domain. |
wrap_fio_tokens | Yes | Positive Int | Amount of SUFs the oracle is requesting for wrapping FIO Tokens. |
actor | Yes | 12 character string | Valid actor of signer |
Example:
Processing
Request is validated per Exception handling.
Actor must be registered oracle.
Oracle fees are set
RAM of signer is increased
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid wrap_fio_domain value | wrap_fio_domain format is not valid | 400 | "wrap_fio_domain" | Value sent in, e.g. "-100" | "Invalid wrap_fio_domain value" |
Invalid wrap_fio_tokens value | wrap_fio_tokens format is not valid | 400 | "wrap_fio_tokens" | Value sent in, e.g. "-100" | "Invalid wrap_fio_tokens value" |
Not an Oracle | actor is not a registered Oracle | 400 | "actor" | Value sent in, e.g. "aftyershcu22" | "Not a registered Oracle" |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
Example:
/get_oracle_fees
Returns current fees for wrapping
Implementation
New endpoint: /get_oracle_fees
Request body
None
Processing
Fees are computed and returned
Median is derived for each oracle fee type and multiplied by number of oracles
Example:
Oracle 1
wrap_fio_domain: 2000000000
wrap_fio_tokens: 2000000000
Oracle 2
wrap_fio_domain: 3000000000
wrap_fio_tokens: 5000000000
Oracle 3
wrap_fio_domain: 5000000000
wrap_fio_tokens: 9000000000
Fees are:
wrap_fio_domain: median is 3000000000 x 3 oracles = 9000000000
wrap_fio_domain: median is 5000000000 x 3 oracles = 15000000000
Response body
Parameter | Format | Definition |
|---|---|---|
wrap_fio_domain | Positive Int | Fee to wrap domain in SUFs. |
wrap_fio_tokens | Positive Int | Fee to wrap tokens in SUFs. |
Example
Future release FIP 17.b: wrapdomain
Implementation
Contract: fio.wrapping
New action: wrapdomain
New end point: /wrap_fio_domain
New fee: wrap_fio_domain, not bundle-eligible
RAM increase: To be determined during implementation
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
fio_domain | Yes | FIO Domain | Valid and unexpired FIO Domain. |
chain_code | Yes | String | Chain code of destination blockchain. |
public_address | Yes | String | Public address on destination blockchain where wrapped domain should be delivered. |
max_oracle_fee | Yes | Positive Int | Maximum amount of SUFs the user is willing to pay as Oracle fee. Should be preceded by /get_oracle_fees |
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
Processing
Request is validated per Exception handling.
Oracle fee is transferred from actor account to fio.wrapping.
Chain wrap_fio_domain fee is collected.
RAM of signer is increased
Owner of domain is changed from current account to fio.wrapping.
Action explicitly not taken:
Domain expiration date is not updated
is_public flag is not updated
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid FIO Domain format | FIO Domain format is not valid | 400 | "fio_domain" | Value sent in, e.g. "alice" | "Invalid FIO domain" |
Invalid oracle fee value | max_oracle_fee format is not valid | 400 | "max_oracle_fee" | Value sent in, e.g. "-100" | "Invalid oracle fee value" |
Oracle fee exceeds maximum | Actual oracle fee is greater than supplied max_oracle_fee | 400 | "max_oracle_fee" | Value sent in, e.g. "1000000000" | "Oracle fee exceeds supplied maximum" |
Invalid fee value | max_fee format is not valid | 400 | "max_fee" | Value sent in, e.g. "-100" | "Invalid fee value" |
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 | Balance is less than oracle fee + chain fee | 400 | "max_oracle_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" |
FIO Domain expired | FIO Domain is expired | 400 | "fio_domain" | Value sent in, e.g. "alice" | "FIO Domain expired. Renew first." |
FIO Domain not registered | FIO Domain is not registered | 400 | "fio_domain" | Value sent in, e.g. "alice" | "FIO Domain not registered" |
Not owner of FIO Domain | The signer does not own the domain | 403 |
|
| Type: invalid_signature |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
oracle_fee_collected | Int | Amount of SUFs collected as Oracle fee |
fee_collected | Int | Amount of SUFs collected as fee |
Example
Future release FIP 17.b: unwrapdomain
Transfers FIO Domain from fio.wrapping to designated FIO account.
Implementation
Contract: fio.wrapping
New action: unwrapdomain
Fee: none
RAM increase: To be determined during implementation
Request body
Parameter | Required | Format | Definition |
|---|---|---|---|
fio_domain | Yes | FIO Domain | Valid and unexpired FIO Domain. |
obt_id | Yes | String | Other Blockchain Transaction ID to identify specific transaction which triggers the unwrap. |
fio_address | Yes | String | FIO Address where domain should be delivered. |
actor | Yes | 12 character string | Valid actor of signer |
Example
Processing
Request is validated per Exception handling.
If all other Oracles have alreday called unwrapdomain for supplied fio_domain and obt_id, owner of domain is changed from fio.wrapping to account which hashes down from FIO Public Key mapped to supplied FIO Address. If does not exist, it is created.
EB: Is this a multisig?
RAM of signer is increased
Action explicitly not taken:
Domain expiration date is not updated
is_public flag is not updated
Exception handling
Error condition | Trigger | Type | fields:name | fields:value | Error message |
|---|---|---|---|---|---|
Invalid FIO Domain format | FIO Domain format is not valid | 400 | "fio_domain" | Value sent in, e.g. "alice" | "Invalid FIO domain" |
Invalid FIO Address | FIO Address is invalid or does not exist | 400 | "fio_address" | Value sent in, e.g. "alice@wallet" | "Invalid FIO Address" |
Not an Oracle | actor is not a registered Oracle | 400 | "actor" | Value sent in, e.g. "aftyershcu22" | "Not a registered Oracle" |
Domain not wrapped or not registered | The domain to unwrap is not owned by fio.wrapping or does not exist. | 400 | "fio_domain" | Value sent in, e.g. "alice" | "Domain not wrapped or not registered" |
Response body
Parameter | Format | Definition |
|---|---|---|
status | String | OK if successful |
Example: