Versions Compared

Old Version 8

changes.mady.by.user Eric Butz

Saved on

compared with

New Version 9

changes.mady.by.user Eric Butz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

v1/chain/get_nft_image example

POST:
'{“url”:”https://fio.eosrio.io/v1/chain/get_nft_image”}'

RESPONSE:
'{“image”:”https://imgur.com/exampleimage.png”}'

IPFS Url formatting:
'{“image”:”https://{gatewayURL}/ipfs/{content ID}/{optional path to resource}”}'

Wrap/Unwrap

wrap

Create wFIO on Ethereum chain

Registering oracles

  • wFIO is created using the wrap action

Implementation

  • New action: wrap

Request body

Parameter

Required

Format

Definition

amount

Yes

Positive Int

Amount of wFIO (in SUFs) to unwrap.

eth_address

Yes

String

Public address on ETH blockchain where wrapped FIO should be delivered.

Example

Code Block
{
  "amount": 100000000000,
  "eth_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
}

Processing

  • Request is validated per Exception handling.

  • Consensus required. Transaction is executed when all registered oracles have called wrap (submitted their “observation”).

  • wFIO is minted and transferred to eth_address

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 public address

Recipient public address is not valid

400

"eth_address"

Value sent in, e.g. "notvalidethaddress"

"Invalid public address"

No authority

The signer is not a registered Oracle and does not have authority to call this function

403

"Only a wFIO Oracle may call this function"

Response body

Parameter

Format

Definition

status

String

OK if successful

Example
Code Block
{
  "status": "OK"
}

unwrap

Convert wFIO on Ethereum chain to FIO Tokens on FIO chain.

Implementation

  • New action: unwrap

Request body

Parameter

Required

Format

Definition

amount

Yes

Positive Int

Amount of wFIO (in SUFs) to unwrap.

fio_address

(or Hash of address to save space?)

Yes

String

FIO Address where FIO Tokens should be delivered.

max_oracle_fee?

Yes

Positive Int

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.

Example

Code Block
{
  "amount": 100000000000,
  "": "FIO8k7N7jU9eyj57AfazGxMuvPGZG5hvXNUyxt9pBchnkXXx9KUuD",
  "max_oracle_fee": 1000000000,
  "max_fee": 1000000000,
  "tpid": "rewards@wallet"
}

Processing

  • Request is validated per Exception handling.

  • No Oracle Consensus required.

  • Oracle fee is transferred from actor account to all registered oracles in even amount.

  • wFIO is burned.

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Invalid FIO address

Recipient public address is not valid

400

"eth_address"

Value sent in, e.g. "notvalidethaddress"

"Invalid FIO address"

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"

No authority

The signer is not a registered Oracle and does not have authority to call this function

403

"Only a wFIO Oracle may call this function"

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

Example
Code Block
{
  "status": "OK",
  "oracle_fee_collected": 2000000000
}

Oracles

regoracle

Register Oracle.

Registering oracles

  • Each Oracle is registered by custodians using regoracle action.

Implementation

  • New action: regoracle

Request body

Parameter

Required

Format

Definition

oracleeth_address

Yes

Ethereum public addressSame as FIO account

Ethereum address owned by the Oracle.

Processing

  • Request is validated per Exception handling.

  • Consensus required. Oracle is added after 7 custodians have registered the same Ethereum public address2/3+1 Custodians have called regoracle with same eth_address.

  • Ethereum address is registered as a valid Oracle.

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Invalid oracleaddress

Oracle Ethereum address is not valid or does not exist

400

"oracleeth_actoraddress"

Value sent in, e.g. "alicenotvalidethaddress"

"Invalid oracleaddress"

No authority

The signer is not a registered Custodian and does not have authority to register oracles

403

Type: invalid_signaturecall this function

403

"Only a wFIO custodian may call this function"

Already registered

The Ethereum address is already registered as an Oracle

400

"eth_address"

“Oracle is already registered”

Response body

Parameter

Format

Definition

status

String

OK if successful

Example
Code Block
{
  "status": "OK"
}

unregoracle

Unregister Oracle.

Implementation

  • New action: unregoracle

Request body

Parameter

Required

Format

Definition

oracleeth_address

Yes

Ethereum public address

Ethereum address owned by the Oracle.

Processing

  • Oracle is removed after 7 custodians 2/3+1 Custodians have unregistered the same public Oracle Ethereum addressoracle_actor

  • is removedConsensus required. Oracle is removed after 2/3+1 Custodians have called unregoracle with same oracle_address.

  • Ethereum address is removed as a valid Oracle.

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Invalid oracle

Oracle is not registered

400

"oracleeth_actoraddress"

Value sent in, e.g. "aliceethaddressnotinoracletable"

"Invalid oracle"

No authority

The signer is not a registered Custodian and does not have authority to register oraclescall this function

403Type: invalid_signature

"Only a wFIO custodian may call this function"

Response body

Parameter

Format

Definition

status

String

OK if successful

Example
Code Block
{
  "status": "OK"
}

Custodians

regcust

Register Custodian

Registering

...

Custodians

  • Each Custodian is registered using regcustodianregcust action.

Implementation

  • New action: regcust

Request body

Parameter

Required

Format

Definition

oracleeth_actoraddress

Yes

12 character string

Same as FIO accountEthereum public address

Ethereum address owned by the Custodian.

Processing

  • Request is validated per Exception handling.

  • Consensus required. Custodian is added after 7 2/3+1 custodians have registered the same public Ethereum address.

  • Ethereum address is added as a valid Custodian.

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Invalid oracleaddress

Oracle Ethereum address is not valid or does not exist

400

"oracleeth_actoraddress"

Value sent in, e.g. "alicenotvalidethaddress"

"Invalid oracleaddress"

No authority

The signer is not a registered Custodian and does not have authority to register oraclescall this function

403Type: invalid_signature

"Only a wFIO custodian may call this function"

Already registered

The Ethereum address is already registered as an Custodian

400

"eth_address"

“Custodian is already registered”

Response body

Parameter

Format

Definition

status

String

OK if successful

unregcust

Unregister Custodian.

Implementation

  • New action: unregcust

Request body

Parameter

Required

Format

Definition

oracleeth_actoraddress

Yes

12 character string

Valid actor (account) of oracleEthereum public address

Ethereum address owned by the Custodian.

Processing

  • Request is validated per Exception handling.

  • Consensus required. Custodian is removed after 7 2/3+1 custodians have unregistered registered the same public Ethereum address.

  • Ethereum address is removed as a valid Custodian.

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Invalid oraclecustodian

Oracle Custodian is not registered

400

"eth_address"

Value sent in, e.g. "ethaddressnotincusttable"

"Invalid custodian"

Invalid address

Ethereum address is not valid

400

"oracleeth_actoraddress"

Value sent in, e.g. "alicenotvalidethaddress"

"Invalid oracleaddress"

No authority

The signer is not a registered Custodian and does not have authority to register oraclescall this function

403Type: invalid_signature

"Only a wFIO custodian may call this function"

Response body

Parameter

Format

Definition

status

String

OK if successful

Example
Code Block
{
  "status": "OK"
}