Local network

This section tutorial how set up and run a local Filecoin network (local-net) with 2 KiB sectors and root key holders using the regular Lotus binaries. A local-net is useful for developing applications and testing features, like Filecoin+ (Fil+).

If you are unfamiliar with the process of setting up and running a local network, it’s highly recommended that you set up a local network without Fil+ first.

Before completing this tutorial, complete the prerequisites.

Complete the prerequisites

Ensure that your system meets the minimum requirements.
Complete the appropriate steps to build the Lotus executables from source based on your operating system:
- Linux
- MacOS
(Optional) Because this tutorial requires multiple terminal windows, install a terminal multiplexer like Tmux.

Now that you’ve completed the prerequisites, set up a Lotus node.

Set up a Lotus node

Filecoin local networks use slightly different binaries than those used in the Filecoin mainnet. This section describes how to set up the Lotus environment and build the binaries.

👉

Remember: Steps marked as Local network with Fil+, such as setting up root key holders and adding notaries, are specific to a local network with the Fil+ feature enabled. Skip these steps if you are setting up a local network without Fil+.

In your terminal, create the following environment variables:

export LOTUS_PATH=~/.lotus-local-net
export LOTUS_MINER_PATH=~/.lotus-miner-local-net
export LOTUS_SKIP_GENESIS_CHECK=_yes_
export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__"
export CGO_CFLAGS="-D__BLST_PORTABLE__"

From the lotus repository, clone the lotus-local-net folder:
```
git clone https://github.com/filecoin-project/lotus lotus-local-net
```
The filecoin-project/lotus repository is the same one that you would use to join the Filecoin mainnet. For this tutorial, you don’t need to clone the entire repository.
Navigate to the lotus-local-net:
```
cd lotus-local-net
```
Checkout to the latest stable branch:
```
git checkout releases
```
👉
Checking out releases will always check out the latest stable release. If you need a specific release, specify a specific <tag_or_release>. For example: git checkout v1.26.0.
Remove any existing repositories.
```
rm -rf ~/.genesis-sectors
```
Build the 2k binary for Lotus:
```
make 2k
```

Fetch the proving parameters for a 2048-byte sector size:

./lotus fetch-params 2048

2021-02-23T10:58:01.469-0500    INFO    build   [email protected]/paramfetch.go:138  Parameter file /var/tmp/filecoin-proof-parameters/v28-proof-of-spacetime-fallback-merkletree-poseidon_hasher-8-0-0-0cfb4f178bbb71cf2ecfcd42accce558b27199ab4fb59cb78f2483fe21ef36d9.vk is ok
...
c261/paramfetch.go:162  parameter and key-fetching complete

This command may take several minutes to complete.

(Local network with Fil+) Build lotus-shed:
```
make lotus-shed
```
(Local network with Fil+) Create a BLS-addresses to serve as the first root key holder:
```
./lotus-shed keyinfo new bls
```
```
t3wjygqclp4bmahoxlf3ncm2pe4m2mray275fqcjgj3l4actndmmpx3wwbxkjwgianbj33mp76ngb542ugtpdq
```
Make a note of this address <root-key-1>, as you will need it in a later step.
(Local network with Fil+) Create a BLS-addresses to serve as the second root key holder:
```
./lotus-shed keyinfo new bls
```
```
t3uzbu6ey3wqop6uesj5tr6g4ntl3rocdymrxfhej2cuwmjmtdvughkhelijcr6rv4ewdghfxxswvqjtit5adq
```
Make a note of this address <root-key-2>, as you will need it in a later step.

Pre-seal 2 sectors for the genesis block:

./lotus-seed pre-seal --sector-size 2KiB --num-sectors 2

sector-id: {{1000 0} 0}, piece info: {2048 baga6ea4seaqoej3hzxzqr5y25ibovtjrhed7yba5vm6gwartr5hsgcbao7aluki}
...
2021-02-23T10:59:36.937-0500    INFO    preseal seed/seed.go:232        Writing preseal manifest to /home/user/.genesis-sectors/pre-seal-t01000.json

