1.6.1-beta.1

Install | Usage | Dapp data | Example | API Docs

3box-js

This is a library which allows you to set, get, and remove private and public data associated with an ethereum account. It can be used to store identity data, user settings, etc. by dapps that use a web3 enabled browser. The data will be retrievable as long as the user has access to the private key for the used ethereum account. The data is encrypted and can not be read by any third party that the user hasn't authorized. There is one shared space for data which all authorized dapps access by default, then there are spaces which dapps have to request explicit consent to access.

Installation

Install 3box in your npm project:

$ npm install 3box

Usage

Import 3Box into your project

Import the 3box module

const Box = require('3box')

Import using the dist build in your html code

<script type="text/javascript" src="../dist/3box.js"></script>

Or optionally by loading remote copy from unpkg CDN.

<!-- The most recent version  -->
<script src="https://unpkg.com/3box/dist/3box.js"></script>
<!-- The most recent minified version  -->
<script src="https://unpkg.com/3box/dist/3box.min.js"></script>
<!-- Load specific versions by specifying the version as follows -->
<script src="https://unpkg.com/3box@<version>/dist/3box.js"></script>

Get the public profile of an address

3Box allows users to create a public profile. In your dapp you might have multiple ethereum addresses that you would like to display a name and picture for. The getProfile method allows you to retrieve the profile of any ethereum address (if it has one). This is a static method so you can call it directly from the Box object.

const profile = await Box.getProfile('0x12345abcde')
console.log(profile)

Get, set, and remove data

To get or modify data in a user's 3Box, first open their 3Box by calling the openBox method. This method prompts the user to authenticate your dapp and returns a promise with a threeBox instance. You can only set, get, and remove data of users that are currently interacting with your dapp. Below ethereumProvider refers to the object that you would get from web3.currentProvider, or window.ethereum.

Open 3Box session

const box = await Box.openBox('0x12345abcde', ethereumProvider)

Network sync

When you first open the box in your dapp all data might not be synced from the network yet. You should therefore add a listener using the onSyncDone method. This will allow you to know when all the users data is available to you. We advice against setting any data before this has happened. However reading data before is fine and encurraged, just remember to check for updates once this callback is fired!

box.onSyncDone(yourCallbackFunction)

Interact with 3Box profile data

You can now use the box instance object to interact with data in the users private and public data. In both the public and the private data store you use a key to set a value.

// use the public profile
// get
const nickname = await box.public.get('name')
console.log(nickname)
// set
await box.public.set('name', 'oed')
// remove
await box.public.remove('name')

// use the private store
// get
const email = await box.private.get('email')
console.log(email)
// set
await box.private.set('email', 'oed@email.service')
// remove
await box.private.remove('email')

Open a space

A space is a named section of a users 3Box. Each space has both a public and a private store, and for every space you open the user has to grant explicit consent to view that space. This means that if your dapp uses a space that no other dapp uses, only your dapp is allowed to update the data and read the private store of that particular space. To open a space called narwhal you simply call:

const space = await box.openSpace('narwhal')

Get, set, and remove space data

Interacting with data in a space is done in the same way as interacting with box.public and box.private (see here). For example:

const config = await space.private.get('dapp-config')

Using threads

WARNING: this is an experimental feature, the api will likely change in the future! Threads are a type of datastore that can be used to communicate between users. For example they could be used to implement a commenting system, among other things. Threads are created within a space and users that join a thread with the same name will be able to communicate.

Joining a thread

const thread = await space.joinThread('myThread')

Posting to thread

await thread.post('hello world')

Getting all posts in a thread

const posts = await thread.getPosts()
console.log(posts)

Listening for updates in thread

thread.onNewPost(myCallbackFunction)

Get all posts in a thread without a space instance

You can get all posts made in a thread without opening a space.

const posts = await Box.getThread(spaceName, threadName)
console.log(posts)

Dapp data

Dapps can store data about users that relate to only their dapp. However we encurage dapps to share data between them for a richer web3 experience. Therefore we have created Key Conventions in order to facilitate this. Feel free to make a PR to this file to explain to the community how you use 3Box!

Example

You can quickly run and interact with some code by looking at the files in the /example folder. You run the example with the following command:

