swarm

package

v0.7.3 Latest Latest Go to latest Published: Oct 21, 2019 License: GPL-3.0 Imports: 34 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/PlatONnetwork/PlatON-Go

README ¶

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.

Building the source

Building Swarm requires Go (version 1.10 or later).

go get -d github.com/ethereum/go-ethereum

go install github.com/ethereum/go-ethereum/cmd/swarm

Running Swarm

Going through all the possible command line flags is out of scope here, but we've enumerated a few common parameter combos to get you up to speed quickly on how you can run your own Swarm node.

To run Swarm you need an Ethereum account. You can create a new account by running the following command:

geth 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, the output will be the Ethereum address representing that account. For example:

Address: {2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1}

Using this account, connect to Swarm with

swarm --bzzaccount <your-account-here>

# in our 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.

Developers Guide

Go Environment

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

You must have your working copy under $GOPATH/src/github.com/ethereum/go-ethereum.

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

git clone git@github.com:nirname/go-ethereum.git $GOPATH/src/github.com/ethereum/go-ethereum

Vendored Dependencies

All dependencies are tracked in the vendor directory. We use govendor to manage them.

If you want to add a new dependency, run govendor fetch <import-path>, then commit the result.

If you want to update all dependencies to their latest upstream version, run govendor fetch +v.

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 ./swarm/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 ./eth -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 ./swarm/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:

Run stateth and keep it running in the background

stateth --rm --grafana-dashboards-folder $GOPATH/src/github.com/ethereum/go-ethereum/swarm/grafana_dashboards --influxdb-database metrics

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"

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. "swarm/fuse: ignore default manifest entry"

License

The go-ethereum 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 go-ethereum 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.

Documentation ¶

Index ¶

type Info
- func (self *Info) Info() *Info
type Swarm
- func NewSwarm(config *api.Config, mockStore *mock.NodeStore) (self *Swarm, err error)
type SwarmAPI
type Voidstore
- func (self Voidstore) Load(string) ([]byte, error)
- func (self Voidstore) Save(string, []byte) error

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Info ¶

type Info struct {
	*api.Config
	*chequebook.Params
}

serialisable info about swarm

func (*Info) Info ¶

func (self *Info) Info() *Info

type Swarm ¶

type Swarm struct {
	// contains filtered or unexported fields
}

the swarm stack

func NewSwarm ¶

func NewSwarm(config *api.Config, mockStore *mock.NodeStore) (self *Swarm, err error)

creates a new swarm service instance implements node.Service If mockStore is not nil, it will be used as the storage for chunk data. MockStore should be used only for testing.

func (*Swarm) API ¶

func (self *Swarm) API() *SwarmAPI

func (*Swarm) APIs ¶

func (self *Swarm) APIs() []rpc.API

implements node.Service APIs returns the RPC API descriptors the Swarm implementation offers

func (*Swarm) Api ¶

func (self *Swarm) Api() *api.API

func (*Swarm) Protocols ¶

func (self *Swarm) Protocols() (protos []p2p.Protocol)

implements the node.Service interface

func (*Swarm) RegisterPssProtocol ¶

func (self *Swarm) RegisterPssProtocol(spec *protocols.Spec, targetprotocol *p2p.Protocol, options *pss.ProtocolParams) (*pss.Protocol, error)

func (*Swarm) SetChequebook ¶

func (self *Swarm) SetChequebook(ctx context.Context) error

SetChequebook ensures that the local checquebook is set up on chain.

func (*Swarm) Start ¶

func (self *Swarm) Start(srv *p2p.Server) error

Start is called when the stack is started * starts the network kademlia hive peer management * (starts netStore level 0 api) * starts DPA level 1 api (chunking -> store/retrieve requests) * (starts level 2 api) * starts http proxy server * registers url scheme handlers for bzz, etc * TODO: start subservices like sword, swear, swarmdns

implements the node.Service interface

func (*Swarm) Stop ¶