Create the genesis block:
```
./lotus-seed genesis new localnet.json
```
This command doesn’t output anything on success.
(Local network with Fil+) Using <root-key-1> and <root-key-2>, set the root key holders in the genesis block with a signature threshold of 2 for the f080 actor:
```
./lotus-seed genesis set-signers --threshold=2 --signers <root-key-1> --signers <root-key-2> localnet.json
```

Create a pre-miner and an address with some funds:

./lotus-seed genesis add-miner localnet.json ~/.genesis-sectors/pre-seal-t01000.json

2022-02-08T15:44:19.734-0500    INFO    lotus-seed      lotus-seed/genesis.go:129       Adding miner t01000 to genesis template 
2022-02-08T15:44:19.734-0500    INFO    lotus-seed      lotus-seed/genesis.go:146       Giving t3xe5je75lkrvye32tfl37gug3az42iotuu3wxgkrhbpbvmum4lu26begiw74ju5a35nveqaw4ywdibj4y6kxq some initial balance

Start the nodes

Now that you’ve set up your Lotus nodes, you can start the lotus and lotus-miner nodes.

Start the first node:

./lotus daemon --lotus-make-genesis=devgen.car --genesis-template=localnet.json --bootstrap=false

This command will continue to run while outputting information.

Leaving the first terminal window open, switch to a second window so that the lotus daemon can continue to run. Complete all further steps in another terminal window.
Because environmental variables are reset when you open a new terminal window, you must re-export the LOTUS_PATH, LOTUS_MINER_PATH, LOTUS_SKIP_GENESIS_CHECK, CGO_CFLAGS_ALLOW and CGO_CFLAGS variables:
👉
Warning: Don’t add the variables to your system-wide settings (/etc/enviroment, /etc/profile.d, etc.), as they will collide with variables in real networks like calibnet or mainnet.
```
export LOTUS_PATH=~/.lotus-local-net 
export LOTUS_MINER_PATH=~/.lotus-miner-local-net
export LOTUS_SKIP_GENESIS_CHECK=_yes_ 
export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__" 
export CGO_CFLAGS="-D__BLST_PORTABLE__" 
```

Import the genesis miner key:

./lotus wallet import --as-default ~/.genesis-sectors/pre-seal-t01000.key

imported key t3xe5je75lkrvye32tfl37gug3az42iotuu3wxgkrhbpbvmum4lu26begiw74ju5a35nveqaw4ywdibj4y6kxq successfully!

Start the genesis miner. This process can take several minutes:

./lotus-miner init --genesis-miner --actor=t01000 --sector-size=2KiB --pre-sealed-sectors=~/.genesis-sectors --pre-sealed-metadata=~/.genesis-sectors/pre-seal-t01000.json --nosync

Miner successfully created, you can now start it with 'lotus-miner run'

Start the lotus-miner:
```
./lotus-miner run --nosync 
```
This command will continue to run while outputting information.
Leaving the second terminal window open, switch to a third window. Complete all further steps in the new terminal window so that the lotus-miner and lotus daemon can continue to run.
Because environmental variables are reset when you open a new terminal window, you must re-export the LOTUS_PATH, LOTUS_MINER_PATH, LOTUS_SKIP_GENESIS_CHECK, CGO_CFLAGS_ALLOW and CGO_CFLAGS variables:
👉
Warning: Don’t add the variables to your system-wide settings (/etc/enviroment, /etc/profile.d, etc.), as they will collide with variables in real networks like calibnet or mainnet.
```
export LOTUS_PATH=~/.lotus-local-net 
export LOTUS_MINER_PATH=~/.lotus-miner-local-net
export LOTUS_SKIP_GENESIS_CHECK=_yes_ 
export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__" 
export CGO_CFLAGS="-D__BLST_PORTABLE__" 
```
(Local network with Fil+) Import the first root key holder address:
```
lotus wallet import bls-<root-key-1>.keyinfo 
```
(Local network with Fil+) Import the second root key holder address:
```
lotus wallet import bls-<root-key-2>.keyinfo 
```

Congratulations! You’ve set up a fully functioning local Filecoin network.

Next steps

Now that your local network is running, you can test various Filecoin features, like adding additional nodes or notaries. Select one of the options below:

