0
# OrbitDB
1

2
OrbitDB is a serverless, distributed, peer-to-peer database that uses IPFS as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges, making it excellent for decentralized applications, blockchain applications, and local-first web applications.
3

4
## Package Information
5

6
- **Package Name**: @orbitdb/core
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript (ES Modules)
9
- **Installation**: `npm install @orbitdb/core helia`
10

11
## Core Imports
12

13
```javascript
14
import { createOrbitDB } from "@orbitdb/core";
15
```
16

17
For specific components:
18

19
```javascript
20
import { 
21
  createOrbitDB,
22
  Documents,
23
  Events, 
24
  KeyValue,
25
  KeyValueIndexed,
26
  useDatabaseType,
27
  isValidAddress,
28
  parseAddress,
29
  Log,
30
  Entry,
31
  DefaultAccessController,
32
  Database,
33
  KeyStore,
34
  useAccessController,
35
  IPFSAccessController,
36
  OrbitDBAccessController,
37
  Identities,
38
  isIdentity,
39
  useIdentityProvider,
40
  PublicKeyIdentityProvider,
41
  IPFSBlockStorage,
42
  LevelStorage,
43
  LRUStorage,
44
  MemoryStorage,
45
  ComposedStorage
46
} from "@orbitdb/core";
47
```
48

49
## Basic Usage
50

51
```javascript
52
import { createHelia } from 'helia';
53
import { createOrbitDB } from '@orbitdb/core';
54

55
// Create OrbitDB instance
56
const ipfs = await createHelia();
57
const orbitdb = await createOrbitDB({ ipfs });
58

59
// Create/open a database (defaults to Events type)
60
const db = await orbitdb.open("my-database");
61

62
// Add data
63
const hash = await db.add("Hello OrbitDB!");
64

65
// Listen for updates
66
db.events.on("update", async (entry) => {
67
  const all = await db.all();
68
  console.log(all);
69
});
70

71
// Close when done
72
await db.close();
73
await orbitdb.stop();
74
```
75

76
## Architecture
77

78
OrbitDB is built around several key components:
79

80
- **Core Factory**: `createOrbitDB` function that creates OrbitDB instances with IPFS integration
81
- **Database Types**: Pre-built database implementations (Events, Documents, KeyValue, KeyValueIndexed)
82
- **OpLog**: Immutable, cryptographically verifiable operation log implementing Merkle-CRDTs
83
- **Access Controllers**: Pluggable access control system for database permissions
84
- **Identity System**: Cryptographic identity management for database operations
85
- **Storage Backends**: Flexible storage system supporting multiple backends (IPFS, Level, Memory, etc.)
86

87
## Capabilities
88

89
### OrbitDB Factory
90

91
Creates and manages OrbitDB instances with IPFS integration and peer synchronization.
92

93
```javascript { .api }
94
function createOrbitDB(params: {
95
  ipfs: IPFS;
96
  id?: string;
97
  identity?: Identity | { provider: IdentityProvider };
98
  identities?: Identities;
99
  directory?: string;
100
}): Promise<OrbitDB>;
101

102
interface OrbitDB {
103
  open(name: string, options?: DatabaseOptions): Promise<Database>;
104
  stop(): Promise<void>;
105
  ipfs: IPFS;
106
  directory: string;
107
  keystore: KeyStore;
108
  identities: Identities;
109
  identity: Identity;
110
  peerId: PeerId;
111
}
112
```
113

114
[OrbitDB Factory](./orbitdb-factory.md)
115

116
### Database Types
117

118
Built-in database implementations for different data models and use cases.
119

120
```javascript { .api }
121
interface Events {
122
  add(value: any): Promise<string>;
123
  get(hash: string): any;
124
  iterator(): AsyncIterable<any>;
125
  all(): Promise<any[]>;
126
}
127

128
interface Documents {
129
  put(doc: object): Promise<string>;
130
  del(key: string): Promise<string>;
131
  get(key: string): object | null;
132
  query(findFn: (doc: object) => boolean): object[];
133
  iterator(): AsyncIterable<object>;
134
  all(): Promise<object[]>;
135
}
136

137
interface KeyValue {
138
  put(key: string, value: any): Promise<string>;
139
  del(key: string): Promise<string>;
140
  get(key: string): any;
141
  iterator(): AsyncIterable<{ key: string; value: any }>;
142
  all(): Promise<object>;
143
}
144
```
145

146
[Database Types](./database-types.md)
147

148
### Address Management
149

150
Utilities for working with OrbitDB database addresses.
151

