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.
- key must be the files path, or name, e.g.
- 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. Requires 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 thelocalpath
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);