Running a local Swarm network
This guide sets up 2 Swarm nodes in a local private network. Each of the nodes is loaded into a specific directory; i.e. the folders
Swarm can be run without a blockchain, since each node—with the help of the bootnodes—will form a network with its peers through Kademlia.
It is through the Swarm Accounting Protocol (SWAP) that Smart Contracts come into play in Swarm, in order to form an incentivized network.
If you need these nodes to run with incentivization, please refer to the incentivized version of this guide.
Table of Contents
- Run the network
- Interact with the network
- Restart the network
- Add more nodes to the network
websocat is a command-line web socket client, used to query the nodes running in the private network.
If you plan to query the nodes, follow the instructions here to install it.
Run the network
1. Choose a directory
Start a terminal and run
cd to move to a directory where the files for the nodes will be created.
2. Start each node
Make sure the
swarm command boots up Swarm correctly before starting the nodes.
Start the first node through:
DATADIR1="s1" && rm -rf "$DATADIR1" && mkdir "$DATADIR1/" && swarm --datadir "$DATADIR1" --ws --wsaddr=0.0.0.0 --wsapi=bzz --wsorigins='*' --bzzkeyhex 40b3e576b606d4580ad3c875e9fda07ba3e4d99a40534c5bf1bc72226451adb1 --nodekeyhex 2eae3526db799cb5f1ab6ab64255ba8182cdaeb4f773a0ae1244f4ca59978dc2
Start the second node through:
DATADIR2="s2" && rm -rf "$DATADIR2" && mkdir "$DATADIR2" && swarm --datadir "$DATADIR2" --port 40400 --bzzport 9100 --bootnodes "enode://email@example.com:30399" --ws --wsaddr=0.0.0.0 --wsapi=bzz --wsport 8556 --wsorigins='*'
This will populate the directories with all of the files needed for each of the Swarm nodes.
- A private key is specified in the first node so that the second one can find it through the
- The first node uses default values for parameters such as ports, but the second one needs them explicitely specified to avoid clashes.
- Both nodes have web socket endpoints enabled through the
ws(and related) parameters. The only API enabled in this case is
bzz, but others can be added at discretion (e.g.
pss, etc.). You can omit this parameter if you don't plan to query the nodes.
Interact with the network
You can interact with the nodes in the network through the following means.
Query the nodes
websocat can be used to call Swarm functions exposed through RPC.
For example, to query all balances for the node listening on port
8546, execute the following:
echo swap_balances | websocat "ws://127.0.0.1:8546" --origin localhost --jsonrpc -n --one-message &&
Note that this particular example requires SWAP to be enabled for this node.
Other calls might only be available depending on the
wsapi configuration parameter.
The Swarm documentation might not be up-to-date in terms of including all exposed functions. Search for the
rpc.API string in the Swarm codebase to figure out which calls are available.
A Swarm local web server endpoint for each node should be accessible through your browser.
The web interface will allow you to upload and download files.
By default, the server will be located at
You can find which port is used for each node by taking a look at the
bzzport flag used in each case.
By using the
swarm binary you can execute operations in the standard manner, such as
down, etc., for the node that uses the default parameters (such as port
You can find a list of commands here.
Restart the network
If you want to start from scratch, simply execute the entire code again.
If you want the to maintain state when restarting the network, only repeat the
swarm command for each node (make sure the
DATADIR variables are defined) found in the start the nodes section.
Add more nodes to the network
To start up more Swarm nodes, repeat the previous instructions with as many directories (
./sn) as you wish.
Make sure that:
- You use different ports for each node.
- All nodes except the first one have the same
- Nodes use node IDs (
bzzkeyhex) which are prefunded by the Ganache seed.
- Alternatively, use node IDs outside of this seed to see how nodes without funding behave in an incentivized network.
Guide based on Swap Test Guide by Ralph Pichler.