Versions Compared

Old Version 29

changes.mady.by.user Eric Butz

Saved on

compared with

New Version 30

changes.mady.by.user Eric Butz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Links

Overview

  • Oracle code will be run by designated FIO Chain BPs with access to:

    • FIO Chain: Existing FIO BPs already run FIO nodes.

    • Ethereum Chain: Local Ethereum node is preferred, but Infura or Etherscan can also be used.

  • Oracles will:

    • On the FIO Chain

      • Monitor specific account by inspecting every block and looking for FIO contract wraptokens action

      • Execute ERC20 wrap action to mint wFIO to the designated account

    • On the Ethereum Chain

      • Monitor Ethereum smart contract for inbound transfers of ERC-20 wFIO

      • Execute FIO contract unwrap action to transfer FIO to the designated account

Oracle Go Prototype

The original Oracle prototype code was written in Go and is located at: https://github.com/blockpane/fio.oracle

The FIO wrapping/unwrapping contract

The Ethereum ERC20 wrapping/unwrapping contract

Misc. Requirements

...

Issue

...

Summary

...

Decision

...

Storage of latest block number

...

The Oracle is getting the latest action from FIO history every 5 seconds. But when we restart the server, we read the all latest actions and calling wrap function from the start. Of course, it doesn't mint again but I think wrapping time can be long in this case. To prevent this problem, we need to save the latest block number to database or any external storage.what do you think about my suggest?

...

Casey Gardiner should we track block number in the oracleledger table?

  • Suggest that Oracles store a log file of all the transactions locally. If they then go down they can grab a time stamp or transaction ID from the log file to know which transactions have not yet been processed.

  • If an oracle server crashes and the logs are lost, then the oracle would have to re-process all transactions (and rebuild the log file). This would be a one time process.

  • Decision: We will start with using log files, but will ask BPs their opinion on this solution.

...

Admin front-end UI

...

Is there a need for a front-end UI to review different transactions, or can we just rely on table lookups, etc.?

Pawel Mastalerz thoughts?

...

Process a single transaction at a time

...

Given the complexity of validating wrap and unwrap transactions all the way through to finality, both Todd and Alex have suggested that we limit oracles to only process a single transaction at a time

Functionality

There are two main use cases that concern the Oracle, Wrap and Unwrap. These are detailed below.

Watchdog routines

In addition to wrap/unwrap, the Oracle should also have certain watchdog/monitoring routines that ensure the processes and routines executed by the Oracle healthy. For example:

  • Make sure a loop didn’t get stuck.

  • Ensure there are no blocked channels.

  • Ensure the health of the daemon itself.

Wrap

  • Wrap creates wFIO on the Ethereum chain.

  • See the following page for an overview of the Wrap use case: Wrap

...

Functionality

...

Alice (via dApp) called wraptokens inside the fio.oracle contract on FIO chain

...

fio.oracle contract actions:

  • Parameter Validation ( ensuring amount, token codes, pubkey and fees are all properly set )

  • Search oracle registration table (contains all registered oracles) and tally up the total number of registered oracles

  • Collect Oracle fees, sort, and find the median.

  • Send fee to all oracles.

  • Emplace wrapping details inside the oracleldgrs table.

    Image Removed

  • Send the wrapped amount from Alice to fio.oracle contract.

  • Collect BP fees

  • Increase Alices RAM by 512.

  • Send successful response to Alice

...

Oracle monitors wraptokens for transfers

...

  • Method 1: Web socket subscription via Hyperion (similar to Solidity contract subscription).

    • Note this method requires extra setup on the Hyperion node to do streaming.

  • Method 2: Poll fio.oracle actions using V1 history node.

TBD: Both methods require a history node so we should reach out to BPs with the requirements and ask which method they prefer

Finality Check:

  • Oracle should monitor FIO chain for finality by ensuring block number is after the last_irreversible_block.

...

Oracle validates wraptokens transaction. If exceptions are found, Oracle takes action to unwind transaction

See Exception handling below

...

Oracle executes wrap on Ethereum chain

...

wrap(ethaddress, FIO (SUF) amount, obtid);
ex. wrap(“0x00000000000”, 10000000, “0x123456789”);