Connect multiple nodes
(Local network with Fil+) Add notaries

Connect multiple nodes

In this section, you will add additional nodes to your local network by copying the devgen.car file in your lotus-local-net folder to new nodes. We will have to connect the new node to the original genesis node manually, as there’s no DHT or bootstrapping for your local network. To get started, lets first fetch the address + peer ID in multiaddr format from the genesis node;

./lotus net listen

This should yield a result like so;

/ip4/172.16.100.22/tcp/40395/p2p/12D3KooWAPNpm3n3PTaK2gkaZbCNeaNWMg18eLyxUe9PschraUqk

The port and IP can be configured by using the LIBP2P variables in your config or environment variables. By default, LIBP2P will listen on a random port and on all available IP addresses.

Start a new node:
```
./lotus daemon  --genesis=devgen.car
```
Using the <MULTIADDRESS_OF_THE_FIRST_NODE>, connect the new node to the first node:
```
./lotus net connect <MULTIADDRESS_OF_THE_FIRST_NODE>
```

You should now see your new node getting synchronized with the chain. You can check the progress;

./lotus sync wait

In case you see a success result, but no established connection (e.g. errors in your genesis daemon) - make sure you are using the same genesis block carfile.

Add notaries

In this section, you will add two notaries to your local network with Fil+.

👉

Remember: These steps won’t work if you don’t have a local network with Fil+ set up.

Create a wallet addresses for the first notary <notary-1>:

lotus wallet new secp256k1

t1ek4mmfiulovffg3jen4a3ruaovrvlimhd6dzmjy

Create a wallet addresses for the second notary <notary-2>:

lotus wallet new secp256k1

t1fbmwxevaj6iawvg3idycg77vxdi2b2paps5nn2i

You should now have a list of addresses for two root key holders and two notaries, like the following:

Node type	ID	Address
`<root-key-1>`	t0100	t3uzbu6ey3wqop6uesj5tr6g4ntl3rocdymrxfhej2cuwmjmtdvughkhelijcr6rv4ewdghfxxswvqjtit5adq
`<root-key-2>`	t0101	t3wjygqclp4bmahoxlf3ncm2pe4m2mray275fqcjgj3l4actndmmpx3wwbxkjwgianbj33mp76ngb542ugtpdq
`<notary-1>`	t01003	t1ek4mmfiulovffg3jen4a3ruaovrvlimhd6dzmjy
`<notary-2>`	t01004	t1fbmwxevaj6iawvg3idycg77vxdi2b2paps5nn2i

Have the first root key holder <root-key-1> propose adding <notary-1> to the network as a notary:

./lotus-shed verifreg add-verifier <root-key-1> <notary-1> 10000000

message sent, now waiting on cid: bafy2bzacecegetr32x4jceywpeivbhlahnst4373emx5f3dp6oo4gg4o6sdpc

Inspect the f080 actor to view the parameters needed by <root-key-2> to approve the proposal created in the previous step:

lotus msig inspect f080

Balance: 0 FIL
Spendable: 0 FIL
Threshold: 2 / 2
Signers:
ID      Address
t0100   t3wjygqclp4bmahoxlf3ncm2pe4m2mray275fqcjgj3l4actndmmpx3wwbxkjwgianbj33mp76ngb542ugtpdq
t0101   t3uzbu6ey3wqop6uesj5tr6g4ntl3rocdymrxfhej2cuwmjmtdvughkhelijcr6rv4ewdghfxxswvqjtit5adq
Transactions:  1
ID      State    Approvals  To      Value   Method          Params
0       pending  1          t06     0 FIL   AddVerifier(2)  82550122b8c615145baa529b6923780dc680756355a1874400989680

Using the parameters displayed in the previous step, have the second root key holder <root-key-2> approve the proposal from <root-key-1>:

lotus msig approve  --from=t3wjygqclp4bmahoxlf3ncm2pe4m2mray275fqcjgj3l4actndmmpx3wwbxkjwgianbj33mp76ngb542ugtpdq f080 0 t0101 f06 0 2 82550122b8c615145baa529b6923780dc680756355a1874400989680

