Hi team, we are expecting our first Filecoin upgrade in 2023, nv18 Hygge upgrade! This is an exciting upgrade for the Filecoin network and its ecosystem, as we are introducing user programmability to the network, meaning developers can now deploy their smart contracts! As a first milestone for enabling user programmability, **we are launching FEVM - an EVM runtime on top of the FVM (**that’s launched via nv16 Skyr upgrade), and we aim to provide full compatibility with the existing EVM ecosystem and its tooling out of the box. Complete details about the upgrade can be found here and the lotus release schedule can be found here. A couple of key dates:

More about FVM/FEVM

You have now heard about FEVM and might be wondering why this is important and why you want to support this upcoming new type of address(FEVM smart contract) with your FIL integration. Those are good questions and let’s get to it!

Why is this important?

FVM stands to unlock a new range of opportunity areas solidifying Filecoin’s standing as a powerful L1 blockchain. The launch of FVM uniquely positions Filecoin to power an open data economy across a number of opportunity areas:

Why should exchanges care about FVM?

Integration Guide

As a reminder, you can find the general/previous exchange integration guide here. In the sections below, we will walk you through the FEVM-related changes that will require new integration work from you.

<aside> 💡 If you have any questions, feel free to leave a comment on this page directly 💙. Or you can reach out to @jennijuju in the shared slack channel.

</aside>

Node Hardware Spec

We do not expect the new FEVM to increase your node hardware spec requirement.

New address type - f4

So far, you have been working with f1-secp256k1, f2-multisig, and f3-bls addresses, where each of those accounts also has an associated f0-id address. With this upgrade, we introduce a new address class, prefixed with f4 for all new user-defined actor addresses. We then further define that all FEVM-compatible accounts(Ethereum address space) will have the prefix f410. Currently, under the Ethereum address space and modeling Ethereum’s Externally Owned Accounts(EOAs), all Eth accounts, including wallet account addresses AND smart contract addresses, all have their equivalent Filecoin address, again prefixed with f410. You can find more technical details and specs here.

Ethereum addresses (0x) and Filecoin address (f410)

As mentioned above, all Ethereum addresses (accounts or smart contract addresses) have their equivalent Filecoin f410 addresses.

Given that we aim to provide a developer/token holder experience that's fully compatible with the Ethereum ecosystem, token holders or developers shall expect that they can use their existing Ethereum accounts (prefixed with 0x ) to send or receive FIL on the Filecoin network. To get the Filecoin address of an Ethereum address (expand to see more instructions):

Withdraw FIL from the exchange’s account to Filecoin f410 address/Ethereum 0x address.

You can expect token holders to withdraw funds from exchange accounts to f4 addresses. Sending to f4 addresses requires some special steps when constructing the message, see the integration guide below. Further, if you are checking the input address format, include f4 and 0x as valid Filecoin account prefixes!

We also have good reason to believe users will want to withdraw to Ethereum-style addresses (0x), as reported by their Ethereum wallets (e.g. MetaMask)…) directly to receive FIL on the Filecoin network from their exchange Filecoin account. As a result, it would be IDEAL if exchanges could allow token holders to provide an Ethereum account, prefixed with 0x.

Suggested integration steps.

  1. Get the address from the user (the To address), and check if it’s a Filecoin formatted address or an Ethereum-style address. If it's a Filecoin formatted address prefixed with f1 or f2 or f3, go to step 4 . if it’s prefixed with f410, go to step 3. If it's an Ethereum-style address (0x), go to step 2.

  2. If it’s an Ethereum account, convert it to its equivalent Filecoin address, then go to step 3.

  3. When a To address is f410, construct the message as you do today with the following:

    1. To address: the Filecoin f410 address
    2. Method: 3844450837
      1. 3844450837 is the method number of InvokeEVM method, which is the method to be used for handling value transfer to EVM accounts, for both pure value transfer to eth accounts or EVM actors and any contract logic invocation triggered upon contract receiving funds(e.g: ERC-20 token receiver hook).
      2. Based on the To address and its potential contract logic, the gas cost of InvokeEVM may differ. We recommend exchanges apply the same rules as how you handle Ethereum transactions.
    3. Value: the amount of FIL to be transferred indicated by the user

    then go to step 5.

  4. When a To address is prefixed f1 or f2 or f3, KEEP THINGS AS IT IS TODAY - I.e: Method number stays as 0 (a regular Send ). Go to step 5.

  5. Sign and Push the message as you do today!

If you want to confirm your eth address to Filecoin address conversion is working correctly, there are a couple of tools you can use to easily convert an Ethereum address to its Filecoin equivalent and check against (expand to see more instructions):

How to ensure all the deposits to exchange accounts are reflected properly?

Accounts, including exchange accounts, can receive funds in two ways: an “external”, or “top-level” transfer (eg. if f1XXX sends a message to f1ZZZ that transfers 1 FIL), and “internal” transfers” that result from a subinvocation. An example of “internal” transfers in Filecoin today is our multisig support: f1XXX could send a top-level message to a multisig f2YYY, which then transfers 1 FIL to f1ZZZ as a result.

If you already support multisig f2 transactions on Filecoin, then there should be no change for you. However, if this sounds unfamiliar, please keep reading 😉

With the introduction of Eth accounts and user actors, exchanges can expect funds (FIL) to be transferred from some user actors (smart contracts) to exchange accounts. The actor-to-actor calls may also trigger the funds’ transfer.

New builtin actors: EthAccount, EVM, and Placeholder

Some of the exchanges are filtering transactions according to the actor code CIDs. In this upgrade, we will introduce three new actors (all under f410 address class): EthAccount, EVM, and Placeholder. Their actor CIDs will be documented in the lotus v1.20.0 release note, or you can find it here in the final release.

💎 Dual FIL Wallet (f1 + f410|0xwallet per user) - Enable the BEST FIL CEX for ALL Token Holders!

As mentioned above, the design of FEVM & client implementation and tooling around it all enable full compatibility with the existing EVM ecosystem and its tooling out of the box. We expect more Ethereum ecosystem participants to join the Filecoin ecosystem and become FIL Hodlers.

That being said, it would be ideal for existing EVM ecosystem participants, especially dApp users, to be able to transfer FIL from their go-to Ethereum Wallet, like MetaMask. These wallets only accept an Ethereum-styled 0x address, which makes Filecoin native address incompatible and further blocks those token holders from efficiently transferring FIL to their exchange FIL wallet. To mitigate that, we propose exchanges to hold two FIL wallets for each user, one secp256k1 f1 wallet and a secp256k1 f4 wallet with a delegated signature that has 0x -style wallet address pair.

UI mockup

same page

same page

switch tabs/pages/dropdown menu

switch tabs/pages/dropdown menu

Technical Integration

There are two approaches to implementing this:

  1. Only use native Filecoin key management - manage f410 wallets
  1. Introduce Eth keys to Filecoin deposit - manage Eth wallets

FAQ

  1. Does Metamask work with Filecoin?