From 17d4f340af3741a0384e5955080baac77dd01ad9 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 04:24:13 +0200 Subject: [PATCH 01/19] Update ipc-agent commands --- README.md | 117 ++++++++++++++++++++++++------------------------------ 1 file changed, 51 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index a829e030..62bc8d77 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ If you meet any obstacles or need help, please join us in **#ipc-help** in the [ ### Build requirements To build the IPC Agent you need to have Rust installed in your environment. The current MSRV (Minimum Supported Rust Version) is nightly-2022-10-03 due to some test build dependencies. A working version is tracked in rust-toolchain (this is picked up by rustup automatically). You can look for instructions on [how to run Rust and rustup following this link](https://www.rust-lang.org/tools/install). -> According to the operating system you are running, you may have to install additional dependencies not installed in your system to follow these instructions like `build-essentials`, `libssl-dev`, `git`, `curl`. If something fails while building the binaries double-check these dependencies. +> According to the operating system you are running, you may have to install additional dependencies not installed in your system to follow these instructions like `build-essential`, `libssl-dev`, `git`, `curl`, and `pkg-config`. If something fails while building the binaries double-check these dependencies. ### Build instructions To build the binary for the IPC agent you need to build the requirements in your environment, clone this repo, and build the binary following these steps: @@ -31,23 +31,13 @@ The IPC agent command line tool Usage: ipc-agent [OPTIONS] Commands: - daemon Launch the ipc agent daemon - reload-config Config commands - init-config Arguments to initialize a new empty config file - create-subnet Subnet manager commands - list-subnets List child subnets - join-subnet Join a subnet - leave-subnet Leaving a subnet - kill-subnet Kill an existing subnet - fund Send funds from a parent to a child subnet - release Release operation in the gateway actor - propagate Propagate operation in the gateway actor - whitelist-propagator Whitelist propagators in the gateway actor - send-value Send value to an address within a subnet - wallet-new Create new wallet in subnet - set-validator-net-addr Set the validator net address - list-checkpoints List checkpoints - help Print this message or the help of the given subcommand(s) + daemon Launch the ipc agent daemon + config config related commands + subnet subnet related commands such as create, join and etc + wallet wallet related commands + cross-msg cross network messages related commands + checkpoint checkpoint related commands + help Print this message or the help of the given subcommand(s) Options: -c, --config-path The toml config file path for IPC Agent, default to ${HOME}/.ipc-agent/config.toml @@ -117,7 +107,7 @@ $ git checkout $ make spacenet # Run your node -$ ./eudico mir daemon --bootstrap=true +$ ./eudico mir daemon --bootstrap ``` With this, your node should automatically connect to the bootstraps of the network and start syncing the latest state of the chain. @@ -126,7 +116,7 @@ With this, your node should automatically connect to the bootstraps of the netwo With the node running, you are ready to connect the IPC agent to Spacenet. For this, you'll need to get an authentication token for your node, and point to the RPC API of the node (by default running on port `1234`). ```bash # Generate auth token to node -$ ./eudico auth create-token --perm admin +$ ./eudico auth token create--perm admin eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.8vIV7pCrWx-nxOBAAw_IayDzrGf22kMjagRYmj_8Qqw ``` @@ -154,7 +144,7 @@ You can now start your IPC agent daemon with `./bin/ipc-agent daemon` .If you ar To check if the agent has been connected to Spacenet successfully you can try creating a new wallet in the network, but this type through the agent by running: ```bash -./bin/ipc-agent wallet-new --key-type=bls --subnet=/root +./bin/ipc-agent wallet new --key-type bls --subnet /root 2023-03-30T12:01:11Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t1om5pijjq5dqic4ccnqqrvv6zgzwrlxf6bh2apvi" } in subnet "/root" ``` @@ -186,11 +176,11 @@ auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3Jpd accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] ``` -> Beware: If you are already running the daemon, changes in the config file are only picked up after running `./bin/ipc-agent reload-config` so be sure to run it after editing your config. +> Beware: If you are already running the daemon, changes in the config file are only picked up after running `./bin/ipc-agent config reload` so be sure to run it after editing your config. Finally, to test if the connection to the rootnet has been successful, we can for instance try to create a new wallet in the rootnet: ``` -./bin/ipc-agent wallet-new --key-type=bls --subnet=/root +./bin/ipc-agent wallet new --key-type bls --subnet /root ``` ### Running a subnet @@ -201,11 +191,10 @@ This section provides instructions for spawning a simple subnet with a single va #### Spawn subnet actor To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation: ```bash -./bin/ipc-agent create-subnet -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period +./bin/ipc-agent subnet create -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period # Sample command execution -./bin/ipc-agent create-subnet -p /root -n test --min-validator-stake 1 \ ---min-validators 0 --finality-threshold 10 --check-period 10 +./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10 [2023-03-21T09:32:58Z INFO ipc_agent::cli::commands::manager::create] created subnet actor with id: /root/t01002 ``` @@ -230,7 +219,7 @@ $ docker exec -it 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf9 Let's illustrate the flow by creating a new wallet in our recently deployed root and exporting the keys. ```bash # Create the new wallet -$ ./bin/ipc-agent wallet-new --key-type=secp256k1 --subnet=/root +$ ./bin/ipc-agent wallet new --key-type secp256k1 --subnet /root [2023-03-29T09:32:52Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t17rnww5qirr2fh5uiqy6fyi6ix7otwjzgu6pgpey" } in subnet "/root" # Export the created wallet into ipc-agent @@ -275,15 +264,15 @@ jsonrpc_api_http = "http://127.0.0.1:1239/rpc/v1" auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.TnoDqZJ1fqdkr_oCHFEXvdwU6kYR7Va_ALyEuoPnksA" accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] ``` -As always, remember to run `./bin/ipc-agent reload-config` for changes in the config of the agent to be picked up by the daemon. +As always, remember to run `./bin/ipc-agent config reload` for changes in the config of the agent to be picked up by the daemon. #### Joining a subnet With the daemon for the subnet deployed, we can join the subnet: ```bash -$ ./bin/ipc-agent join-subnet --subnet= --collateral= --validator-net-addr= +$ ./bin/ipc-agent subnet join --subnet --collateral --validator-net-addr # Sample execution -$ ./bin/ipc-agent join-subnet --subnet=/root/t01002 --collateral=2 --validator-net-addr="GET_ADDRESS_FROM_SCRIPT" +$ ./bin/ipc-agent subnet join --subnet /root/t01002 --collateral 2 --validator-net-addr "GET_ADDRESS_FROM_SCRIPT" ``` This command specifies the subnet to join, the amount of collateral to provide and the validator net address used by other validators to dial them. We can pick up this information from the execution of the script above or running `eudico mir validator config validator-addr` from your deployment. Bear in mind that the multiaddress provided for the validator needs to be accessible publicly by other validators. According to the deployment used you may need to tweak the IP addresses of the multiaddresses and the ones provided by these scripts and commands won't be usable out-of-the-box. @@ -292,10 +281,10 @@ For instance, in the example above, we are using the DNS endpoint `/dns/host.doc As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: ```bash -$ ./bin/ipc-agent list-subnets --gateway-address= --subnet= +$ ./bin/ipc-agent subnet list --gateway-address --subnet # Sample execution -$ ./bin/ipc-agent list-subnets --gateway-address=t064 --subnet=/root +$ ./bin/ipc-agent subnet list --gateway-address t064 --subnet /root [2023-03-30T17:00:25Z INFO ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL ``` @@ -319,29 +308,28 @@ It may be the case that while joining the subnet, you didn't set the multiaddres Changing the validator is as simple as running the following command: ```bash -$ ./bin/ipc-agent set-validator-net-addr --subnet= --validator-net-addr= +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet --validator-net-addr # Sample execution -$ ./bin/ipc-agent set-validator-net-addr --subnet=/root/t01002 --validator-net-addr="/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet /root/t01002 --validator-net-addr "/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" ``` #### Committing checkpoints from a subnet -Subnets are periodically committing checkpoints to their parent every `check-period` (parameter defined when creating the subnet). When you configure the connection to your child subnet in the agent config, and `reload-config`, your agent should automatically start the process responsible for creating the checkpoints and submitting them to the parent. This process will only commit new subnet if you are a validator in that subnet. If the agent has spawned successfully the checkpointing process, you should start seeing every now and then these logs: +Subnets are periodically committing checkpoints to their parent every `check-period` (parameter defined when creating the subnet). When you configure the connection to your child subnet in the agent config, and `config reload`, your agent should automatically start the process responsible for creating the checkpoints and submitting them to the parent. This process will only commit new subnet if you are a validator in that subnet. If the agent has spawned successfully the checkpointing process, you should start seeing every now and then these logs: ``` [2023-03-29T09:52:48Z INFO ipc_agent::manager::checkpoint] Submitting checkpoint for account t1cp4q4lqsdhob23ysywffg2tvb [2023-03-29T09:52:55Z INFO ipc_agent::manager::checkpoint] successfully published checkpoint submission for epoch 50 ``` -It is common for the checkpointing process to fail while configuring a child subnet: either because the auth token is not correct, or because no wallet addresses have been configured in the subnet, etc. If this happens, running `./bin/ipc-agent reload-config` will restart the checkpoint manager and pick up the latest config values. Whenever you see an error in the checkpointing process, check that your subnet's configuration is correct and `reload-config` to restart the process. +It is common for the checkpointing process to fail while configuring a child subnet: either because the auth token is not correct, or because no wallet addresses have been configured in the subnet, etc. If this happens, running `./bin/ipc-agent config reload` will restart the checkpoint manager and pick up the latest config values. Whenever you see an error in the checkpointing process, check that your subnet's configuration is correct and `reload-config` to restart the process. -Finally, if you want to inspect the information of a range of checkpoints committed in the parent for a subnet, you can use the `list-checkpoints` command provided by the agent as follows: +Finally, if you want to inspect the information of a range of checkpoints committed in the parent for a subnet, you can use the `checkpoint list` command provided by the agent as follows: ```bash # List checkpoints between two epochs for a subnet -$ ./bin/ipc-agent list-checkpoints --from-epoch= --to-epoch= --subnet= +$ ./bin/ipc-agent checkpoint list --from-epoch --to-epoch --subnet # Sample execution -$ ./bin/ipc-agent list-checkpoints --from-epoch=0 --to-epoch=100 --subnet=/ -root/t01002 +$ ./bin/ipc-agent checkpoint list --from-epoch 0 --to-epoch 100 --subnet root/t01002 [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 0 - prev_check={"/":"bafy2bzacedkoa623kvi5gfis2yks7xxjl73vg7xwbojz4tpq63dd5jpfz757i"}, cross_msgs=null, child_checks=null [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 10 - prev_check={"/":"bafy2bzacecsatvda6lodrorh7y7foxjt3a2dexxx5jiyvtl7gimrrvywb7l5m"}, cross_msgs=null, child_checks=null [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 30 - prev_check={"/":"bafy2bzaceauzdx22hna4e4cqf55jqmd64a4fx72sxprzj72qhrwuxhdl7zexu"}, cross_msgs=null, child_checks=null @@ -350,19 +338,19 @@ root/t01002 #### Sending funds in a subnet The agent provides a command to conveniently exchange funds between addresses of the same subnet. This can be achieved through the following command: ```bash -$ ./bin/ipc-agent send-value --subnet= --to= +$ ./bin/ipc-agent subnet send-value --subnet --to # Sample execution -$ ./bin/ipc-agent send-value --subnet=/root/t01002 --to=t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i 10 +$ ./bin/ipc-agent subnet send-value --subnet /root/t01002 --to t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i 10 ``` #### Leaving a subnet To leave a subnet, the following agent command can be used: ```bash -$ ./bin/ipc-agent leave-subnet --subnet= +$ ./bin/ipc-agent subnet leave --subnet # Sample execution -$ ./bin/ipc-agent leave-subnet --subnet=/root/t01002 +$ ./bin/ipc-agent subnet leave --subnet /root/t01002 ``` Leaving a subnet will release the collateral for the validator and remove all the validation rights from its account. This means that if you have a validator running in that subnet, its validation process will immediately terminate. @@ -384,30 +372,28 @@ $ docker cp ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key 91d2af805 ### Running a subnet with several validators In this section, we will deploy a subnet where the IPC agent is responsible for handling more than one validator in the subnet. Throughout this guide, we use the `ipc-infra` scripts to deploy the nodes in Docker containers, but a similar steps could be used to deploy the nodes on bare-metal or any other runtime. -For the rest of this tutorial, we'll assume that you have your agent already configured and interacting with a rootnet. For more information on how to connect to a rootnet [revisit this section](#Interacting-with-a-rootnet). We are going to deploy a subnet with 5 validators. The first thing we'll need to do is creating a new wallet for every validator we want to run. We can do this directly through the agent with the following command: +For the rest of this tutorial, we'll assume that you have your agent already configured and interacting with a rootnet. For more information on how to connect to a rootnet [revisit this section](#Interacting-with-a-rootnet). We are going to deploy a subnet with 35 validators. The first thing we'll need to do is creating a new wallet for every validator we want to run. We can do this directly through the agent with the following command: ```bash -$ ./bin/ipc-agent wallet-new --key-type=secp256k1 --subnet=/root +$ ./bin/ipc-agent wallet new --key-type secp256k1 --subnet /root ``` We also need to provide with some funds our wallets so they can put collateral to join the subnet. According to the rootnet you are connected to, you may need to get some funds from the faucet, or send some from your main wallet. Funds can be send from your main wallet also through the agent with: ```bash -$ ./bin/ipc-agent send-value --subnet=/root --to= +$ ./bin/ipc-agent subnet send-value --subnet /root --to ``` -With this, we can already create the subnet with `/root` as its parent. We are going to set the `--min-validators 5` so no new blocks can be created without this number of validators in the subnet. +With this, we can already create the subnet with `/root` as its parent. We are going to set the `--min-validators 2` so no new blocks can be created without this number of validators in the subnet. ```bash # Creating a sample subnet with 5 as the minimum number of validators. -./bin/ipc-agent create-subnet -p /root -n test --min-validator-stake 1 --min-validators 5 --finality-threshold 10 --check-period 10 +./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 ``` #### Deploying the infrastructure -In order to deploy the 5 validators for the subnet, we will have to first export the keys from our root node so we can import them to our validators. Depending on how you are running your rootnet node you'll have to make a call to the docker container, or your nodes API. More information about exporting keys from your node can be found under [this section](#Exporting-wallet-keys). +In order to deploy the 3 validators for the subnet, we will have to first export the keys from our root node so we can import them to our validators. Depending on how you are running your rootnet node you'll have to make a call to the docker container, or your nodes API. More information about exporting keys from your node can be found under [this section](#Exporting-wallet-keys). -With the five keys conveniently exported, we can deploy the subnet nodes using the `infra-scripts`. The following code snippet showcases the deployment of five sample nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports for their API and validators: +With the keys conveniently exported, we can deploy the subnet nodes using the `infra-scripts`. The following code snippet showcases the deployment of five sample nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports for their API and validators: ```bash $ ./bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/t01002 ~/.ipc-agent/wallet1.key $ ./bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/t01002 ~/.ipc-agent/wallet2.key $ ./bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/t01002 ~/.ipc-agent/wallet3.key -$ ./bin/ipc-infra/run-subnet-docker.sh 1254 1354 /root/t01002 ~/.ipc-agent/wallet4.key -$ ./bin/ipc-infra/run-subnet-docker.sh 1255 1355 /root/t01002 ~/.ipc-agent/wallet5.key ``` If the deployment is successful each of these nodes should return the following output at the end of their logs. Note down this information somewhere as we will need it to conveniently join our validators to the subnet. ``` @@ -415,12 +401,9 @@ If the deployment is successful each of these nodes should return the following >>> Token to /root/t01002 daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk >>> Default wallet: t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy >>> Subnet subnet validator info: -t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/ip4/172.17.0.4/udp/1348/quic/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR -t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/ip4/127.0.0.1/udp/1348/quic/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR -t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/ip4/172.17.0.4/tcp/1347/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR -t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/ip4/127.0.0.1/tcp/1347/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR ->>> API listening in host port 1240 ->>> Validator listening in host port 1359 +t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/1352/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR +>>> API listening in host port 1251 +>>> Validator listening in host port 1351 ``` #### Configuring the agent @@ -434,21 +417,21 @@ gateway_addr = "t064" network_name = "test" jsonrpc_api_http = "http://127.0.0.1:1240/rpc/v1" auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk" -accounts = ["t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy", "t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq", "t1nv5jrdxk4ljzndaecfjgmu35k6iz54pkufktvua", "t1pr3qzqieikp33pfdaygwkwt5v35a5ljsxsu64xq", "t1pmxk3nhg2u2ge7ioilrk7c5rmdmmbgpazipvzyy"] +accounts = ["t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy", "t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq", "t1nv5jrdxk4ljzndaecfjgmu35k6iz54pkufktvua"] ``` -Remember to run `./bin/ipc-agent reload-config` for your agent to pick up the latest changes for the config. +Remember to run `./bin/ipc-agent config reload` for your agent to pick up the latest changes for the config. #### Joining the subnet All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. We can get the validator multiaddress from the output of the script we ran to deploy the infrastructure (or by running `eudico mir validator config validator-addr`). These scripts expose through docker the port for the TPC port of the libp2p host of the validator (if there is interest to use the UDP-based multiaddress drop an issue and we can update them accordingly). Hence, we need to choose from the available multiaddresses one that exposes a TCP connection. Finally, our validators are configured so their docker containers interact with each other through ports in the host machine, so instead of exposing an IP address for the multiaddress, the following DNS-based multiaddress needs to be used for all validators: `/dns/host.docker.internal/`. This is the command that needs to be executed for every validator to join the subnet: ```bash -$ ./bin/ipc-agent join-subnet --from= --subnet=/root/t01002 --collateral= --validator-net-addr="/dns/host.docker.internal/tcp//p2p/" +$ ./bin/ipc-agent subnet join --from --subnet /root/t01002 --collateral --validator-net-addr "/dns/host.docker.internal/tcp//p2p/" # Sample execution for the validator whose logs where shared above for 2FIL collateral -$ ./bin/ipc-agent join-subnet --from=t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy --subnet=/root/t01002 --collateral=2 --validator-net-addr="/dns/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR" +$ ./bin/ipc-agent subnet join --from t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy --subnet /root/t01002 --collateral 2 --validator-net-addr "/dns/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR" ``` -Remember doing the above step for the five validators. +Remember doing the above step for the 3 validators. #### Mining in subnet We have everything in place now to start mining. Mining is as simple as running the following script for each of the validators, passing the container id/name: @@ -456,7 +439,7 @@ We have everything in place now to start mining. Mining is as simple as running $ ./bin/ipc-infra/mine-subnet.sh ``` -The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or tmux to run the process in the background and redirect the logs to some file as handling the mining process of the five validators in the foreground may be quite cumbersome. +The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or tmux to run the process in the background and redirect the logs to some file as handling the mining process of the three validators in the foreground may be quite cumbersome. ## Troubleshooting @@ -493,4 +476,6 @@ Generally, the issue is that: - There was some network instability, and lotus params couldn't be downloaded successfully. #### My agent is not submitting checkpoints after an error -Try running `./bin/ipc-agent reload-config`, this should pick up the latest config and restart all checkpointing processes. If the error has been fixed or it was an network instability between the agent and your subnet daemon, checkpoints should start being committed again seamlessly. +Try running `./bin/ipc-agent config reload`, this should pick up the latest config and restart all checkpointing processes. If the error has been fixed or it was an network instability between the agent and your subnet daemon, checkpoints should start being committed again seamlessly. + + From 6ed8b7a9291975cf976081218876efb45dc46e64 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 04:24:25 +0200 Subject: [PATCH 02/19] First iteration of quick guide --- GUIDE.md | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 GUIDE.md diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 00000000..27605e2b --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,220 @@ +# Deploying your first subnet + +Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. In each step, we'll link back to the details of the command/action, which should provide additional context. + +Several steps in this guide involve running long-lived processes. These commands are usually prefaced with `nohup` so that they run in the background. For improved usability, we recommend instead using a `screen` session and spawning a new window for each of these commands. In that case, you should omit `nohup` and `&`. + + +## Step 0: Prepare your system + +We assume a Ubuntu Linux instance when discussing prerequisites, but annotate steps with system-specificity and links to detailed multi-OS instructions. Exact procedures will vary for other systems, so please follow the links if running something different. More details on IPC-specific requirements can also be found in the [IPC Agent readme](https://github.com/consensus-shipyard/ipc-agent). + +* Install basic dependencies [Ubuntu/Debian] ([details](https://lotus.filecoin.io/lotus/install/prerequisites/#supported-platforms)) +```bash +$ sudo apt update && sudo apt install build-essential libssl-dev mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang hwloc libhwloc-dev wget ca-certificates gnupg -y +``` + +* Install Rust [Linux] ([details](https://www.rust-lang.org/tools/install)) +```bash +$ curl https://sh.rustup.rs -sSf | sh +$ source "$HOME/.cargo/env" +$ rustup target add wasm32-unknown-unknown +``` + +* Install Go [Linux] ([details](https://go.dev/doc/install)) +```bash +$ curl -fsSL https://golang.org/dl/go1.19.7.linux-amd64.tar.gz | sudo tar -xz -C /usr/local +$ echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc +``` + +* Install Docker Engine [Ubuntu] ([details](https://docs.docker.com/engine/install/)) +```bash +$ sudo install -m 0755 -d /etc/apt/keyrings +$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +$ sudo chmod a+r /etc/apt/keyrings/docker.gpg +$ echo \ + "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +$ sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y +$ sudo usermod -aG docker $USER && newgrp docker +``` + + +## Step 1: Build the IPC stack + +Next, we'll download and build the different components (IPC agent, docker images, and eudico). + +* Pick a folder where to build the IPC stack. In this example, we'll go with `~/ipc/`. +```bash +$ mkdir -p ~/ipc/ && cd ~/ipc/ +``` +* Download and compile the IPC Agent (might take a while) +```bash +$ git clone https://github.com/consensus-shipyard/ipc-agent.git +$ (cd ipc-agent && make build && make install-infra) +``` +* Download and compile eudico (might take a while) +```bash +$ git clone https://github.com/consensus-shipyard/lotus +$ (cd lotus && make spacenet) +``` + + +## Step 2: Deploy a Spacenet node + +Let's deploy a eudico instance on Spacenet and configure the IPC Agent to interact with it. + +* Start your eudico instance (might take a while to sync the chain) +```bash +$ nohup ./lotus/eudico mir daemon --bootstrap & +``` +* Get configuration parameters +```bash +$ ./lotus/eudico auth create-token --perm admin +$ ./lotus/eudico wallet new +``` +* Configure your IPC Agent +```bash +$ ./ipc-agent/bin/ipc-agent config init +$ nano ~/.ipc-agent/config.toml +``` +* Replace the content of `config.toml` with the text below, substituting the token and wallet retrieved above. +```toml +[server] +json_rpc_address = "0.0.0.0:3030" + +[[subnets]] +id = "/root" +gateway_addr = "t064" +network_name = "root" +jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1" +auth_token = "" +accounts = [""] +``` +* Start your IPC Agent +```bash +$ nohup ./ipc-agent/bin/ipc-agent daemon & +``` + + +## Step 3: Fund your account + +* Obtain some Spacenet FIL by requesting it from the [faucet](https://spacenet.consensus.ninja/), using your wallet address. + + +## Step 4: Create the subnet + +* The next step is to create a subnet under `/root` +```bash +$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 +``` +* Make a note of the address of the subnet you created (`/root/`) + + +## Step 5: Create and export validator wallets + +Although we set a minimum of 2 active validators in the previous, we'll deploy 3 validators to add some redundancy. + +* First, we'll need to create a wallet for each validator +```bash +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +``` +* Export each wallet (WALLET_1, WALLET_2, and WALLET_3) by substituting their addresses below +```bash +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet1.key +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet2.key +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet3.key +``` +* We also need to fund the wallets with enough collateral to; we'll send the funds from our default wallet +```bash +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +``` + + +## Step 6: Deploy the infrastructure + +We can deploy the subnet nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports. If these ports are unavailable in your system, please pick different ones. + +* Deploy and run a container for each validator, importing corresonding wallet keys +```bash +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/ ~/.ipc-agent/wallet1.key +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/ ~/.ipc-agent/wallet2.key +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/.ipc-agent/wallet3.key +``` +* If the deployment is successful, each of these nodes should return the following output at the end of their logs. You will need it in the next step. +``` +>>> Subnet /root/ daemon running in container: (friendly name: ) +>>> Token to /root/ daemon: +>>> Default wallet: +>>> Subnet subnet validator info: + +>>> API listening in host port +>>> Validator listening in host port +``` + + +## Step 7: Configure the IPC agent + +For ease of use, we'll import all the wallet keys into the first validator, via which the IPC Agent will act on behalf of all. + +* Copy the wallets into the docker containers and import them +```bash +$ docker cp ~/.ipc-agent/wallet1.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key +$ docker cp ~/.ipc-agent/wallet2.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key +$ docker cp ~/.ipc-agent/wallet3.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key +``` +* Edit the IPC agent configuration `config.toml` +```bash +$ nano ~/.ipc-agent/config.toml +``` +* Append the new subnet to the configuration +```toml +[[subnets]] +id = "/root/" +gateway_addr = "t064" +network_name = "Andromeda" +jsonrpc_api_http = "http://127.0.0.1:1251/rpc/v1" +auth_token = "" +accounts = ["", "", ""] +``` +* Reload the config +```bash +$ ./ipc-agent/bin/ipc-agent config reload +``` + + +## Step 8: Join the subnet + +All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. + +* Join the subnet with each validators +```bash +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +``` + + +## Step 9: Start validating! + +We have everything in place now to start validating. This is as simple as running the following script for each of the validators, passing the container name (or id): +```bash +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +``` + + +## Step 10: What now? + +* Check that the subnet is running +```bash +$ ./ipc-agent/bin/ipc-agent subnet list --gateway-address t064 --subnet /root +``` +* If something went wrong, please have a look at the [README](https://github.com/consensus-shipyard/ipc-agent). If it doesn't help, please join us in #ipc-help. In either case, let us know your experience! +* Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system. \ No newline at end of file From 7bdeb475bdf0d16197746bd0fa399f39048d39cd Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:13:39 +0200 Subject: [PATCH 03/19] Update GUIDE.md --- GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index 27605e2b..a2920647 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -107,7 +107,7 @@ $ nohup ./ipc-agent/bin/ipc-agent daemon & * The next step is to create a subnet under `/root` ```bash -$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 +$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n andromeda --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 ``` * Make a note of the address of the subnet you created (`/root/`) @@ -177,7 +177,7 @@ $ nano ~/.ipc-agent/config.toml [[subnets]] id = "/root/" gateway_addr = "t064" -network_name = "Andromeda" +network_name = "andromeda" jsonrpc_api_http = "http://127.0.0.1:1251/rpc/v1" auth_token = "" accounts = ["", "", ""] @@ -217,4 +217,4 @@ $ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & $ ./ipc-agent/bin/ipc-agent subnet list --gateway-address t064 --subnet /root ``` * If something went wrong, please have a look at the [README](https://github.com/consensus-shipyard/ipc-agent). If it doesn't help, please join us in #ipc-help. In either case, let us know your experience! -* Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system. \ No newline at end of file +* Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system. From 8fc73ee13ae4e71f05ccebfb43ac668adeab3f36 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:14:52 +0200 Subject: [PATCH 04/19] Update GUIDE.md --- GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index a2920647..c84c18d4 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,6 +1,6 @@ # Deploying your first subnet -Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. In each step, we'll link back to the details of the command/action, which should provide additional context. +Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. The full documentation provides more details on each step. Several steps in this guide involve running long-lived processes. These commands are usually prefaced with `nohup` so that they run in the background. For improved usability, we recommend instead using a `screen` session and spawning a new window for each of these commands. In that case, you should omit `nohup` and `&`. From 2f24e5afff50c32c09f4584a01d7efcd4dbb6d5a Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:16:08 +0200 Subject: [PATCH 05/19] Update GUIDE.md --- GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index c84c18d4..ab1bfb07 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -146,7 +146,7 @@ $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/ ~/. $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/ ~/.ipc-agent/wallet2.key $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/.ipc-agent/wallet3.key ``` -* If the deployment is successful, each of these nodes should return the following output at the end of their logs. You will need it in the next step. +* If the deployment is successful, each of these nodes should return the following output at the end of their logs. Save the information for the next step. ``` >>> Subnet /root/ daemon running in container: (friendly name: ) >>> Token to /root/ daemon: From 41f2b9c3765998d061009a473f7c20d5a1358cfb Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:17:13 +0200 Subject: [PATCH 06/19] Update GUIDE.md --- GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index ab1bfb07..f9914b10 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -56,7 +56,7 @@ $ (cd ipc-agent && make build && make install-infra) ``` * Download and compile eudico (might take a while) ```bash -$ git clone https://github.com/consensus-shipyard/lotus +$ git clone https://github.com/consensus-shipyard/lotus.git $ (cd lotus && make spacenet) ``` From 5a08427242c911604434dedf845a22c1646d38c3 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:19:03 +0200 Subject: [PATCH 07/19] Update GUIDE.md --- GUIDE.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index f9914b10..25346443 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -140,7 +140,7 @@ $ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 We can deploy the subnet nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports. If these ports are unavailable in your system, please pick different ones. -* Deploy and run a container for each validator, importing corresonding wallet keys +* Deploy and run a container for each validator, importing the corresponding wallet keys ```bash $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/ ~/.ipc-agent/wallet1.key $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/ ~/.ipc-agent/wallet2.key @@ -160,11 +160,10 @@ $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/. ## Step 7: Configure the IPC agent -For ease of use, we'll import all the wallet keys into the first validator, via which the IPC Agent will act on behalf of all. +For ease of use, we'll import the remaining keys into the first validator, via which the IPC Agent will act on behalf of all. * Copy the wallets into the docker containers and import them ```bash -$ docker cp ~/.ipc-agent/wallet1.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key $ docker cp ~/.ipc-agent/wallet2.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key $ docker cp ~/.ipc-agent/wallet3.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key ``` From 2d104f1d4f4d43557ccecbc4919361c232414295 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:20:03 +0200 Subject: [PATCH 08/19] Update GUIDE.md --- GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index 25346443..d57f90a7 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -162,7 +162,7 @@ $ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/. For ease of use, we'll import the remaining keys into the first validator, via which the IPC Agent will act on behalf of all. -* Copy the wallets into the docker containers and import them +* Copy the wallet keys into the docker container and import them ```bash $ docker cp ~/.ipc-agent/wallet2.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key $ docker cp ~/.ipc-agent/wallet3.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key From d639f4202f9a4a09093c237adddb1294dc0940d4 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 14:41:33 +0200 Subject: [PATCH 09/19] Clean up readme (part1) --- README.md | 134 ++++++++++++++++++++++++------------------------------ 1 file changed, 59 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 62bc8d77..57c39750 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ See the [docs](docs) for a conceptual overview. If you meet any obstacles or need help, please join us in **#ipc-help** in the [Filecoin Slack workspace](https://filecoin.io/slack). + ## Installation ### Build requirements To build the IPC Agent you need to have Rust installed in your environment. The current MSRV (Minimum Supported Rust Version) is nightly-2022-10-03 due to some test build dependencies. A working version is tracked in rust-toolchain (this is picked up by rustup automatically). You can look for instructions on [how to run Rust and rustup following this link](https://www.rust-lang.org/tools/install). @@ -45,31 +46,35 @@ Options: -V, --version Print version ``` + ## Infrastructure -IPC currently uses [a fork of Lotus](https://github.com/consensus-shipyard/lotus), that we like to call _Eudico_, to run its subnets. The IPC agent does nothing by itself, and is just an orchestrator over existing subnet deployments. To ease the deployment of new subnets and nodes, we provide a set of convenient scripts to deploy all the infrastructure required to run IPC. +IPC currently uses [a fork of Lotus](https://github.com/consensus-shipyard/lotus), which we like to call _Eudico_, to run its subnets. The IPC agent does nothing by itself, and is just an orchestrator over existing subnet deployments. To ease the deployment of new subnets and nodes, we provide a set of convenient scripts to deploy all the infrastructure required to run IPC. ### Install infrastructure scripts [Eudico](https://github.com/consensus-shipyard/lotus/tree/spacenet/scripts/ipc) provides a set of infrastructure scripts, which assume a working installation of Docker. To install Docker [follow this link](https://docs.docker.com/get-docker/) and choose your working environment. > Some users have reported some issues trying to build the required images using Docker Desktop, if this is the case, try installing a version of [Docker engine](https://docs.docker.com/engine/install/#server) supported by your system. -With Docker installed, you can then `make install-infra` in the root of the `ipc-agent`. This make rule will clone the eudico repo, build the docker image that you need to run subnets, and install the infrastructure scripts in the `./bin` folder. In Unix-based systems, it is highly recommended to include your user inside the `docker` group to avoid having to run many of the commands from this tutorial using `sudo`. You can achieve this running the following commands: +With Docker installed, you can then `make install-infra` in the root of the `ipc-agent`. This make rule will clone the eudico repo, build the docker image that you need to run subnets, and install the infrastructure scripts in the `./bin` folder. In Unix-based systems, it is highly recommended to include your user in the `docker` group to avoid having to run many of the commands from this tutorial using `sudo`. You can achieve this running the following commands: ```bash -$ sudo usermod -aG docker $USER newgrp docker +$ sudo usermod -aG docker $USER $ newgrp docker ``` -To check if the installation of the image and all infra-related scripts was successful you can run the following command, and it should return a similar output: +To check if the installation of the image and all infra-related scripts was successful, check your docker images for `eudico`. + +*Example*: ```bash $ docker images | grep eudico -eudico latest 8fb6db609712 2 minutes ago 341MB +eudico latest 8fb6db609712 2 minutes ago 341MB ``` ## Usage + ### Configuration If you are running the agent for the first time, the first thing you need to do is to create a new config. The default config path for the agent is `~/.ipc-agent/config.toml`. The agent will always try to pick up the config from this path unless told otherwise. To populate a sample config file in the default path, you can run the following command: ```bash -$ ./bin/ipc-agent init-config +$ ./bin/ipc-agent config init ``` If you `cat ~/.ipc-agent/config.toml` you should see a new config populated with a sample root and subnet configurations. @@ -77,79 +82,38 @@ If you `cat ~/.ipc-agent/config.toml` you should see a new config populated with The IPC agent runs as a foreground daemon process that spawns a new JSON RPC server to interact with it, and all the processes to automatically handle checkpoints and the execution of cross-net messages for the subnets our agent is participating in. The agent determines the list of subnets it should interact with from its config file. Alternatively, the agent can also be used as a CLI to interact with IPC. Under the hood, this cli sends new commands to the RPC server of the daemon. To run the IPC agent daemon you can run: -``` +```bash $ ./bin/ipc-agent daemon ``` +Running the agent with the default config will throw an error, because it hasn't been configured to interact with any specific IPC network. Keep reading for different ways of spawning an instance with which to interact. -Running the agent at this point will throw an error, because we havenΒ΄t configured it to interact with any IPC network. In the next few sections we will walk you through different alternatives to spawn and connect your agent to a running IPC instance. - -The RPC server of the daemon will be listening to the endpoint determined in the `json_rpc_address` field of the config. If you are looking for your agent to be accessible from Docker or externally, remember to listen from `0.0.0.0` instead of `127.0.0.1` as specified in the empty configuration. +The RPC server of the daemon will be listening to the endpoint determined in the `json_rpc_address` field of the config. If you are looking for your agent to be accessible from Docker or externally, remember to listen on `0.0.0.0` instead of `127.0.0.1` as specified in the default config. - -### Interacting with a rootnet +### Connecting to a rootnet You can deploy an IPC hierarchy from any compatible rootnet. At this time, your options are to use the public Spacenet testnet or to deploy or your own rootnet. Instructions are provided for both below, but we recommend using Spacenet if possible. #### Option 1: Spacenet -For more information about the Spacenet testnet have a look at the [Spacenet repo](https://github.com/consensus-shipyard/spacenet). In this section we will guide you through how to connect your IPC agent to a running instance of Spacenet. Spacenet hosts all the IPC actors and can be used as a rootnet to deploy new subnets from. - -In order to use the IPC agent with Spacenet we need to have access to a full-node syncing with the network. The easiest way to achieve this is to run your own Spacenet node. Running you own Spacenet node is as simple as [installing the dependencies](https://github.com/consensus-shipyard/lotus#basic-build-instructions), cloning the Eudico repo, and compiling and running it: -```bash -$ git clone https://github.com/consensus-shipyard/lotus -$ cd lotus +Spacenet hosts all the IPC actors and can be used as a rootnet on which to deploy new subnets. For more information, have a look at the [Spacenet repo](https://github.com/consensus-shipyard/spacenet). -# `spacenet` is the master branch of the repo. To find the latest -# release deployed over spacenet, you can check the last release -# published in the repo and use checkout that tag. -$ git checkout +In order to use the IPC agent with Spacenet we need to have access to a full node syncing with the network. The easiest way to achieve this is to run your own. Please follow the instructions on the [Spacenet repo](https://github.com/consensus-shipyard/spacenet/blob/main/README.md#getting-started-for-developers) to install the dependencies and set up your node. -# Compile eudico for Spacenet -$ make spacenet +With the node running, you are ready to connect the IPC agent to Spacenet. For this, you'll need to get an authentication token for your node and create a wallet for the interaction. -# Run your node -$ ./eudico mir daemon --bootstrap -``` -With this, your node should automatically connect to the bootstraps of the network and start syncing the latest state of the chain. - -> More information and further details about the operation of Spacenet can be found in the [Spacenet repo](https://github.com/consensus-shipyard/spacenet) - -With the node running, you are ready to connect the IPC agent to Spacenet. For this, you'll need to get an authentication token for your node, and point to the RPC API of the node (by default running on port `1234`). +*Example*: ```bash # Generate auth token to node -$ ./eudico auth token create--perm admin - +$ ./eudico auth token create --perm admin eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.8vIV7pCrWx-nxOBAAw_IayDzrGf22kMjagRYmj_8Qqw -``` -Additionally, you should create a new wallet address (if you don't have one already) to use for your IPC interactions. You can create a new wallet by running the following command in your eudico node: -```bash -# Create new wallet -./eudico wallet new +# Create new wallet +$ ./eudico wallet new t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq ``` -With all this information, the config of the agent should be updated to connect to the peer and start interacting with Spacenet's IPC by adding the following section for the `/root`: -```toml -[[subnets]] -id = "/root" -gateway_addr = "t064" -network_name = "root" -jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1" -auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.8vIV7pCrWx-nxOBAAw_IayDzrGf22kMjagRYmj_8Qqw" -accounts = ["t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i"] -``` - -You can now start your IPC agent daemon with `./bin/ipc-agent daemon` .If you are already running the daemon, changes in the config file are only picked up after running `./bin/ipc-agent reload-config` so be sure to run it after editing your config. - -> In the current implementation of Spacenet, the gateway is always deployed in the `t064` address. This should be the address always reflected on your config for the gateway. In the future, this will change, and the gateway may be deployed in different addresses. -To check if the agent has been connected to Spacenet successfully you can try creating a new wallet in the network, but this type through the agent by running: -```bash -./bin/ipc-agent wallet new --key-type bls --subnet /root +This information will be relevant to configure our agent to connect to this rootnet node. -2023-03-30T12:01:11Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t1om5pijjq5dqic4ccnqqrvv6zgzwrlxf6bh2apvi" } in subnet "/root" -``` - -Finally, to be able to interact with Spacenet and run new subnets, some FIL should be provided to, at least, the wallet that will be used by the agent to interact with IPC. You can request some Spacenet FIL for your address through the [Spacenet Faucet](https://spacenet.consensus.ninja/). +To be able to interact with Spacenet and run new subnets, some FIL should be provided to, at least, the wallet that will be used by the agent to interact with IPC. You can request some Spacenet FIL for your address through the [Spacenet Faucet](https://spacenet.consensus.ninja/). #### Option 2: Local deployment To deploy sample rootnet locally for testing you can use the IPC scripts installed in `./bin/ipc-infra` (refer to the [installation of infrastructure](#Installation-infrastructure-scripts)) by running: @@ -157,30 +121,44 @@ To deploy sample rootnet locally for testing you can use the IPC scripts install $ ./bin/ipc-infra/run-root-docker-1val.sh ``` -For instance, running `./bin/ipc-infra/run-root-docker-1val.sh 1235 1379` will run a rootnet daemon listening at `localhost:1235`, and a single validator mining in the rootnet listening through its libp2p host in `localhost:1379`. The end of the log in the execution of this script should look something like: -``` +For instance, running `./bin/ipc-infra/run-root-docker-1val.sh 1234 1235` will run a rootnet daemon listening at `localhost:1234`, and a single validator mining in the rootnet listening through its libp2p host in `localhost:1235`. + +*Example*: +```bash +./bin/ipc-infra/run-root-docker-1val.sh 1234 1235 +(...) >>> Root daemon running in container: 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 >>> Token to /root daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.j94YYOr8_AWhGGHQd0q8JuQVuNhJA017SK9EUkqDOO0 >>> Default wallet: t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq ``` -This information will be relevant to configure our agent to connect to this rootnet node. For this, the `config.toml` section should be updated accordingly. In the above case, we need to set the endpoint of our rootnet node to be `127.0.0.1:1235`, we need to set `auth_token` to the one provided by the script, and the default account, for instance, the one provided by the script (although we could use ant other). +This information will be relevant to configure our agent to connect to this rootnet node. + +### Configuring the agent -The configuration for our rootnet should look therefore like this: +The `/root` section of the agent's `config.toml` must be updated to connect to the node. In the examples above, we need to set the endpoint of our rootnet node to be `127.0.0.1:1234`, and replace the `auth_token` and `account` with the ones provided by our node. + +*Example*: ```toml [[subnets]] id = "/root" gateway_addr = "t064" network_name = "root" -jsonrpc_api_http = "http://127.0.0.1:1235/rpc/v1" +jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1" auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.j94YYOr8_AWhGGHQd0q8JuQVuNhJA017SK9EUkqDOO0" accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] ``` -> Beware: If you are already running the daemon, changes in the config file are only picked up after running `./bin/ipc-agent config reload` so be sure to run it after editing your config. +You can now start your IPC agent daemon with `./bin/ipc-agent daemon`. If you are already running the daemon, then run `./bin/ipc-agent config reload` to pick up the config changes. -Finally, to test if the connection to the rootnet has been successful, we can for instance try to create a new wallet in the rootnet: -``` -./bin/ipc-agent wallet new --key-type bls --subnet /root +> In the current implementation of Spacenet, the gateway is always deployed in the `t064` address. This should be the address always reflected on your config for the gateway. In the future, this will change, and the gateway may be deployed in different addresses. + +To check if the agent has been connected to Spacenet successfully you can try creating a new wallet in the network, but this time through the agent. + +*Example*: +```bash +$ ./bin/ipc-agent wallet new --key-type bls --subnet /root + +2023-03-30T12:01:11Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t1om5pijjq5dqic4ccnqqrvv6zgzwrlxf6bh2apvi" } in subnet "/root" ``` ### Running a subnet @@ -189,25 +167,31 @@ To spawn a new subnet, our IPC agent should be connected to at least the subnet This section provides instructions for spawning a simple subnet with a single validator. If you'd like to spawn a subnet with multiple validators in a Docker setup, be sure to also read on till the [corresponding section](#running-a-subnet-with-several-validators). #### Spawn subnet actor -To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation: ```bash -./bin/ipc-agent subnet create -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period +$ ./bin/ipc-agent subnet create -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period +``` -# Sample command execution -./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10 +To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation. +*Example*: +```bash +$ ./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10 [2023-03-21T09:32:58Z INFO ipc_agent::cli::commands::manager::create] created subnet actor with id: /root/t01002 ``` This command deploys a subnet actor for a new subnet from the `root`, with a human-readable name `test`, that requires at least `1` validator to join the subnet to be able to mine new blocks, and with a checkpointing period to the parent of `10` blocks. We can see that the output of this command is the ID of the new subnet. #### Exporting wallet keys -In order to run a validator in a subnet, we'll need a set of keys to handle that validator. To export the validator key from a wallet that may live in another network into a file (like the wallet address we are using in the rootnet), we can use the following Lotus command: ```bash eudico wallet export --lotus-json > +``` -# Sample execution +In order to run a validator in a subnet, we'll need a set of keys to handle that validator. To export the validator key from a wallet that may live in another network into a file (like the wallet address we are using in the rootnet), we can use the following Lotus command: + +*Example*: +```bash eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key ``` + If your daemon is running on a docker container, you can get the container id (provided also in the output of the infra scripts), and run the following command above inside a container outputting the exported private key into a file locally: ```bash $ docker exec -it eudico wallet export --lotus-json > ~/.ipc-agent/wallet.key From 6288db6c83e4e64c3e3edb16f84bc1268d87d5ad Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 19:38:42 +0200 Subject: [PATCH 10/19] Split readme --- README.md | 409 ++++------------------------ docs/{README.md => architecture.md} | 0 docs/subnet.md | 204 ++++++++++++++ docs/troubleshooting.md | 40 +++ docs/usage.md | 73 +++++ 5 files changed, 368 insertions(+), 358 deletions(-) rename docs/{README.md => architecture.md} (100%) create mode 100644 docs/subnet.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 57c39750..2bba1679 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,8 @@ # IPC Agent -> The InterPlanetary Consensus (IPC) orchestrator. - -The IPC Agent is the entrypoint to interacting with IPC. It is a client application that provides a simple and easy-to-use interface to interact with IPC as a user and run all the processes required for the operation of a subnet. - -See the [docs](docs) for a conceptual overview. -If you meet any obstacles or need help, please join us in **#ipc-help** in the [Filecoin Slack workspace](https://filecoin.io/slack). - - -## Installation -### Build requirements -To build the IPC Agent you need to have Rust installed in your environment. The current MSRV (Minimum Supported Rust Version) is nightly-2022-10-03 due to some test build dependencies. A working version is tracked in rust-toolchain (this is picked up by rustup automatically). You can look for instructions on [how to run Rust and rustup following this link](https://www.rust-lang.org/tools/install). - -> According to the operating system you are running, you may have to install additional dependencies not installed in your system to follow these instructions like `build-essential`, `libssl-dev`, `git`, `curl`, and `pkg-config`. If something fails while building the binaries double-check these dependencies. +> The InterPlanetary Consensus (IPC) orchestrator. -### Build instructions -To build the binary for the IPC agent you need to build the requirements in your environment, clone this repo, and build the binary following these steps: ```bash -$ git clone https://github.com/consensus-shipyard/ipc-agent.git -$ cd ipc-agent -$ rustup target add wasm32-unknown-unknown -$ make build -``` - -This builds the binary of the IPC agent in the `./bin` folder of your repo. If you want to make the command available everywhere, add this folder to the binary `PATH` of your system. To see if the installation was successfully you can run the following command: -``` bash $ ./bin/ipc-agent --help The IPC agent command line tool @@ -46,54 +24,53 @@ Options: -V, --version Print version ``` +The IPC Agent is the entry point to interacting with IPC. It is a client application that provides a simple and easy-to-use interface to interact with IPC as a user and run all the processes required for the operation of a subnet. -## Infrastructure -IPC currently uses [a fork of Lotus](https://github.com/consensus-shipyard/lotus), which we like to call _Eudico_, to run its subnets. The IPC agent does nothing by itself, and is just an orchestrator over existing subnet deployments. To ease the deployment of new subnets and nodes, we provide a set of convenient scripts to deploy all the infrastructure required to run IPC. +See: +- [docs/architecture.md](docs/architecture.md) for a conceptual overview of the tool +- [docs/subnet.md](docs/subnet.md) for instructions on how to deploy a new subnet and the required architecture +- [docs/usage.md](docs/usage.md) for instructions on how to use the IPC Agent to interact with subnets +- [docs/troubleshooting.md](docs/troubleshooting.md) for answers to some common questions -### Install infrastructure scripts -[Eudico](https://github.com/consensus-shipyard/lotus/tree/spacenet/scripts/ipc) provides a set of infrastructure scripts, which assume a working installation of Docker. To install Docker [follow this link](https://docs.docker.com/get-docker/) and choose your working environment. +High level documentation on IPC is available on docs.filecoin.io [TODO: link to section]. -> Some users have reported some issues trying to build the required images using Docker Desktop, if this is the case, try installing a version of [Docker engine](https://docs.docker.com/engine/install/#server) supported by your system. +>πŸ’‘ **We also provide a quick start guide [TODO: link to page] that will have you running and validating on your own subnet in a matter of minutes!** -With Docker installed, you can then `make install-infra` in the root of the `ipc-agent`. This make rule will clone the eudico repo, build the docker image that you need to run subnets, and install the infrastructure scripts in the `./bin` folder. In Unix-based systems, it is highly recommended to include your user in the `docker` group to avoid having to run many of the commands from this tutorial using `sudo`. You can achieve this running the following commands: -```bash -$ sudo usermod -aG docker $USER -$ newgrp docker -``` +## Building -To check if the installation of the image and all infra-related scripts was successful, check your docker images for `eudico`. +To build the IPC Agent you need to have Rust installed in your environment. The current MSRV (Minimum Supported Rust Version) is nightly-2022-10-03 due to some test build dependencies. A working version is tracked in rust-toolchain (this is picked up by rustup automatically). You can look for instructions on [how to run Rust and rustup following this link](https://www.rust-lang.org/tools/install). -*Example*: +>πŸ’‘ According to the operating system you are running, you may have to install additional dependencies not installed in your system to follow these instructions like `build-essential`, `libssl-dev`, `git`, `curl`, and `pkg-config`. If something fails while building the binaries double-check these dependencies. + +To build the binary for the IPC agent you need to build the requirements in your environment, clone this repo, and build the binary following these steps: ```bash -$ docker images | grep eudico -eudico latest 8fb6db609712 2 minutes ago 341MB +$ git clone https://github.com/consensus-shipyard/ipc-agent.git +$ cd ipc-agent +$ rustup target add wasm32-unknown-unknown +$ make build ``` -## Usage +This builds the binary of the IPC agent in the `./bin` folder of your repo. If you want to make the command available everywhere, add this folder to the binary `PATH` of your system. To see if the installation was successfully you can run the following command: -### Configuration -If you are running the agent for the first time, the first thing you need to do is to create a new config. The default config path for the agent is `~/.ipc-agent/config.toml`. The agent will always try to pick up the config from this path unless told otherwise. To populate a sample config file in the default path, you can run the following command: -```bash -$ ./bin/ipc-agent config init -``` -If you `cat ~/.ipc-agent/config.toml` you should see a new config populated with a sample root and subnet configurations. +## Eudico -### Running the daemon -The IPC agent runs as a foreground daemon process that spawns a new JSON RPC server to interact with it, and all the processes to automatically handle checkpoints and the execution of cross-net messages for the subnets our agent is participating in. The agent determines the list of subnets it should interact with from its config file. +IPC uses [a fork of Lotus](https://github.com/consensus-shipyard/lotus), which we like to call _Eudico_, to connect to the rootnet and run subnets. To ease the deployment of new nodes, Eudico provides [a set of infrastructure scripts](https://github.com/consensus-shipyard/lotus/tree/spacenet/scripts/ipc) that make use of Docker. In order to install Docker, [click this link](https://docs.docker.com/get-docker/) and follow the instructions for your working environment. -Alternatively, the agent can also be used as a CLI to interact with IPC. Under the hood, this cli sends new commands to the RPC server of the daemon. To run the IPC agent daemon you can run: +>πŸ’‘ Some users have reported some issues trying to build the required images using Docker Desktop. Consider installing a version of [Docker engine](https://docs.docker.com/engine/install/#server) supported by your system. + +With Docker installed, you can then `make install-infra` in the root of the `ipc-agent` repo. This will clone the eudico repo, build the docker image that you need to run subnets, and install the infrastructure scripts in the `./bin` folder. + +In Unix-based systems, it is highly recommended to include your user in the `docker` group to avoid having to run many of the commands from this tutorial using `sudo`. You can achieve this running: ```bash -$ ./bin/ipc-agent daemon +$ sudo usermod -aG docker $USER +$ newgrp docker ``` -Running the agent with the default config will throw an error, because it hasn't been configured to interact with any specific IPC network. Keep reading for different ways of spawning an instance with which to interact. -The RPC server of the daemon will be listening to the endpoint determined in the `json_rpc_address` field of the config. If you are looking for your agent to be accessible from Docker or externally, remember to listen on `0.0.0.0` instead of `127.0.0.1` as specified in the default config. - -### Connecting to a rootnet +## Connecting to a rootnet You can deploy an IPC hierarchy from any compatible rootnet. At this time, your options are to use the public Spacenet testnet or to deploy or your own rootnet. Instructions are provided for both below, but we recommend using Spacenet if possible. -#### Option 1: Spacenet +### Option 1: Spacenet Spacenet hosts all the IPC actors and can be used as a rootnet on which to deploy new subnets. For more information, have a look at the [Spacenet repo](https://github.com/consensus-shipyard/spacenet). In order to use the IPC agent with Spacenet we need to have access to a full node syncing with the network. The easiest way to achieve this is to run your own. Please follow the instructions on the [Spacenet repo](https://github.com/consensus-shipyard/spacenet/blob/main/README.md#getting-started-for-developers) to install the dependencies and set up your node. @@ -115,8 +92,8 @@ This information will be relevant to configure our agent to connect to this root To be able to interact with Spacenet and run new subnets, some FIL should be provided to, at least, the wallet that will be used by the agent to interact with IPC. You can request some Spacenet FIL for your address through the [Spacenet Faucet](https://spacenet.consensus.ninja/). -#### Option 2: Local deployment -To deploy sample rootnet locally for testing you can use the IPC scripts installed in `./bin/ipc-infra` (refer to the [installation of infrastructure](#Installation-infrastructure-scripts)) by running: +### Option 2: Local deployment +To deploy a Example rootnet locally for testing you can use the IPC scripts installed in `./bin/ipc-infra` by running: ```bash $ ./bin/ipc-infra/run-root-docker-1val.sh ``` @@ -133,9 +110,14 @@ For instance, running `./bin/ipc-infra/run-root-docker-1val.sh 1234 1235` will r ``` This information will be relevant to configure our agent to connect to this rootnet node. -### Configuring the agent +## Configuring the agent -The `/root` section of the agent's `config.toml` must be updated to connect to the node. In the examples above, we need to set the endpoint of our rootnet node to be `127.0.0.1:1234`, and replace the `auth_token` and `account` with the ones provided by our node. +The default config path for the agent is `~/.ipc-agent/config.toml`. The agent will always try to pick up the config from this path unless told otherwise. To populate a Example config file in the default path, you can run the following command: +```bash +$ ./bin/ipc-agent config init +``` + +The `/root` section of the agent's `config.toml` must be updated to connect to your node. In the examples above, we need to set the endpoint of our rootnet node to be `127.0.0.1:1234`, and replace the `auth_token` and `account` with the ones provided by our node. *Example*: ```toml @@ -148,318 +130,29 @@ auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3Jpd accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] ``` -You can now start your IPC agent daemon with `./bin/ipc-agent daemon`. If you are already running the daemon, then run `./bin/ipc-agent config reload` to pick up the config changes. - -> In the current implementation of Spacenet, the gateway is always deployed in the `t064` address. This should be the address always reflected on your config for the gateway. In the future, this will change, and the gateway may be deployed in different addresses. - -To check if the agent has been connected to Spacenet successfully you can try creating a new wallet in the network, but this time through the agent. - -*Example*: -```bash -$ ./bin/ipc-agent wallet new --key-type bls --subnet /root - -2023-03-30T12:01:11Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t1om5pijjq5dqic4ccnqqrvv6zgzwrlxf6bh2apvi" } in subnet "/root" -``` - -### Running a subnet -To spawn a new subnet, our IPC agent should be connected to at least the subnet of the parent we want to spawn the subnet from. You can refer to the previous section for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. - -This section provides instructions for spawning a simple subnet with a single validator. If you'd like to spawn a subnet with multiple validators in a Docker setup, be sure to also read on till the [corresponding section](#running-a-subnet-with-several-validators). - -#### Spawn subnet actor -```bash -$ ./bin/ipc-agent subnet create -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period -``` - -To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation. - -*Example*: -```bash -$ ./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10 -[2023-03-21T09:32:58Z INFO ipc_agent::cli::commands::manager::create] created subnet actor with id: /root/t01002 -``` -This command deploys a subnet actor for a new subnet from the `root`, with a human-readable name `test`, that requires at least `1` validator to join the subnet to be able to mine new blocks, and with a checkpointing period to the parent of `10` blocks. We can see that the output of this command is the ID of the new subnet. - -#### Exporting wallet keys -```bash -eudico wallet export --lotus-json > -``` - -In order to run a validator in a subnet, we'll need a set of keys to handle that validator. To export the validator key from a wallet that may live in another network into a file (like the wallet address we are using in the rootnet), we can use the following Lotus command: - -*Example*: -```bash -eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key -``` - -If your daemon is running on a docker container, you can get the container id (provided also in the output of the infra scripts), and run the following command above inside a container outputting the exported private key into a file locally: -```bash -$ docker exec -it eudico wallet export --lotus-json > ~/.ipc-agent/wallet.key - -# Sample execution -$ docker exec -it 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key -``` - -Let's illustrate the flow by creating a new wallet in our recently deployed root and exporting the keys. -```bash -# Create the new wallet -$ ./bin/ipc-agent wallet new --key-type secp256k1 --subnet /root -[2023-03-29T09:32:52Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t17rnww5qirr2fh5uiqy6fyi6ix7otwjzgu6pgpey" } in subnet "/root" - -# Export the created wallet into ipc-agent -$ docker exec -it eudico wallet export --lotus-json > - -# Sample execution for the address created above -$ docker exec -it 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 eudico wallet export --lotus-json t17rnww5qirr2fh5uiqy6fyi6ix7otwjzgu6pgpey > ~/.ipc-agent/wallet.key -``` - -#### Deploy subnet daemon -Before joining a new subnet, our node for that subnet should be initialized, because as part of the joining process we would need to provide information about our validator network address, so other validators know how to dial them. For the deployment of subnet daemons we also provide a convenient infra script: -```bash -$ ./bin/ipc-infra/run-subnet-docker.sh - -# Sample execution -$ ./bin/ipc-infra/run-subnet-docker.sh 1239 1349 /root/t01002 ~/.ipc-agent/wallet.key -``` -> Beware: This script doesn't support the use of relative paths for the wallet path. - -The end of the log of the execution of this script provides a bit more of information than the previous one as it is implemented to be used for production deployments: -```bash ->>> Subnet /root/t01002 daemon running in container: 22312347b743f1e95e50a31c1f47736580c9a84819f41cb4ed3d80161a0d750f ->>> Token to /root/t01002 daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.TnoDqZJ1fqdkr_oCHFEXvdwU6kYR7Va_ALyEuoPnksA ->>> Default wallet: t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq ->>> Subnet subnet validator info: -t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq@/ip4/172.17.0.3/udp/1348/quic/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmS -t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq@/ip4/127.0.0.1/udp/1348/quic/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmS -t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq@/ip4/172.17.0.3/tcp/1347/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmSw3Fb -t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq@/ip4/127.0.0.1/tcp/1347/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmSw3FbaVcL ->>> API listening in host port 1239 ->>> Validator listening in host port 1349 -``` -> Beware: The validator address specified here should be the same as the one that will be used in the next step to join the subnet. - -This log provides information about the API and auth tokens for the daemon, default validator wallet used, the multiaddresses where the validator is listening, etc. To configure our IPC agent with this subnet daemon, we need to once again update our IPC agent with the relevant information. In this case, for the sample execution above we need to add the following section to the end of our config file: -```toml -[[subnets]] -id = "/root/t01002" -gateway_addr = "t064" -network_name = "test" -jsonrpc_api_http = "http://127.0.0.1:1239/rpc/v1" -auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.TnoDqZJ1fqdkr_oCHFEXvdwU6kYR7Va_ALyEuoPnksA" -accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] -``` -As always, remember to run `./bin/ipc-agent config reload` for changes in the config of the agent to be picked up by the daemon. - -#### Joining a subnet -With the daemon for the subnet deployed, we can join the subnet: -```bash -$ ./bin/ipc-agent subnet join --subnet --collateral --validator-net-addr - -# Sample execution -$ ./bin/ipc-agent subnet join --subnet /root/t01002 --collateral 2 --validator-net-addr "GET_ADDRESS_FROM_SCRIPT" -``` -This command specifies the subnet to join, the amount of collateral to provide and the validator net address used by other validators to dial them. We can pick up this information from the execution of the script above or running `eudico mir validator config validator-addr` from your deployment. Bear in mind that the multiaddress provided for the validator needs to be accessible publicly by other validators. According to the deployment used you may need to tweak the IP addresses of the multiaddresses and the ones provided by these scripts and commands won't be usable out-of-the-box. - -For instance, in the example above, we are using the DNS endpoint `/dns/host.docker.internal/` so other Docker containers for the subnet deployed in the host machine know how to contact the validator. - -As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: -```bash - -$ ./bin/ipc-agent subnet list --gateway-address --subnet - -# Sample execution -$ ./bin/ipc-agent subnet list --gateway-address t064 --subnet /root - -[2023-03-30T17:00:25Z INFO ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL -``` -This command only shows subnets that have been registered to the gateway, i.e. that have provided enough collateral to participate in the IPC protocol and haven't been killed. It is not an exhaustive list of all of the subnet actors deployed over the network. - -> Note: In the current implementation of IPC the gateway actor is deployed as a system actor on the default addres `t064`, so whenever one of the IPC commands requests the address of the gateway actor you can use that value. - -#### Mining in a subnet -With our subnet daemon deployed, and having joined the network, as the minimum number of validators we set for our subnet is 0, we can start mining and creating new blocks in the subnet. Doing so is a simple as running the following script using as an argument the container of our subnet node: -```bash -$ ./bin/ipc-infra/mine-subnet.sh - -# Sample execution -$ ./bin/ipc-infra/mine-subnet.sh 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 -``` - -The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or tmux to run the process in the background and redirect the logs to some file. - -#### Changing subnet validator network address -It may be the case that while joining the subnet, you didn't set the multiaddress for your validator correctly and you need to update it. You'll realize that the network address of your validator is not configured correctly, because your agent throws an error when trying to connect to your subnet node, or starting the validator in your subnet throws a network-related error. - -Changing the validator is as simple as running the following command: -```bash -$ ./bin/ipc-agent subnet set-validator-net-addr --subnet --validator-net-addr - -# Sample execution -$ ./bin/ipc-agent subnet set-validator-net-addr --subnet /root/t01002 --validator-net-addr "/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" -``` - -#### Committing checkpoints from a subnet -Subnets are periodically committing checkpoints to their parent every `check-period` (parameter defined when creating the subnet). When you configure the connection to your child subnet in the agent config, and `config reload`, your agent should automatically start the process responsible for creating the checkpoints and submitting them to the parent. This process will only commit new subnet if you are a validator in that subnet. If the agent has spawned successfully the checkpointing process, you should start seeing every now and then these logs: -``` -[2023-03-29T09:52:48Z INFO ipc_agent::manager::checkpoint] Submitting checkpoint for account t1cp4q4lqsdhob23ysywffg2tvb -[2023-03-29T09:52:55Z INFO ipc_agent::manager::checkpoint] successfully published checkpoint submission for epoch 50 -``` - -It is common for the checkpointing process to fail while configuring a child subnet: either because the auth token is not correct, or because no wallet addresses have been configured in the subnet, etc. If this happens, running `./bin/ipc-agent config reload` will restart the checkpoint manager and pick up the latest config values. Whenever you see an error in the checkpointing process, check that your subnet's configuration is correct and `reload-config` to restart the process. - -Finally, if you want to inspect the information of a range of checkpoints committed in the parent for a subnet, you can use the `checkpoint list` command provided by the agent as follows: -```bash -# List checkpoints between two epochs for a subnet -$ ./bin/ipc-agent checkpoint list --from-epoch --to-epoch --subnet - -# Sample execution -$ ./bin/ipc-agent checkpoint list --from-epoch 0 --to-epoch 100 --subnet root/t01002 -[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 0 - prev_check={"/":"bafy2bzacedkoa623kvi5gfis2yks7xxjl73vg7xwbojz4tpq63dd5jpfz757i"}, cross_msgs=null, child_checks=null -[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 10 - prev_check={"/":"bafy2bzacecsatvda6lodrorh7y7foxjt3a2dexxx5jiyvtl7gimrrvywb7l5m"}, cross_msgs=null, child_checks=null -[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 30 - prev_check={"/":"bafy2bzaceauzdx22hna4e4cqf55jqmd64a4fx72sxprzj72qhrwuxhdl7zexu"}, cross_msgs=null, child_checks=null -``` - -#### Sending funds in a subnet -The agent provides a command to conveniently exchange funds between addresses of the same subnet. This can be achieved through the following command: -```bash -$ ./bin/ipc-agent subnet send-value --subnet --to +> πŸ’‘ In the current implementation of Spacenet, the gateway is always deployed in the `t064` address. This should be the address always reflected on your config for the gateway. In the future, this will change, and the gateway may be deployed in different addresses. -# Sample execution -$ ./bin/ipc-agent subnet send-value --subnet /root/t01002 --to t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i 10 -``` - -#### Leaving a subnet -To leave a subnet, the following agent command can be used: -```bash -$ ./bin/ipc-agent subnet leave --subnet - -# Sample execution -$ ./bin/ipc-agent subnet leave --subnet /root/t01002 -``` - -Leaving a subnet will release the collateral for the validator and remove all the validation rights from its account. This means that if you have a validator running in that subnet, its validation process will immediately terminate. - -#### Importing a wallet to a subnet node -Depending on whether the subnet is running inside a docker container or not, we can use the following commands to import a wallet to a subnet node: -```bash -# Importing directly into the node -$ eudico wallet import --lotus-json - -# Copy the wallet key into the container -$ docker cp : -# Import the key into eudico -$ docker exec -it eudico wallet import --format=json-lotus -# Sample execution -$ docker cp ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key 91d2af805346:/input.key && docker exec -it 91d2af805346 eudico wallet import --format=json-lotus input.key -``` - -### Running a subnet with several validators -In this section, we will deploy a subnet where the IPC agent is responsible for handling more than one validator in the subnet. Throughout this guide, we use the `ipc-infra` scripts to deploy the nodes in Docker containers, but a similar steps could be used to deploy the nodes on bare-metal or any other runtime. - -For the rest of this tutorial, we'll assume that you have your agent already configured and interacting with a rootnet. For more information on how to connect to a rootnet [revisit this section](#Interacting-with-a-rootnet). We are going to deploy a subnet with 35 validators. The first thing we'll need to do is creating a new wallet for every validator we want to run. We can do this directly through the agent with the following command: -```bash -$ ./bin/ipc-agent wallet new --key-type secp256k1 --subnet /root -``` -We also need to provide with some funds our wallets so they can put collateral to join the subnet. According to the rootnet you are connected to, you may need to get some funds from the faucet, or send some from your main wallet. Funds can be send from your main wallet also through the agent with: -```bash -$ ./bin/ipc-agent subnet send-value --subnet /root --to -``` -With this, we can already create the subnet with `/root` as its parent. We are going to set the `--min-validators 2` so no new blocks can be created without this number of validators in the subnet. -```bash -# Creating a sample subnet with 5 as the minimum number of validators. -./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 -``` - -#### Deploying the infrastructure -In order to deploy the 3 validators for the subnet, we will have to first export the keys from our root node so we can import them to our validators. Depending on how you are running your rootnet node you'll have to make a call to the docker container, or your nodes API. More information about exporting keys from your node can be found under [this section](#Exporting-wallet-keys). - -With the keys conveniently exported, we can deploy the subnet nodes using the `infra-scripts`. The following code snippet showcases the deployment of five sample nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports for their API and validators: -```bash -$ ./bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/t01002 ~/.ipc-agent/wallet1.key -$ ./bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/t01002 ~/.ipc-agent/wallet2.key -$ ./bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/t01002 ~/.ipc-agent/wallet3.key -``` -If the deployment is successful each of these nodes should return the following output at the end of their logs. Note down this information somewhere as we will need it to conveniently join our validators to the subnet. -``` ->>> Subnet /root/t01002 daemon running in container: 91d2af80534665a8d9a20127e480c16136d352a79563e74ee3c5497d50b9eda8 (friendly name: ipc_root_t01002_1240) ->>> Token to /root/t01002 daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk ->>> Default wallet: t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy ->>> Subnet subnet validator info: -t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy@/1352/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR ->>> API listening in host port 1251 ->>> Validator listening in host port 1351 -``` - -#### Configuring the agent -To configure the agent for its use with all the validators, we need to connect to the RPC API of one of the validators, and import all of the wallets of the validators in that node, so the agent is able through the same API to act on behalf of any validator. More information about importing [keys can be found in this section](#Importing-a-wallet-to-a-subnet-node). - -Here's an example of the configuration connecting to the RPC of the first validator, and configuring all the wallets for the validators in the subnet. -```toml -[[subnets]] -id = "/root/t01002" -gateway_addr = "t064" -network_name = "test" -jsonrpc_api_http = "http://127.0.0.1:1240/rpc/v1" -auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk" -accounts = ["t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy", "t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq", "t1nv5jrdxk4ljzndaecfjgmu35k6iz54pkufktvua"] -``` -Remember to run `./bin/ipc-agent config reload` for your agent to pick up the latest changes for the config. - -#### Joining the subnet -All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. We can get the validator multiaddress from the output of the script we ran to deploy the infrastructure (or by running `eudico mir validator config validator-addr`). These scripts expose through docker the port for the TPC port of the libp2p host of the validator (if there is interest to use the UDP-based multiaddress drop an issue and we can update them accordingly). Hence, we need to choose from the available multiaddresses one that exposes a TCP connection. Finally, our validators are configured so their docker containers interact with each other through ports in the host machine, so instead of exposing an IP address for the multiaddress, the following DNS-based multiaddress needs to be used for all validators: `/dns/host.docker.internal/`. - -This is the command that needs to be executed for every validator to join the subnet: -```bash -$ ./bin/ipc-agent subnet join --from --subnet /root/t01002 --collateral --validator-net-addr "/dns/host.docker.internal/tcp//p2p/" - -# Sample execution for the validator whose logs where shared above for 2FIL collateral -$ ./bin/ipc-agent subnet join --from t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy --subnet /root/t01002 --collateral 2 --validator-net-addr "/dns/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR" -``` -Remember doing the above step for the 3 validators. - -#### Mining in subnet -We have everything in place now to start mining. Mining is as simple as running the following script for each of the validators, passing the container id/name: -```bash -$ ./bin/ipc-infra/mine-subnet.sh -``` - -The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or tmux to run the process in the background and redirect the logs to some file as handling the mining process of the three validators in the foreground may be quite cumbersome. +> πŸ’‘ If you are already running the daemon, then run `./bin/ipc-agent config reload` to pick up the config changes. +## Running +The IPC agent runs as a foreground daemon process that spawns a new JSON RPC server to interact with it, and all the processes to automatically handle checkpoints and the execution of cross-net messages for the subnets our agent is participating in. The agent determines the list of subnets it should interact with from its config file. -## Troubleshooting -#### I need to upgrade my IPC agent -Sometimes, things break, and we'll need to push a quick path to fix some bug. If this happens, and you need to upgrade your agent version, kill you agent daemon if you have any running, pull the latest changes from this repo, build the binary, and start your daemon again. This should pick up the latest version for the agent. In the future, we will provide a better way to upgrade your agent. +Alternatively, the agent can also be used as a CLI to interact with IPC. Under the hood, this cli sends new commands to the RPC server of the daemon. To run the IPC agent daemon you can run: ```bash -# Pull latest changes -$ git pull -# Build the agent -$ make build -# Restart the daemon $ ./bin/ipc-agent daemon ``` -#### `make install-infra` is not building the `eudico` image -`make install-infra` may fail and not build the `eudico` image if your system is not configured correctly. If this happens, you can always try to build the image yourself to have a finer-grain report of the issues to help you debug them. For this you can [follow these instructions](https://github.com/consensus-shipyard/lotus/blob/spacenet/scripts/ipc/README.md). +The RPC server of the daemon will be listening to the endpoint determined in the `json_rpc_address` field of the config. If you are looking for your agent to be accessible from Docker or externally, remember to listen on `0.0.0.0` instead of `127.0.0.1` as specified in the default config. -High-level you just need to clone the [eudico repo](https://github.com/consensus-shipyard/lotus), and run `docker build -t eudico .` in the root of the repo. +To check if the agent has connected to the rootnet successfully, you can try using it to create a new wallet. -#### My subnet node doesn't start -Either because the dockerized subnet node after running `./bin/ipc-infra/run-subnet-docker.sh` gets stuck waiting for the API to be started with the following message: -``` -Not online yet... (could not get API info for FullNode: could not get api endpoint: API not running (no endpoint)) -``` -Or because when the script finishes no validator address has been reported as expected by the logs, the best way to debug this situation is to attach to the docker container and check the logs with the following command: +*Example*: ```bash -$ docker exec -it bash - -# Inside the container -tmux a +$ ./bin/ipc-agent wallet new --key-type bls --subnet /root +2023-03-30T12:01:11Z INFO ipc_agent::cli::commands::manager::wallet] created new wallet with address WalletNewResponse { address: "t1om5pijjq5dqic4ccnqqrvv6zgzwrlxf6bh2apvi" } in subnet "/root" ``` -Generally, the issue is that: -- You haven't passed the validator key correctly and it couldn't be imported. -- There was some network instability, and lotus params couldn't be downloaded successfully. -#### My agent is not submitting checkpoints after an error -Try running `./bin/ipc-agent config reload`, this should pick up the latest config and restart all checkpointing processes. If the error has been fixed or it was an network instability between the agent and your subnet daemon, checkpoints should start being committed again seamlessly. +## Help +If you meet any obstacles, please check [docs/troubleshooting.md](docs/troubleshooting.md) or join us in **#ipc-help** in the [Filecoin Slack workspace](https://filecoin.io/slack). diff --git a/docs/README.md b/docs/architecture.md similarity index 100% rename from docs/README.md rename to docs/architecture.md diff --git a/docs/subnet.md b/docs/subnet.md new file mode 100644 index 00000000..de0f45c5 --- /dev/null +++ b/docs/subnet.md @@ -0,0 +1,204 @@ +# Deploying a subnet + +To spawn a new subnet, our IPC agent should be connected to at least the subnet of the parent we want to spawn the subnet from. You can refer to the [readme](/readme) for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. + +## Preliminaries + +### Exporting wallet keys + +In order to run a validator in a subnet, we'll need a set of keys to handle that validator. To export the validator key from a wallet that may live in another network into a file (like the wallet address we are using in the rootnet), we can use the following Lotus command: + +*Example*: +```bash +$ ./eudico wallet export --lotus-json > + +# Example execution +$ ./eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key +``` + +If your daemon is running on a docker container, you can get the container id or name (provided also in the output of the infra scripts), and run the following command above inside a container outputting the exported private key into a file locally: +```bash +$ docker exec -it eudico wallet export --lotus-json > ~/.ipc-agent/wallet.key + +# Example execution +$ docker exec -it 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key +``` + +### Importing wallet keys + +Depending on whether the subnet is running inside a docker container or not, you may need to import keys into a node. You may use the following commands to import a wallet to a subnet node: + +```bash +# Bare: Import directly into eudico +$ ./eudico wallet import --lotus-json + +# Example execution +$ ./eudico wallet import --lotus-json ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key +``` + +```bash +# Docker: Copy the wallet key into the container and import into eudico +$ docker cp : && docker exec -it eudico wallet import --format=json-lotus + +# Example execution +$ docker cp ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key 91d2af805346:/input.key && docker exec -it 91d2af805346 eudico wallet import --format=json-lotus input.key +``` + +## Running a simple subnet with a single validator + +This section provides instructions for spawning a simple subnet with a single validator. If you'd like to spawn a subnet with multiple validators in a Docker setup, read and understand this section first but then follow the steps under [the multi-validator section below](#running-a-subnet-with-several-validators). + +### Spawning a subnet actor + +To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation. + +```bash +$ ./bin/ipc-agent subnet create -p -n --min-validator-stake 1 --min-validators --finality-threshold --check-period + +# Example execution +$ ./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10 +[2023-03-21T09:32:58Z INFO ipc_agent::cli::commands::manager::create] created subnet actor with id: /root/t01002 +``` +This command deploys a subnet actor for a new subnet from the `root`, with a human-readable name `test`, that requires at least `1` validator to join the subnet to be able to mine new blocks, and with a checkpointing period to the parent of `10` blocks. We can see that the output of this command is the ID of the new subnet. + +### Exporting your wallet + +Let's export the default wallet (or other wallet you'd like to use) for use in the subnet validator. +```bash +$ ./eudico wallet export --lotus-json `./eudico wallet default` > ~/.ipc-agent/wallet.key +``` + +Make sure that your wallet has enough funds to put up the collateral to join the subnet. + +### Deploying a subnet node + +Before joining a new subnet, our node for that subnet must be initialised. For the deployment of subnet daemons we also provide a convenient infra script: +```bash +$ ./bin/ipc-infra/run-subnet-docker.sh + +# Example execution +$ ./bin/ipc-infra/run-subnet-docker.sh 1250 1350 /root/t01002 ~/.ipc-agent/wallet.key +(...) +>>> Subnet /root/t01002 daemon running in container: 22312347b743f1e95e50a31c1f47736580c9a84819f41cb4ed3d80161a0d750f (friendly name: ipc_root_t01002_1239) +>>> Token to /root/t01002 daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.TnoDqZJ1fqdkr_oCHFEXvdwU6kYR7Va_ALyEuoPnksA +>>> Default wallet: t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq +>>> Subnet validator info: +/dns/host.docker.internal/tcp/1349/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmSw3Fb +>>> API listening in host port 1250 +>>> Validator listening in host port 1350 +``` +> πŸ’‘ Beware: This script doesn't support the use of relative paths for the wallet path. + +The end of the log of the execution of this script provides a bit more of information than the previous one as it is implemented to be used for production deployments: API and auth tokens for the daemon, default validator wallet used, the multiaddress where the validator is listening, etc. To configure our IPC agent with this subnet daemon, we need to once again update our IPC agent with the relevant information. In this case, for the Example execution above we need to add the following section to the end of our config file. + +*Example*: +```toml +[[subnets]] +id = "/root/t01002" +gateway_addr = "t064" +network_name = "test" +jsonrpc_api_http = "http://127.0.0.1:1250/rpc/v1" +auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.TnoDqZJ1fqdkr_oCHFEXvdwU6kYR7Va_ALyEuoPnksA" +accounts = ["t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq"] +``` +> πŸ’‘ Remember to run `./bin/ipc-agent config reload` for changes in the config of the agent to be picked up by the daemon. + +### Joining a subnet + +With the daemon for the subnet deployed, we can join the subnet: +```bash +$ ./bin/ipc-agent subnet join --subnet --collateral --validator-net-addr + +# Example execution +$ ./bin/ipc-agent subnet join --subnet /root/t01002 --collateral 2 --validator-net-addr /dns/host.docker.internal/tcp/1349/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmSw3Fb +``` +This command specifies the subnet to join, the amount of collateral to provide and the validator net address used by other validators to dial them. We can pick up this information from the execution of the script above or running `eudico mir validator config validator-addr` from your deployment. Bear in mind that the multiaddress provided for the validator needs to be accessible publicly by other validators. + +### Mining in a subnet + +With our subnet daemon deployed, and having joined the network, as the minimum number of validators we set for our subnet is 0, we can start mining and creating new blocks in the subnet. Doing so is a simple as running the following script using as an argument the container of our subnet node: +```bash +$ ./bin/ipc-infra/mine-subnet.sh + +# Example execution +$ ./bin/ipc-infra/mine-subnet.sh 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 +``` + +The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or tmux to run the process in the background and redirect the logs to some file. + +## Running a subnet with several validators + +In this section, we will deploy a subnet where the IPC agent is responsible for handling more than one validator in the subnet. We are going to deploy a subnet with 3 validators. The first thing we'll need to do is create a new wallet for every validator we want to run. We can do this directly through the agent with the following command (3x): +```bash +$ ./bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +``` + +We also need to provide with some funds our wallets so they can put collateral to join the subnet. According to the rootnet you are connected to, you may need to get some funds from the faucet, or send some from your main wallet. Funds can be sent from your main wallet also through the agent with (3x, adjusting `target-wallet` for each): +```bash +$ ./bin/ipc-agent subnet send-value --subnet /root --to +``` + +With this, we can already create the subnet with `/root` as its parent. We are going to set the `--min-validators 2` so no new blocks can be created without this number of validators in the subnet. +```bash +./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 +``` +### Deploying the infrastructure + +In order to deploy the 3 validators for the subnet, we will have to first export the keys from our root node so we can import them to our validators. Depending on how you are running your rootnet node you'll have to make a call to the docker container, or your nodes API. More information about exporting keys from your node can be found under [this section](#Exporting-wallet-keys). + +With the keys conveniently exported, we can deploy the subnet nodes using the `infra-scripts`. The following code snippet showcases the deployment of five Example nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports for their API and validators. + +*Example*: +```bash +$ ./bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/t01002 ~/.ipc-agent/wallet1.key +$ ./bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/t01002 ~/.ipc-agent/wallet2.key +$ ./bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/t01002 ~/.ipc-agent/wallet3.key +``` +If the deployment is successful, each of these nodes should return the following output at the end of their logs. Note down this information somewhere as we will need it to conveniently join our validators to the subnet. + +*Example*: +``` +>>> Subnet /root/t01002 daemon running in container: 91d2af80534665a8d9a20127e480c16136d352a79563e74ee3c5497d50b9eda8 (friendly name: ipc_root_t01002_1240) +>>> Token to /root/t01002 daemon: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk +>>> Default wallet: t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy +>>> Subnet subnet validator info: +/dns/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR +>>> API listening in host port 1251 +>>> Validator listening in host port 1351 +``` + +### Configuring the agent +To configure the agent for its use with all the validators, we need to connect to the RPC API of one of the validators, and import all of the wallets of the validators in that node, so the agent is able through the same API to act on behalf of any validator. More information about importing keys can be found in [this section](#Importing-wallet-keys). + +Here's an example of the configuration connecting to the RPC of the first validator, and configuring all the wallets for the validators in the subnet. +```toml +[[subnets]] +id = "/root/t01002" +gateway_addr = "t064" +network_name = "test" +jsonrpc_api_http = "http://127.0.0.1:1240/rpc/v1" +auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBbGxvdyI6WyJyZWFkIiwid3JpdGUiLCJzaWduIiwiYWRtaW4iXX0.JTiumQwFIutkTb0gUC5JWTATs-lUvDaopEDE0ewgzLk" +accounts = ["t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy", "t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq", "t1nv5jrdxk4ljzndaecfjgmu35k6iz54pkufktvua"] +``` +Remember to run `./bin/ipc-agent config reload` for your agent to pick up the latest changes for the config. + +### Joining the subnet +All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. We can get the validator multiaddress from the output of the script we ran to deploy the infrastructure. + +This is the command that needs to be executed for every validator to join the subnet: +```bash +$ ./bin/ipc-agent subnet join --from --subnet /root/t01002 --collateral --validator-net-addr + +# Example execution +$ ./bin/ipc-agent subnet join --from t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy --subnet /root/t01002 --collateral 2 --validator-net-addr /dns/host.docker.internal/tcp/1359/p2p/12D3KooWEJXcSPw6Yv4jDk52xvp2rdeG3J6jCPX9AgBJE2mRCVoR +``` +Remember doing the above step for the 3 validators. + +### Mining in subnet +We have everything in place now to start mining. Mining is as simple as running the following script for each of the validators, passing the container id/name: +```bash +$ ./bin/ipc-infra/mine-subnet.sh +``` + +The mining process is currently run in the foreground in interactive mode. Consider using `nohup ./bin/ipc-infra/mine-subnet.sh` or screen to run the process in the background and redirect the logs to some file as handling the mining process of the three validators in the foreground may be quite cumbersome. + diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..d3a2aa56 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,40 @@ +# Troubleshooting + +## I need to upgrade my IPC agent + +Sometimes, things break, and we'll need to push a quick path to fix some bug. If this happens, and you need to upgrade your agent version, kill you agent daemon if you have any running, pull the latest changes from this repo, build the binary, and start your daemon again. This should pick up the latest version for the agent. In the future, we will provide a better way to upgrade your agent. +```bash +# Pull latest changes +$ git pull +# Build the agent +$ make build +# Restart the daemon +$ ./bin/ipc-agent daemon +``` + +## The eudico image is not building successful + +`make install-infra` may fail and not build the `eudico` image if your system is not configured correctly. If this happens, you can always try to build the image yourself to have a finer-grain report of the issues to help you debug them. For this you can [follow these instructions](https://github.com/consensus-shipyard/lotus/blob/spacenet/scripts/ipc/README.md). + +High-level you just need to clone the [eudico repo](https://github.com/consensus-shipyard/lotus), and run `docker build -t eudico .` in the root of the repo. + +## My subnet node doesn't start + +Either because the dockerized subnet node after running `./bin/ipc-infra/run-subnet-docker.sh` gets stuck waiting for the API to be started with the following message: +``` +Not online yet... (could not get API info for FullNode: could not get api endpoint: API not running (no endpoint)) +``` +Or because when the script finishes no validator address has been reported as expected by the logs, the best way to debug this situation is to attach to the docker container and check the logs with the following command: +```bash +$ docker exec -it bash + +# Inside the container +tmux a +``` +Generally, the issue is that: +- You haven't passed the validator key correctly and it couldn't be imported. +- There was some network instability, and lotus params couldn't be downloaded successfully. + +## My agent is not submitting checkpoints after an error + +Try running `./bin/ipc-agent config reload`, this should pick up the latest config and restart all checkpointing processes. If the error has been fixed or it was an network instability between the agent and your subnet daemon, checkpoints should start being committed again seamlessly. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..8a65d2f3 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,73 @@ +# Using the IPC Agent + +## Joining a subnet + +With the daemon for a subnet deployed, we can join the subnet: +```bash +$ ./bin/ipc-agent subnet join --subnet --collateral --validator-net-addr + +# Example execution +$ ./bin/ipc-agent subnet join --subnet /root/t01002 --collateral 2 --validator-net-addr /dns/host.docker.internal/tcp/1349/p2p/12D3KooWN5hbWkCxwvrX9xYxMwFbWm2Jpa1o4qhwifmSw3Fb +``` +This command specifies the subnet to join, the amount of collateral to provide and the validator net address used by other validators to dial them. + +## Sending funds in a subnet + +The agent provides a command to conveniently exchange funds between addresses of the same subnet. This can be achieved through the following command: +```bash +$ ./bin/ipc-agent subnet send-value --subnet --to + +# Example execution +$ ./bin/ipc-agent subnet send-value --subnet /root/t01002 --to t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i 10 +``` + +## Leaving a subnet + +To leave a subnet, the following agent command can be used: +```bash +$ ./bin/ipc-agent subnet leave --subnet + +# Example execution +$ ./bin/ipc-agent subnet leave --subnet /root/t01002 +``` +Leaving a subnet will release the collateral for the validator and remove all the validation rights from its account. This means that if you have a validator running in that subnet, its validation process will immediately terminate. + +### Listing active subnets + +As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: + +```bash +$ ./bin/ipc-agent list-subnets --gateway-address= --subnet= + +# Sample execution +$ ./bin/ipc-agent list-subnets --gateway-address=t064 --subnet=/root +[2023-03-30T17:00:25Z INFO ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL +``` + +This command only shows subnets that have been registered to the gateway, i.e. that have provided enough collateral to participate in the IPC protocol and haven't been killed. It is not an exhaustive list of all of the subnet actors deployed over the network. + +### Changing subnet validator network address + +It may be the case that while joining the subnet, you didn't set the multiaddress for your validator correctly and you need to update it. You'll realize that the network address of your validator is not configured correctly, because your agent throws an error when trying to connect to your subnet node, or starting the validator in your subnet throws a network-related error. + +Changing the validator is as simple as running the following command: +```bash +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet --validator-net-addr + +# Example execution +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet /root/t01002 --validator-net-addr "/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" +``` + +### Listing checkpoints from a subnet + +Subnets are periodically committing checkpoints to their parent every `check-period` (parameter defined when creating the subnet). If you want to inspect the information of a range of checkpoints committed in the parent for a subnet, you can use the `checkpoint list` command provided by the agent as follows: +```bash +# List checkpoints between two epochs for a subnet +$ ./bin/ipc-agent checkpoint list --from-epoch --to-epoch --subnet + +# Example execution +$ ./bin/ipc-agent checkpoint list --from-epoch 0 --to-epoch 100 --subnet root/t01002 +[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 0 - prev_check={"/":"bafy2bzacedkoa623kvi5gfis2yks7xxjl73vg7xwbojz4tpq63dd5jpfz757i"}, cross_msgs=null, child_checks=null +[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 10 - prev_check={"/":"bafy2bzacecsatvda6lodrorh7y7foxjt3a2dexxx5jiyvtl7gimrrvywb7l5m"}, cross_msgs=null, child_checks=null +[2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 30 - prev_check={"/":"bafy2bzaceauzdx22hna4e4cqf55jqmd64a4fx72sxprzj72qhrwuxhdl7zexu"}, cross_msgs=null, child_checks=null +``` \ No newline at end of file From cf0e1cffdc532c15e603e06f57b0067c962d1dfa Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 20:30:49 +0200 Subject: [PATCH 11/19] Update GUIDE.md --- GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GUIDE.md b/GUIDE.md index d57f90a7..2c201239 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,4 +1,4 @@ -# Deploying your first subnet +# IPC101: Deploying your first subnet Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. The full documentation provides more details on each step. From 9b79aa19ef02f342cefbddeab3a50fbce8c0b53b Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Fri, 14 Apr 2023 20:31:53 +0200 Subject: [PATCH 12/19] Update arch title --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 20887b0a..34b5558e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,4 +1,4 @@ -# IPC Agent +# IPC Agent Architecture The IPC Agent is a process faciliting the participation of Filecoin clients like Lotus in the InterPlanetary Consensus (formerly Hierarchical Consensus). From 7052e81e66ef3a52b71aecf7a5596ba4f1e2cca7 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 00:52:45 +0200 Subject: [PATCH 13/19] Update usage.md --- docs/usage.md | 43 ++++++++++++++++--------------------------- 1 file changed, 16 insertions(+), 27 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 8a65d2f3..fbebdb72 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,8 +1,22 @@ # Using the IPC Agent +## Listing active subnets + +As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: + +```bash +$ ./bin/ipc-agent list-subnets --gateway-address= --subnet= + +# Sample execution +$ ./bin/ipc-agent list-subnets --gateway-address=t064 --subnet=/root +[2023-03-30T17:00:25Z INFO ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL +``` + +This command only shows subnets that have been registered to the gateway, i.e. that have provided enough collateral to participate in the IPC protocol and haven't been killed. It is not an exhaustive list of all of the subnet actors deployed over the network. + ## Joining a subnet -With the daemon for a subnet deployed, we can join the subnet: +With the daemon for a subnet deployed (see [instructions](/docs/subnet.md)), one can join the subnet: ```bash $ ./bin/ipc-agent subnet join --subnet --collateral --validator-net-addr @@ -32,31 +46,6 @@ $ ./bin/ipc-agent subnet leave --subnet /root/t01002 ``` Leaving a subnet will release the collateral for the validator and remove all the validation rights from its account. This means that if you have a validator running in that subnet, its validation process will immediately terminate. -### Listing active subnets - -As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: - -```bash -$ ./bin/ipc-agent list-subnets --gateway-address= --subnet= - -# Sample execution -$ ./bin/ipc-agent list-subnets --gateway-address=t064 --subnet=/root -[2023-03-30T17:00:25Z INFO ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL -``` - -This command only shows subnets that have been registered to the gateway, i.e. that have provided enough collateral to participate in the IPC protocol and haven't been killed. It is not an exhaustive list of all of the subnet actors deployed over the network. - -### Changing subnet validator network address - -It may be the case that while joining the subnet, you didn't set the multiaddress for your validator correctly and you need to update it. You'll realize that the network address of your validator is not configured correctly, because your agent throws an error when trying to connect to your subnet node, or starting the validator in your subnet throws a network-related error. - -Changing the validator is as simple as running the following command: -```bash -$ ./bin/ipc-agent subnet set-validator-net-addr --subnet --validator-net-addr - -# Example execution -$ ./bin/ipc-agent subnet set-validator-net-addr --subnet /root/t01002 --validator-net-addr "/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" -``` ### Listing checkpoints from a subnet @@ -70,4 +59,4 @@ $ ./bin/ipc-agent checkpoint list --from-epoch 0 --to-epoch 100 --subnet root/t0 [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 0 - prev_check={"/":"bafy2bzacedkoa623kvi5gfis2yks7xxjl73vg7xwbojz4tpq63dd5jpfz757i"}, cross_msgs=null, child_checks=null [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 10 - prev_check={"/":"bafy2bzacecsatvda6lodrorh7y7foxjt3a2dexxx5jiyvtl7gimrrvywb7l5m"}, cross_msgs=null, child_checks=null [2023-03-29T12:43:42Z INFO ipc_agent::cli::commands::manager::list_checkpoints] epoch 30 - prev_check={"/":"bafy2bzaceauzdx22hna4e4cqf55jqmd64a4fx72sxprzj72qhrwuxhdl7zexu"}, cross_msgs=null, child_checks=null -``` \ No newline at end of file +``` From 933d621175544a974f1dd9f085dadb5b807fb451 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 00:54:02 +0200 Subject: [PATCH 14/19] Update troubleshooting.md --- docs/troubleshooting.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d3a2aa56..078f66f9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -38,3 +38,15 @@ Generally, the issue is that: ## My agent is not submitting checkpoints after an error Try running `./bin/ipc-agent config reload`, this should pick up the latest config and restart all checkpointing processes. If the error has been fixed or it was an network instability between the agent and your subnet daemon, checkpoints should start being committed again seamlessly. + +### I set the wrong validator address or need to change it + +It may be the case that while joining the subnet, you didn't set the multiaddress for your validator correctly and you need to update it. You'll realize that the network address of your validator is not configured correctly, because your agent throws an error when trying to connect to your subnet node, or starting the validator in your subnet throws a network-related error. + +Changing the validator is as simple as running the following command: +```bash +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet --validator-net-addr + +# Example execution +$ ./bin/ipc-agent subnet set-validator-net-addr --subnet /root/t01002 --validator-net-addr "/dns/host.docker.internal/tcp/1349/p2p/12D3KooWDeN3bTvZEH11s9Gq5bDeZZLKgRZiMDcy2KmA6mUaT9KE" +``` From b45342eb7144df1e1b91dfd7e67dba7c5b7828c4 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 14:31:13 +0200 Subject: [PATCH 15/19] Reorg docs --- docs/architecture.md | 4 +- docs/quickstart.md | 220 ++++++++++++++++++++++++++++++++++++++++ docs/subnet.md | 6 +- docs/troubleshooting.md | 4 +- 4 files changed, 230 insertions(+), 4 deletions(-) create mode 100644 docs/quickstart.md diff --git a/docs/architecture.md b/docs/architecture.md index 34b5558e..b90cc960 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,8 +1,10 @@ # IPC Agent Architecture +>πŸ’‘ For background and setup information, make sure to start with the [README](/README.md). + The IPC Agent is a process faciliting the participation of Filecoin clients like Lotus in the InterPlanetary Consensus (formerly Hierarchical Consensus). -Please refer to the [IPD Agent Design](https://docs.google.com/document/d/14lkRRv6MQYnuEfp2GoGngdD8Q5YgfE38D8HTZWKgKf4) document for details on the agent. +Please refer to the [IPC Agent Design](https://docs.google.com/document/d/14lkRRv6MQYnuEfp2GoGngdD8Q5YgfE38D8HTZWKgKf4) document for details on the agent. # IPLD Resolver diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..5f951d99 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,220 @@ +# IPC Quick Start: zero-to-subnet + +Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. The full documentation provides more details on each step. + +Several steps in this guide involve running long-lived processes. These commands are usually prefaced with `nohup` so that they run in the background. For improved usability, we recommend instead using a `screen` session and spawning a new window for each of these commands. In that case, you should omit `nohup` and `&`. + +>πŸ’‘ For more background and information, make sure to start with the [README](/README.md). + +## Step 0: Prepare your system + +We assume a Ubuntu Linux instance when discussing prerequisites, but annotate steps with system-specificity and links to detailed multi-OS instructions. Exact procedures will vary for other systems, so please follow the links if running something different. More details on IPC-specific requirements can also be found in the [IPC Agent readme](https://github.com/consensus-shipyard/ipc-agent). + +* Install basic dependencies [Ubuntu/Debian] ([details](https://lotus.filecoin.io/lotus/install/prerequisites/#supported-platforms)) +```bash +$ sudo apt update && sudo apt install build-essential libssl-dev mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang hwloc libhwloc-dev wget ca-certificates gnupg -y +``` + +* Install Rust [Linux] ([details](https://www.rust-lang.org/tools/install)) +```bash +$ curl https://sh.rustup.rs -sSf | sh +$ source "$HOME/.cargo/env" +$ rustup target add wasm32-unknown-unknown +``` + +* Install Go [Linux] ([details](https://go.dev/doc/install)) +```bash +$ curl -fsSL https://golang.org/dl/go1.19.7.linux-amd64.tar.gz | sudo tar -xz -C /usr/local +$ echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc +``` + +* Install Docker Engine [Ubuntu] ([details](https://docs.docker.com/engine/install/)) +```bash +$ sudo install -m 0755 -d /etc/apt/keyrings +$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +$ sudo chmod a+r /etc/apt/keyrings/docker.gpg +$ echo \ + "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +$ sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y +$ sudo usermod -aG docker $USER && newgrp docker +``` + + +## Step 1: Build the IPC stack + +Next, we'll download and build the different components (IPC agent, docker images, and eudico). + +* Pick a folder where to build the IPC stack. In this example, we'll go with `~/ipc/`. +```bash +$ mkdir -p ~/ipc/ && cd ~/ipc/ +``` +* Download and compile the IPC Agent (might take a while) +```bash +$ git clone https://github.com/consensus-shipyard/ipc-agent.git +$ (cd ipc-agent && make build && make install-infra) +``` +* Download and compile eudico (might take a while) +```bash +$ git clone https://github.com/consensus-shipyard/lotus.git +$ (cd lotus && make spacenet) +``` + + +## Step 2: Deploy a Spacenet node + +Let's deploy a eudico instance on Spacenet and configure the IPC Agent to interact with it. + +* Start your eudico instance (might take a while to sync the chain) +```bash +$ nohup ./lotus/eudico mir daemon --bootstrap & +``` +* Get configuration parameters +```bash +$ ./lotus/eudico auth create-token --perm admin +$ ./lotus/eudico wallet new +``` +* Configure your IPC Agent +```bash +$ ./ipc-agent/bin/ipc-agent config init +$ nano ~/.ipc-agent/config.toml +``` +* Replace the content of `config.toml` with the text below, substituting the token and wallet retrieved above. +```toml +[server] +json_rpc_address = "0.0.0.0:3030" + +[[subnets]] +id = "/root" +gateway_addr = "t064" +network_name = "root" +jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1" +auth_token = "" +accounts = [""] +``` +* Start your IPC Agent +```bash +$ nohup ./ipc-agent/bin/ipc-agent daemon & +``` + + +## Step 3: Fund your account + +* Obtain some Spacenet FIL by requesting it from the [faucet](https://spacenet.consensus.ninja/), using your wallet address. + + +## Step 4: Create the subnet + +* The next step is to create a subnet under `/root` +```bash +$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n andromeda --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 +``` +* Make a note of the address of the subnet you created (`/root/`) + + +## Step 5: Create and export validator wallets + +Although we set a minimum of 2 active validators in the previous, we'll deploy 3 validators to add some redundancy. + +* First, we'll need to create a wallet for each validator +```bash +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root +``` +* Export each wallet (WALLET_1, WALLET_2, and WALLET_3) by substituting their addresses below +```bash +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet1.key +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet2.key +$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet3.key +``` +* We also need to fund the wallets with enough collateral to; we'll send the funds from our default wallet +```bash +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 +``` + + +## Step 6: Deploy the infrastructure + +We can deploy the subnet nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports. If these ports are unavailable in your system, please pick different ones. + +* Deploy and run a container for each validator, importing the corresponding wallet keys +```bash +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/ ~/.ipc-agent/wallet1.key +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/ ~/.ipc-agent/wallet2.key +$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/.ipc-agent/wallet3.key +``` +* If the deployment is successful, each of these nodes should return the following output at the end of their logs. Save the information for the next step. +``` +>>> Subnet /root/ daemon running in container: (friendly name: ) +>>> Token to /root/ daemon: +>>> Default wallet: +>>> Subnet subnet validator info: + +>>> API listening in host port +>>> Validator listening in host port +``` + + +## Step 7: Configure the IPC agent + +For ease of use, we'll import the remaining keys into the first validator, via which the IPC Agent will act on behalf of all. + +* Copy the wallet keys into the docker container and import them +```bash +$ docker cp ~/.ipc-agent/wallet2.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key +$ docker cp ~/.ipc-agent/wallet3.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key +``` +* Edit the IPC agent configuration `config.toml` +```bash +$ nano ~/.ipc-agent/config.toml +``` +* Append the new subnet to the configuration +```toml +[[subnets]] +id = "/root/" +gateway_addr = "t064" +network_name = "andromeda" +jsonrpc_api_http = "http://127.0.0.1:1251/rpc/v1" +auth_token = "" +accounts = ["", "", ""] +``` +* Reload the config +```bash +$ ./ipc-agent/bin/ipc-agent config reload +``` + + +## Step 8: Join the subnet + +All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. + +* Join the subnet with each validators +```bash +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr +``` + + +## Step 9: Start validating! + +We have everything in place now to start validating. This is as simple as running the following script for each of the validators, passing the container name (or id): +```bash +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & +``` + + +## Step 10: What now? + +* Check that the subnet is running +```bash +$ ./ipc-agent/bin/ipc-agent subnet list --gateway-address t064 --subnet /root +``` +* If something went wrong, please have a look at the [README](https://github.com/consensus-shipyard/ipc-agent). If it doesn't help, please join us in #ipc-help. In either case, let us know your experience! +* Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system. diff --git a/docs/subnet.md b/docs/subnet.md index de0f45c5..bfc1471c 100644 --- a/docs/subnet.md +++ b/docs/subnet.md @@ -1,6 +1,8 @@ -# Deploying a subnet +# Deploying an IPC subnet -To spawn a new subnet, our IPC agent should be connected to at least the subnet of the parent we want to spawn the subnet from. You can refer to the [readme](/readme) for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. +>πŸ’‘ For background and setup information, make sure to start with the [README](/README.md). + +To spawn a new subnet, our IPC agent should be connected to at least the subnet of the parent we want to spawn the subnet from. You can refer to the [readme](/README.md) for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. ## Preliminaries diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 078f66f9..77ccbf49 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,4 +1,6 @@ -# Troubleshooting +# Troubleshooting IPC + +>πŸ’‘ For background and setup information, make sure to start with the [README](/README.md). ## I need to upgrade my IPC agent From 568c7dd47ebd185cba63cf37e3c15f225f818b75 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 14:31:22 +0200 Subject: [PATCH 16/19] Reorg docs --- GUIDE.md | 219 -------------------------------------------------- README.md | 3 +- docs/usage.md | 2 + 3 files changed, 4 insertions(+), 220 deletions(-) delete mode 100644 GUIDE.md diff --git a/GUIDE.md b/GUIDE.md deleted file mode 100644 index 2c201239..00000000 --- a/GUIDE.md +++ /dev/null @@ -1,219 +0,0 @@ -# IPC101: Deploying your first subnet - -Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. The full documentation provides more details on each step. - -Several steps in this guide involve running long-lived processes. These commands are usually prefaced with `nohup` so that they run in the background. For improved usability, we recommend instead using a `screen` session and spawning a new window for each of these commands. In that case, you should omit `nohup` and `&`. - - -## Step 0: Prepare your system - -We assume a Ubuntu Linux instance when discussing prerequisites, but annotate steps with system-specificity and links to detailed multi-OS instructions. Exact procedures will vary for other systems, so please follow the links if running something different. More details on IPC-specific requirements can also be found in the [IPC Agent readme](https://github.com/consensus-shipyard/ipc-agent). - -* Install basic dependencies [Ubuntu/Debian] ([details](https://lotus.filecoin.io/lotus/install/prerequisites/#supported-platforms)) -```bash -$ sudo apt update && sudo apt install build-essential libssl-dev mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang hwloc libhwloc-dev wget ca-certificates gnupg -y -``` - -* Install Rust [Linux] ([details](https://www.rust-lang.org/tools/install)) -```bash -$ curl https://sh.rustup.rs -sSf | sh -$ source "$HOME/.cargo/env" -$ rustup target add wasm32-unknown-unknown -``` - -* Install Go [Linux] ([details](https://go.dev/doc/install)) -```bash -$ curl -fsSL https://golang.org/dl/go1.19.7.linux-amd64.tar.gz | sudo tar -xz -C /usr/local -$ echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc -``` - -* Install Docker Engine [Ubuntu] ([details](https://docs.docker.com/engine/install/)) -```bash -$ sudo install -m 0755 -d /etc/apt/keyrings -$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg -$ sudo chmod a+r /etc/apt/keyrings/docker.gpg -$ echo \ - "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ - "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ - sudo tee /etc/apt/sources.list.d/docker.list > /dev/null -$ sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y -$ sudo usermod -aG docker $USER && newgrp docker -``` - - -## Step 1: Build the IPC stack - -Next, we'll download and build the different components (IPC agent, docker images, and eudico). - -* Pick a folder where to build the IPC stack. In this example, we'll go with `~/ipc/`. -```bash -$ mkdir -p ~/ipc/ && cd ~/ipc/ -``` -* Download and compile the IPC Agent (might take a while) -```bash -$ git clone https://github.com/consensus-shipyard/ipc-agent.git -$ (cd ipc-agent && make build && make install-infra) -``` -* Download and compile eudico (might take a while) -```bash -$ git clone https://github.com/consensus-shipyard/lotus.git -$ (cd lotus && make spacenet) -``` - - -## Step 2: Deploy a Spacenet node - -Let's deploy a eudico instance on Spacenet and configure the IPC Agent to interact with it. - -* Start your eudico instance (might take a while to sync the chain) -```bash -$ nohup ./lotus/eudico mir daemon --bootstrap & -``` -* Get configuration parameters -```bash -$ ./lotus/eudico auth create-token --perm admin -$ ./lotus/eudico wallet new -``` -* Configure your IPC Agent -```bash -$ ./ipc-agent/bin/ipc-agent config init -$ nano ~/.ipc-agent/config.toml -``` -* Replace the content of `config.toml` with the text below, substituting the token and wallet retrieved above. -```toml -[server] -json_rpc_address = "0.0.0.0:3030" - -[[subnets]] -id = "/root" -gateway_addr = "t064" -network_name = "root" -jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1" -auth_token = "" -accounts = [""] -``` -* Start your IPC Agent -```bash -$ nohup ./ipc-agent/bin/ipc-agent daemon & -``` - - -## Step 3: Fund your account - -* Obtain some Spacenet FIL by requesting it from the [faucet](https://spacenet.consensus.ninja/), using your wallet address. - - -## Step 4: Create the subnet - -* The next step is to create a subnet under `/root` -```bash -$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n andromeda --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10 -``` -* Make a note of the address of the subnet you created (`/root/`) - - -## Step 5: Create and export validator wallets - -Although we set a minimum of 2 active validators in the previous, we'll deploy 3 validators to add some redundancy. - -* First, we'll need to create a wallet for each validator -```bash -$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root -$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root -$ ./ipc-agent/bin/ipc-agent wallet new --key-type secp256k1 --subnet /root -``` -* Export each wallet (WALLET_1, WALLET_2, and WALLET_3) by substituting their addresses below -```bash -$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet1.key -$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet2.key -$ ./lotus/eudico wallet export --lotus-json > ~/.ipc-agent/wallet3.key -``` -* We also need to fund the wallets with enough collateral to; we'll send the funds from our default wallet -```bash -$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 -$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 -$ ./ipc-agent/bin/ipc-agent subnet send-value --subnet /root --to 2 -``` - - -## Step 6: Deploy the infrastructure - -We can deploy the subnet nodes. Note that each node should be importing a different wallet key for their validator, and should be exposing different ports. If these ports are unavailable in your system, please pick different ones. - -* Deploy and run a container for each validator, importing the corresponding wallet keys -```bash -$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1251 1351 /root/ ~/.ipc-agent/wallet1.key -$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1252 1352 /root/ ~/.ipc-agent/wallet2.key -$ ./ipc-agent/bin/ipc-infra/run-subnet-docker.sh 1253 1353 /root/ ~/.ipc-agent/wallet3.key -``` -* If the deployment is successful, each of these nodes should return the following output at the end of their logs. Save the information for the next step. -``` ->>> Subnet /root/ daemon running in container: (friendly name: ) ->>> Token to /root/ daemon: ->>> Default wallet: ->>> Subnet subnet validator info: - ->>> API listening in host port ->>> Validator listening in host port -``` - - -## Step 7: Configure the IPC agent - -For ease of use, we'll import the remaining keys into the first validator, via which the IPC Agent will act on behalf of all. - -* Copy the wallet keys into the docker container and import them -```bash -$ docker cp ~/.ipc-agent/wallet2.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key -$ docker cp ~/.ipc-agent/wallet3.key :/input.key && docker exec -it eudico wallet import --format=json-lotus input.key -``` -* Edit the IPC agent configuration `config.toml` -```bash -$ nano ~/.ipc-agent/config.toml -``` -* Append the new subnet to the configuration -```toml -[[subnets]] -id = "/root/" -gateway_addr = "t064" -network_name = "andromeda" -jsonrpc_api_http = "http://127.0.0.1:1251/rpc/v1" -auth_token = "" -accounts = ["", "", ""] -``` -* Reload the config -```bash -$ ./ipc-agent/bin/ipc-agent config reload -``` - - -## Step 8: Join the subnet - -All the infrastructure for the subnet is now deployed, and we can join our validators to the subnet. For this, we need to send a `join` command from each of our validators from their validator wallet addresses providing the validators multiaddress. - -* Join the subnet with each validators -```bash -$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr -$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr -$ ./ipc-agent/bin/ipc-agent subnet join --from --subnet /root/ --collateral 1 --validator-net-addr -``` - - -## Step 9: Start validating! - -We have everything in place now to start validating. This is as simple as running the following script for each of the validators, passing the container name (or id): -```bash -$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & -$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & -$ nohup ./ipc-agent/bin/ipc-infra/mine-subnet.sh & -``` - - -## Step 10: What now? - -* Check that the subnet is running -```bash -$ ./ipc-agent/bin/ipc-agent subnet list --gateway-address t064 --subnet /root -``` -* If something went wrong, please have a look at the [README](https://github.com/consensus-shipyard/ipc-agent). If it doesn't help, please join us in #ipc-help. In either case, let us know your experience! -* Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system. diff --git a/README.md b/README.md index 2bba1679..2178f5c9 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ Options: The IPC Agent is the entry point to interacting with IPC. It is a client application that provides a simple and easy-to-use interface to interact with IPC as a user and run all the processes required for the operation of a subnet. +>πŸ’‘ **We've prepared a [quick start guide](/docs/quickstart.md) that will have you running and validating on your own subnet quickly, at the cost of detailed explanations.** + See: - [docs/architecture.md](docs/architecture.md) for a conceptual overview of the tool - [docs/subnet.md](docs/subnet.md) for instructions on how to deploy a new subnet and the required architecture @@ -34,7 +36,6 @@ See: High level documentation on IPC is available on docs.filecoin.io [TODO: link to section]. ->πŸ’‘ **We also provide a quick start guide [TODO: link to page] that will have you running and validating on your own subnet in a matter of minutes!** ## Building diff --git a/docs/usage.md b/docs/usage.md index fbebdb72..451e005b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,5 +1,7 @@ # Using the IPC Agent +>πŸ’‘ For background and setup information, make sure to start with the [README](/README.md). + ## Listing active subnets As a sanity-check that we have joined the subnet successfully and that we provided enough collateral to register the subnet to IPC, we can list the child subnets of our parent with the following command: From 6a8ef1d56dddd570d834503883976a2b7849ff35 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 14:48:59 +0200 Subject: [PATCH 17/19] Update links --- docs/quickstart.md | 6 +++--- docs/subnet.md | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 5f951d99..c7af3a3d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,14 +1,14 @@ # IPC Quick Start: zero-to-subnet +>πŸ’‘ Background and detailed are available in the [README](/README.md). + Ready to test the waters with your first subnet? This guide will deploy a subnet with multiple local validators orchestrated by the same IPC agent. This subnet will be anchored to the public Spacenet. This will be a minimal example and may not work on all systems. The full documentation provides more details on each step. Several steps in this guide involve running long-lived processes. These commands are usually prefaced with `nohup` so that they run in the background. For improved usability, we recommend instead using a `screen` session and spawning a new window for each of these commands. In that case, you should omit `nohup` and `&`. ->πŸ’‘ For more background and information, make sure to start with the [README](/README.md). - ## Step 0: Prepare your system -We assume a Ubuntu Linux instance when discussing prerequisites, but annotate steps with system-specificity and links to detailed multi-OS instructions. Exact procedures will vary for other systems, so please follow the links if running something different. More details on IPC-specific requirements can also be found in the [IPC Agent readme](https://github.com/consensus-shipyard/ipc-agent). +We assume a Ubuntu Linux instance when discussing prerequisites, but annotate steps with system-specificity and links to detailed multi-OS instructions. Exact procedures will vary for other systems, so please follow the links if running something different. Details on IPC-specific requirements can also be found in the [README](/README.md). * Install basic dependencies [Ubuntu/Debian] ([details](https://lotus.filecoin.io/lotus/install/prerequisites/#supported-platforms)) ```bash diff --git a/docs/subnet.md b/docs/subnet.md index bfc1471c..ba1e8f65 100644 --- a/docs/subnet.md +++ b/docs/subnet.md @@ -2,7 +2,9 @@ >πŸ’‘ For background and setup information, make sure to start with the [README](/README.md). -To spawn a new subnet, our IPC agent should be connected to at least the subnet of the parent we want to spawn the subnet from. You can refer to the [readme](/README.md) for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. +To spawn a new subnet, our IPC agent should be connected to the parent subnet (or rootnet) from which we plan to deploy a new subnet. Please refer to the [README](/README.md) for information on how to run or connect to a rootnet. This instructions will assume the deployment of a subnet from `/root`, but the steps are equivalent for any other parent subnet. + +We provide instructions for running both a [simple single-validator subnet](#running-a-simple-subnet-with-a-single-validator) and a more useful [multi-validator subnet](#running-a-subnet-with-several-validators). The two sets mostly overlap. ## Preliminaries From 159cfe20d736ff53dc662c1ee6588c2705b1d930 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 14:49:34 +0200 Subject: [PATCH 18/19] rm design link --- docs/architecture.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index b90cc960..ea8fbab5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,9 +4,6 @@ The IPC Agent is a process faciliting the participation of Filecoin clients like Lotus in the InterPlanetary Consensus (formerly Hierarchical Consensus). -Please refer to the [IPC Agent Design](https://docs.google.com/document/d/14lkRRv6MQYnuEfp2GoGngdD8Q5YgfE38D8HTZWKgKf4) document for details on the agent. - - # IPLD Resolver The [IPLD Resolver](../ipld/resolver) is a library that IPC Agents can use to exchange data between subnets in IPLD format. From 08da2be3392931b926fece38f866f46989292621 Mon Sep 17 00:00:00 2001 From: Jorge Soares <547492+jsoares@users.noreply.github.com> Date: Mon, 17 Apr 2023 14:58:35 +0200 Subject: [PATCH 19/19] Link design doc --- README.md | 3 +-- docs/architecture.md | 2 +- docs/subnet.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2178f5c9..f20095f8 100644 --- a/README.md +++ b/README.md @@ -34,8 +34,7 @@ See: - [docs/usage.md](docs/usage.md) for instructions on how to use the IPC Agent to interact with subnets - [docs/troubleshooting.md](docs/troubleshooting.md) for answers to some common questions -High level documentation on IPC is available on docs.filecoin.io [TODO: link to section]. - +For a detailed overview of the entire IPC stack design, please check the up-to-date [IPC Design Reference](https://github.com/consensus-shipyard/IPC-design-reference-spec/blob/main/main.pdf) doc. ## Building diff --git a/docs/architecture.md b/docs/architecture.md index ea8fbab5..e83c6063 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,7 +6,7 @@ The IPC Agent is a process faciliting the participation of Filecoin clients like # IPLD Resolver -The [IPLD Resolver](../ipld/resolver) is a library that IPC Agents can use to exchange data between subnets in IPLD format. +The [IPLD Resolver](/ipld/resolver) is a library that IPC Agents can use to exchange data between subnets in IPLD format. ## Checkpointing diff --git a/docs/subnet.md b/docs/subnet.md index ba1e8f65..ccebcf59 100644 --- a/docs/subnet.md +++ b/docs/subnet.md @@ -1,4 +1,4 @@ -# Deploying an IPC subnet +# Deploying IPC subnet infrastructure >πŸ’‘ For background and setup information, make sure to start with the [README](/README.md).