@toolkit-p2p/bulletin

CRDT-based shared state bulletin board for toolkit-p2p Lighthouse persistence layer.

Overview

The Bulletin package provides a shared, eventually-consistent state store built on top of LWW-Map CRDT from @toolkit-p2p/sync. It enables Lighthouse nodes to maintain synchronized state across disconnected peers with automatic conflict resolution.

Features

• CRDT-based State: Built on Last-Writer-Wins Map for automatic conflict resolution
• Field-level TTL: Automatic expiration of stale data
• Provenance Tracking: Track which peers have handled each update
• Type-safe API: Full TypeScript support
• Production Ready: Comprehensive test coverage

Installation

pnpm add @toolkit-p2p/bulletin

Usage

import { Bulletin } from '@toolkit-p2p/bulletin';

// Create a bulletin instance
const bulletin = new Bulletin();

// Set a field with TTL
bulletin.set('status', 'online', { ttlSec: 3600 }); // 1 hour TTL

// Get a field value
const status = bulletin.get('status');

// Get full state snapshot for sync
const snapshot = bulletin.getSnapshot();

// Merge remote state
bulletin.merge(remoteSnapshot);

// Listen for changes
bulletin.onChange((field, value) => {
  console.log(`Field ${field} updated:`, value);
});

API

Bulletin

Methods

• set(field: string, value: any, options: { ttlSec: number }): void

  • Update a field with automatic TTL

• get(field: string): any

  • Retrieve the current value of a field

• getSnapshot(): BulletinSnapshot

  • Get complete state for synchronization

• merge(patch: BulletinSnapshot): void

  • Merge remote state (CRDT operation)

• onChange(callback: (field: string, value: any) => void): void

  • Subscribe to field changes

• purgeExpired(): void

  • Remove expired fields (called automatically)

Architecture

Bulletin extends the LWW-Map CRDT from @toolkit-p2p/sync with:

1. TTL Management: Each field tracks creation time and TTL duration
2. Provenance Chain: Records which peers have handled each update
3. Auto-expiration: Background job removes expired fields hourly

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Type check
pnpm typecheck

License

MIT