fio.erc20 contract actions:

  • ethereum wallet provider (usually truffle/hd-wallet-provider) set to use oracles ethereum private key

  • wFIO recipient eth address, wFIO amount to mint (must match what was wrapped on FIO chain exactly), and the obtid of the FIO transaction are provided as parameters to wrap action

  • Transaction is executed

    • address provided receives wrapped FIO assets

    • event emitted:
      wrapped(address ethaddress, uint256 amount, uint256 obtid);

...

Oracle validates wrap transaction

...

  • Oracles monitor all wrap transactions in process to ensure consensus has been reached.

  • If a transaction is stuck in a pre-consensus state for some reason, a rollback should be triggered or a warning event should be thrown.

  • Ensure finality. Don’t end up on a fork.

    • It is common to have transactions go into a mempool, and then transaction ends up in an uncle (orphan) block. If the transaction in the uncle block has not been validated elsewhere, then it should be returned to the mempool. But, there are situations where it can disappear from the mempool.

  • How do transactions leave the memory pool?

  • Why some transactions disappear from the mempool?

  • Err on the side of waiting to make sure the block has reached finality.

  • Only process one transaction at a time to reduce complexity.

...

Once all Oracles have submitted wrap, the wFIO Tokens will be minted and transferred to designated Ethereum public address

...

Table of Contents

Links

Overview

  • Oracle code will be run by designated FIO Chain BPs with access to:

    • FIO Chain: Existing FIO BPs already run FIO nodes.

    • Ethereum Chain: Local Ethereum node is preferred, but Infura or Etherscan can also be used.

  • Oracles will:

    • On the FIO Chain

      • Monitor specific account by inspecting every block and looking for FIO contract wraptokens action

      • Execute ERC20 wrap action to mint wFIO to the designated account

    • On the Ethereum Chain

      • Monitor Ethereum smart contract for inbound transfers of ERC-20 wFIO

      • Execute FIO contract unwrap action to transfer FIO to the designated account

Oracle Go Prototype

The original Oracle prototype code was written in Go and is located at: https://github.com/blockpane/fio.oracle

The FIO wrapping/unwrapping contract

The Ethereum ERC20 wrapping/unwrapping contract

Misc. Requirements

Issue

Summary

Decision

Storage of latest block number

The Oracle is getting the latest action from FIO history every 5 seconds. But when we restart the server, we read the all latest actions and calling wrap function from the start. Of course, it doesn't mint again but I think wrapping time can be long in this case. To prevent this problem, we need to save the latest block number to database or any external storage.what do you think about my suggest?

Casey Gardiner should we track block number in the oracleledger table?

  • Suggest that Oracles store a log file of all the transactions locally. If they then go down they can grab a time stamp or transaction ID from the log file to know which transactions have not yet been processed.

  • If an oracle server crashes and the logs are lost, then the oracle would have to re-process all transactions (and rebuild the log file). This would be a one time process.

  • Decision: We will start with using log files, but will ask BPs their opinion on this solution.

Admin front-end UI

Is there a need for a front-end UI to review different transactions, or can we just rely on table lookups, etc.?

Pawel Mastalerz thoughts?

Process a single transaction at a time

Given the complexity of validating wrap and unwrap transactions all the way through to finality, both Todd and Alex have suggested that we limit oracles to only process a single transaction at a time

Functionality

There are two main use cases that concern the Oracle, Wrap and Unwrap. These are detailed below.

Watchdog routines

In addition to wrap/unwrap, the Oracle should also have certain watchdog/monitoring routines that ensure the processes and routines executed by the Oracle healthy. For example:

  • Make sure a loop didn’t get stuck.

  • Ensure there are no blocked channels.

  • Ensure the health of the daemon itself.

Wrap

  • Wrap creates wFIO on the Ethereum chain.

  • See the following page for an overview of the Wrap use case: Wrap

Functionality

Oracle Initialization

  • Set the initial value of actionIndex = last_irreversible_block number when server starts.

  • TBD: What is the best way to store the actionIndex to persist when an Oracle restarts?

    • See “Storage of latest block number” above

