The purpose of this document is to define initial recommendation for the operating procedures for running the wrapping operations, which is planned to be conducted by a decentralized group of oracles and custodians, who are also FIO Chain Block Producers. This document is not intended to describe the detailed functionality of the FIO contracts, Ethereum contracts or the Oracle software. See References below for that information.
Operations on the Ethereum Chain will require gas.
Oracles receive FIO tokens every time a user wraps FIO. The amount is set by Oracles themselves and should be set in such a way that it covers all associated costs including Ethereum gas fees for wrapping. It is the Oracles' responsibility to convert FIO to ETH as required to maintain Oracle operations.
Custodians do not receive wrapping fees, so the Ethereum gas fees should be covered by standard fee income generated by the FIO Chain.
Custodians' responsibilities are:
Ensure minimum 3 oracles willing to participate in Wrapping Operations are registered on both the FIO and Ethereum Chains. Oracles are required to be recruited from the top 21 Block Producer population.
FIO Chain
Custodians register and un-register Oracles on the FIO Chain’s fio.oracle contract using regoracle and unregoracle actions. These actions require an msig of 2/3+1 of active BPs.
Ethereum Chain
Custodians register and un-register Oracles on the Ethereum contract using regoracle and unregoracle actions and Ethereum public address. These actions are callable individually by then current custodians and are executed once 2/3+1 of then current custodians call the action.
Ensure that all FIO Chain active Block Producers are registered as custodians on the Ethereum Chain. It is not required that this action happen in real-time as active BPs change on FIO Chain, but should be done periodically, e.g. once a week or month or once major changes occur. Initial 10 custodians will be set at Mainnet launch of Ethereum contract and there is a minimum of 7 custodians, but all 21 should be targeted to be added.
Ensure their Ethereum private key is secured and has ETH to cover gas fees.
Respond to emergency situations which may impact the security or stability of the wrapping infrastructure. See Potential Issues and Suggested Resolution below.
A single custodian is allowed to pause the contract.
2/3+1 is required to un-pause the contract.
Oracles' responsibilities are:
Monitor FIO Chain for wrap transactions
When observed, record observation on Ethereum Chain using wrap action.
Monitor Ethereum Chain for unwrap transactions
When observed, record observation on FIO Chain using unwraptokens action.
Set Oracle fees on FIO Chain using setoraclefee action. This fee will be paid by FIO users when they want to wrap tokens. This fee amount in FIO should be sufficient to cover:
Ethereum Chain gas fee to wrap
FIO Chain unwrap fee. Since a user can unwrap a smaller amount than was originally wrapped, this fee should potentially cover multiple unwraps on the FIO Chain per a single wrap.
Ensure their Ethereum private key is secured and has ETH to cover gas fees.
Ensure proper operation of the oracles
Monitor oracle operations and fix any issues. See Potential Issues and Suggested Resolution below.
A single oracle is allowed to pause the contract.
All oracles are required to un-pause the contract.
Oracles will need to set environment variables as defined in the fio.oracle README: https://github.com/fioprotocol/fio.oracle
If the .env file is updated, the oracle service must be restarted to pull in the latest values.
If an approval is missing for some reason, it is the responsibility of the Oracle to execute a manual approval. The Mainnet Wrapping Status Page contains all of the information needed to execute a manual approval. (Click here for the Testnet Wrapping Status Page)
A command line script is included in the fio.oracle repository that enables manual wrapping and unwrapping of tokens and domains.
The manual scripts must be run on the server where the oracle is running. It uses the oracle functionality to execute the transactions. Success and error information will be logged in the usual oracle log files.
From the fio.oracle root directory:
> npm run oracle
This returns the usage:
Usage: npm run oracle ['wrap'|'unwrap'] ['tokens'|'domain'] [amount|domain] [fio handle or eth address] trxid
Examples:
npm run oracle wrap tokens 12000000000 0xe28FF0D44d533d15cD1f811f4DE8e6b1549945c9 ec52a13e3fd60c1a06ad3d9c0d66b97144aa020426d91cc43565483c743dd320 clean
npm run oracle wrap domain fiohacker 0xe28FF0D44d533d15cD1f811f4DE8e6b1549945c9 ec52a13e3fd60c1a06ad3d9c0d66b97144aa020426d91cc43565483c743dd320 clean
npm run oracle unwrap tokens 12000000000 alice@fiotestnet ec52a13e3fd60c1a06ad3d9c0d66b97144aa020426d91cc43565483c743dd320 clean
npm run oracle unwrap domain fiohacker alice@fiotestnet ec52a13e3fd60c1a06ad3d9c0d66b97144aa020426d91cc43565483c743dd320 clean |
Requests for manual transactions should be posted to the FIO Token Wrapping Committee Telegram channel.
clio -u http://fiotestnet.blockpane.com push action fio.oracle setoraclefee '{
"wrap_fio_domain": 60000000000,
"wrap_fio_tokens": 50000000000,
"actor": "qbxn5zhw2ypw"
}' -p qbxn5zhw2ypw@active |
ERC-20 vulnerability or attack
Possible mitigation:
Custodians to pause Ethereum contract using pause action until issue can be resolved and contract un-paused.
FIO contract vulnerability or attack
Possible mitigation:
Custodians to remove fio.oracle actions from whitelist as required until issue can be resolved and actions added back to whitelist.
User is attempting to wrap FIO to WFIO (FIO->Ethereum):
Errors on FIO Chain. If user receives errors on the FIO Chain, FIO tokens will not be transferred, so no customer service issue exists.
Possible mitigation:
Oracles investigate issue.
Errors on Ethereum Chain. If the Oracle experiences an error when trying to record an observation onto the Ethereum Chain using wrap action, it means that the user has sent FIO, but did not receive the WFIO, creating a customer service issue. Oracles should monitor their nodes to look for errors.
Possible mitigation:
Preferred: Fix and manually resubmit the wrap transaction to the Ethereum chain to ensure WFIO is delivered to target user.
Alternatively, Oracles can unwrap FIO Tokens on FIO Chain using unwraptokens action. This effectively refunds the user’s FIO tokens which failed to wrap.
fio_address - use FIO Address owned by account which initiated the wrap
obt_id - manually set, e.g. 20210604001RefundDueToFailure - this has to be globally unique and Oracles have to coordinate to all use the same obt_id.
User is attempting to unwrap WFIO to FIO (Ethereum->FIO):
Errors on Ethereum Chain. If user receives errors on the Ethereum Chain, WFIO tokens will not be transferred, so no customer service issue exists.
Possible mitigation:
Oracles investigate issue.
Errors on FIO Chain. If the Oracle experiences an error when trying to record an observation onto the FIO Chain using unwraptokens action, it means that the user has sent WFIO, but did not receive the FIO, creating a customer service issue. Oracles should monitor their nodes to look for errors.
Possible mitigation:
Preferred: Fix and manually resubmit the unwrap transaction to the FIO chain to ensure FIO is delivered to target user.
Alternatively, Oracles can wrap FIO Tokens on the Ethereum Chain using wrap action. This will mint new WFIO tokens, but it will effectively be a refund of the user’s WFIO tokens which failed to unwrap.
address - use Ethereum Public Address which initiated the unwrap
obtid - manually set, e.g. 20210604001RefundDueToFailure - this has to be globally unique and Oracles have to coordinate to all use the same obtid.
The nature of the local testing framework requires the use of the 3 producer accounts devtools utilized during the startup procedures.
Keys used during the startup process here:
eosio: 5KBX1dwHME4VyuUss2sYM25D5ZTDvyYrbEz37UJqwAVAsR4tGuY
bp1: EOSUSA
FIO_ORACLE_PRIVATE_KEY = 5KQ6f9ZgUtagD3LZ4wcMKhhvK9qy4BuwL3L1pkm6E2v62HCne2R
FIO_ORACLE_PUBLIC_KEY = FIO7jVQXMNLzSncm7kxwg9gk7XUBYQeJPk8b6QfaK5NVNkh3QZrRr
FIO_ORACLE_ACCOUNT = qbxn5zhw2ypw
ETH_ORACLE_PUBLIC = 0x2bFBc5e0e4ac9CF3dCE2512812Ef7Fa46031b506
ETH_ORACLE_PRIVATE = 6b949ad580282b883c16f04f3c141f7ecbc7a49a405d245a89a32e166800bba1
bp2: Yuriy
FIO_ORACLE_PRIVATE_KEY = 5JnhMxfnLhZeRCRvCUsaHbrvPSxaqjkQAgw4ZFodx4xXyhZbC9P
FIO_ORACLE_PUBLIC_KEY = FIO7uTisye5w2hgrCSE1pJhBKHfqDzhvqDJJ4U3vN9mbYWzataS2b
FIO_ORACLE_ACCOUNT = hfdg2qumuvlc
ETH_ORACLE_PUBLIC = 0xBA08B88cb85e8fDCCdfa2F59A415824d6BD634ca
ETH_ORACLE_PRIVATE = 9ea4cac7b0585354940e7b78630c2d3166ab8e9e3b3f8e69c0d16779bf7adc6b
bp3: EOS DETROIT
FIO_ORACLE_PRIVATE_KEY = 5JvmPVxPxypQEKPwFZQW4Vx7EC8cDYzorVhSWZvuYVFMccfi5mU
FIO_ORACLE_PUBLIC_KEY = FIO6oa5UV9ghWgYH9en8Cv8dFcAxnZg2i9z9gKbnHahciuKNRPyHc
FIO_ORACLE_ACCOUNT = wttywsmdmfew
ETH_ORACLE_PUBLIC = 0xf55C6d387b440Ab78CF3475bD7f8aD7Af9F6716f
ETH_ORACLE_PRIVATE = 76c1a0873d88e693e018ea6e894a0c79f0e7d215655f5f55043ea5d57400e592
backup bp: 5KLxezoCEw5Ca97FHq3HPyrzkmZQT6Wqw9DmKaJ6inE6fiN1ijT
These BPs are typically registered as oracles manually after the launch of the development chain. In the case of the oracles not registered, please use the following command using the eosio permissions:
./clio -u http://localhost:8889 push action fio.oracle regoracle '{"oracle_actor":"qbxn5zhw2ypw","actor":"eosio"}' --permission eosio
Each oracle will be required to vote for fees prior to the activation of the wrapping services. Example of using setoraclefees:
./clio -u http://localhost:8889 push action fio.oracle setoraclefee '{"wrap_fio_domain":2000000000,"wrap_fio_tokens":2000000000,"actor":"qbxn5zhw2ypw"}' --permission qbxn5zhw2ypw
Use Mainnet Telegram channel
Use FIO Token Wrapping Committee Telegram channel
FIO Token Wrapping Go-to-market plan
/wiki/spaces/FO/pages/349569342 (Information on using the Devnet to wrap and unwrap tokens and Domains)
FIO Token Wrapping Technical Documentation