Connecting to Swarm (Simple)

These instructions layout the simplest way to use swarm.

How do I connect?

To start a basic swarm node you must have both geth and swarm installed on your manchine. You can find the relevant instructions in the Installation section of the Swarm manual.

Note

You can find the relevant instructions in the Installation and Updates section of the Swarm manual.

If you do have not yet made your Ethereum account, start 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 (for example MYPASSWORD) the output will be your Ethereum address. This is also the base address for your Swarm node.

Address: {2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1}

Since we need to use it later, save it into your ENV variables under the name BZZKEY

BZZKEY=2f1cd699b0bf461dcfbf0098ad8f5587b038f0f1

Next, start your geth node and establish connection with Ethereum main network with the following command

geth

After the connection is established, open another terminal window and connect to Swarm with

swarm --bzzaccount $BZZKEY

How do I upload and download?

Swarm runs an HTTP API. Thus, a simple way to upload and download files to/from Swarm is through this API. We can use the curl tool to exemplify how to interact with this API.

Note

Files can be uploaded in a single HTTP request, where the body is either a single file to store, a tar stream (application/x-tar) or a multipart form (multipart/form-data).

To upload a single file, run this:

curl -H "Content-Type: text/plain" --data-binary "some-data" http://localhost:8500/bzz:/

Once the file is uploaded, you will receive a hex string which will look similar to.

027e57bcbae76c4b6a1c5ce589be41232498f1af86e1b1a2fc2bdffd740e9b39

This is the address string of your content inside Swarm.

To download a file from swarm, you just need the file’s address string. Once you have it the process is simple. Run:

curl http://localhost:8500/bzz:/027e57bcbae76c4b6a1c5ce589be41232498f1af86e1b1a2fc2bdffd740e9b39/

The result should be your file:

some-data

And that’s it. Note that if you omit the trailing slash from the url then the request will result in a redirect.

Tar stream upload

( mkdir dir1 dir2; echo "some-data" | tee dir1/file.txt | tee dir2/file.txt; )

tar c dir1/file.txt dir2/file.txt | curl -H "Content-Type: application/x-tar" --data-binary @- http://localhost:8500/bzz:/
> 1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e

curl http://localhost:8500/bzz:/1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e/dir1/file.txt
> some-data

curl http://localhost:8500/bzz:/1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e/dir2/file.txt
> some-data

GET requests work the same as before with the added ability to download multiple files by setting Accept: application/x-tar:

curl -s -H "Accept: application/x-tar" http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/ | tar t
> dir1/file.txt
  dir2/file.txt
  dir3/file.txt

Multipart form upload

curl -F 'dir1/file.txt=some-data;type=text/plain' -F 'dir2/file.txt=some-data;type=text/plain' http://localhost:8500/bzz:/
> 9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177

curl http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177/dir1/file.txt
> some-data

curl http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177/dir2/file.txt
> some-data

Files can also be added to an existing manifest:

curl -F 'dir3/file.txt=some-other-data;type=text/plain' http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177
> ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8

curl http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir1/file.txt
> some-data

curl http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir3/file.txt
> some-other-data

Files can also be uploaded using a simple HTML form:

<form method="POST" action="/bzz:/" enctype="multipart/form-data">
  <input type="file" name="dir1/file.txt">
  <input type="file" name="dir2/file.txt">
  <input type="submit" value="upload">
</form>

Listing files

A GET request with bzz-list url scheme returns a list of files contained under the path, grouped into common prefixes which represent directories:

curl -s http://localhost:8500/bzz-list:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/ | jq .
> {
   "common_prefixes": [
     "dir1/",
     "dir2/",
     "dir3/"
   ]
 }

curl -s http://localhost:8500/bzz-list:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir1/ | jq .
> {
  "entries": [
    {
      "path": "dir1/file.txt",
      "contentType": "text/plain",
      "size": 9,
      "mod_time": "2017-03-12T15:19:55.112597383Z",
      "hash": "94f78a45c7897957809544aa6d68aa7ad35df695713895953b885aca274bd955"
    }
  ]
}

Setting Accept: text/html returns the list as a browsable HTML document

Good luck, we hope you will enjoy using Swarm!