Alice (via dApp) calls wraptokens inside the fio.oracle contract on FIO chain

Example: Calling wraptokens using Cryptonym:

Image Added

fio.oracle contract actions

fio.oracle contract actions:

  • Parameter Validation ( ensuring amount, token codes, pubkey and fees are all properly set )

  • Search oracle registration table (contains all registered oracles) and tally up the total number of registered oracles

  • Collect Oracle fees, sort, and find the median.

  • Send fee to all oracles.

  • Emplace wrapping details inside the oracleldgrs table.

    Image Added

  • Send the wrapped amount from Alice to fio.oracle contract.

  • Collect FIO/BP fees

  • Increase Alices RAM by 512.

  • Send successful response to Alice

Oracle monitors get_actions API on V1 History node

Every 5 seconds Oracle polls the get_actions API on History node Plugin to detect activity on the wrapping account (e.g. "o2ouxipw2rt4")

Code Block
curl -s -XPOST http://44.242.158.42:8080/v1/history/get_actions -d '{
  "account_name": "o2ouxipw2rt4",
  "pos": -1
}'

  1. Retrieve all actions

  2. For each action, if block_num > actionIndex then validate and process the action (call ERC-20 wrap)

  3. Set actionIndex = block_num of most recent wraptokens action

Code Block
const actionIdx = config.oracleCache.get("actionIndex");
          const dataLen = Object.keys(data.data.actions).length;
          var array = Array();
          for (var i = 0; i<dataLen;i++){
            if (data.data.actions[i].block_num > actionIdx) {
                array.push(data.data.actions[i]);
            }
            config.oracleCache.set("actionIndex", data.data.actions[dataLen-1].block_num)
          }
          return array;

TBD:

  • Since there eventually may be very many transactions, it may make sense to walk backward through the table using "pos" and "offset". Maybe you grab the most recent 5 actions and see if any of them are new. If ALL of them are new, then you need to grab the next 5 actions, etc.

Finality:

  • TBD: Should the oracle monitor FIO chain for finality by ensuring block number is after the last_irreversible_block?

Oracle validates the FIO chain wraptokens transaction.

  • See “Exception handling” below

  • Check the actions to confirm it is a wrapping action:

Code Block
if (wrapData[i].action_trace.act.data.memo == "Token Wrapping")

  • TBD: If exceptions are found, what actions does the Oracle take unwind wraptokens action?

Oracle executes wrap on fio.erc20 contract on Ethereum chain

wrap(ethaddress, FIO (SUF) amount, obtid);
ex. wrap(“0x00000000000”, 10000000, “0x123456789”);

fio.erc20 contract actions:

  • ethereum wallet provider (usually truffle/hd-wallet-provider) set to use oracles ethereum private key

  • wFIO recipient eth address, wFIO amount to mint (must match what was wrapped on FIO chain exactly), and the obtid of the FIO transaction are provided as parameters to wrap action

  • Transaction is executed

    • address provided receives wrapped FIO assets

    • event emitted:
      wrapped(address ethaddress, uint256 amount, uint256 obtid);

Oracle validates wrap transaction

  • Oracles monitor all wrap transactions in process to ensure consensus has been reached.

    • Decision: Based on 5/13 discussion with Luke/Pawel/Dev team, only limited monitoring of the transaction on the Ethereum chain is required.

    • All of the following do NOT need to be monitored or tracked by the Oracle:

      • A transaction gets stuck in a pre-consensus state.

      • A transaction disappears (e.g., ending up on a fork, etc.)

        • It is common to have transactions go into a mempool, and then transaction ends up in an uncle (orphan) block. If the transaction in the uncle block has not been validated elsewhere, then it should be returned to the mempool. But, there are situations where it can disappear from the mempool.

      • Waiting to make sure the block has reached finality.

  • TBD: Only process one transaction at a time to reduce complexity?

Once all Oracles have submitted wrap, the wFIO Tokens will be minted and transferred to designated Ethereum public address

Example of three oracles calling wrap:

