Connecting to Swarm (Advanced)¶
These instructions will begin by laying out how to start a local, private, personal (singleton) swarm. Use this to familiarise yourself with the functioning of the client; upload and download and http proxy.
Preparation¶
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
Note
If you followed the installation instructions from this guide, you will find your executables in the $GOPATH/bin directory. Make sure to move your files into an executable $PATH, or include $GOPATH/bin directory on it.
DATADIR=/tmp/BZZ/`date +%s`
mkdir $DATADIR
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:
Once you have specified the password (for example MYPASSWORD) the output will be an address - the base address of the swarm node.
Address: {2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1}
We save it under the name BZZKEY
BZZKEY=2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1
With these preparations complete, we can now launch our swarm client. In what follows we detail a few ways you might want to use swarm.
- Connecting to the swarm testnet without blockchain
- Connecting to the swarm testnet and connecting to the Ropsten blockchain
- Using swarm in singleton mode for local testing
- Launching a private swarm
- Testing SWAP accounting with a private Swarm
Connecting to the swarm testnet¶
Note
IMPORTANT: Automatic connection to the testnet is currently not working properly for all users. This issue is being fixed right now. In the meantime, please add a few enodes manually to bootstrap your node. See “Adding enodes manually” below.
Swarm needs an ethereum blockchain for
- Domain name resolution using the Ethereum Name Service (ENS) contract.
- Incentivisation (for example: SWAP)
If you do not care about domain resolution and run your swarm without SWAP (the default), then connecting to the blockchain is unnecessary. swarm per default tries to connect to the blockchain via geth’s IPC endpoint (usually $DATADIR/geth.ipc). Thus, to start swarm with no domain resolution, the --ens-api option should be set to "" (empty string). The --swap-api flag should only be set if SWAP is enabled.
Connecting swarm only (no blockchain)¶
Set up your environment as seen above, ie., make sure you have a data directory.
Note
Even though you do not need the ethereum blockchain, you will need geth to generate a swarm account ($BZZKEY), since this account determines the base address that your swarm node is going to use.
In the following examples, swarm’s output will be written to a log file. These instructions are for getting familiar with swarm and employ a syntax to speed up this documentation a bit (e.g. automatic password entry). Note though that the password will remain in plain text in your shell’s history.
swarm --bzzaccount $BZZKEY \
--datadir $DATADIR \
--ens-api '' \
2>> $DATADIR/swarm.log < <(echo -n "MYPASSWORD") &
The swarm daemon will seek out and connect to other swarm nodes. It manages its own peer connections independent of geth.
Using swarm together with the Ropsten testnet blockchain¶
In case you don’t yet have an account, run
geth --datadir $DATADIR --testnet account new
Run a geth node connected to the Ropsten testnet
nohup geth --datadir $DATADIR \
--unlock 0 \
--password <(echo -n "MYPASSWORD") \
--testnet \
2>> $DATADIR/geth.log &
Then launch the swarm; connecting it to the geth node (–ens-api).
swarm --bzzaccount $BZZKEY \
--datadir $DATADIR \
--keystore $DATADIR/testnet/keystore \
--ens-api $DATADIR/testnet/geth.ipc \
2>> $DATADIR/swarm.log < <(echo -n "MYPASSWORD") &
Adding enodes manually¶
Eventually automatic node discovery will be working for swarm nodes. Until then you can start off the connection process by adding a few peers manually using the admin.addPeer console command.
geth --exec='admin.addPeer("ENODE")' attach ipc:/path/to/bzzd.ipc
Where ENODE is one of the following:
enode://01f7728a1ba53fc263bcfbc2acacc07f08358657070e17536b2845d98d1741ec2af00718c79827dfdbecf5cfcd77965824421508cc9095f378eb2b2156eb79fa@40.68.194.101:30400
enode://6d9102dd1bebb823944480282c4ba4f066f8dcf15da513268f148890ddea42d7d8afa58c76b08c16b867a58223f2b567178ac87dcfefbd68f0c3cc1990f1e3cf@40.68.194.101:30427
enode://fca15e2e40788e422b6b5fc718d7041ce395ff65959f859f63b6e4a6fe5886459609e4c5084b1a036ceca43e3eec6a914e56d767b0491cd09f503e7ef5bb87a1@40.68.194.101:30428
enode://b795d0c872061336fea95a530333ee49ca22ce519f6b9bf1573c31ac0b62c99fe5c8a222dbc83d4ef5dc9e2dfb816fdc89401a36ecfeaeaa7dba1e5285a6e63b@40.68.194.101:30429
enode://756f582f597843e630b35371fc080d63b027757493f00df91dd799069cfc6cb52ac4d8b1a56b973baf015dd0e9182ea3a172dcbf87eb33189f23522335850e99@40.68.194.101:30430
enode://d9ccde9c5a90c15a91469b865ffd81f2882dd8731e8cbcd9a493d5cf42d875cc2709ccbc568cf90128896a165ac7a0b00395c4ae1e039f17056510f56a573ef9@40.68.194.101:30431
enode://65382e9cd2e6ffdf5a8fb2de02d24ac305f1cd014324b290d28a9fba859fcd2ed95b8152a99695a6f2780c342b9815d3c8c2385b6340e96981b10728d987c259@40.68.194.101:30433
enode://7e09d045cc1522e86f70443861dceb21723fad5e2eda3370a5e14747e7a8a61809fa6c11b37b2ecf1d5aab44976375b6d695fe39d3376ff3a15057296e570d86@40.68.194.101:30434
enode://bd8c3421167f418ecbb796f843fe340550d2c5e8a3646210c9c9d747bbd34d29398b3e3716ee76aa3f2fc46d325eb685ece0375a858f20b759b40429fbf0d050@40.68.194.101:30435
enode://8bb7fb70b80f60962c8979b20905898f8f6172ae4f6a715b89712cb7e965bfaab9aa0abd74c7966ad688928604815078c5e9c978d6e57507f45173a03f95b5e0@40.68.194.101:30436
Swarm in singleton mode¶
To launch in singleton mode, start geth using --maxpeers 0
nohup geth --datadir $DATADIR \
--unlock 0 \
--password <(echo -n "MYPASSWORD") \
--verbosity 4 \
--networkid 322 \
--nodiscover \
--maxpeers 0 \
2>> $DATADIR/geth.log &
and launch the swarm; connecting it to the geth node. For consistency, let’s use the same network id 322 as geth.
swarm --bzzaccount $BZZKEY \
--datadir $DATADIR \
--ens-api $DATADIR/geth.ipc \
--verbosity 4 \
--maxpeers 0 \
--bzznetworkid 322 \
2>> $DATADIR/swarm.log < <(echo -n "MYPASSWORD") &
Note
In this example, running geth is optional, it is not strictly needed. To run without geth, simply change the ens-api flag to --ens-api '' (an empty string).
At this verbosity level you should see plenty(!) of output accumulating in the logfiles. You can keep an eye on the output by using the command tail -f $DATADIR/swarm.log and tail -f $DATADIR/geth.log. Note: if doing this from another terminal you will have to specify the path manually because $DATADIR will not be set.
You can change the verbosity level without restarting geth and swarm via the console:
geth --exec "web3.debug.verbosity(3)" attach ipc:$DATADIR/geth.ipc
geth --exec "web3.debug.verbosity(3)" attach ipc:$DATADIR/bzzd.ipc
Note
Following these instructions you are now running a single local swarm node, not connected to any other.
If you want to run all these instructions in a single script, you can wrap them in something like
#!/bin/bash
# Working directory
cd /tmp
# Preparation
DATADIR=/tmp/BZZ/`date +%s`
mkdir -p $DATADIR
read -s -p "Enter Password. It will be stored in $DATADIR/my-password: " MYPASSWORD && echo $MYPASSWORD > $DATADIR/my-password
echo
BZZKEY=$($GOPATH/bin/geth --datadir $DATADIR --password $DATADIR/my-password account new | awk -F"{|}" '{print $2}')
echo "Your account is ready: "$BZZKEY
# Run geth in the background
nohup $GOPATH/bin/geth --datadir $DATADIR \
--unlock 0 \
--password <(cat $DATADIR/my-password) \
--verbosity 6 \
--networkid 322 \
--nodiscover \
--maxpeers 0 \
2>> $DATADIR/geth.log &
echo "geth is running in the background, you can check its logs at "$DATADIR"/geth.log"
# Now run swarm in the background
$GOPATH/bin/swarm \
--bzzaccount $BZZKEY \
--datadir $DATADIR \
--ens-api $DATADIR/geth.ipc \
--verbosity 6 \
--maxpeers 0 \
--bzznetworkid 322 \
&> $DATADIR/swarm.log < <(cat $DATADIR/my-password) &
echo "swarm is running in the background, you can check its logs at "$DATADIR"/swarm.log"
# Cleaning up
# You need to perform this feature manually
# USE THESE COMMANDS AT YOUR OWN RISK!
##
# kill -9 $(ps aux | grep swarm | grep bzzaccount | awk '{print $2}')
# kill -9 $(ps aux | grep geth | grep datadir | awk '{print $2}')
# rm -rf /tmp/BZZ
Running a private swarm¶
You can extend your singleton node into a private swarm. First you fire up a number of swarm instances, following the instructions above. You can keep the same datadir, since all node-specific into will reside under $DATADIR/bzz-$BZZKEY/
Make sure that you create an account for each instance of swarm you want to run.
For simplicity we can assume you run one geth instance and each swarm daemon process connects to that via ipc if they are on the same computer (or local network), otherwise you can use http or websockets as transport for the eth network traffic.
Once your n nodes are up and running, you can list all there enodes using admin.nodeInfo.enode (or cleaner: console.log(admin.nodeInfo.enode)) on the swarm console. With a shell one-liner:
geth --exec "console.log(admin.nodeInfo.enode)" attach /path/to/bzzd.ipc
Then you can for instance connect each node with one particular node (call it bootnode) by injecting admin.addPeer(enode) into the swarm console (this has the same effect as if you created a static-nodes.json file for devp2p:
geth --exec "admin.addPeer($BOOTNODE)" attach /path/to/bzzd.ipc
Fortunately there is also an easier short-cut for this, namely adding the --bootnodes $BOOTNODE flag when you start swarm.
These relatively tedious steps of managing connections need to be performed only once. If you bring up the same nodes a second time, earlier peers are remembered and contacted.
Note
Note that if you run several swarm daemons locally on the same instance, you can use the same data directory ($DATADIR), each swarm will automatically use its own subdirectory corresponding to the bzzaccount. This means that you can store all your keys in one keystore directory: $DATADIR/keystore.
In case you want to run several nodes locally and you are behind a firewall, connection between nodes using your external IP will likely not work. In this case, you need to substitute [::] (indicating localhost) for the IP address in the enode.
To list all enodes of a local cluster:
for i in `ls $DATADIR | grep -v keystore`; do geth --exec "console.log(admin.nodeInfo.enode)" attach $DATADIR/$i/bzzd.ipc; done > enodes.lst
To change IP to localhost:
cat enodes.lst | perl -pe 's/@[\d\.]+/@[::]/' > local-enodes.lst
Note
Steps in this section are not necessary if you simply want to connect to the swarm testnet. Since a bootnode to the testnet is set by default, your node will have a way to bootstrap its connections.
Testing SWAP¶
Note
Important! Please only test SWAP on a private network.
Testing SWAP on your private blockchain.¶
The SWarm Accounting Protocol (SWAP) is disabled by default. Set the --swap flag to enable it. If it is set to true, then SWAP will be enabled.
However, activating SWAP requires more than just adding the –swap flag. This is because it requires a chequebook contract to be deployed and for that we need to have ether in the main account. We can get some ether either through mining or by simply issuing ourselves some ether in a custom genesis block.
Custom genesis block¶
Open a text editor and write the following (be sure to include the correct BZZKEY)
{
"nonce": "0x0000000000000042",
"mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"difficulty": "0x4000",
"alloc": {
"THE BZZKEY address starting with 0x eg. 0x2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1": {
"balance": "10000000000000000000"
}
},
"coinbase": "0x0000000000000000000000000000000000000000",
"timestamp": "0x00",
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"extraData": "Custom Ethereum Genesis Block to test Swarm with SWAP",
"gasLimit": "0xffffffff"
}
Save the file as $DATADIR/genesis.json.
If you already have swarm and geth running, kill the processes
killall -s SIGKILL geth
killall -s SIGKILL swarm
and remove the old data from the $DATADIR and then reinitialise with the custom genesis block
rm -rf $DATADIR/geth $DATADIR/swarm
geth --datadir $DATADIR init $DATADIR/genesis.json
We are now ready to restart geth and swarm using our custom genesis block
nohup geth --datadir $DATADIR \
--mine \
--unlock 0 \
--password <(echo -n "MYPASSWORD") \
--verbosity 6 \
--networkid 322 \
--nodiscover \
--maxpeers 0 \
2>> $DATADIR/geth.log &
and launch the swarm (with SWAP); connecting it to the geth node. For consistency let’s use the same network id 322 for the swarm private network.
swarm --bzzaccount $BZZKEY \
--swap \
--swap-api $DATADIR/geth.ipc \
--datadir $DATADIR \
--verbosity 6 \
--ens-api $DATADIR/geth.ipc \
--maxpeers 0 \
--bzznetworkid 322 \
2>> $DATADIR/swarm.log < <(echo -n "MYPASSWORD") &
If all is successful you will see the message “Deploying new chequebook” on the swarm.log. Once the transaction is mined, SWAP is ready.
Note
Astute readers will notice that enabling SWAP while setting maxpeers to 0 seems futile. These instructions will be updated soon to allow you to run a private swap testnet with several peers.
Mining on your private chain¶
The alternative to creating a custom genesis block is to earn all your ether by mining on your private chain.
You can start your geth node in mining mode using the --mine flag, or (in our case) we can start mining on an already running geth node by issuing the miner.start() command:
geth --exec 'miner.start()' attach ipc:$DATADIR/geth.ipc
There will be an initial delay while the necessary DAG is generated. You can see the progress in the geth.log file.
After mining has started, you can see your balance increasing via eth.getBalance():
geth --exec 'eth.getBalance(eth.coinbase)' attach ipc:$DATADIR/geth.ipc
# or
geth --exec 'eth.getBalance(eth.accounts[0])' attach ipc:$DATADIR/geth.ipc
Once the balance is greater than 0 we can restart swarm with swap enabled.
killall swarm
swarm --bzzaccount $BZZKEY \
--swap \
--swap-api $DATADIR/geth.ipc \
--datadir $DATADIR \
--verbosity 6 \
--ens-api $DATADIR/geth.ipc \
--maxpeers 0 \
2>> $DATADIR/swarm.log < <(echo -n "MYPASSWORD") &
Note: without a custom genesis block the mining difficulty may be too high to be practical (depending on your system). You can see the current difficulty with admin.nodeInfo
geth --exec 'admin.nodeInfo' attach ipc:$DATADIR/geth.ipc | grep difficulty
Configuration¶
Command line options for swarm¶
The Swarm executable supports the following configuration options:
- Configuration file
- Environment variables
- Command line
Options provided via command line override options from the environment variables, which will override options in the config file. If an option is not explicitly provided, a default will be chosen.
In order to keep the set of flags and variables manageable, only a subset of all available configuration options are available via command line and environment variables. Some are only available through a TOML configuration file.
Note
Swarm reuses code from ethereum, specifically some p2p networking protocol and other common parts. To this end, it accepts a number of environment variables which are actually from the geth environment. Refer to the geth documentation for reference on these flags.
This is the list of flags inherited from geth:
--identity
--bootnodes
--datadir
--keystore
--nodiscover
--v5disc
--netrestrict
--nodekey
--nodekeyhex
--maxpeers
--nat
--ipcdisable
--ipcpath
--password
The following table illustrates the list of all configuration options and how they can be provided.
Configuration options¶
Note
swarm can be executed with the dumpconfig command, which prints a default configuration to STDOUT, and thus can be redirected to a file as a template for the config file.
A TOML configuration file is organized in sections. The below list of available configuration options is organized according to these sections. The sections correspond to Go modules, so need to be respected in order for file configuration to work properly. See https://github.com/naoina/toml for the TOML parser and encoder library for Golang, and https://github.com/toml-lang/toml for further information on TOML.
General configuration parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| n/a | –config | n/a | n/a | Path to config file in TOML format |
| Contract | –chequebook | SWARM_CHEQUEBOOK_ADDR | 0x0000000000000000000000000000000000000000 | Swap chequebook contract address |
| EnsRoot | –ens-addr | SWARM_ENS_ADDR | ens.TestNetAddress | Ethereum Name Service contract address |
| EnsApi | –ens-api | SWARM_ENS_API | <$GETH_DATADIR>/geth.ipc | Ethereum Name Service API address |
| Path | –datadir | GETH_DATADIR | <$GETH_DATADIR>/swarm | Path to the geth configuration directory |
| ListenAddr | –httpaddr | SWARM_LISTEN_ADDR | 127.0.0.1 | Swarm listen address |
| Port | –bzzport | SWARM_PORT | 8500 | Port to run the http proxy server |
| PublicKey | n/a | n/a | n/a | Public key of swarm base account |
| BzzKey | n/a | n/a | n/a | Swarm node base address (\(hash(PublicKey)hash(PublicKey))\). This is used to decide storage based on radius and routing by kademlia. |
| NetworkId | –bzznetworkid | SWARM_NETWORK_ID | 3 | Network ID |
| SwapEnabled | –swap | SWARM_SWAP_ENABLE | false | Enable SWAP |
| SyncEnabled | –sync | SWARM_SYNC_ENABLE | true | Disable swarm node synchronization. This option will be deprecated. It is only for testing. |
| SwapApi | –swap-api | SWARM_SWAP_API | URL of the Ethereum API provider to use to settle SWAP payments | |
| Cors | –corsdomain | SWARM_CORS | Domain on which to send Access-Control-Allow-Origin header (multiple domains can be supplied separated by a ‘,’) | |
| BzzAccount | –bzzaccount | SWARM_ACCOUNT | Swarm account key | |
| BootNodes | –boot-nodes | SWARM_BOOTNODES | Boot nodes |
Storage parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| ChunkDbPath | n/a | n/a | <$GETH_ENV_DIR>/swarm/bzz-<$BZZ_KEY>/chunks | Path to leveldb chunk DB |
| DbCapacity | n/a | n/a | 5000000 | DB capacity, number of chunks (5M is roughly 20-25GB) |
| CacheCapacity | n/a | n/a | 5000 | Cache capacity, number of recent chunks cached in memory |
| Radius | n/a | n/a | 0 | Storage Radius: minimum proximity order (number of identical prefix bits of address key) for chunks to warrant storage. Given a storage radius \(r\) and total number of chunks in the network \(n\), the node stores \(n*2^{-r}\) chunks minimum. If you allow \(b\) bytes for guaranteed storage and the chunk storage size is \(c\), your radius should be set to \(int(log_2(nc/b))\) |
Chunker parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| Branches | n/a | n/a | 128 | Number of branches in bzzhash merkle tree. \(Branches*ByteSize(Hash)\) gives the datasize of chunks |
| Hash | n/a | n/a | SHA3 | Hash: The hash function used by the chunker (base hash algo of bzzhash): SHA3 or SHA256.This option will be removed in a later release. |
Hive parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| CallInterval | n/a | n/a | 3000000000 | Time elapsed before attempting to connect to the most needed peer |
| KadDbPath | n/a | n/a | <$GETH_ENV_DIR>/swarm/bzz-<$BZZ_KEY>/ | Kademblia DB path, json file path storing the known bzz peers used to bootstrap kademlia table. |
Kademlia parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| MaxProx | n/a | n/a | 8 | highest Proximity order (i.e., Maximum number of identical prefix bits of address key) considered distinct. Given the total number of nodes in the network \(N\), MaxProx should be larger than \(log_2(N/ProxBinSize)\)), safely \(log_2(N)\). |
| ProxBinSize | n/a | n/a | 2 | Number of most proximate nodes lumped together in the most proximate kademlia bin |
| BuckerSize | n/a | n/a | 4 | maximum number of active peers in a kademlia proximity bin. If new peer is added, the worst peer in the bin is dropped. |
| PurgeInterval | n/a | n/a | 151200000000000 | |
| InitialRetryInterval | n/a | n/a | 42000000 | |
| MaxIdleInterval | n/a | n/a | 42000000000 | |
| ConnRetryExp | n/a | n/a | 2 |
SWAP profile parameters¶
These parameters are likely to change in POC 0.3
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| BuyAt | n/a | n/a | 20000000000 | (\(2*10^{10}\) wei), highest accepted price per chunk in wei |
| SellAt | n/a | n/a | 20000000000 | (\(2*10^{10}\) wei) offered price per chunk in wei |
| PayAt | n/a | n/a | 100 | Maximum number of chunks served without receiving a cheque. Debt tolerance. |
| DropAtMaximum | n/a | n/a | 10000 | Number of chunks served without receiving a cheque. Debt tolerance. |
SWAP strategy parameters¶
These parameters are likely to change in POC 0.3
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| AutoCashInterval | n/a | n/a | 300000000000 | (\(3*10^{11}\), 5 minutes) Maximum Time before any outstanding cheques are cashed |
| AutoCashThreshold | n/a | n/a | 50000000000000 | (\(5*10^{13}\)) Maximum total amount of uncashed cheques in Wei |
| AutoDepositInterval | n/a | n/a | 300000000000 | (\(3*10^{11}\), 5 minutes) Maximum time before cheque book is replenished if necessary by sending funds from the baseaccount |
| AutoDepositThreshold | n/a | n/a | 50000000000000 | (\(5*10^{13}\)) Minimum balance in Wei required before replenishing the cheque book |
| AutoDepositBuffer | n/a | n/a | 100000000000000 | (\(10^{14}\)) Maximum amount of Wei expected as a safety credit buffer on the cheque book |
SWAP pay profile parameters¶
These parameters are likely to change in POC 0.3
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| PublicKey | n/a | n/a | Public key of your swarm base account use | |
| Contract | n/a | n/a | 0x0000000000000000000000000000000000000000 | Address of the cheque book contract deployed on the Ethereum blockchain. If blank, a new chequebook contract will be deployed. |
| Beneficiary | n/a | n/a | 0x0000000000000000000000000000000000000000 | Ethereum account address serving as beneficiary of incoming cheques |
Synchronisation parameters¶
| Config file | Command-line flag | Environment variable | Default value | Description |
|---|---|---|---|---|
| RequestDbPath | n/a | n/a | <$GETH_ENV_DIR>/swarm/bzz-<$BZZ_KEY>/requests | Path to request DB |
| RequestDbBatchSize | n/a | n/a | 512 | Request DB Batch size |
| KeyBufferSize | n/a | n/a | 1024 | In-memory cache for unsynced keys |
| SyncBatchSize | n/a | n/a | 128 | In-memory cache for unsynced keys |
| SyncBufferSize | n/a | n/a | 128 | In-memory cache for outgoing deliveries |
| SyncCacheSize | n/a | n/a | 1024 | Maximum number of unsynced keys sent in one batch |
| Sync priorities | n/a | n/a | [2, 1, 1, 0, 0] | Array of 5 priorities corresponding to 5 delivery types:<delivery, propagation, deletion, history, backlog>.Specifying a monotonically decreasing list of priorities is highly recommended. |
| SyncModes | n/a | n/a | [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. |
Note
The status of this project warrants that there will be potentially a lot of changes to these options.
If 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 Incentivisation, esp. 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 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 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:
[BZZ] SWAP unable to deploy new chequebook: unable to send chequebook creation transaction: Account
does not exist or account balance too low.. .retrying in 10s
[BZZ] SWAP arrangement with <enode://23ae0e62.. .. .. [email protected]:30301>: purchase from peer disabled; selling to peer disabled)
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).
[BZZ] netStore.startSearch: unable to send retrieveRequest to peer [<addr>]: [SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> we cannot have debt (unable to buy)
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:
[CHEQUEBOOK] chequebook deployed at 0x77de9813e52e3a.. .c8835ea7 (owner: 0xe10536ae628f7d6e319435ef9b429dcdc085e491)
[CHEQUEBOOK] new chequebook initialised from 0x77de9813e52e3a.. .c8835ea7 (owner: 0xe10536ae628f7d6e319435ef9b429dcdc085e491)
[BZZ] SWAP auto deposit ON for 0xe10536 -> 0x77de98: interval = 5m0s, threshold = 50000000000000, buffer = 100000000000000)
[BZZ] Swarm: new chequebook set: saving config file, resetting all connections in the hive
[KΛÐ]: remove node enode://23ae0e6.. [email protected]:30301 from table
Once the node deployed a new chequebook, its address is set in the config file and all connections are reset with the new conditions. Purchase in one direction should be enabled. The logs from the point of view of the peer with no valid chequebook:
[CHEQUEBOOK] initialised inbox (0x9585.. .3bceee6c -> 0xa5df94be.. .bbef1e5) expected signer: 041e18592.. .. .. 702cf5e73cf8d618
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> set autocash to every 5m0s, max uncashed limit: 50000000000000
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> autodeposit off (not buying)
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> remote profile set: pay at: 100, drop at: 10000, buy at: 20000000000, sell at: 20000000000
[BZZ] SWAP arrangement with <enode://23ae0e62.. .. .. [email protected]:30301>: purchase from peer disabled; selling to peer enabled at 20000000000 wei/chunk)
Depending on autodeposit settings, the chequebook will be regularly replenished:
[BZZ] SWAP auto deposit ON for 0x6d2c5b -> 0xefbb0c:
interval = 5m0s, threshold = 50000000000000,
buffer = 100000000000000)
deposited 100000000000000 wei to chequebook (0xefbb0c0.. .16dea, balance: 100000000000000, target: 100000000000000)
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:
[BZZ] netStore.startSearch: unable to send retrieveRequest to peer [aff89da0c6...623e5671c01]: [SWAP] <enode://[email protected]:30301> we cannot have debt (unable to buy)
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:
initialised inbox (0x95850c6.. .bceee6c -> 0xa5df94b.. .bef1e5) expected signer: 041e185925bb.. .. .. 702cf5e73cf8d618
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> set autocash to every 5m0s, max uncashed limit: 50000000000000
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> set autodeposit to every 5m0s, pay at: 50000000000000, buffer: 100000000000000
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> remote profile set: pay at: 100, drop at: 10000, buy at: 20000000000, sell at: 20000000000
[SWAP] <enode://23ae0e62.. .. .. [email protected]:30301> remote profile set: pay at: 100, drop at: 10000, buy at: 20000000000, sell at: 20000000000
[BZZ] SWAP arrangement with <node://[email protected]:30301>: purchase from peer enabled at 20000000000 wei/chunk; selling to peer enabled at 20000000000 wei/chunk)
As part of normal operation, after a peer reaches a balance of PayAt (number of chunks), a cheque payment is sent via the protocol. Logs on the receiving end:
[CHEQUEBOOK] verify cheque: contract: 0x95850.. .eee6c, beneficiary: 0xe10536ae628.. .cdc085e491, amount: 868020000000000,signature: a7d52dc744b8.. .. .. f1fe2001 - sum: 866020000000000
[CHEQUEBOOK] received cheque of 2000000000000 wei in inbox (0x95850.. .eee6c, uncashed: 42000000000000)
The cheque is verified. If uncashed cheques have an outstanding balance of more than 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.
[CHEQUEBOOK] cashing cheque (total: 104000000000000) on chequebook (0x95850c6.. .eee6c) sending to 0xa5df94be.. .e5aaz
For further fine tuning of SWAP, see SWAP profile parameters.