sent approval in message:  bafy2bzaceboalihtoo6yds2ptev5ysdkbslc2j5vwgwhl2fr6d6ukee3dzd56

Check that <notary-1> is in the list of notaries:
```
lotus filplus list-notaries
```
```
t01002: 100000
```
To add <notary-2> to your local network, repeat steps 3 through 6.

Grant datacap

In this section, you will grant datacap to a client from a notary.

👉

Remember: These steps won’t work if you don’t have a local network with Fil+ and notaries added on the network.

Grant datacap from <notary-1> to a client, and specify the amount of bytes in datacap you want to give the client.

lotus filplus grant-datacap --from=<notary-1> <client-address> <bytes>

message sent, now waiting on cid: bafy2bzaceacajb2hpk6ywlk7xzghnm2n5rxndhaikwyvuvo2m2taynpaqrclc

FEVM features

Using the Filecoin EVM runtime features within a Lotus node, you can deploy and interact with Solidity contracts on the Filecoin network.

Enable Filecoin EVM runtime features by setting EnableEthRPC to true within your config.toml file:

[Fevm]
  # EnableEthRPC enables eth_ rpc, and enables storing a mapping of eth transaction hashes to filecoin message Cids.
  # This will also enable the RealTimeFilterAPI and HistoricFilterAPI by default, but they can be disabled by config options above.
  #
  # type: bool
  # env var: LOTUS_FEVM_ENABLEETHRPC
   EnableEthRPC = true

Create a new f4 address:

lotus wallet new delegated

f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey

Using the output of the previous command, find the associated Ethereum address using lotus evm stat:

lotus evm stat f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey

Filecoin address:  f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey
Eth address:  0xa7cfe88fe6858e2ba1fe9eaec174be70d38ee2b7
Code cid:  bafk2bzacedfvut2myeleyq67fljcrw4kkmn5pb5dpyozovj7jpoez5irnc3ro

You can also supply lotus evm stat an ethereum address to get the corresponding Filecoin address:

lotus evm stat 0xa7cfe88fe6858e2ba1fe9eaec174be70d38ee2b7

Filecoin address:  f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey
Eth address:  0xa7cfe88fe6858e2ba1fe9eaec174be70d38ee2b7

...

Deploy the testcoin.bin using emv deploy:

lotus evm deploy --from=f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey testcoin.bin

sending message...
waiting for message to execute...
Actor ID: 1008
ID Address: f01008
Robust Address: f2mf75wcwurklloyc6zbrew2wqj4gyiih2cgcwjbi
Eth Address: 0xfe6173918b2448ce93f4710f71a1051e405fdc29
f4 Address: f410f7zqxhemlerem5e7uoehxdiifdzaf7xbjawmljkq
Return: gxkD8FUCYX/bCtSKlrdgXshiS2rQTw2EIPpU/mFzkYskSM6T9HEPcaEFHkBf3Ck=

Call the contract by running the evm invoke command and supplying the ID Address from the previous command and calldata:

lotus evm invoke <ID address> <calldata>

For example:

lotus evm invoke --from=f410fu7h6rd7gqwhcxip6t2xmc5f6odjy5yvxaih7xey f01008 f8b2cb4f000000000000000000000000ff00000000000000000000000000000000000064

sending message...
waiting for message to execute...
Gas used:  2459725
0000000000000000000000000000000000000000000000000000000000000000

If you encounter any issues, you can add a --help or -h behind the cmd you are trying to execute:

NAME:
   lotus evm - Commands related to the Filecoin EVM runtime

USAGE:
   lotus evm command [command options] [arguments...]

COMMANDS:
     deploy            Deploy an EVM smart contract and return its address
     invoke            Invoke an EVM smart contract using the specified CALLDATA
     stat              Print eth/filecoin addrs and code cid
     call              Simulate an eth contract call
     contract-address  Generate contract address from smart contract code
     help, h           Shows a list of commands or help for one command

Edit this page on GitHub

Local network

Complete the prerequisites #

Set up a Lotus node #

Start the nodes #

Next steps #

Connect multiple nodes #

Add notaries #

Grant datacap #

FEVM features #