Running a node¶
Installation¶
Swarm is part of the Ethereum stack, the reference implementation is currently at POC (proof of concept) version 0.2.
The source code is found on github: https://github.com/ethereum/go-ethereum/tree/swarm/
Supported Platforms¶
Geth runs on all major platforms (linux, MacOSX, Windows, also raspberry pi, android OS, iOS).
Note
This package has not been tested on platforms other than linux and OSX.
Prerequisites¶
building the swarm daemon bzzd requires the following packages:
- [Go](https://golang.org)
- [Git](http://git.org)
Grab the relevant prerequisites and build from source.
On linux (ubuntu/debian variants) use apt to install go and git
sudo apt install golang git
while on Mac OSX you’d use brew
brew install go git
Then you must prepare your go environment as follows
mkdir ~/go
export GOPATH=~/go
echo 'GOPATH=~/go' >> ~/.profile
Installing from source¶
Once all prerequisites are met, download the go-ethereum source code
mkdir -p $GOPATH/src/github.com/ethereum
cd $GOPATH/src/github.com/ethereum
git clone https://github.com/ethereum/go-ethereum
cd go-ethereum
git checkout develop
go get github.com/etherem/go-ethereum
and finally compile the swarm daemon bzzd and the main go-ethereum client geth
go build ./cmd/bzzd
go build ./cmd/geth
You can now run ./bzzd to start your swarm node.
Running your swarm client¶
To start a basic swarm node we must start geth with an empty data directory on a private network and then connect the swarm daemon to this instance of geth.
First set aside an empty temporary directory to be the data store
DATADIR=/tmp/BZZ/`date +%s`
then make a new account using this directory
./geth --datadir $DATADIR account new
You will be prompted for a password:
Your new account is locked with a password. Please give a password. Do not forget this password.
Passphrase:
Repeat passphrase:
and the output will be an address - the base address of the swarm node.
Address: {2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1}
We save it under the name BZZKEY
BZZKEY=2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1
and finally, launch geth on a private network (id 322)
./geth --datadir $DATADIR \
--unlock 0 \
--verbosity 6 \
--networkid 322 \
--nodiscover \
--maxpeers 0 \
console 2>> $DATADIR/geth.log
and launch the bzzd; connecting it to the geth node
./bzzd --bzzaccount $BZZKEY \
--datadir $DATADIR \
--ethapi $DATADIR/geth.ipc \
--bzznoswap 2>> $DATADIR/bzz.log
At this verbosity level you should see plenty of output accumulating in the logfile. You can keep en eye on it using the command tail -f $DATADIR/bzz.log.
Configuration options¶
This section lists all the options you can set in the swarm configuration file.
The default location for the swarm configuration file is <datadir>/bzzd/bzz-<baseaccount>/config.json. Thus continuing from the previous section, the configuration file would be
$DATADIR/bzzd/bzz-$BZZKEY/config.json
It is possible to specify a different config file when launching bzzd by using the –bzzconfig flag.
Note
TODO: The following is out of date and needs to be re-written.
By default the swarm data directory is nested under the ethereum’s data directory, using a different subdirectoryfor each swarm node base address. This is important if you run muliple swarm nodes since storage, configuration, connected peers will all be distinct depending on the base address.
Main parameters¶
Storage parameters¶
Chunker/bzzhash parameters¶
Syncronisation parameters¶
@defopt SyncPriorities ([3, 3, 2, 1, 1]) Array of 5 priorities corresponding to 5 delivery types: delivery, propagation, deletion, history, backlog. Specifying a monotonically decreasing list of priorities is highly recommended. @end defopt
@defopt SyncModes ([true, true, true, true, false]) A boolean array specifying confirmation mode ON corresponding to 5 delivery types: delivery, propagation, deletion, history, backlog. Specifying true for a type means all deliveries will be preceeded by a confirmation roundtrip: the hash key is sent first in an unsyncedKeysMsg and delivered only if confirmed in a deliveryRequestMsg. @end defopt
Hive/Kademlia parameters¶
@node Getting started, , Configuration options, Running a node @section Getting started
Use :command:{geth} with the @code{–bzzaccount} parameter to start the client with Swarm enabled. If you want automatic deposits to your chequebook, then this account should be unlocked @code{–unlock}.
By default, the config file is sought under @file{<datadir>/bzz/<bzzaccount>/config.json}. If this file does not exist at startup, the default config file is created which you can then edit (the directories on the path will be created if necessary). In this case or if @code{config.Contract} is blank (zero address), a new chequebook contract is deployed. Until the contract is confirmed on the blockchain, no outgoing retrieve requests will be allowed.
Setting up SWAP¶
SWAP (Swarm accounting protocol) is the system that allows fair utilisation of bandwidth (see :ref:{Incentivisation}, esp. :ref:{SWAP – Swarm Accounting Protocol}). In order for SWAP to be used, a chequebook contract has to have been deployed. If the chequebook contract does not exist when the client is launched or if the contract specified in the config file is invalid, then the client attempts to autodeploy a chequebook:
[BZZ] SWAP Deploying new chequebook (owner: 0xe10536.. .5e491)
If you already have a valid chequebook on the blockchain you can just enter it in the config file @code{Contract} field.
You can set a separate account as beneficiary to which the cashed cheque payment for your services are to be credited. Set it on the @code{Beneficiary} field in the config file.
Autodeployment of the chequebook can fail if the baseaccount has no funds and cannot pay for the transaction. Note that this can also happen if your blockchain is not synchronised. In this case you will see the log message:
Since no business is possible here, the connection is idle until at least one party has a contract. In fact, this is only enabled for a test phase. If we are not allowed to purchase chunks, then no outgoing requests are allowed. If we still try to download content that we dont have locally, the request will fail (unless we have credit with other peers).
Once one of the nodes has funds (say after mining a bit), and also someone on the network is mining, then the autodeployment will eventually succeed:
Once the node deployed a new chequebook its address is set in the config file and all connections are dropped to be reset with the new conditions. Once we reconnect, purchase in one direction should be enabled. The logs from the point of view of the peer with no valid chequebook:
Depending on autodeposit settings, the chequebook will be regularly replenished:
The peer with no chequebook (yet) should not be allowed to download and thus retrieve requests will not go out. The other peer however is able to pay, therefore this other peer can retrieve chunks from the first peer and pay for them. This in turn puts the first peer in positive, which they can then use both to (auto)deploy their own chequebook and to pay for retrieving data as well. If they do not deploy a chequebook for whatever reason, they can use their balance to pay for retrieving data, but only down to 0 balance; after that no more requests are allowed to go out. Again you will see:
If a peer without a chequebook tries to send requests without paying, then the remote peer (who can see that they have no chequebook contract) interprets this as adverserial behaviour resulting in the peer being dropped.
Following on in this example, we start mining and then restart the node. The second chequebook autodeploys, the peers sync their chains and reconnect and then if all goes smoothly the logs will show something like:
As part of normal operation, after a peer reaches a balance of @code{PayAt} (number of chunks), a cheque payment is sent via the protocol. Logs on the receiving end:
The cheque is verified. If uncashed cheques have an outstanding balance of more than @code{AutoCashThreshold}, the last cheque (with a cumulative amount) is cashed. This is done by sending a transaction containing the cheque to the remote peer’s cheuebook contract. Therefore in order to cash a payment, your sender account (baseaddress) needs to have funds and the network should be mining.
For further fine tuning of SWAP, see :ref:{SWAP parameters}.