Code Block
Using these oracle, we call the wrap function on FIO token contract using web3.js like below.
instance.wrap[accounts[5], 10000, "99e20de9bb9f178f3ff1328c089925daff1d5dcb1da7dceaad7fc5126a08eaf5". {from: accounts[1]}); 
instance.wrap[accounts[5], 10000, "99e20de9bb9f178f3ff1328c089925daff1d5dcb1da7dceaad7fc5126a08eaf5". {from: accounts[2]}); 
instance.wrap[accounts[5], 10000, "99e20de9bb9f178f3ff1328c089925daff1d5dcb1da7dceaad7fc5126a08eaf5". {from: accounts[3]});

The last oracle call the _mint function, then the same amount of asset will be mint to designated ERC20 address.

After mint, the event is emitted then we can receive the event and alert to user about wrapping result.

  • Does the oracle do any kind of monitoring or validation of the overall transaction (post consensus?)

    • Decision: Based on 5/13 discussion with Luke/Pawel/Dev team, no additional monitoring of the transaction on the Ethereum chain is required.

  • TBD: What happens if the Oracle does not have enough ETH to cover the transaction? Does it roll back? Does it stay in the queue?

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Oracle Action

Invalid chain

Chain passed to wraptokens action is not Ethereum (Note: this restriction is not enforced in the FIO Contract to allow for wrapping chain expansion without deployment of code)

Oracle triggers unwraptokens action to send FIO back to originating address

TBD: How do other oracle get notified when a transaction is getting unwound?

TBD: What if one oracle approves the transaction and another oracle rejects?

Invalid Ethereum address

Public address passed to wraptokens action is not a valid Ethereum address (Note: this restriction is not enforced in the FIO Contract to allow for wrapping chain expansion without deployment of code)

Oracle triggers unwraptokens action to send FIO back to originating address

...

Functionality

Alice (dApp) executes unwrap on Ethereum chain

unwrap(fio address, amount);
ex. unwrap(hard@edge, 100000000);

fio.erc20 contract actions:

  • Alice provides amount to unwrap and the FIO Address for the oracle to send the FIO to as parameters to unwrap action

  • Alice is paying gas fee for the unwrap

  • Transaction executed:

    • wFIO amount is burned

    • event emitted:
      unwrapped(string fioaddress, uint256 amount);

Oracle monitors unwrap event for transfers

  • Oracle subscribes to fio.erc20 events and reacts to the unwrap event

  • No consensus is required for the unwrap transaction. Any oracle can initiate the FIO unwraptokens action.

    • TBD: How do we prevent multiple oracles from simultaneously initiating unwraptokens?

Oracle validates unwrap transaction

Validation includes:

  • Has another Oracle already initiated the unwraptokens action on the FIO chain?

    • TBD: Other validations?

If exceptions are found, Oracle takes action to unwind transaction

See Exception handling below

Registered Oracles call upwraptokens inside the fio.oracle contract on FIO chain

fio.oracle contract Actions:

  • Parameter Validation ( min/max amount, fio address check )

  • Verify the actor is a registered oracle

  • Find the fio.address inside the fionames table

  • Search for previous votes of the same obt_id

    • If found

      • Search and verify actor has not voted prior

      • copy vector and push account name to list of voted oracles to the vector of votes

      • modify voters table with new vector

    • If not found

      • add actor to new vector

      • emplace new record with voters information

  • Compare number of votes with number of registered oracles

    • if number of votes equal the number of registered oracles, transfer amount from fio.oracle contract to the fio.address provided.

  • Send successful response to the oracle

Oracle validates unwraptokens transaction

  • Oracles monitor all unwraptokens transactions in process to ensure consensus has been reached.

  • If a transaction is stuck in a pre-consensus state for some reason, a rollback should be triggered or a warning event should be thrown.

Once all Oracles have submitted unwraptokens , the FIO Tokens will be transferred to designated Ethereum public address

TBD: Does the oracle do any kind of monitoring or validation of the overall transaction (post consensus?)

Exception handling

Error condition

Trigger

Type

fields:name

fields:value

Error message

Oracle Action

Invalid FIO Address

FIO Address passed in with ERC-20 is not valid or does not exist

Oracle triggers a ERC20 wrap action to send wFIO back to originating address

  • TBD: What event is being monitored for this?