filecoin-project / filecoin-fvm-localnet

A complete filecoin lotus and boost docker image to spin up a localnet for smart contract development

Filecoin FVM localnet

Filecoin FVM Localnet is a complete Filecoin Lotus and Boost Docker image that allows you to spin up a localnet for FVM smart contract development. You can also run two miners for testing things like replication between SPs.

System requirements

ARM64 (e.g. Macbook M1/M2s) or AMD64 (e.g. x86 Linux / Windows / MacOS).

Prerequisites

Ensure you have Docker installed.

Installation

Please note, that running the commands below will result in docker downloading a 3GB image on first run (or 7GB if you choose to run an 8M network). So if you are going to be running this at somewhere with poor or metered internet connectivity, please be aware.

1. Clone this repository:

   git clone https://github.com/filecoin-project/filecoin-fvm-localnet.git

2. Navigate to the repository:

   cd filecoin-fvm-localnet

3. OPTIONAL: Edit the file .env if you wish to optionally run an 8M sector network, otherwise the default 2k sectors will be used

4. To run a single miner instance (default): run Docker compose up:

   cp .env.example .env

   docker compose up

5. To run two miners and two Boost instances (replication): run:

   docker compose --profile replication up

6. To stop the network type ctrl-c.

Once the localnet is started, you can navigate the Boost UI at: http://localhost:8080. If you run in replication mode there is a second Boost instance at: http://localhost:8081.

Metamask and Funding a Wallet

Setting up Metamask

You can configure metamask to connect to this local network by adding a new custom network, with the following steps:

1. Click the network at the top of Metamask

2. Click Add a network manually at the bottom

3. Enter the network information below

   Network name: Filecoin localnet
   New RPC URL: http://127.0.0.1:1234/rpc/v1
   Chain ID: 31415926
   Currency symbol: tFIL
   

Funding a wallet

In order to transact with the network, you will need some funds (tFIL) in your wallet, you can fund a wallet using the lotus command:

1. First find out the t4 address of your wallet from its 0x address shown in Metamask:

   docker compose exec lotus lotus evm stat 0x403D6E3Aff483A3c727Df731c6720A49E36De3eb
   

   Filecoin address:  t410fia6w4ox7ja5dy4t564y4m4qkjhrw3y7ldcn3u3q
   Eth address:  0x403d6e3aff483a3c727df731c6720a49e36de3eb
   Actor lookup failed for faddr t410fia6w4ox7ja5dy4t564y4m4qkjhrw3y7ldcn3u3q with error: resolution lookup failed (t410fia6w4ox7ja5dy4t564y4m4qkjhrw3y7ldcn3u3q): resolve address t410fia6w4ox7ja5dy4t564y4m4qkjhrw3y7ldcn3u3q: actor not found
   

2. Then send some funds to that wallet using the t4 address above:

   docker compose exec lotus lotus send t410fia6w4ox7ja5dy4t564y4m4qkjhrw3y7ldcn3u3q 1000
   

   bafy2bzacecdtzoq6llosskugezsmtlefxjbjww3pddj42iqgqa3vcalgjm6rs
   

   The funds will show up in your metamask wallet in around 45 seconds.

Fill with Metamask Mnemonic

ensure the MNEMONIC .env variable contains your seed phrase

docker cp ./scripts lotus:/app/
docker exec -it lotus bash './scripts/fillAccounts.sh'

Usage notes

• This network has a sector size of 2KiB. This means that the largest storage deals you can make with the miner will be 2KiB. If you want an 8MiB network and storage deals of up to 8MiB, then uncomment the appropriate section in the .env file, delete the data/ directory and restart docker compose.

• The localnet will take a while to start up -- around 5 - 10 minutes depending on how quickly it can download the docker image and initial proof data.

• If you have not started the network for a while, then it may take a while to re-sync with itself. If you wish to avoid the wait and wish to reset the network (losing any local state) then you can delete the data directory.

• This network has a block time of 15 seconds (half the time of Filecoin mainnet).

• Running in 'replication' mode will start up a second Lotus miner instance and a second boost instance connected to it. This allows you to test replication between miners, and smart contracts that need two miners to work.

filecoin-fvm-localnet's Issues

Metamask won't accept network manually: lotus node RPC error

I love the videos, and this is a very cool project.
But I'm stuck at the point trying to connect my Metamask wallet to the localnet.
I'm entering the correct parameters