$ npm run example:start

This runs a simple server at http://localhost:3000/ that serves the static example/index.html file. This allows it easily interact with metamask. You can edit the example/index.html file to try differnt code.

Optimize build for read only 3Box API

If you only want to fetch profile data from 3Box's profile APIs you can optimize by importing only those functions or the API specific dist file. Since this includes minimal dependencies, file size is ~ 80kb vs 4+mb for the full build.

const { profileGraphQL, getProfile, getProfiles, getVerifiedAccounts } = require('3box/lib/api')

<script src="https://unpkg.com/3box/dist/3box.api.min.js"></script>

API Documentation

Box

Kind: global class

• Box
  • new Box()
  • instance
    • .public
    • .private
    • .verified
    • .spaces
    • .openSpace(name, opts) ⇒ Space
    • .onSyncDone(syncDone)
    • .logout()
  • static
    • .getProfile(address, opts) ⇒ Object
    • .getProfiles(address, opts) ⇒ Object
    • .getSpace(address, name, opts) ⇒ Object
    • .getThread(space, name, opts) ⇒ Array.<Object>
    • .listSpaces(address, opts) ⇒ Object
    • .profileGraphQL(query, opts) ⇒ Object
    • .getVerifiedAccounts(profile) ⇒ Object
    • .openBox(address, ethereumProvider, opts) ⇒ Box
    • .isLoggedIn(address) ⇒ Boolean

new Box()

Please use the openBox method to instantiate a 3Box

box.public

Kind: instance property of Box
Properties

box.private

Kind: instance property of Box
Properties

box.verified

Kind: instance property of Box
Properties

box.spaces

Kind: instance property of Box
Properties

box.openSpace(name, opts) ⇒ Space

Opens the space with the given name in the users 3Box

Kind: instance method of Box
Returns: Space - the Space instance for the given space name

box.onSyncDone(syncDone)

Sets the callback function that will be called once when the db is fully synced.

Kind: instance method of Box

box.logout()

Closes the 3box instance and clears local cache. If you call this, users will need to sign a consent message to log in the next time you call openBox.

Kind: instance method of Box

Box.getProfile(address, opts) ⇒ Object

Get the public profile of a given address

Kind: static method of Box
Returns: Object - a json object with the profile for the given address

Box.getProfiles(address, opts) ⇒ Object

Get a list of public profiles for given addresses. This relies on 3Box profile API.

Kind: static method of Box
Returns: Object - a json object with each key an address and value the profile

Box.getSpace(address, name, opts) ⇒ Object

Get the public data in a space of a given address with the given name

Kind: static method of Box
Returns: Object - a json object with the public space data

Box.getThread(space, name, opts) ⇒ Array.<Object>

Get all posts that are made to a thread.

Kind: static method of Box
Returns: Array.<Object> - An array of posts

Box.listSpaces(address, opts) ⇒ Object

Get the names of all spaces a user has

Kind: static method of Box
Returns: Object - an array with all spaces as strings

Box.profileGraphQL(query, opts) ⇒ Object

GraphQL for 3Box profile API

Kind: static method of Box
Returns: Object - a json object with each key an address and value the profile

Box.getVerifiedAccounts(profile) ⇒ Object

Verifies the proofs of social accounts that is present in the profile.

Kind: static method of Box
Returns: Object - An object containing the accounts that have been verified

Box.openBox(address, ethereumProvider, opts) ⇒ Box

Opens the 3Box associated with the given address

Kind: static method of Box
Returns: Box - the 3Box instance for the given address

Box.isLoggedIn(address) ⇒ Boolean

Check if the given address is logged in

Kind: static method of Box
Returns: Boolean - true if the user is logged in

KeyValueStore

Kind: global class

• KeyValueStore
  • new KeyValueStore()
  • .log ⇒ Array.<Object>
  • .get(key) ⇒ String
  • .set(key, value) ⇒ Boolean
  • .remove(key) ⇒ Boolean

new KeyValueStore()

Please use box.public or box.private to get the instance of this class

keyValueStore.log ⇒ Array.<Object>

Returns array of underlying log entries. In linearized order according to their Lamport clocks. Useful for generating a complete history of all operations on store.