152
```javascript { .api }
153
function isValidAddress(address: string | OrbitDBAddress): boolean;
154
function parseAddress(address: string): OrbitDBAddress;
155

156
interface OrbitDBAddress {
157
  toString(): string;
158
  root: string;
159
  path: string;
160
}
161
```
162

163
[Address Management](./address-management.md)
164

165
### OpLog System
166

167
Immutable, cryptographically verifiable operation log implementing Merkle-CRDTs.
168

169
```javascript { .api }
170
interface Log {
171
  append(entry: Entry): Promise<string>;
172
  join(log: Log): Promise<Log>;
173
  heads: Entry[];
174
  entries: Entry[];
175
  length: number;
176
}
177

178
interface Entry {
179
  hash: string;
180
  payload: {
181
    op: string;
182
    key: string | null;
183
    value: any;
184
  };
185
  identity: string;
186
  sig: string;
187
  clock: Clock;
188
}
189
```
190

191
[OpLog System](./oplog-system.md)
192

193
### Access Controllers
194

195
Pluggable access control system for managing database permissions.
196

197
```javascript { .api }
198
function useAccessController(accessController: AccessController): void;
199

200
interface IPFSAccessController {
201
  type: 'ipfs';
202
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
203
  grant(capability: string, identity: string): Promise<void>;
204
}
205

206
interface OrbitDBAccessController {
207
  type: 'orbitdb';
208
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
209
}
210
```
211

212
[Access Controllers](./access-controllers.md)
213

214
### Identity System
215

216
Cryptographic identity management for database operations and peer authentication.
217

218
```javascript { .api }
219
interface Identities {
220
  createIdentity(options?: IdentityOptions): Promise<Identity>;
221
  verifyIdentity(identity: Identity): Promise<boolean>;
222
  keystore: KeyStore;
223
}
224

225
interface Identity {
226
  id: string;
227
  publicKey: string;
228
  signatures: object;
229
  type: string;
230
  provider: IdentityProvider;
231
}
232

233
function isIdentity(identity: any): identity is Identity;
234
function useIdentityProvider(provider: IdentityProvider): void;
235
```
236

237
[Identity System](./identity-system.md)
238

239
### Storage Backends
240

241
Flexible storage system supporting multiple backends for different use cases.
242

243
```javascript { .api }
244
interface IPFSBlockStorage {
245
  put(hash: string, data: Uint8Array): Promise<void>;
246
  get(hash: string): Promise<Uint8Array>;
247
  del(hash: string): Promise<void>;
248
}
249

250
interface LevelStorage {
251
  put(key: string, value: any): Promise<void>;
252
  get(key: string): Promise<any>;
253
  del(key: string): Promise<void>;
254
}
255

256
interface MemoryStorage {
257
  put(key: string, value: any): Promise<void>;
258
  get(key: string): Promise<any>;
259
  del(key: string): Promise<void>;
260
}
261
```
262

263
[Storage Backends](./storage-backends.md)
264

265
## Common Types
266

267
```javascript { .api }
268
interface DatabaseOptions {
269
  type?: string;
270
  Database?: DatabaseConstructor;
271
  AccessController?: AccessControllerConstructor;
272
  directory?: string;
273
  meta?: object;
274
  headsStorage?: Storage;
275
  entryStorage?: Storage;
276
  indexStorage?: Storage;
277
  referencesCount?: number;
278
  syncAutomatically?: boolean;
279
  onUpdate?: (entry: Entry) => void;
280
  encryption?: {
281
    encryptFn: (data: any) => any;
282
    decryptFn: (data: any) => any;
283
  };
284
}
285

286
interface Database {
287
  address: OrbitDBAddress;
288
  name: string;
289
  identity: Identity;
290
  meta: object;
291
  log: Log;
292
  sync: Sync;
293
  peers: Set<string>;
294
  events: EventEmitter;
295
  access: AccessController;
296
  close(): Promise<void>;
297
  drop(): Promise<void>;
298
  addOperation(op: Operation): Promise<string>;
299
}
300

301
interface Clock {
302
  id: string;
303
  time: number;
304
}
305

306
interface PeerId {
307
  toString(): string;
308
}
309

310
interface Sync {
311
  add(heads: Entry[]): Promise<void>;
312
  start(): Promise<void>;
313
  stop(): Promise<void>;
314
  peers: Set<string>;
315
}
316

317
interface Operation {
318
  op: string;
319
  key: string | null;
320
  value: any;
321
}
322

323
interface AccessController {
324
  type: string;
325
  address: string;
326
  write: string[];
327
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
328
}
329
```