• 31415926
• http://127.0.0.1:1234/rpc/v1
• tFIL

I do see the instance of Lotus Node is getting hit with a request, but it results in an error

2023-09-08T19:58:32.991+0200    ERROR   rpc     [email protected]/server.go:108 RPC Error: Invalid request
2023-09-08T19:58:32.991+0200    WARN    rpc     [email protected]/server.go:118 rpc error: Invalid request

In Metamask, I get:

Could not fetch chain ID. Is your RPC URL correct?

Interestingly, I get the same error running lotus directly: cloning https://github.com/filecoin-project/lotus, without docker, starting up the daemon.

I suspect it might have to do with the lack of Authorization header.

When I allocate an API token (lotus auth create-token --perm sign), and pass it in via a curl command calling the eth_chainId method, it succeeds, returning the hex version of 31415926. WIthout the header, I get an error.

curl --location 'http://127.0.0.1:1234/rpc/v1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIl19.D5Vjz4S8DVb3MCcU-pLQBXwscrv5Wk0JwnixLrwo5Lg' \
--header 'Content-Type: application/json' \
--data '{"jsonrpc": "2.0",
"method": "eth_chainId",
"params": [],
"id": 1}'

Thank you for any ideas about what I might be doing wrong!

Platform: Ubuntu 22.04, Firefox browser, Metamask 10.34.0

Download size

The default is to run an 8MiB sector size miner. This results in 5.8GB of proof data needed on startup:

matt@Matts-MacBook-Pro filecoin-proof-parameters-8k % du -sh .
5.8G	.

Perhaps we can start with a 2K sector size miner by default, and give the option to run 8M if wanted, as 2K sector size is a lot smaller.

matt@Matts-MacBook-Pro filecoin-proof-parameters % du -sh .
2.0G	.

Also the image itself is 1.5GB. Most of that is the lotus/boost binaries. These are not stripped, and constitute 1.3GB. By stripping this can be reduced down to 783MB:

root@497c71917abc:/usr/local/bin# ls -l 
total 1304520
-rwxr-xr-x 1 root root 179700016 Apr 14 09:45 boost
-rwxr-xr-x 1 root root 189575672 Apr 14 09:48 boostd
-rwxr-xr-x 1 root root 139131032 Apr 14 09:52 booster-bitswap
-rwxr-xr-x 1 root root 145816536 Apr 14 09:51 booster-http
-rwxr-xr-x 1 root root 146361656 Apr 14 09:46 boostx
-rwxr-xr-x 1 root root 199370624 Apr  6 02:59 lotus
-rwxr-xr-x 1 root root 185908304 Apr  6 03:01 lotus-miner
-rwxr-xr-x 1 root root 149914032 Apr  6 03:06 lotus-seed
root@497c71917abc:/usr/local/bin# du -sh .
1.3G	.
root@497c71917abc:/usr/local/bin# strip *
root@497c71917abc:/usr/local/bin# ls -l
total 801416
-rwxr-xr-x 1 root root 112016856 Apr 14 20:20 boost
-rwxr-xr-x 1 root root 119805080 Apr 14 20:20 boostd
-rwxr-xr-x 1 root root  80601576 Apr 14 20:20 booster-bitswap
-rwxr-xr-x 1 root root  85259496 Apr 14 20:20 booster-http
-rwxr-xr-x 1 root root  85657352 Apr 14 20:20 boostx
-rwxr-xr-x 1 root root 129836112 Apr 14 20:21 lotus
-rwxr-xr-x 1 root root 116600240 Apr 14 20:21 lotus-miner
-rwxr-xr-x 1 root root  90854312 Apr 14 20:21 lotus-seed
root@497c71917abc:/usr/local/bin# du -sh .
783M	.

Need to publish new filecoin-fvm-localnet-preproofs-2k image

Can you please publish the latest image for 2k network as we need these fixes for our product filecoin-project/lotus#11123

Container for service "lotus-miner" is unhealthy and fails to start

Description:
I recently experienced an issue with the Docker container running the "lotus-miner" service. Upon tearing down the compose setup using docker-compose down, I've been unable to bring it back up due to an error stating that the container for the "lotus-miner" service is unhealthy.

Steps to reproduce:
Ran docker-compose down to tear down the running setup.
Attempted to bring the setup back up using docker-compose up.
Expected result:
The "lotus-miner" service container should have started normally without any issues.