Skip to content

Latest commit

 

History

History
309 lines (202 loc) · 7.92 KB

web3-bzz.rst

File metadata and controls

309 lines (202 loc) · 7.92 KB
Raw

web3.bzz

Note

This API might change over time.

The web3-bzz package allows you to interact 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

  1. Object - myProvider: :ref:`a valid provider <web3-providers>`.

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. Will return 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

Will return 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

  1. 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:
      1. 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.
      2. 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".
      3. 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

  1. 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.
  2. 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);
> {
    ...
}