web3.bzz¶

Note

This API might change over time.

The web3-bzz package allows you to interact with swarm, the decentralized file store. For more see the Swarm Docs.

var Bzz = require('web3-bzz');

// will autodetect if the "ethereum" object is present and will either connect to the local swarm node, or the swarm-gateways.net.
// Optional you can give your own provider URL; If no provider URL is given it will use "http://swarm-gateways.net"
var bzz = new Bzz(Bzz.givenProvider || 'http://swarm-gateways.net');


// or using the web3 umbrella package

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.bzz.currentProvider // if Web3.givenProvider was an ethereum provider it will set: "http://localhost:8500" otherwise it will set: "http://swarm-gateways.net"

// set the provider manually if necessary
web3.bzz.setProvider("http://localhost:8500");

setProvider¶

web3.bzz.setProvider(myProvider)

Will change the provider for its module.

Note

When called on the umbrella package web3 it will also set the provider for all sub modules web3.eth, web3.shh, etc. EXCEPT web3.bzz which needs a separate provider at all times.

Parameters¶

Object - myProvider: a valid provider.

Returns¶

Boolean

Example¶

var Bzz = require('web3-bzz');
var bzz = new Bzz('http://localhost:8500');

// change provider
bzz.setProvider('http://swarm-gateways.net');

givenProvider¶

web3.bzz.givenProvider

When using web3.js in an Ethereum compatible browser, it will set with the current native provider by that browser. Returns the given provider by the (browser) environment, otherwise null.

Returns¶

Object: The given provider set or null;

Example¶

bzz.givenProvider;
> {
    send: function(),
    on: function(),
    bzz: "http://localhost:8500",
    shh: true,
    ...
}

bzz.setProvider(bzz.givenProvider || "http://swarm-gateways.net");

currentProvider¶

bzz.currentProvider

Returns the current provider URL, otherwise null.

Returns¶

Object: The current provider URL or null.

Example¶

bzz.currentProvider;
> "http://localhost:8500"


if(!bzz.currentProvider) {
    bzz.setProvider("http://swarm-gateways.net");
}

upload¶

web3.bzz.upload(mixed)

Uploads files, folders or raw data to swarm.

Parameters¶

mixed - String|Buffer|Uint8Array|Object: The data to upload, can be a file content, file Buffer/Uint8Array, multiple files, or a directory or file (only in node.js). The following types are allowed:
- String|Buffer|Uint8Array: A file content, file Uint8Array or Buffer to upload, or:
- Object:
  
  Multiple key values for files and directories. The paths will be kept the same:
  
  key must be the files path, or name, e.g. "/foo.txt" and its value is an object with:
  
  type: The mime-type of the file, e.g. "text/html".
  
  data: A file content, file Uint8Array or Buffer to upload.
  
  Upload a file or a directory from disk in Node.js. Requires and object with the following properties:
  
  path: The path to the file or directory.
  
  kind: The type of the source "directory", "file" or "data".
  
  defaultFile (optional): Path of the “defaultFile” when "kind": "directory", e.g. "/index.html".
  
  Upload file or folder in the browser. Requres and object with the following properties:
  
  pick: The file picker to launch. Can be "file", "directory" or "data".

Returns¶

Promise returning String: Returns the content hash of the manifest.

Example¶

var bzz = web3.bzz;

// raw data
bzz.upload("test file").then(function(hash) {
    console.log("Uploaded file. Address:", hash);
})

// raw directory
var dir = {
    "/foo.txt": {type: "text/plain", data: "sample file"},
    "/bar.txt": {type: "text/plain", data: "another file"}
};
bzz.upload(dir).then(function(hash) {
    console.log("Uploaded directory. Address:", hash);
});

// upload from disk in node.js
bzz.upload({
    path: "/path/to/thing",      // path to data / file / directory
    kind: "directory",           // could also be "file" or "data"
    defaultFile: "/index.html"   // optional, and only for kind === "directory"
})
.then(console.log)
.catch(console.log);

// upload from disk in the browser
bzz.upload({pick: "file"}) // could also be "directory" or "data"
.then(console.log);

download¶

web3.bzz.download(bzzHash [, localpath])

Downloads files and folders from swarm as buffer or to disk (only node.js).

Parameters¶

bzzHash - String: The file or directory to download. If the hash is a raw file it will return a Buffer, if a manifest file, it will return the directory structure. If the localpath is given, it will return that path where it downloaded the files to.
localpath - String: The local folder to download the content into. (only node.js)

Returns¶

Promise returning Buffer|Object|String: The Buffer of the file downloaded, an object with the directory structure, or the path where it was downloaded to.

Example¶

var bzz = web3.bzz;

// download raw file
var fileHash = "a5c10851ef054c268a2438f10a21f6efe3dc3dcdcc2ea0e6a1a7a38bf8c91e23";
bzz.download(fileHash).then(function(buffer) {
    console.log("Downloaded file:", buffer.toString());
});

// download directory, if the hash is manifest file.
var dirHash = "7e980476df218c05ecfcb0a2ca73597193a34c5a9d6da84d54e295ecd8e0c641";
bzz.download(dirHash).then(function(dir) {
    console.log("Downloaded directory:");
    > {
        'bar.txt': { type: 'text/plain', data: <Buffer 61 6e 6f 74 68 65 72 20 66 69 6c 65> },
        'foo.txt': { type: 'text/plain', data: <Buffer 73 61 6d 70 6c 65 20 66 69 6c 65> }
    }
});

// download file/directory to disk (only node.js)
var dirHash = "a5c10851ef054c268a2438f10a21f6efe3dc3dcdcc2ea0e6a1a7a38bf8c91e23";
bzz.download(dirHash, "/target/dir")
.then(path => console.log(`Downloaded directory to ${path}.`))
.catch(console.log);

pick¶

web3.bzz.pick.file()
web3.bzz.pick.directory()
web3.bzz.pick.data()

Opens a file picker in the browser to select file(s), directory or data.

Parameters¶

none

Returns¶

Promise returning Object: Returns the file or multiple files.

Example¶

web3.bzz.pick.file()
.then(console.log);
> {
    ...
}