...
The Ethereum wrapping/unwrapping contract specification is detailed on the wiki: fio.erc20 - wFIO Contract Specification
Github fio.erc20
repository: https://github.com/fioprotocol/fio.erc20
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? |
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? |
| | |
| | |
Functionality
There are two main use cases that concern the Oracle, Wrap and Unwrap. These are detailed below.
...
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. 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 | 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 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 | TBD: Does the oracle do any kind of monitoring or validation of the overall transaction (post consensus?) 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:
|
Oracle monitors unwrap event for transfers | |
Oracle validates unwrap transaction | Validation includes: |
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
Compare number of votes with number of registered oracles 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 |
| | | | | | |
| | | | | | |