3Box is an open source solution for web3 (The decentralized web). It is a distributed database that supports public and private data for Ethereum users. All data is openly accessible, yet private data can only be decrypted by DApps that the user has given explicit authorization. Data is stored on IPFS (The distributed web – a P2P hypermedia protocol to make the web faster, safer and more open) and managed via OrbitDB (a serverless, distributed, peer-to-peer database).

The 3Box system primarily comprises of the 3Box.js API, the 3Box Profiles App, and a distributed user data network.


  • Make it easy for users to publicly share information while preserving privacy when desired.
  • Enhance the onboarding experience for decentralized applications by making it simple for developers to get information about Ethereum clients.
  • Enhance Ethereum usability with distributed database infrastructure that works in production today.
  • Provide a decentralized system, but utilize centralized components in a realistic way to facilitate the transition.


3BOX database comprises two components-

  1. 3box-js – a client-side library used to read, write, and delete public and private data associated with the user. This library is used to get profile information about an address.
  2. 3box-address-server – a server utilizing, a REST-API (an architectural style that defines a set of constraints to be used for creating web services) that is used to associate an Ethereum address with its latest 3Box address. To sync the user’s information, this is what must be looked up to.

The 3Box user data network comprises of a few fundamental components: a data pinning server (a service worked by 3Box that pins 3Box user information on the IPFS network to guarantee availability), an identity model, and an address server. Together they are used to keep track of user data stored in orbit-DB instances.


The 3Box DApp is how users manage their 3Box data, including profile information and other.


3box-DApp is a web interface that allows users to interact with 3box. It is a service operated by 3Box that pins 3Box user data on the IPFS network to guarantee availability.


3box-verifications is a service that enables 3box.io users to confirm their Github and Twitter social accounts and connect them to their 3Box profile.


A high-level overview of the 3box architecture and a brief description of all interactions follows below.

After exploring potential use cases for 3box, DApp developers wanted shareable Ethereum Profiles first, as they would make the DApp onboarding process smoother and richer.

Each user has their own root IPFS (InterPlanetary File System) object and associated data stores. The hash of this object is stored in the 3box-root-hash-tracker. The root-hash-tracker (3box-address-server) also stores a mapping from a DID (Decentralized ID) that is created in the 3box-js library to this hash, as well as a mapping between the user’s ethereum address to the DID.

  • The DApp gets the users address from MetaMask (or any web3 compliant browser)
  • Dapp request public or private data from the users 3box
  • 3box-js MM interactions 
    • 3box-js requests consent for storing and retrieving private and public data. The signature is used as a key material when creating the 3box DID. 
    • 3box-js requests consent for linking the public profile to the users ethereum address
  • 3box-js stores and retrieves data from IPFS. Using two separate orbit-DB instances for public and private data, and a separate IPFS object which always links to the latest hash of the two orbit-DB instances.
  • All IPFS data is automatically pinned in the infura IPFS cloud.
  • 3box-js root-hash-tracker interactions 
    • 3box-js publishes the link between ethereum address and DID 
    • 3box-js publishes a new root hash (this is the hash of the latest IPFS object linking to the two orbit-DB instances)
WhatsApp chat