@decentnetwork/dora

npm install @decentnetwork/dora@0.1.16

npm install @decentnetwork/peer@0.1.172

mkdir dora-demo && cd dora-demo
npm init -y
npm install @decentnetwork/dora@0.1.16
npx dora --data-dir ./data --range-start 10.86.2.10 --range-end 10.86.2.254 \
         --http-port 18790 --name docs-dora --verbose
# in another terminal: read-only status JSON
curl -s http://127.0.0.1:18790/api/status

registry identity: address=V58F5TvJAM7VEA8GyrtSgp87mA3WpbQnDWDRjSYqTKq6JbGTNeuP userid=DmkXCCAiXu36tdAnxjHQqPRgRB1yQct5WAtsFWLhvQKR
registry roster file: …/dora-demo/data/roster.yaml
registry pool start: 10.86.2.10 end: 10.86.2.254
[registry] dora server started — friend requests will auto-accept
registry ready — clients should configure registry.userid in decentlan's config.yaml
[registry] status UI on http://127.0.0.1:18790

$ curl -s http://127.0.0.1:18790/api/status      # trimmed
{
  "self": {
    "userid": "DmkXCCAiXu36tdAnxjHQqPRgRB1yQct5WAtsFWLhvQKR",
    "address": "V58F5TvJAM7VEA8GyrtSgp87mA3WpbQnDWDRjSYqTKq6JbGTNeuP",
    "name": "docs-dora",
    "segment": "10.86.2.10-10.86.2.254",
    "capacity": 245,
    "used": 0,
    …
  },
  "siblings": [],
  "records": [],
  "conflicts": [],
  …
}
^C
shutting down registry

// quickstart.mjs
// Library quickstart: drive DoraClient against an in-process registry built
// from the exported DoraStore + IpAllocator + encode/decode wire helpers.
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  DoraClient, DoraStore, IpAllocator, encode, decode, randomIpInSubnet, DORA_PREFIX,
} from "@decentnetwork/dora";

const dir = mkdtempSync(join(process.env.DORA_DEMO_DIR ?? tmpdir(), "dora-"));
const store = new DoraStore(join(dir, "roster.yaml"));
const allocator = new IpAllocator(store, { rangeStart: "10.86.2.10", rangeEnd: "10.86.2.254" });
console.log("segment:", allocator.segment(), "capacity:", allocator.capacity());

// A fake transport: the "registry" answers register/lookup/list in-process.
const REGISTRY = "registry-userid";
let deliver = () => {};
async function sendText(to, text) {
  const req = decode(text);
  let res;
  if (req.op === "register") {
    const record = { userid: req.userid, name: req.name, address: req.address,
      virtualIp: allocator.nextFree(), registeredAt: new Date().toISOString() };
    store.put(record);
    res = { op: "register-ok", record };
  } else if (req.op === "lookup") {
    const rec = req.by === "name" ? store.findByName(req.value)
      : req.by === "ip" ? store.findByIp(req.value) : store.get(req.value);
    res = rec ? { op: "lookup-ok", record: rec } : { op: "lookup-err", reason: "not found" };
  } else {
    res = { op: "list-ok", records: store.list(), total: store.list().length };
  }
  setTimeout(() => deliver(to, encode(res)), 10);
}
const client = new DoraClient({
  registryUserids: [REGISTRY],
  sendText,
  onText: (h) => { deliver = h; },
  timeoutMs: 2000,
});

const rec = await client.register({ userid: "node-a-userid", name: "node-a" });
console.log("registered:", rec.name, rec.virtualIp);
console.log("lookup by name:", (await client.lookup({ by: "name", value: "node-a" }))?.virtualIp);
console.log("roster size:", (await client.list()).length);
console.log("wire frame:", encode({ op: "lookup", by: "ip", value: rec.virtualIp }));
console.log("prefix:", DORA_PREFIX, "non-dora text decodes to:", decode("hello"));
console.log("fallback IP:", randomIpInSubnet("10.86.0.0/16"));

$ node quickstart.mjs
segment: 10.86.2.10-10.86.2.254 capacity: 245
registered: node-a 10.86.2.10
lookup by name: 10.86.2.10
roster size: 1
wire frame: DORA:{"op":"lookup","by":"ip","value":"10.86.2.10"}
prefix: DORA: non-dora text decodes to: null
fallback IP: 10.86.198.251

