Skip to content
Swarm: Censorship resistant storage and communication infrastructure for a truly sovereign digital society
Go NSIS Solidity Shell Makefile Dockerfile
Branch: master
Clone or download
santicomp2014 Swap logger (#1754)
* api,debug,log,main,swap,swarm: adds swap specific logger and saves to disk if --swap-audit-logpath is specified
Latest commit 5122fcc Sep 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github .github: fix contributing.md (#1408) Jun 3, 2019
api Swap logger (#1754) Sep 20, 2019
bmt swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
build build: increase golangci-lint deadline (#1778) Sep 19, 2019
bzzeth bzzeth: protocol runloop now quits on peer disconnect Sep 14, 2019
chunk all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
client client: add bzz client, update smoke tests (#1582) Jul 18, 2019
cmd Swap logger (#1754) Sep 20, 2019
contracts contracts/swap, swap: refactor contractAddress, remove backend as inp… Sep 16, 2019
dev swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
docker cmd/swarm: make bzzaccount flag optional and add bzzkeyhex flag (#1531) Jul 4, 2019
docs docs/swarm-guide: cleanup (#1620) Jul 30, 2019
fuse all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
internal Swap logger (#1754) Sep 20, 2019
log Swap logger (#1754) Sep 20, 2019
metrics api, metrics, network: check caps when deciding on next peer for a ch… Sep 12, 2019
network network: Add capability filtered depth calculation (#1787) Sep 20, 2019
p2p protocols, retrieval: swap-enabled messages implement Price (#1771) Sep 19, 2019
pot network: Add Capabilities to Kademlia database (#1713) Sep 19, 2019
pss network, pss: Capability in pss (#1764) Sep 20, 2019
sctx swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
shed chunk, storage: add HasMulti to chunk.Store (#1686) Aug 26, 2019
simulation all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
spancontext swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
state all: first working SWAP version (#1554) Aug 27, 2019
storage api, metrics, network: check caps when deciding on next peer for a ch… Sep 12, 2019
swap Swap logger (#1754) Sep 20, 2019
testutil all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
tracing swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
vendor pss: Refactor. Step 2. Refactor forward cache (#1742) Sep 18, 2019
version version: update to v0.5.0 unstable (#1694) Aug 27, 2019
.dockerignore docker: ignore build/bin when copying files (#1780) Sep 19, 2019
.gitattributes .gitattributes: enable solidity highlighting on github (#16425) Apr 3, 2018
.gitignore dashboard, p2p, vendor: visualize peers (#19247) Mar 13, 2019
.golangci.yml build, vendor: use go modules for vendoring (#1532) Aug 14, 2019
.travis.yml travis: remove go1.12 job (#1784) Sep 20, 2019
AUTHORS swarm: codebase split from go-ethereum (#1405) Jun 3, 2019
CHANGELOG.md version: update to v0.5.0 unstable (#1694) Aug 27, 2019
COPYING all: update license information Jul 7, 2015
COPYING.LESSER all: update license information Jul 7, 2015
Dockerfile all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
Dockerfile.alltools all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
Makefile vendor: upgrade go-ethereum to 1.9.2 (#1689) Aug 29, 2019
OWNERS
README.md README.md: Update Vendored Dependencies section (#1667) Aug 14, 2019
appveyor.yml all: support go 1.13 change to testing/flag packages (#1710) Sep 11, 2019
go.mod travis: remove go1.12 job (#1784) Sep 20, 2019
go.sum pss: Refactor. Step 2. Refactor forward cache (#1742) Sep 18, 2019
network_test.go network: new stream! protocol and pull syncer implementation (#1538) Sep 11, 2019
swarm.go Swap logger (#1754) Sep 20, 2019
swarm_test.go all: configurable payment/disconnect thresholds (#1729) Sep 18, 2019

README.md

Swarm

https://swarm.ethereum.org

Swarm is a distributed storage platform and content distribution service, a native base layer service of the ethereum web3 stack. The primary objective of Swarm is to provide a decentralized and redundant store for dapp code and data as well as block chain and state data. Swarm is also set out to provide various base layer services for web3, including node-to-node messaging, media streaming, decentralised database services and scalable state-channel infrastructure for decentralised service economies.

Travis Gitter

Table of Contents

Building the source

Building Swarm requires Go (version 1.11 or later).

To simply compile the swarm binary without a GOPATH:

$ git clone https://github.com/ethersphere/swarm
$ cd swarm
$ make swarm

You will find the binary under ./build/bin/swarm.

To build a vendored swarm using go get you must have GOPATH set. Then run:

$ go get -d github.com/ethersphere/swarm
$ go install github.com/ethersphere/swarm/cmd/swarm

Running Swarm

$ swarm

If you don't have an account yet, then you will be prompted to create one and secure it with a password:

Your new account is locked with a password. Please give a password. Do not forget this password.
Passphrase:
Repeat passphrase:

If you have multiple accounts created, then you'll have to choose one of the accounts by using the --bzzaccount flag.

$ swarm --bzzaccount <your-account-here>

# example
$ swarm --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1

Verifying that your local Swarm node is running

When running, Swarm is accessible through an HTTP API on port 8500.

Confirm that it is up and running by pointing your browser to http://localhost:8500

Ethereum Name Service resolution

The Ethereum Name Service is the Ethereum equivalent of DNS in the classic web. In order to use ENS to resolve names to Swarm content hashes (e.g. bzz://theswarm.eth), swarm has to connect to a geth instance, which is synced with the Ethereum mainnet. This is done using the --ens-api flag.

$ swarm --bzzaccount <your-account-here> \
        --ens-api '$HOME/.ethereum/geth.ipc'

# in our example
$ swarm --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1 \
        --ens-api '$HOME/.ethereum/geth.ipc'

For more information on usage, features or command line flags, please consult the Documentation.

Documentation

Swarm documentation can be found at https://swarm-guide.readthedocs.io.

Docker

Swarm container images are available at Docker Hub: ethersphere/swarm

Docker tags

  • latest - latest stable release
  • edge - latest build from master
  • v0.x.y - specific stable release

Swarm command line arguments

All Swarm command line arguments are supported and can be sent as part of the CMD field to the Docker container.

Examples:

Running a Swarm container from the command line

$ docker run -it ethersphere/swarm \
                            --debug \
                            --verbosity 4

Running a Swarm container with custom ENS endpoint

$ docker run -it ethersphere/swarm \
                            --ens-api http://1.2.3.4:8545 \
                            --debug \
                            --verbosity 4

Running a Swarm container with metrics enabled

$ docker run -it ethersphere/swarm \
                            --debug \
                            --metrics \
                            --metrics.influxdb.export \
                            --metrics.influxdb.endpoint "http://localhost:8086" \
                            --metrics.influxdb.username "user" \
                            --metrics.influxdb.password "pass" \
                            --metrics.influxdb.database "metrics" \
                            --metrics.influxdb.host.tag "localhost" \
                            --verbosity 4

Running a Swarm container with tracing and pprof server enabled

$ docker run -it ethersphere/swarm \
                            --debug \
                            --tracing \
                            --tracing.endpoint 127.0.0.1:6831 \
                            --tracing.svc myswarm \
                            --pprof \
                            --pprofaddr 0.0.0.0 \
                            --pprofport 6060

Running a Swarm container with a custom data directory mounted from a volume and a password file to unlock the swarm account

$ docker run -it -v $PWD/hostdata:/data \
                 -v $PWD/password:/password \
                 ethersphere/swarm \
                            --datadir /data \
                            --password /password \
                            --debug \
                            --verbosity 4

Developers Guide

Go Environment

We assume that you have Go v1.11 installed, and GOPATH is set.

You must have your working copy under $GOPATH/src/github.com/ethersphere/swarm.

Most likely you will be working from your fork of swarm, let's say from github.com/nirname/swarm. Clone or move your fork into the right place:

$ git clone git@github.com:nirname/swarm.git $GOPATH/src/github.com/ethersphere/swarm

Vendored Dependencies

Vendoring is done by Makefile rule make vendor which uses go mod vendor and additionally copies cgo dependencies into vendor directory from go modules cache.

If you want to add a new dependency, run GO111MODULE=on go get <import-path>, vendor it make vendor, then commit the result.

If you want to update all dependencies to their latest upstream version, run GO111MODULE=on go get -u all and vendor them with make vendor.

By default, go tool will use dependencies defined in go.mod file from modules cache. In order to import code from vendor directory, an additional flag -mod=vendor must be provided when calling go run, go test, go build and go install. If vendor directory is in sync with go.mod file by updating it with make vendor, there should be no difference to use the flag or not. All Swarm build tools are using code only from the vendor directory and it is encouraged to do the same in the development process, as well.

Testing

This section explains how to run unit, integration, and end-to-end tests in your development sandbox.

Testing one library:

$ go test -v -cpu 4 ./api

Note: Using options -cpu (number of cores allowed) and -v (logging even if no error) is recommended.

Testing only some methods:

$ go test -v -cpu 4 ./api -run TestMethod

Note: here all tests with prefix TestMethod will be run, so if you got TestMethod, TestMethod1, then both!

Running benchmarks:

$ go test -v -cpu 4 -bench . -run BenchmarkJoin

Profiling Swarm

This section explains how to add Go pprof profiler to Swarm

If swarm is started with the --pprof option, a debugging HTTP server is made available on port 6060.

You can bring up http://localhost:6060/debug/pprof to see the heap, running routines etc.

By clicking full goroutine stack dump (clicking http://localhost:6060/debug/pprof/goroutine?debug=2) you can generate trace that is useful for debugging.

Metrics and Instrumentation in Swarm

This section explains how to visualize and use existing Swarm metrics and how to instrument Swarm with a new metric.

Swarm metrics system is based on the go-metrics library.

The most common types of measurements we use in Swarm are counters and resetting timers. Consult the go-metrics documentation for full reference of available types.

// incrementing a counter
metrics.GetOrRegisterCounter("network.stream.received_chunks", nil).Inc(1)

// measuring latency with a resetting timer
start := time.Now()
t := metrics.GetOrRegisterResettingTimer("http.request.GET.time"), nil)
...
t := UpdateSince(start)

Visualizing metrics

Swarm supports an InfluxDB exporter. Consult the help section to learn about the command line arguments used to configure it:

$ swarm --help | grep metrics

We use Grafana and InfluxDB to visualise metrics reported by Swarm. We keep our Grafana dashboards under version control at https://github.com/ethersphere/grafana-dashboards. You could use them or design your own.

We have built a tool to help with automatic start of Grafana and InfluxDB and provisioning of dashboards at https://github.com/nonsense/stateth, which requires that you have Docker installed.

Once you have stateth installed, and you have Docker running locally, you have to:

  1. Run stateth and keep it running in the background
$ stateth --rm --grafana-dashboards-folder $GOPATH/src/github.com/ethersphere/grafana-dashboards --influxdb-database metrics
  1. Run swarm with at least the following params:
--metrics \
--metrics.influxdb.export \
--metrics.influxdb.endpoint "http://localhost:8086" \
--metrics.influxdb.username "admin" \
--metrics.influxdb.password "admin" \
--metrics.influxdb.database "metrics"
  1. Open Grafana at http://localhost:3000 and view the dashboards to gain insight into Swarm.

Public Gateways

Swarm offers a local HTTP proxy API that Dapps can use to interact with Swarm. The Ethereum Foundation is hosting a public gateway, which allows free access so that people can try Swarm without running their own node.

The Swarm public gateways are temporary and users should not rely on their existence for production services.

The Swarm public gateway can be found at https://swarm-gateways.net and is always running the latest stable Swarm release.

Swarm Dapps

You can find a few reference Swarm decentralised applications at: https://swarm-gateways.net/bzz:/swarmapps.eth

Their source code can be found at: https://github.com/ethersphere/swarm-dapps

Contributing

Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!

If you'd like to contribute to Swarm, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on our Swarm gitter channel to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.

Please make sure your contributions adhere to our coding guidelines:

  • Code must adhere to the official Go formatting guidelines (i.e. uses gofmt).
  • Code must be documented adhering to the official Go commentary guidelines.
  • Pull requests need to be based on and opened against the master branch.
  • Code review guidelines.
  • Commit messages should be prefixed with the package(s) they modify.
    • E.g. "fuse: ignore default manifest entry"

License

The swarm library (i.e. all code outside of the cmd directory) is licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file.

The swarm binaries (i.e. all code inside of the cmd directory) is licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file.

You can’t perform that action at this time.