OrbitDb is a Peer-to-Peer Database for the Decentralized Web

OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS as its data storage and IPFS Pubsub to automatically sync databases with peers. It’s an eventually consistent database that uses CRDTs for conflict-free database merges making OrbitDB an excellent choice for decentralized apps (dApps), blockchain applications, and offline-first web applications.

In the TEA Project, every hosting_cml has an OrbitDb instance running outside of the enclave.

OrbitDb is used to store large data blobs. OrbitDb provides limited non-relational database features but at a much lower cost. For a relational database, developers can use gluesql. For more essential account balance (money) data, we'd suggest using state instead.

Privacy protection

IPFS is open to the public. Anything stored in the IPFS can be accessed by anyone. OrbitDB is no exception. How do we protect the data in the OrbitDB? We use the app_aes_key

The data used in one applicaiton is encrypted using this application AES key inside enclave. When the data is saved to the OrbitDB, it has been encrypted. It will be decrypted when again loaded into the enclave by the same application. Other application cnanot decrypt because they do not have such app_aes_key.

The app_aes_key is stored inside the state machine which is consider the top security of the whole TEA Project network. When a new applicaiton host instance starts, it will request such a AES key to the state machine. After a restricted scurity check, the instance can receive such AES key. Because the AES key only live inside enclave (both state machine or hosting nodes.), it is unknown to outside world.


For every TApp, there are multiple hosting nodes. Every node has their own OrbitDB instance running inside the node (outside of the enclave). They sync with each other using the standard OrbitDB sync algorithm. Please visit orbitdb.org for more details on the sync method.

Because all of these instances share the same app_aes_key, the data is the same across all nodes as they take advantage of the duplication provided by IPFS/OrbitDB.


Since OrbitDB lives outside of the enclave and is stored on a hard disk (actually IPFS), using it would be much cheaper compared to the state machine (whose data stays inside the RAM of the enclave). Of course, the state machine would be a much more limited resource and be much more expensive than hard disk space outside of the enclave.

Eventual consistency

OrbitDB provides eventual consistency, which means you could get temporary inconsistency across all nodes. Your TApp has to handle this possible scenario in its business and UI logic.

If your data is very time sensitive and requires strong consistency, please use the more expensive state machine instead.

Last updated