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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Parameter

Format

Definition

status

String

OK if successful

Example: