0
# Address Management
1

2
OrbitDB uses unique addresses to identify and locate distributed databases across the network. These addresses enable database sharing and replication between peers.
3

4
## Capabilities
5

6
### Address Validation
7

8
Validates whether a string is a valid OrbitDB database address.
9

10
```javascript { .api }
11
/**
12
 * Validates an OrbitDB database address
13
 * @param address An OrbitDB database address string or OrbitDBAddress object
14
 * @returns True if the address is valid, false otherwise
15
 */
16
function isValidAddress(address: string | OrbitDBAddress): boolean;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import { isValidAddress } from '@orbitdb/core';
23

24
// Valid OrbitDB addresses
25
const validAddress1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To';
26
const validAddress2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/my-database';
27

28
console.log(isValidAddress(validAddress1)); // true
29
console.log(isValidAddress(validAddress2)); // true
30

31
// Invalid addresses
32
console.log(isValidAddress('not-an-address')); // false
33
console.log(isValidAddress('/ipfs/QmHash')); // false
34
console.log(isValidAddress('')); // false
35
```
36

37
### Address Parsing
38

39
Parses OrbitDB address strings into structured OrbitDBAddress objects.
40

41
```javascript { .api }
42
/**
43
 * Parses an OrbitDB address string into an OrbitDBAddress object
44
 * @param address OrbitDB address string to parse
45
 * @returns Parsed OrbitDBAddress object
46
 * @throws Error if address is invalid
47
 */
48
function parseAddress(address: string): OrbitDBAddress;
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
import { parseAddress } from '@orbitdb/core';
55

56
// Parse a basic address
57
const address1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To';
58
const parsed1 = parseAddress(address1);
59
console.log(parsed1.root); // 'zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To'
60
console.log(parsed1.path); // ''
61

62
// Parse an address with path
63
const address2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/my-database';
64
const parsed2 = parseAddress(address2);
65
console.log(parsed2.root); // 'zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To'
66
console.log(parsed2.path); // 'my-database'
67
```
68

69
### OrbitDBAddress Interface
70

71
The OrbitDBAddress class provides methods for working with parsed addresses.
72

73
```javascript { .api }
74
interface OrbitDBAddress {
75
  /** The root hash of the database manifest */
76
  root: string;
77
  /** The path component of the address (database name) */
78
  path: string;
79
  
80
  /** Converts the address back to its string representation */
81
  toString(): string;
82
}
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
import { parseAddress } from '@orbitdb/core';
89

90
const address = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/users';
91
const parsed = parseAddress(address);
92

93
// Access components
94
console.log('Root:', parsed.root);
95
console.log('Path:', parsed.path);
96

97
// Convert back to string
98
console.log('Full address:', parsed.toString());
99

100
// Use in database operations
101
const orbitdb = await createOrbitDB({ ipfs });
102
const db = await orbitdb.open(parsed.toString());
103
```
104

105
### Database Address Creation
106

107
When you create a database, OrbitDB automatically generates an address for it.
108

109
```javascript
110
import { createHelia } from 'helia';
111
import { createOrbitDB } from '@orbitdb/core';
112

113
const ipfs = await createHelia();
114
const orbitdb = await createOrbitDB({ ipfs });
115

116
// Create a new database
117
const db = await orbitdb.open('my-database');
118

119
// Get the generated address
120
const address = db.address;
121
console.log('Database address:', address.toString());
122
console.log('Root hash:', address.root);
123
console.log('Database name:', address.path);
124

125
// Share this address with other peers
126
const addressString = address.toString();
127
// Other peers can open the same database using this address
128
```
129

130
### Cross-Platform Address Handling
131

132
OrbitDB addresses work consistently across platforms and handle different path separators.
133

134
```javascript
135
import { isValidAddress, parseAddress } from '@orbitdb/core';
136

137
// Unix-style paths
138
const unixAddress = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/path/to/db';
139
console.log(isValidAddress(unixAddress)); // true
140

141
// Windows-style paths (also supported)
142
const windowsAddress = '\\orbitdb\\zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To\\path\\to\\db';
143
console.log(isValidAddress(windowsAddress)); // true
144

145
// Both parse to the same result
146
const parsed1 = parseAddress(unixAddress);
147
const parsed2 = parseAddress(windowsAddress);
148
console.log(parsed1.toString() === parsed2.toString()); // true
149
```
150

151
### Address-Based Database Operations
152

153
You can perform various operations using database addresses directly.
154

155
```javascript
156
import { createOrbitDB, isValidAddress } from '@orbitdb/core';
157

158
const ipfs = await createHelia();
159
const orbitdb = await createOrbitDB({ ipfs });
160

161
// Function to safely open a database by address
162
async function openDatabaseByAddress(addressString) {
163
  if (!isValidAddress(addressString)) {
164
    throw new Error('Invalid OrbitDB address');
165
  }
166
  
167
  try {
168
    const db = await orbitdb.open(addressString);
169
    console.log(`Opened database: ${db.name}`);
170
    return db;
171
  } catch (error) {
172
    console.error('Failed to open database:', error.message);
173
    throw error;
174
  }
175
}
176

177
// Example usage
178
const address = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/shared-data';
179
const db = await openDatabaseByAddress(address);
180
```
181

182
### Address Comparison and Equality
183

184
Compare addresses to check if they refer to the same database.
185

186
```javascript
187
import { parseAddress } from '@orbitdb/core';
188

189
const address1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db1';
190
const address2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db1';
191
const address3 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db2';
192

193
const parsed1 = parseAddress(address1);
194
const parsed2 = parseAddress(address2);
195
const parsed3 = parseAddress(address3);
196

197
// Compare addresses
198
console.log(parsed1.toString() === parsed2.toString()); // true (same database)
199
console.log(parsed1.toString() === parsed3.toString()); // false (different databases)
200

201
// Compare components
202
console.log(parsed1.root === parsed3.root); // true (same manifest)
203
console.log(parsed1.path === parsed3.path); // false (different names)
204
```
205

206
### Working with Database Manifests
207

208
The root hash in an OrbitDB address points to the database manifest, which contains metadata about the database.
209

210
```javascript
211
import { createOrbitDB } from '@orbitdb/core';
212

213
const ipfs = await createHelia();
214
const orbitdb = await createOrbitDB({ ipfs });
215

216
// Create database with metadata
217
const db = await orbitdb.open('my-app-data', {
218
  meta: {
219
    description: 'Application data store',
220
    version: '1.0.0',
221
    created: new Date().toISOString()
222
  }
223
});
224

225
console.log('Database address:', db.address.toString());
226
console.log('Database metadata:', db.meta);
227

228
// The root hash identifies this specific database configuration
229
console.log('Manifest hash:', db.address.root);
230
```
231

232
## Error Handling
233

234
Handle common address-related errors:
235

236
```javascript
237
import { isValidAddress, parseAddress } from '@orbitdb/core';
238

239
function safeParseAddress(addressString) {
240
  try {
241
    if (!isValidAddress(addressString)) {
242
      throw new Error(`Invalid OrbitDB address format: ${addressString}`);
243
    }
244
    return parseAddress(addressString);
245
  } catch (error) {
246
    console.error('Address parsing failed:', error.message);
247
    return null;
248
  }
249
}
250

251
// Example usage
252
const validAddress = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/test';
253
const invalidAddress = 'not-an-address';
254

255
const parsed1 = safeParseAddress(validAddress); // Returns OrbitDBAddress
256
const parsed2 = safeParseAddress(invalidAddress); // Returns null
257
```