{"id":13483248,"url":"https://github.com/ethersphere/swarm","last_synced_at":"2026-01-10T18:22:13.720Z","repository":{"id":15063898,"uuid":"17790136","full_name":"ethersphere/swarm","owner":"ethersphere","description":"Swarm: Censorship resistant storage and communication infrastructure for a truly sovereign digital society","archived":true,"fork":false,"pushed_at":"2021-03-18T09:51:41.000Z","size":151946,"stargazers_count":487,"open_issues_count":311,"forks_count":110,"subscribers_count":35,"default_branch":"master","last_synced_at":"2024-12-22T20:02:11.557Z","etag":null,"topics":["blockchain","ethereum","go","obsolete","p2p","storage","swarm"],"latest_commit_sha":null,"homepage":"https://swarm.ethereum.org/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethersphere.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2014-03-16T02:06:34.000Z","updated_at":"2024-12-17T08:42:43.000Z","dependencies_parsed_at":"2022-07-16T11:30:34.851Z","dependency_job_id":null,"html_url":"https://github.com/ethersphere/swarm","commit_stats":null,"previous_names":["ethersphere/go-ethereum"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethersphere","download_url":"https://codeload.github.com/ethersphere/swarm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245863065,"owners_count":20684782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","ethereum","go","obsolete","p2p","storage","swarm"],"created_at":"2024-07-31T17:01:09.398Z","updated_at":"2026-01-10T18:22:13.621Z","avatar_url":"https://github.com/ethersphere.png","language":"Go","readme":"## Swarm  \u003c!-- omit in toc --\u003e\n\n[https://swarm.ethereum.org](https://swarm.ethereum.org)\n\nSwarm 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.\n\n## New Bee client\n\nIn the effort to release a production-ready version of Swarm, the Swarm dev team has migrated their effort to build the [new Bee client](https://github.com/ethersphere/bee), a brand-new implementation of Swarm. The main reason for this switch was the availability of a more mature networking layer (libp2p) and the secondary reason being that the insight gained from developing Swarm taught us many lessons which can be implemented best from scratch. While Bee does not currently expose every feature in the original Swarm client, development is happening at lightspeed and soon, it will surpass Swarm in functionality and stability!\n\nPlease refer to [Swarm webpage](https://ethswarm.org) for more information about the state of the Bee client and to [the Bee documentation](https://docs.ethswarm.org) for info on installing and using the new client.\n\n### Original Swarm client\n\nThe old Swarm client, contained in this repository, can still be used while the network exists, however no maintenance or upgrades are planned for it.\n\nPlease read the [The sun is setting for the old Swarm](https://medium.com/ethereum-swarm/the-sun-is-setting-for-the-old-swarm-network-46cdc8048f8b) network blog post for more information and also how to reach out for help with migration.\n\n### Compatibility of Bee with the first Swarm\n\nNo compatibility on the network layer with the first Ethereum Swarm implementation can be provided, mainly due to the migration in underlying network protocol from devp2p to libp2p. This means that a Bee node cannot join first Swarm network and vice versa. Migrating data is possible, please get in touch for more info on how to approach this. 🐝 \n\n### How to get in touch\n\nPlease use any of the following channels for help with migration or any other questions:\n\nThe Swarm team is reachable on [Mattermost](http://beehive.ethswarm.org/).\nJoin the Swarm Orange Lounge on [Telegram](https://t.me/joinchat/GoVG8RHYjUpD_-bEnLC4EQ).\nFollow us on [Twitter](https://twitter.com/ethswarm).\n\n[![Travis](https://travis-ci.org/ethersphere/swarm.svg?branch=master)](https://travis-ci.org/ethersphere/swarm)\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ethersphere/orange-lounge?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![](https://godoc.org/github.com/nathany/looper?status.svg)](https://godoc.org/github.com/ethersphere/swarm/)\n\n\n## Table of Contents  \u003c!-- omit in toc --\u003e\n\n- [Building the source](#building-the-source)\n- [Running Swarm](#running-swarm)\n  - [Verifying that your local Swarm node is running](#verifying-that-your-local-swarm-node-is-running)\n  - [Ethereum Name Service resolution](#ethereum-name-service-resolution)\n- [Documentation](#documentation)\n- [Docker](#docker)\n  - [Docker tags](#docker-tags)\n  - [Swarm command line arguments](#swarm-command-line-arguments)\n- [Developers Guide](#developers-guide)\n  - [Go Environment](#go-environment)\n  - [Vendored Dependencies](#vendored-dependencies)\n  - [Testing](#testing)\n  - [Profiling Swarm](#profiling-swarm)\n  - [Metrics and Instrumentation in Swarm](#metrics-and-instrumentation-in-swarm)\n    - [Visualizing metrics](#visualizing-metrics)\n- [Public Gateways](#public-gateways)\n- [Swarm Dapps](#swarm-dapps)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Building the source\n\nIt's recommended to use Go 1.14 to build Swarm.\n\nTo simply compile the `swarm` binary without a `GOPATH`:\n\n```bash\n$ git clone https://github.com/ethersphere/swarm\n$ cd swarm\n$ make swarm\n```\n\nYou will find the binary under `./build/bin/swarm`.\n\nTo build a vendored `swarm` using `go get` you must have `GOPATH` set. Then run:\n\n```bash\n$ go get -d github.com/ethersphere/swarm\n$ go install github.com/ethersphere/swarm/cmd/swarm\n```\n\n## Running Swarm\n\n```bash\n$ swarm\n```\n\nIf you don't have an account yet, then you will be prompted to create one and secure it with a password:\n\n```\nYour new account is locked with a password. Please give a password. Do not forget this password.\nPassphrase:\nRepeat passphrase:\n```\n\nIf you have multiple accounts created, then you'll have to choose one of the accounts by using the `--bzzaccount` flag.\n\n```bash\n$ swarm --bzzaccount \u003cyour-account-here\u003e\n\n# example\n$ swarm --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1\n```\n\n### Verifying that your local Swarm node is running\n\nWhen running, Swarm is accessible through an HTTP API on port 8500.\n\nConfirm that it is up and running by pointing your browser to http://localhost:8500\n\n### Ethereum Name Service resolution\n\nThe 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.\n\n```bash\n$ swarm --bzzaccount \u003cyour-account-here\u003e \\\n        --ens-api '$HOME/.ethereum/geth.ipc'\n\n# in our example\n$ swarm --bzzaccount 2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1 \\\n        --ens-api '$HOME/.ethereum/geth.ipc'\n```\n\nFor more information on usage, features or command line flags, please consult the Documentation.\n\n## Documentation\n\nSwarm documentation can be found at [https://swarm-guide.readthedocs.io](https://swarm-guide.readthedocs.io).\n\n## Docker\n\nSwarm container images are available at Docker Hub: [ethersphere/swarm](https://hub.docker.com/r/ethersphere/swarm)\n\n### Docker tags\n\n* `latest` - latest stable release\n* `edge` - latest build from `master`\n* `v0.x.y` - specific stable release\n\n### Swarm command line arguments\n\nAll Swarm command line arguments are supported and can be sent as part of the CMD field to the Docker container.\n\n**Examples:**\n\nRunning a Swarm container from the command line\n\n```bash\n$ docker run -it ethersphere/swarm \\\n                            --debug \\\n                            --verbosity 4\n```\n\n\nRunning a Swarm container with custom ENS endpoint\n\n```bash\n$ docker run -it ethersphere/swarm \\\n                            --ens-api http://1.2.3.4:8545 \\\n                            --debug \\\n                            --verbosity 4\n```\n\nRunning a Swarm container with metrics enabled\n\n```bash\n$ docker run -it ethersphere/swarm \\\n                            --debug \\\n                            --metrics \\\n                            --metrics.influxdb.export \\\n                            --metrics.influxdb.endpoint \"http://localhost:8086\" \\\n                            --metrics.influxdb.username \"user\" \\\n                            --metrics.influxdb.password \"pass\" \\\n                            --metrics.influxdb.database \"metrics\" \\\n                            --metrics.influxdb.host.tag \"localhost\" \\\n                            --verbosity 4\n```\n\nRunning a Swarm container with tracing and pprof server enabled\n\n```bash\n$ docker run -it ethersphere/swarm \\\n                            --debug \\\n                            --tracing \\\n                            --tracing.endpoint 127.0.0.1:6831 \\\n                            --tracing.svc myswarm \\\n                            --pprof \\\n                            --pprofaddr 0.0.0.0 \\\n                            --pprofport 6060\n```\n\nRunning a Swarm container with a custom data directory mounted from a volume and a password file to unlock the swarm account\n\n```bash\n$ docker run -it -v $PWD/hostdata:/data \\\n                 -v $PWD/password:/password \\\n                 ethersphere/swarm \\\n                            --datadir /data \\\n                            --password /password \\\n                            --debug \\\n                            --verbosity 4\n```\n\n## Developers Guide\n\n### Go Environment\n\nWe assume that you have Go v1.11 installed, and `GOPATH` is set.\n\nYou must have your working copy under `$GOPATH/src/github.com/ethersphere/swarm`.\n\nMost 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:\n\n```bash\n$ git clone git@github.com:nirname/swarm.git $GOPATH/src/github.com/ethersphere/swarm\n```\n\n\n### Vendored Dependencies\n\nVendoring is done by Makefile rule `make vendor` which uses `go mod vendor` and additionally copies cgo dependencies into `vendor` directory from go modules cache.\n\nIf you want to add a new dependency, run `go get \u003cimport-path\u003e`, vendor it `make vendor`, then commit the result.\n\nIf you want to update all dependencies to their latest upstream version, run `go get -u all` and vendor them with `make vendor`.\n\nBy 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.\n\n\n### Testing\n\nThis section explains how to run unit, integration, and end-to-end tests in your development sandbox.\n\nTesting one library:\n\n```bash\n$ go test -v -cpu 4 ./api\n```\n\nNote: Using options -cpu (number of cores allowed) and -v (logging even if no error) is recommended.\n\nTesting only some methods:\n\n```bash\n$ go test -v -cpu 4 ./api -run TestMethod\n```\n\nNote: here all tests with prefix TestMethod will be run, so if you got TestMethod, TestMethod1, then both!\n\nRunning benchmarks:\n\n```bash\n$ go test -v -cpu 4 -bench . -run BenchmarkJoin\n```\n\n\n### Profiling Swarm\n\nThis section explains how to add Go `pprof` profiler to Swarm\n\nIf `swarm` is started with the `--pprof` option, a debugging HTTP server is made available on port 6060.\n\nYou can bring up http://localhost:6060/debug/pprof to see the heap, running routines etc.\n\nBy clicking full goroutine stack dump (clicking http://localhost:6060/debug/pprof/goroutine?debug=2) you can generate trace that is useful for debugging.\n\n\n### Metrics and Instrumentation in Swarm\n\nThis section explains how to visualize and use existing Swarm metrics and how to instrument Swarm with a new metric.\n\nSwarm metrics system is based on the `go-metrics` library.\n\nThe 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.\n\n```go\n// incrementing a counter\nmetrics.GetOrRegisterCounter(\"network/stream/received_chunks\", nil).Inc(1)\n\n// measuring latency with a resetting timer\nstart := time.Now()\nt := metrics.GetOrRegisterResettingTimer(\"http/request/GET/time\"), nil)\n...\nt := UpdateSince(start)\n```\n\n#### Visualizing metrics\n\nSwarm supports an InfluxDB exporter. Consult the help section to learn about the command line arguments used to configure it:\n\n```bash\n$ swarm --help | grep metrics\n```\n\nWe 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.\n\nWe 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.\n\nOnce you have `stateth` installed, and you have Docker running locally, you have to:\n\n1. Run `stateth` and keep it running in the background\n\n```bash\n$ stateth --rm --grafana-dashboards-folder $GOPATH/src/github.com/ethersphere/grafana-dashboards --influxdb-database metrics\n```\n\n2. Run `swarm` with at least the following params:\n\n```bash\n--metrics \\\n--metrics.influxdb.export \\\n--metrics.influxdb.endpoint \"http://localhost:8086\" \\\n--metrics.influxdb.username \"admin\" \\\n--metrics.influxdb.password \"admin\" \\\n--metrics.influxdb.database \"metrics\"\n```\n\n3. Open Grafana at http://localhost:3000 and view the dashboards to gain insight into Swarm.\n\n\n## Public Gateways\n\nSwarm 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.\n\nThe Swarm public gateways are temporary and users should not rely on their existence for production services.\n\nThe Swarm public gateway can be found at https://swarm-gateways.net and is always running the latest `stable` Swarm release.\n\n## Swarm Dapps\n\nYou can find a few reference Swarm decentralised applications at: https://swarm-gateways.net/bzz:/swarmapps.eth\n\nTheir source code can be found at: https://github.com/ethersphere/swarm-dapps\n\n## Contributing\n\nThank you for considering to help out with the source code! We welcome contributions from\nanyone on the internet, and are grateful for even the smallest of fixes!\n\nIf you'd like to contribute to Swarm, please fork, fix, commit and send a pull request\nfor the maintainers to review and merge into the main code base. If you wish to submit more\ncomplex changes though, please check up with the core devs first on [our Swarm gitter channel](https://gitter.im/ethersphere/orange-lounge)\nto ensure those changes are in line with the general philosophy of the project and/or get some\nearly feedback which can make both your efforts much lighter as well as our review and merge\nprocedures quick and simple.\n\nPlease make sure your contributions adhere to our coding guidelines:\n\n * Code must adhere to the official Go [formatting](https://golang.org/doc/effective_go.html#formatting) guidelines (i.e. uses [gofmt](https://golang.org/cmd/gofmt/)).\n * Code must be documented adhering to the official Go [commentary](https://golang.org/doc/effective_go.html#commentary) guidelines.\n * Pull requests need to be based on and opened against the `master` branch.\n * [Code review guidelines](https://github.com/ethersphere/swarm/blob/master/docs/Code-Review-Guidelines.md).\n * Commit messages should be prefixed with the package(s) they modify.\n   * E.g. \"fuse: ignore default manifest entry\"\n\n\n## License\n\nThe swarm library (i.e. all code outside of the `cmd` directory) is licensed under the\n[GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html), also\nincluded in our repository in the `COPYING.LESSER` file.\n\nThe swarm binaries (i.e. all code inside of the `cmd` directory) is licensed under the\n[GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), also included\nin our repository in the `COPYING` file.\n","funding_links":[],"categories":["Applications"],"sub_categories":["Data Storage and Sharing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethersphere%2Fswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fswarm/lists"}