fio.oracle Design
Archived. Refer to FIP for final design decisions: https://github.com/fioprotocol/fips/blob/master/fip-0017.md
Links
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
{
"status": "OK"
}
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
{
"oracle_actor": "aftyershcu21",
"actor": "eosio"
}
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
{
"status": "OK"
}
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
{
"oracle_actor": "aftyershcu21",
"actor": "eosio"
}
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
{
"status": "OK"
}
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 |