FIO Domain Wrapping Operations Manual

Overview

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, Polygon contracts or the Oracle software. See References below for that information.

Polygon gas fees

Operations on the Polygon will require gas.

Oracles

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 Polygon gas fees for wrapping. It is the Oracles' responsibility to convert FIO to MATIC as required to maintain Oracle operations.

Custodians

Custodians do not receive wrapping fees, so the Polygon gas fees should be covered by standard fee income generated by the FIO Chain.

Procedures

Custodians

  • Custodians' responsibilities are:

    • Ensure minimum 3 oracles willing to participate in Wrapping Operations are registered on both the FIO and Polygon Chains. Oracles should be recruited from the 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.

      • Polygon Chain

        • Custodians register and un-register Oracles on the Polygon 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 Polygon 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 Polygon contract and there is a minimum of 7 custodians, but all 21 should be targeted to be added.

      • Custodians register and un-register Custodians on the Polygon contract using regcust and unregcust actions and Polygon public address. These actions are callable individually by then current custodian and are executed once 2/3+1 of then current custodians call the action.

    • Ensure their Polygon private key is secured and has MATIC 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

  • Oracles' responsibilities are:

    • Monitor FIO Chain for wrap transactions

      • When observed, record observation on Polygon Chain using wrap action.

    • Monitor Polygon Chain for unwrap transactions

      • When observed, record observation on FIO Chain using unwrapdomain action.

    • Set Oracle fees on FIO Chain using setoraclefee action. This fee will be paid by FIO users when they want to wrap domains. This fee amount in FIO should be sufficient to cover:

      • Polygon Chain gas fee to wrap

      • FIO Chain unwrap fee.

    • Ensure their Polygon private key is secured and has MATIC 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.

Environment Variables

Oracles will need to set the following environment variables:

General variables:

  • POLLTIME - Seconds between poll for wrap and unwrap events (recommend 60 seconds?)

  • SERVER_URL_HISTORY - URL of FIO history node

FIO chain variables:

  • FIO_ORACLE_PRIVATE_KEY

  • FIO_ORACLE_PUBLIC_KEY

  • FIO_ORACLE_ACCOUNT

  • FIO_ORACLE_ADDRESS

  • POLLOFFSET - The number of wrap transactions to get on FIO side in each call. If you set 20, you can get 20 latest actions on FIO side.

ETH chain variables:

  • ETH_ORACLE_PUBLIC, ETH_ORACLE_PRIVATE - The ETH oracle public and private addresses used for signing ERC20 transactions

ETH gas settings:

  • USEGASAPI (1 - Use the etherscan API, 0 - Use the GASPRICE and GASLIMIT env vars)

  • GASPRICELEVEL - Used to select the high/average/low price on etherscan API for gas pricing.

  • TGASPRICE, TGASLIMIT - Manual gas price and gas limit settings.

Potential Issues and Suggested Resolution

Security and Stability

  • ERC-721 vulnerability or attack

    • Possible mitigation:

      • Custodians to pause Polygon 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.

Wrapping

User is attempting to wrap FIO Domain (FIO->Polygon):

  • Errors on FIO Chain. If user receives errors on the FIO Chain, FIO Domain will not be transferred, so no customer service issue exists.

    • Possible mitigation:

      • Oracles investigate issue.

  • Errors on Polygon Chain. If the Oracle experiences an error when trying to record an observation onto the Polygon Chain using wrap action, it means that the user has sent FIO Domian, but did not receive the ERC-721 token, 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 Polygon chain to ensure the ERC-721 token is delivered to target user.

      • Alternatively, Oracles can unwrap FIO Domain on FIO Chain using unwrapdomain action. This effectively returns the user’s FIO Domain which failed to wrap.

        • fio_address - use FIO Address owned by account which initiated the wrap

        • obt_id - manually set, e.g. 20210604001ReturnDueToFailure - this has to be globally unique and Oracles have to coordinate to all use the same obt_id.

Unwrapping

User is attempting to unwrap FIO Domain (Polygon->FIO):

  • Errors on Polygon Chain. If user receives errors on the Ethereum Chain, ERC-721 token 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 unwrapdomain action, it means that the user has sent ERC-721 token, but did not receive the FIO Domain, 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 Domain is delivered to target user.

      • Alternatively, Oracles can wrap FIO Domain on the Ethereum Chain using wrap action. This will mint new ERC-721 token, but it will effectively be a return of the user’s ERC-721 token tokens which failed to unwrap.

        • address - use Ethereum Public Address which initiated the unwrap

        • obtid - manually set, e.g. 20210604001ReturnDueToFailure - this has to be globally unique and Oracles have to coordinate to all use the same obtid.

Coordination channels

Custodians

Use Mainnet Telegram channel

Oracles

Use FIO Token Wrapping Committee Telegram channel

References

FIO Domain Wrapping project

FIO Domain Wrapping Go-to-market plan

FIO Domain Wrapping Technical Documentation