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. 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
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.
Using async/await
const profile = await Box.getProfile('0x12345abcde')
console.log(profile)
or using .then
Box.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 ethereumProvider
refers to the object that you would get from web3.currentProvider
, or window.ethereum
.
Open 3Box session
Using async/await
const box = await Box.openBox('0x12345abcde', ethereumProvider)
or using .then
Box.openBox('0x12345abcde', ethereumProvider).then(box => {
// interact with 3Box data
})
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.
box.onSyncDone(yourCallbackFunction)
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
.
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(() => {
})
})
})
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.
API Documentation
Box
Kind: global class
- Box
- new Box()
- instance
- static
- .getProfile(address, opts) ⇒
Object
- .getProfiles(address, opts) ⇒
Object
- .profileGraphQL(query, opts) ⇒
Object
- .openBox(address, ethereumProvider, opts) ⇒
Box
- .isLoggedIn(address) ⇒
Boolean
- .getProfile(address, opts) ⇒
new Box()
Please use the openBox method to instantiate a 3Box
box.public
Kind: instance property of Box
Properties
Name | Type | Description |
---|---|---|
public | KeyValueStore |
access the profile store of the users 3Box |
box.private
Kind: instance property of Box
Properties
Name | Type | Description |
---|---|---|
private | KeyValueStore |
access the private store of the users 3Box |
box.onSyncDone(syncDone)
Sets the callback function that will be called once when the db is fully synced.
Kind: instance method of Box
Param | Type | Description |
---|---|---|
syncDone | function |
The function that will be called |
box.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 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
Object
Box.getProfile(address, opts) ⇒ 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
Param | Type | Description |
---|---|---|
address | String |
An ethereum address |
opts | Object |
Optional parameters |
opts.addressServer | String |
URL of the Address Server |
opts.ipfs | Object |
A js-ipfs ipfs object |
opts.orbitPath | String |
A custom path for orbitdb storage |
opts.iframeStore | Boolean |
Use iframe for storage, allows shared store across domains. Default true when run in browser. |
opts.useCacheService | Boolean |
Use 3Box API and Cache Service to fetch profile instead of OrbitDB. Default true. |
Object
Box.getProfiles(address, opts) ⇒ 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
Param | Type | Description |
---|---|---|
address | Array |
An array of ethereum addresses |
opts | Object |
Optional parameters |
opts.profileServer | String |
URL of Profile API server |
Object
Box.profileGraphQL(query, opts) ⇒ GraphQL for 3Box profile API
Kind: static method of Box
Returns: Object
- a json object with each key an address and value the profile
Param | Type | Description |
---|---|---|
query | Object |
A graphQL query object. |
opts | Object |
Optional parameters |
opts.graphqlServer | String |
URL of graphQL 3Box profile service |
Box
Box.openBox(address, ethereumProvider, opts) ⇒ Opens the user space associated with the given address
Kind: static method of Box
Returns: Box
- the 3Box instance for the given address
Param | Type | Description |
---|---|---|
address | String |
An ethereum address |
ethereumProvider | ethereumProvider |
An ethereum provider |
opts | Object |
Optional parameters |
opts.consentCallback | function |
A function that will be called when the user has consented to opening the box |
opts.pinningNode | String |
A string with an ipfs multi-address to a 3box pinning node |
opts.ipfs | Object |
A js-ipfs ipfs object |
opts.orbitPath | String |
A custom path for orbitdb storage |
opts.addressServer | String |
URL of the Address Server |
opts.iframeStore | Boolean |
Use iframe for storage, allows shared store across domains. Default true when run in browser. |
Boolean
Box.isLoggedIn(address) ⇒ Check if the given address is logged in
Kind: static method of Box
Returns: Boolean
- true if the user is logged in
Param | Type | Description |
---|---|---|
address | String |
An ethereum 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 box.profileStore or box.profileStore to get the instance of this class
Array.<Object>
keyValueStore.log ⇒ 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' }
String
keyValueStore.get(key) ⇒ Get the value of the given key
Kind: instance method of KeyValueStore
Returns: String
- the value associated with the key
Param | Type | Description |
---|---|---|
key | String |
the key |
Boolean
keyValueStore.set(key, value) ⇒ Set a value for the given key
Kind: instance method of KeyValueStore
Returns: Boolean
- true if successful
Param | Type | Description |
---|---|---|
key | String |
the key |
value | String |
the value |
Boolean
keyValueStore.remove(key) ⇒ Remove the value for the given key
Kind: instance method of KeyValueStore
Returns: Boolean
- true if successful
Param | Type | Description |
---|---|---|
key | String |
the key |