Kind: instance property of KeyValueStore
Returns: Array.<Object> - Array of ordered log entry objects
Example

const log = store.log
 const entry = log[0]
 console.log(entry)
 // { op: 'PUT', key: 'Name', value: 'Botbot', timeStamp: '1538575416068' }

keyValueStore.get(key) ⇒ String

Get the value of the given key

Kind: instance method of KeyValueStore
Returns: String - the value associated with the key

keyValueStore.set(key, value) ⇒ Boolean

Set a value for the given key

Kind: instance method of KeyValueStore
Returns: Boolean - true if successful

keyValueStore.remove(key) ⇒ Boolean

Remove the value for the given key

Kind: instance method of KeyValueStore
Returns: Boolean - true if successful

Space

Kind: global class

• Space
  • new Space()
  • .public
  • .private
  • .joinThread(name, opts) ⇒ Thread
  • .subscribeThread(name)
  • .unsubscribeThread(name)
  • .subscribedThreads() ⇒ Array.<String>

new Space()

Please use box.openSpace to get the instance of this class

space.public

Kind: instance property of Space
Properties

space.private

Kind: instance property of Space
Properties

space.joinThread(name, opts) ⇒ Thread

Join a thread. Use this to start receiving updates from, and to post in threads

Kind: instance method of Space
Returns: Thread - An instance of the thread class for the joined thread

space.subscribeThread(name)

Subscribe to the given thread, if not already subscribed

Kind: instance method of Space

space.unsubscribeThread(name)

Unsubscribe from the given thread, if subscribed

Kind: instance method of Space

space.subscribedThreads() ⇒ Array.<String>

Get a list of all the threads subscribed to in this space

Kind: instance method of Space
Returns: Array.<String> - A list of thread names

Thread

Kind: global class

• Thread
  • new Thread()
  • .post(message) ⇒ String
  • .getPosts(opts) ⇒ Array.<Object>
  • .onNewPost(newPostFn)

new Thread()

Please use space.joinThread to get the instance of this class

thread.post(message) ⇒ String

Post a message to the thread

Kind: instance method of Thread
Returns: String - The postId of the new post

thread.getPosts(opts) ⇒ Array.<Object>

Returns an array of posts, based on the options. If hash not found when passing gt, gte, lt, or lte, the iterator will return all items (respecting limit and reverse).

Kind: instance method of Thread
Returns: Array.<Object> - true if successful

thread.onNewPost(newPostFn)

Register a function to be called for every new post that is received from the network. The function takes one parameter, which is the post. Note that posts here might be out of order.

Kind: instance method of Thread

Verified

Kind: global class

• Verified
  • new Verified()
  • .DID() ⇒ String
  • .github() ⇒ Object
  • .addGithub(gistUrl) ⇒ Object
  • .twitter() ⇒ Object
  • .addTwitter(claim) ⇒ Object
  • .email() ⇒ Object
  • .addEmail(claim) ⇒ Object

new Verified()

Please use box.verified to get the instance of this class

verified.DID() ⇒ String

Returns the verified DID of the user

Kind: instance method of Verified
Returns: String - The DID of the user

verified.github() ⇒ Object

Verifies that the user has a valid github account Throws an error otherwise.

Kind: instance method of Verified
Returns: Object - Object containing username, and proof

verified.addGithub(gistUrl) ⇒ Object

Adds a github verification to the users profile Throws an error if the verification fails.

Kind: instance method of Verified
Returns: Object - Object containing username, and proof

verified.twitter() ⇒ Object

Verifies that the user has a valid twitter account Throws an error otherwise.

Kind: instance method of Verified
Returns: Object - Object containing username, proof, and the verifier

verified.addTwitter(claim) ⇒ Object

Adds a twitter verification to the users profile Throws an error if the verification fails.

Kind: instance method of Verified
Returns: Object - Object containing username, proof, and the verifier

verified.email() ⇒ Object

Verifies that the user has a verified email account Throws an error otherwise.

Kind: instance method of Verified
Returns: Object - Object containing username, proof, and the verifier

verified.addEmail(claim) ⇒ Object

Adds an email verification to the users profile Throws an error if the verification fails.

Kind: instance method of Verified
Returns: Object - Object containing username, proof, and the verifier