func (self *Swarm) Stop() error

implements the node.Service interface stops all component services.

type SwarmAPI ¶

type SwarmAPI struct {
	Api     *api.API
	Backend chequebook.Backend
}

type Voidstore ¶

type Voidstore struct {
}

func (Voidstore) Load ¶

func (self Voidstore) Load(string) ([]byte, error)

func (Voidstore) Save ¶

func (self Voidstore) Save(string, []byte) error

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
api
client
http A simple http server interface to Swarm	A simple http server interface to Swarm
bmt Package bmt provides a binary merkle tree implementation used for swarm chunk hash Package bmt is a simple nonconcurrent reference implementation for hashsize segment based Binary Merkle tree hash on arbitrary but fixed maximum chunksize This implementation does not take advantage of any paralellisms and uses far more memory than necessary, but it is easy to see that it is correct.	Package bmt provides a binary merkle tree implementation used for swarm chunk hash Package bmt is a simple nonconcurrent reference implementation for hashsize segment based Binary Merkle tree hash on arbitrary but fixed maximum chunksize This implementation does not take advantage of any paralellisms and uses far more memory than necessary, but it is easy to see that it is correct.
chunk
fuse
log
metrics
multihash
network
bitvector
priorityqueue
simulation
simulations You can run this simulation using go run ./swarm/network/simulations/overlay.go	You can run this simulation using go run ./swarm/network/simulations/overlay.go
simulations/discovery
stream
stream/intervals
pot Package pot see doc.go Package pot (proximity order tree) implements a container similar to a binary tree.	Package pot see doc.go Package pot (proximity order tree) implements a container similar to a binary tree.
pss Pss provides devp2p functionality for swarm nodes without the need for a direct tcp connection between them.	Pss provides devp2p functionality for swarm nodes without the need for a direct tcp connection between them.
client simple abstraction for implementing pss functionality the pss client library aims to simplify usage of the p2p.protocols package over pss IO is performed using the ordinary p2p.MsgReadWriter interface, which transparently communicates with a pss node via RPC using websockets as transport layer, using methods in the PssAPI class in the swarm/pss package Minimal-ish usage example (requires a running pss node with websocket RPC): import ( "context" "fmt" "os" pss "github.com/PlatONnetwork/PlatON-Go/swarm/pss/client" "github.com/PlatONnetwork/PlatON-Go/p2p/protocols" "github.com/PlatONnetwork/PlatON-Go/p2p" "github.com/PlatONnetwork/PlatON-Go/swarm/pot" "github.com/PlatONnetwork/PlatON-Go/swarm/log" ) type FooMsg struct { Bar int } func fooHandler (msg interface{}) error { foomsg, ok := msg.(FooMsg) if ok { log.Debug("Yay, just got a message", "msg", foomsg) } return errors.New(fmt.Sprintf("Unknown message")) } spec := &protocols.Spec{ Name: "foo", Version: 1, MaxMsgSize: 1024, Messages: []interface{}{ FooMsg{}, }, } proto := &p2p.Protocol{ Name: spec.Name, Version: spec.Version, Length: uint64(len(spec.Messages)), Run: func(p p2p.Peer, rw p2p.MsgReadWriter) error { pp := protocols.NewPeer(p, rw, spec) return pp.Run(fooHandler) }, } func implementation() { cfg := pss.NewClientConfig() psc := pss.NewClient(context.Background(), nil, cfg) err := psc.Start() if err != nil { log.Crit("can't start pss client") os.Exit(1) } log.Debug("connected to pss node", "bzz addr", psc.BaseAddr) err = psc.RunProtocol(proto) if err != nil { log.Crit("can't start protocol on pss websocket") os.Exit(1) } addr := pot.RandomAddress() // should be a real address, of course psc.AddPssPeer(addr, spec) // use the protocol for something psc.Stop() } BUG(test): TestIncoming test times out due to deadlock issues in the swarm hive	simple abstraction for implementing pss functionality the pss client library aims to simplify usage of the p2p.protocols package over pss IO is performed using the ordinary p2p.MsgReadWriter interface, which transparently communicates with a pss node via RPC using websockets as transport layer, using methods in the PssAPI class in the swarm/pss package Minimal-ish usage example (requires a running pss node with websocket RPC): import ( "context" "fmt" "os" pss "github.com/PlatONnetwork/PlatON-Go/swarm/pss/client" "github.com/PlatONnetwork/PlatON-Go/p2p/protocols" "github.com/PlatONnetwork/PlatON-Go/p2p" "github.com/PlatONnetwork/PlatON-Go/swarm/pot" "github.com/PlatONnetwork/PlatON-Go/swarm/log" ) type FooMsg struct { Bar int } func fooHandler (msg interface{}) error { foomsg, ok := msg.(FooMsg) if ok { log.Debug("Yay, just got a message", "msg", foomsg) } return errors.New(fmt.Sprintf("Unknown message")) } spec := &protocols.Spec{ Name: "foo", Version: 1, MaxMsgSize: 1024, Messages: []interface{}{ FooMsg{}, }, } proto := &p2p.Protocol{ Name: spec.Name, Version: spec.Version, Length: uint64(len(spec.Messages)), Run: func(p p2p.Peer, rw p2p.MsgReadWriter) error { pp := protocols.NewPeer(p, rw, spec) return pp.Run(fooHandler) }, } func implementation() { cfg := pss.NewClientConfig() psc := pss.NewClient(context.Background(), nil, cfg) err := psc.Start() if err != nil { log.Crit("can't start pss client") os.Exit(1) } log.Debug("connected to pss node", "bzz addr", psc.BaseAddr) err = psc.RunProtocol(proto) if err != nil { log.Crit("can't start protocol on pss websocket") os.Exit(1) } addr := pot.RandomAddress() // should be a real address, of course psc.AddPssPeer(addr, spec) // use the protocol for something psc.Stop() } BUG(test): TestIncoming test times out due to deadlock issues in the swarm hive
notify
sctx
services
swap
swap/swap
spancontext
state
storage
encryption
mock Package mock defines types that are used by different implementations of mock storages.	Package mock defines types that are used by different implementations of mock storages.
mock/db Package db implements a mock store that keeps all chunk data in LevelDB database.	Package db implements a mock store that keeps all chunk data in LevelDB database.
mock/mem Package mem implements a mock store that keeps all chunk data in memory.	Package mem implements a mock store that keeps all chunk data in memory.
mock/rpc Package rpc implements an RPC client that connect to a centralized mock store.	Package rpc implements an RPC client that connect to a centralized mock store.
mock/test Package test provides functions that are used for testing GlobalStorer implementations.	Package test provides functions that are used for testing GlobalStorer implementations.
mru Package mru defines Mutable resource updates.	Package mru defines Mutable resource updates.
testutil
tracing
version

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

Swarm

Table of Contents

Building the source

Running Swarm

Verifying that your local Swarm node is running

Ethereum Name Service resolution

Documentation

Developers Guide

Go Environment

Vendored Dependencies

Testing

Profiling Swarm

Metrics and Instrumentation in Swarm

Visualizing metrics

Public Gateways

Swarm Dapps

Contributing

License

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type Info ¶

func (*Info) Info ¶

type Swarm ¶

func NewSwarm ¶

func (*Swarm) API ¶

func (*Swarm) APIs ¶

func (*Swarm) Api ¶

func (*Swarm) Protocols ¶

func (*Swarm) RegisterPssProtocol ¶

func (*Swarm) SetChequebook ¶

func (*Swarm) Start ¶

func (*Swarm) Stop ¶

type SwarmAPI ¶

type Voidstore ¶

func (Voidstore) Load ¶

func (Voidstore) Save ¶

Source Files ¶

Directories ¶