// server.mjs — embed a dora registry in your own Node process.
import { mkdirSync } from "node:fs";
import { resolve } from "node:path";
import { Peer } from "@decentnetwork/peer";
import { DoraServer, DoraStore, IpAllocator } from "@decentnetwork/dora";

const dataDir = resolve(process.argv[2] ?? "./my-dora");
mkdirSync(dataDir, { recursive: true });

const peer = await Peer.create({
  keyFile: resolve(dataDir, "keypair.json"),
  compatibilityMode: "legacy",
  // Same public bootstrap + express nodes the dora CLI uses (dist/cli.js).
  bootstrapNodes: [
    { host: "13.58.208.50", port: 33445, pk: "89vny8MrKdDKs7Uta9RdVmspPjnRMdwMmaiEW27pZ7gh" },
    { host: "18.216.102.47", port: 33445, pk: "G5z8MqiNDFTadFUPfMdYsYtkUDbX5mNCMVHMZtsCnFeb" },
    { host: "54.193.141.205", port: 33445, pk: "7TfZWZNV8vnBxxWzJXuvKgX2QyKkLpg2oXx3LQ5tg8LW" },
  ],
  expressNodes: [
    { host: "lens.beagle.chat", port: 443, pk: "ECbs4GxwGzxGerNkmqDJFibEmevu8jAXqAZtikccvD95" },
  ],
});
await peer.start();
console.log(`dora address=${peer.address()} userid=${peer.userid()}`);
await peer.joinNetwork();
await peer.announceSelf(15000).catch((e) => console.warn("announce:", e.message));

const store = new DoraStore(resolve(dataDir, "roster.yaml"));
const allocator = new IpAllocator(store, { rangeStart: "10.86.2.10", rangeEnd: "10.86.2.254" });
const server = new DoraServer({ peer, store, allocator, verbose: true });
server.start();
console.log("serving segment", allocator.segment());

process.on("SIGINT", async () => { await peer.stop(); process.exit(0); });

$ node server.mjs ./embedded-dora
dora address=ZGiTEA8PV35YHAhdUPNXoGMcY7wVba6XJ5B63zeow4PnDr5HPGMw userid=FgaTFrzoAjXwTFRnLzKdm2y422ShsXR7DP5FVKRHof2f
[registry] dora server started — friend requests will auto-accept
serving segment 10.86.2.10-10.86.2.254

new DoraServer(opts: DoraServerOptions)
start(): void
availabilityLog(): AvailabilityLog | null
availabilitySummary(): string[]

new DoraClient(opts: DoraClientOptions)
ensureSubscribed(): void
register(opts: { userid: string; name: string; address?: string; requestedIp?: string; replace?: boolean }): Promise<DoraRecord>
lookup(opts: { by: "userid" | "name" | "ip"; value: string }): Promise<DoraRecord | null>
list(): Promise<DoraRecord[]>

new DoraStore(filePath: string)          // YAML roster; created on first write
get(userid): DoraRecord | null
findByName(name): DoraRecord | null
findByIp(ip): DoraRecord | null
list(): DoraRecord[]
listOwned(): DoraRecord[]                 // records without replicatedFrom
put(record: DoraRecord): void             // upsert + persist; caller checks collisions
remove(userid): boolean
touch(userid): void                       // update lastSeenAt
putReplicatedBatch(records, fromUserid, skip?): { merged: number; conflicts: IpConflict[] }
findIpConflicts(): IpConflict[]
pruneStaleReplicas(ttlMs: number, now?: number): number

new IpAllocator(store: DoraStore, opts?: AllocatorOptions)   // { rangeStart?, rangeEnd? }
capacity(): number
segment(): string               // "<start>-<end>"
overlaps(segment: string): boolean
ownsIp(ip: string): boolean
acceptRequested(ip: string): boolean
nextFree(): string | null       // null when the band is exhausted

const DORA_PREFIX = "DORA:";
encode(msg: DoraRequest | DoraResponse): string        // "DORA:" + JSON
decode(text: string): DoraRequest | DoraResponse | null // null for non-dora text
randomIpInSubnet(subnetCidr?: string, reservedFirstSlashTwentyFour?: boolean): string
class AllRegistriesUnavailableError extends Error

dora --range-start <ip> --range-end <ip> [options]
dora friend-add <userid> [name] [address] [--data-dir <dir>]

records:
  - userid: node-a-userid
    name: node-a
    virtualIp: 10.86.2.10
    registeredAt: '2026-11-06T08:37:15.267Z'