1.0.0-beta-9

3box-js

Warning: This project is under active development, APIs are subject to change.

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. Currently it supports one shared space which all dapps can access. In the future there will be support for more granular access control using namespaces.

Installation

Install 3box in your npm project:

$ npm install 3box@next

Usage

Import 3Box into your project

Import the 3box module

const ThreeBox = require('3box')

or use the dist build in your html code

<script type="text/javascript" src="../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 ThreeBox object.

Using async/await

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

or using .then

ThreeBox.getProfile('0x12345abcde').then(profile => {
  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 web3provider refers to the object that you would get from web3.currentProvider, or request directly from the web3 browser, e.g. MetaMask.

Open 3Box session

Using async/await

const box = await ThreeBox.openBox('0x12345abcde', web3provider)

or using .then

ThreeBox.openBox('0x12345abcde', web3provider).then(box => {
  // interact with 3Box data
})

Interact with 3Box data

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

Using async/await

// 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')

or using .then

// use the public profile
// get
box.public.get('name').then(nickname => {
  console.log(nickname)
  // set
  box.public.set('name', 'oed').then(() => {
    // remove
    box.public.remove('name').then(() => {
    })
  })
})

// use the private store
// get
box.private.get('email').then(email => {
  console.log(email)
  // set
  box.private.set('email', 'oed@email.service').then(() => {
    // remove
    box.private.remove('email').then(() => {
    })
  })
})

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.

API Documentation

ThreeBox

Kind: global class

• ThreeBox
  • new ThreeBox()
  • instance
    • .public
    • .private
    • .close()
    • .logout()
  • static
    • .getProfile(address, opts) ⇒ Object
    • .openBox(address, web3provider, opts) ⇒ ThreeBox

new ThreeBox()

Please use the openBox method to instantiate a ThreeBox

threeBox.public

Kind: instance property of ThreeBox
Properties

threeBox.private

Kind: instance property of ThreeBox
Properties

threeBox.close()

Closes the 3box instance without clearing the local cache. Should be called after you are done using the 3Box instance, but without logging the user out.

Kind: instance method of ThreeBox

threeBox.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 ThreeBox

ThreeBox.getProfile(address, opts) ⇒ Object

Get the public profile of a given address

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

ThreeBox.openBox(address, web3provider, opts) ⇒ ThreeBox

Opens the user space associated with the given address

Kind: static method of ThreeBox
Returns: ThreeBox - the threeBox instance for the given address

KeyValueStore

Kind: global class

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

new KeyValueStore()

Please use threeBox.profileStore or threeBox.profileStore 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