@nostrwatch/negentropy 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Sandwich Farm LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @nostrwatch/negentropy-utils
+
+Utilities for [NIP-77](https://github.com/nostr-protocol/nips/blob/master/77.md) Negentropy set reconciliation between Nostr clients and relays.
+
+[![npm version](https://img.shields.io/npm/v/@nostrwatch/negentropy-utils?style=flat-square&label=npm)](https://www.npmjs.com/package/@nostrwatch/negentropy-utils)
+[![License](https://img.shields.io/github/license/sandwichfarm/nostr-watch?style=flat-square)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)](https://github.com/sandwichfarm/nostr-watch)
+[![Runtime](https://img.shields.io/badge/runtime-node%20%7C%20browser-blue?style=flat-square)](https://github.com/sandwichfarm/nostr-watch)
+
+## Overview
+
+`@nostrwatch/negentropy-utils` implements the [NIP-77](https://github.com/nostr-protocol/nips/blob/master/77.md) Negentropy protocol — a set reconciliation algorithm that efficiently identifies which Nostr events (signed JSON objects that are the fundamental unit of the Nostr protocol) a client and relay do not have in common. Instead of transferring full event lists, Negentropy uses fingerprint-based range comparisons to minimize data transferred during sync. The package provides `ClientHandler` for use in Nostr clients and `ServerHandler` for use in relay implementations, both operating over a pluggable `Transport` interface.
+
+## Prerequisites
+
+Node.js >=20 and pnpm >=9.
+
+## Installation
+
+```sh
+pnpm add @nostrwatch/negentropy-utils
+```
+
+Or with npm:
+
+```sh
+npm install @nostrwatch/negentropy-utils
+```
+
+## Quick Start
+
+```ts
+import {ClientHandler} from '@nostrwatch/negentropy-utils'
+import {WebSocketTransport} from '@nostrwatch/negentropy-utils/transports/WebSocket'
+import type {RecordItem} from '@nostrwatch/negentropy-utils'
+
+// Local event records (timestamp + 32-byte ID)
+const localRecords: RecordItem[] = [
+  {timestamp: BigInt(1700000000), id: new Uint8Array(32).fill(1)},
+  {timestamp: BigInt(1700000001), id: new Uint8Array(32).fill(2)}
+]
+
+const ws = new WebSocket('wss://relay.damus.io')
+const transport = new WebSocketTransport(ws)
+
+// Subscribe to kind 1 events and start sync
+const client = new ClientHandler(localRecords, transport, {kinds: [1]}, 'sync-1')
+
+ws.onopen = () => {
+  client.startSync()
+  // Sends NEG-OPEN to the relay and begins reconciliation
+}
+```
+
+## API
+
+### `ClientHandler`
+
+Used on the client side to synchronize a local event set with a relay.
+
+```ts
+class ClientHandler {
+  constructor(
+    records: RecordItem[],
+    transport: Transport,
+    filter: object,
+    subscriptionId: string
+  )
+  startSync(): void
+  handleMessage(message: string): void
+}
+```
+
+**`constructor(records, transport, filter, subscriptionId)`**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `records` | `RecordItem[]` | Local event records to synchronize |
+| `transport` | `Transport` | Message transport (e.g., `WebSocketTransport`) |
+| `filter` | `object` | Nostr filter (e.g., `{kinds: [1]}`) scoping which events to sync |
+| `subscriptionId` | `string` | Unique identifier for this sync session |
+
+**`startSync()`**
+
+Initiates the NIP-77 handshake by sending a `NEG-OPEN` message to the relay. Call this after the transport connection is open.
+
+**`handleMessage(message: string)`**
+
+Processes an incoming relay message (`NEG-MSG`, `NEG-ERR`, or `NEG-CLOSE`). The `Transport` implementation calls this automatically via `onMessage`.
+
+### `ServerHandler`
+
+Used on the relay side to respond to client sync requests.
+
+```ts
+class ServerHandler {
+  constructor(
+    records: RecordItem[],
+    transport: Transport,
+    applyFilter: (records: RecordItem[], filter: object) => Promise<RecordItem[]>
+  )
+  handleMessage(message: string): Promise<void>
+}
+```
+
+**`constructor(records, transport, applyFilter)`**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `records` | `RecordItem[]` | All event records stored on the relay |
+| `transport` | `Transport` | Message transport connected to the client |
+| `applyFilter` | `function` | Async function that filters `records` by a Nostr filter object |
+
+**`handleMessage(message: string)`**
+
+Handles incoming client messages (`NEG-OPEN`, `NEG-MSG`, `NEG-CLOSE`). The `Transport` implementation calls this automatically.
+
+### `Transport`
+
+An abstract interface that both handlers communicate through. Implement it for any transport layer (WebSocket, stdio, etc.).
+
+```ts
+abstract class Transport {
+  abstract send(message: string): void
+  abstract onMessage(handler: (message: string) => void): void
+}
+```
+
+### Types
+
+```ts
+type RecordItem = {timestamp: bigint; id: Uint8Array}
+
+type RangeMode = 0 | 1 | 2
+
+interface Range {
+  upperBound: Bound
+  mode: RangeMode
+  payload: Uint8Array
+}
+
+interface Bound {
+  timestampOffset: bigint
+  idPrefix: Uint8Array
+}
+```
+
+## Known Limitations
+
+No known limitations at this time.
+
+## Agent Skills
+
+No agent skills defined yet for this package.
+
+## Related Packages
+
+- [`@nostrwatch/worker-relay`](../../libraries/worker-relay/README.md) — in-browser relay; negentropy-utils can be used with it for client-side event sync
+- [`@nostrwatch/route66`](../../libraries/route66/README.md) — relay monitoring library that uses negentropy for event set synchronization
+
+## License
+
+[MIT](../../LICENSE)

package/build.js

@@ -0,0 +1,25 @@
+// build.js
+const esbuild = require('esbuild');
+
+const commonOptions = {
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  sourcemap: true,
+  minify: true,
+};
+
+esbuild.build({
+  ...commonOptions,
+  platform: 'node',
+  target: ['node14'],
+  outfile: 'dist/index.node.js',
+  format: 'cjs',
+});
+
+esbuild.build({
+  ...commonOptions,
+  platform: 'browser',
+  target: ['es2020'],
+  outfile: 'dist/index.browser.js',
+  format: 'esm',
+});

package/dist/index.browser.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.browser.js.map

package/dist/index.browser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/index.node.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.node.js.map

package/dist/index.node.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@nostrwatch/negentropy",
+  "version": "0.0.1",
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5"
+  },
+  "scripts": {
+    "build": "npm run build:node && npm run build:browser",
+    "build:node": "esbuild src/index.ts --bundle --platform=node --target=node14 --outfile=dist/index.node.js --format=cjs --sourcemap",
+    "build:browser": "esbuild src/index.ts --bundle --platform=browser --target=es2020 --outfile=dist/index.browser.js --format=esm --sourcemap"
+  }
+}

package/src/ClientHandler.test.ts

@@ -0,0 +1,34 @@
+// src/ClientHandler.test.ts
+
+import { describe, it, expect, vi } from 'vitest';
+import { NegentropyClient } from './ClientHandler';
+import { RecordItem } from './types';
+
+describe('NegentropyClient', () => {
+  describe('startSync', () => {
+    it('should send NEG-OPEN message with initial message', async () => {
+      // Arrange
+      const records: RecordItem[] = []; // Provide test records
+      const websocket = {
+        send: vi.fn(),
+        onmessage: null,
+        onopen: null,
+      };
+      const filter = {};
+      const subscriptionId = 'test-subscription';
+
+      const client = new NegentropyClient(records, websocket as any, filter, subscriptionId);
+
+      // Act
+      await client.startSync();
+
+      // Assert
+      expect(websocket.send).toHaveBeenCalled();
+      const sentMessage = JSON.parse(websocket.send.mock.calls[0][0]);
+      expect(sentMessage[0]).toBe('NEG-OPEN');
+      expect(sentMessage[1]).toBe(subscriptionId);
+      // Further assertions as needed
+    });
+  });
+
+});

package/src/ClientHandler.ts

@@ -0,0 +1,145 @@
+// src/ClientHandler.ts
+
+import { Transport } from './transports/Transport';
+import { hexToUint8Array, uint8ArrayToHex } from './utils/hex';
+import { decodeMessage, decodeVarint, encodeMessage } from './utils/encoding';
+import { compareUint8Arrays, computeFingerprint } from './utils/helpers';
+import type { RecordItem, Range } from './types';
+
+export class ClientHandler {
+  private records: RecordItem[];
+  private transport: Transport;
+  private subscriptionId: string;
+  private filter: any;
+  private serverRecords: RecordItem[] = [];
+  private clientNeedsRecords: RecordItem[] = [];
+
+  constructor(records: RecordItem[], transport: Transport, filter: any, subscriptionId: string) {
+    this.records = records;
+    this.transport = transport;
+    this.filter = filter;
+    this.subscriptionId = subscriptionId;
+
+    // Set up message handling
+    this.transport.onMessage((message) => this.handleMessage(message));
+  }
+
+  public startSync() {
+    const initialMessage = this.generateInitialMessage();
+    const messageHex = uint8ArrayToHex(initialMessage);
+
+    const negOpenMessage = [
+      "NEG-OPEN",
+      this.subscriptionId,
+      this.filter,
+      messageHex,
+    ];
+
+    this.transport.send(JSON.stringify(negOpenMessage));
+  }
+
+  public handleMessage(message: string) {
+    const parsed = JSON.parse(message);
+
+    const messageType = parsed[0];
+
+    switch (messageType) {
+      case "NEG-MSG":
+        this.handleNegMsg(parsed);
+        break;
+      case "NEG-ERR":
+        this.handleNegErr(parsed);
+        break;
+      case "NEG-CLOSE":
+        this.handleNegClose(parsed);
+        break;
+      default:
+        break;
+    }
+  }
+
+  private handleNegMsg(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    const messageHex = parsed[2];
+    if (subscriptionId !== this.subscriptionId) return;
+
+    const messageBuffer = hexToUint8Array(messageHex);
+    const ranges = decodeMessage(messageBuffer);
+
+    this.processRanges(ranges);
+
+    const nextMessage = this.generateNextMessage();
+    if (nextMessage) {
+      const messageHex = uint8ArrayToHex(nextMessage);
+      const negMsg = ["NEG-MSG", this.subscriptionId, messageHex];
+      this.transport.send(JSON.stringify(negMsg));
+    } else {
+      this.sendNegClose();
+    }
+  }
+
+  private handleNegErr(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    const reason = parsed[2];
+    if (subscriptionId !== this.subscriptionId) return;
+
+    console.error(`NEG-ERR received: ${reason}`);
+  }
+
+  private handleNegClose(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    if (subscriptionId !== this.subscriptionId) return;
+
+    console.log(`NEG-CLOSE received for subscription ${subscriptionId}`);
+  }
+
+  private generateInitialMessage(): Uint8Array {
+    this.records.sort((a, b) => {
+      if (a.timestamp !== b.timestamp) {
+        return a.timestamp < b.timestamp ? -1 : 1;
+      }
+      return compareUint8Arrays(a.id, b.id);
+    });
+
+    const fingerprint = computeFingerprint(this.records);
+
+    const ranges: Range[] = [
+      {
+        upperBound: {
+          timestampOffset: BigInt(0),
+          idPrefix: new Uint8Array(),
+        },
+        mode: 1,
+        payload: fingerprint,
+      },
+    ];
+
+    return encodeMessage(ranges);
+  }
+
+  private generateNextMessage(): Uint8Array | null {
+    // Implement logic to generate next message
+    return null;
+  }
+
+  private processRanges(ranges: Range[]) {
+    for (const range of ranges) {
+      if (range.mode === 2) {
+        let offset = 0;
+        const lengthResult = decodeVarint(range.payload, offset);
+        offset += lengthResult.bytesRead;
+        const idCount = lengthResult.value;
+        for (let i = 0; i < idCount; i++) {
+          const id = range.payload.subarray(offset, offset + 32);
+          offset += 32;
+          this.clientNeedsRecords.push({ timestamp: BigInt(0), id });
+        }
+      }
+    }
+  }
+
+  private sendNegClose() {
+    const negCloseMessage = ["NEG-CLOSE", this.subscriptionId];
+    this.transport.send(JSON.stringify(negCloseMessage));
+  }
+}

package/src/ServerHandler.test.ts

@@ -0,0 +1,36 @@
+// src/ServerHandler.test.ts
+
+import { describe, it, expect, vi } from 'vitest';
+import { NegentropyServer } from './ServerHandler';
+import { RecordItem } from './types';
+
+describe('NegentropyServer', () => {
+  describe('handleMessage', () => {
+    it('should handle NEG-OPEN message and send NEG-MSG response', async () => {
+      // Arrange
+      const records: RecordItem[] = []; // Provide test records
+      const websocket = {
+        send: vi.fn(),
+        onmessage: null,
+        onopen: null,
+      };
+      const server = new NegentropyServer(records, websocket as any);
+
+      const subscriptionId = 'test-subscription';
+      const filter = {};
+      const initialMessageHex = '00'; // Provide a valid hex string
+
+      const message = JSON.stringify(['NEG-OPEN', subscriptionId, filter, initialMessageHex]);
+
+      // Act
+      await server.handleMessage(message);
+
+      // Assert
+      expect(websocket.send).toHaveBeenCalled();
+      const sentMessage = JSON.parse(websocket.send.mock.calls[0][0]);
+      expect(sentMessage[0]).toBe('NEG-MSG');
+      expect(sentMessage[1]).toBe(subscriptionId);
+      // Further assertions as needed
+    });
+  });
+});

package/src/ServerHandler.ts

@@ -0,0 +1,165 @@
+// src/ServerHandler.ts
+
+import { Range, RecordItem } from './types';
+import { decodeMessage, encodeMessage, encodeVarint } from './utils/encoding';
+import { Transport } from './transports/Transport';
+import { hexToUint8Array, uint8ArrayToHex } from './utils/hex';
+
+type ApplyFilterFunction = (records: RecordItem[], filter: any) => Promise<RecordItem[]>;
+
+export class ServerHandler {
+  private records: RecordItem[];
+  private transport: Transport;
+  private subscriptions: Map<string, any>;
+  private applyFilter: ApplyFilterFunction;
+
+  constructor(records: RecordItem[], transport: Transport, applyFilter: ApplyFilterFunction) {
+    this.records = records;
+    this.transport = transport;
+    this.subscriptions = new Map();
+    this.applyFilter = applyFilter;
+
+    // Set up message handling
+    this.transport.onMessage((message) => this.handleMessage(message));
+  }
+
+  public async handleMessage(message: string) {
+    const parsed = JSON.parse(message);
+
+    const messageType = parsed[0];
+
+    switch (messageType) {
+      case 'NEG-OPEN':
+        await this.handleNegOpen(parsed);
+        break;
+      case 'NEG-MSG':
+        await this.handleNegMsg(parsed);
+        break;
+      case 'NEG-CLOSE':
+        this.handleNegClose(parsed);
+        break;
+      default:
+        break;
+    }
+  }
+
+  private async handleNegOpen(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    const filter = parsed[2];
+    const initialMessageHex = parsed[3];
+
+    if (this.subscriptions.has(subscriptionId)) {
+      this.subscriptions.delete(subscriptionId);
+    }
+
+    // Apply filter to server records (asynchronous)
+    let filteredRecords: RecordItem[];
+    try {
+      filteredRecords = await this.applyFilter(this.records, filter);
+    } catch (error) {
+      // Send NEG-ERR if filter application fails
+      const negErr = ['NEG-ERR', subscriptionId, 'error: failed to apply filter'];
+      this.transport.send(JSON.stringify(negErr));
+      return;
+    }
+
+    // Decode client's initial message
+    let clientRanges: Range[];
+    try {
+      const clientMessageBuffer = hexToUint8Array(initialMessageHex);
+      clientRanges = decodeMessage(clientMessageBuffer);
+    } catch (error) {
+      // Send NEG-ERR if message cannot be decoded
+      const negErr = ['NEG-ERR', subscriptionId, 'invalid: failed to decode initial message'];
+      this.transport.send(JSON.stringify(negErr));
+      return;
+    }
+
+    // Generate server response
+    const serverMessageBuffer = await this.generateResponseMessage(filteredRecords, clientRanges);
+    const messageHex = uint8ArrayToHex(serverMessageBuffer);
+
+    // Send NEG-MSG back to client
+    const negMsg = ['NEG-MSG', subscriptionId, messageHex];
+    this.transport.send(JSON.stringify(negMsg));
+
+    // Store subscription state
+    this.subscriptions.set(subscriptionId, {
+      filteredRecords,
+      clientRanges,
+    });
+  }
+
+  private async handleNegMsg(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    const messageHex = parsed[2];
+
+    if (!this.subscriptions.has(subscriptionId)) {
+      // Send NEG-ERR: closed
+      const negErr = ['NEG-ERR', subscriptionId, 'closed: subscription not found'];
+      this.transport.send(JSON.stringify(negErr));
+      return;
+    }
+
+    const subscription = this.subscriptions.get(subscriptionId);
+
+    // Decode client's message
+    let clientRanges: Range[];
+    try {
+      const clientMessageBuffer = hexToUint8Array(messageHex);
+      clientRanges = decodeMessage(clientMessageBuffer);
+    } catch (error) {
+      // Send NEG-ERR if message cannot be decoded
+      const negErr = ['NEG-ERR', subscriptionId, 'invalid: failed to decode message'];
+      this.transport.send(JSON.stringify(negErr));
+      return;
+    }
+
+    // Generate server response
+    const serverMessageBuffer = await this.generateResponseMessage(subscription.filteredRecords, clientRanges);
+    const messageHexResponse = uint8ArrayToHex(serverMessageBuffer);
+
+    // Send NEG-MSG back to client
+    const negMsg = ['NEG-MSG', subscriptionId, messageHexResponse];
+    this.transport.send(JSON.stringify(negMsg));
+
+    // Update subscription state
+    subscription.clientRanges = clientRanges;
+  }
+
+  private handleNegClose(parsed: any[]) {
+    const subscriptionId = parsed[1];
+    if (this.subscriptions.has(subscriptionId)) {
+      this.subscriptions.delete(subscriptionId);
+    }
+  }
+
+  private async generateResponseMessage(serverRecords: RecordItem[], clientRanges: Range[]): Promise<Uint8Array> {
+    // For simplicity, we'll send an IdList of all server records
+    const idCount = serverRecords.length;
+    const idCountVarint = encodeVarint(idCount);
+
+    // Concatenate all IDs
+    const idsBuffer = new Uint8Array(32 * idCount);
+    for (let i = 0; i < idCount; i++) {
+      idsBuffer.set(serverRecords[i].id, i * 32);
+    }
+
+    const payload = new Uint8Array(idCountVarint.length + idsBuffer.length);
+    payload.set(idCountVarint, 0);
+    payload.set(idsBuffer, idCountVarint.length);
+
+    const ranges: Range[] = [
+      {
+        upperBound: {
+          timestampOffset: BigInt(0), // Infinity timestamp encoded as 0
+          idPrefix: new Uint8Array(),
+        },
+        mode: 2, // IdList
+        payload: payload,
+      },
+    ];
+
+    return encodeMessage(ranges);
+  }
+}

package/src/transports/Transport.ts

@@ -0,0 +1,4 @@
+export interface Transport {
+  send(message: string): void;
+  onMessage(callback: (message: string) => void): void;
+}

package/src/transports/WebSocket.ts

@@ -0,0 +1,19 @@
+import { Transport } from './Transport';
+
+export class BrowserWebSocketTransport implements Transport {
+  private websocket: WebSocket;
+
+  constructor(websocket: WebSocket) {
+    this.websocket = websocket;
+  }
+
+  send(message: string): void {
+    this.websocket.send(message);
+  }
+
+  onMessage(callback: (message: string) => void): void {
+    this.websocket.onmessage = (event: MessageEvent) => {
+      callback(event.data);
+    };
+  }
+}

package/src/transports/Websocket/Browser.ts

@@ -0,0 +1,21 @@
+// src/transports/BrowserWebSocketTransport.ts
+
+import { Transport } from '../Transport';
+
+export class BrowserWebSocketTransport implements Transport {
+  private websocket: WebSocket;
+
+  constructor(websocket: WebSocket) {
+    this.websocket = websocket;
+  }
+
+  send(message: string): void {
+    this.websocket.send(message);
+  }
+
+  onMessage(callback: (message: string) => void): void {
+    this.websocket.onmessage = (event: MessageEvent) => {
+      callback(event.data);
+    };
+  }
+}

package/src/transports/Websocket/Node.ts

@@ -0,0 +1,32 @@
+import { Transport } from '../Transport';
+import WebSocket from 'ws';
+
+export class NodeWebSocketTransport implements Transport {
+  private websocket: WebSocket;
+
+  constructor(websocket: WebSocket) {
+    this.websocket = websocket;
+  }
+
+  send(message: string): void {
+    this.websocket.send(message);
+  }
+
+  onMessage(callback: (message: string) => void): void {
+    this.websocket.on('message', (data: WebSocket.Data) => {
+      if (typeof data === 'string') {
+        callback(data);
+      } else if (data instanceof Buffer) {
+        callback(data.toString());
+      } else if (data instanceof ArrayBuffer) {
+        callback(Buffer.from(data).toString());
+      } else if (Array.isArray(data)) {
+        // Handle array of Buffers (rare case)
+        callback(Buffer.concat(data).toString());
+      } else {
+        // Handle other types if necessary
+        callback(String(data));
+      }
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+export type RecordItem = { timestamp: bigint; id: Uint8Array };
+export type RangeMode = 0 | 1 | 2;
+
+export interface Range {
+  upperBound: Bound;
+  mode: RangeMode;
+  payload: Uint8Array;
+}
+
+export interface Bound {
+  timestampOffset: bigint;
+  idPrefix: Uint8Array;
+}

package/src/utils/encoding.ts

@@ -0,0 +1,114 @@
+import PROTOCOL_VERSION from '../version';
+import type { Range, Bound, RangeMode } from '../types';
+
+export function encodeMessage(ranges: Range[]): Uint8Array {
+  const buffers: Uint8Array[] = [];
+  buffers.push(Uint8Array.from([PROTOCOL_VERSION]));
+  let prevTimestamp = BigInt(0);
+
+  for (const range of ranges) {
+    const timestampOffset = range.upperBound.timestampOffset;
+    const timestampVarint = encodeVarint(Number(timestampOffset));
+    const idPrefixLengthVarint = encodeVarint(range.upperBound.idPrefix.length);
+    const upperBoundBuffer = Buffer.concat([timestampVarint, idPrefixLengthVarint, range.upperBound.idPrefix]);
+
+    const modeVarint = encodeVarint(range.mode);
+
+    buffers.push(upperBoundBuffer);
+    buffers.push(modeVarint);
+
+    if (range.mode === 0) {
+    } else if (range.mode === 1) {
+      buffers.push(range.payload);
+    } else if (range.mode === 2) {
+      buffers.push(range.payload);
+    }
+    prevTimestamp += timestampOffset;
+  }
+  return Buffer.concat(buffers);
+}
+
+export function decodeMessage(buffer: Uint8Array): Range[] {
+  let offset = 0;
+  const ranges: Range[] = [];
+  const protocolVersion = buffer[offset++];
+  if (protocolVersion !== PROTOCOL_VERSION) {
+    throw new Error(`Unsupported protocol version: ${protocolVersion}`);
+  }
+  let prevTimestamp = BigInt(0);
+
+  while (offset < buffer.length) {
+    const timestampResult = decodeVarint(buffer, offset);
+    offset += timestampResult.bytesRead;
+    const timestampOffset = BigInt(timestampResult.value);
+    const idPrefixLengthResult = decodeVarint(buffer, offset);
+    offset += idPrefixLengthResult.bytesRead;
+    const idPrefixLength = idPrefixLengthResult.value;
+    const idPrefix = buffer.subarray(offset, offset + idPrefixLength);
+    offset += idPrefixLength;
+
+    const upperBound: Bound = {
+      timestampOffset,
+      idPrefix,
+    };
+
+    const modeResult = decodeVarint(buffer, offset);
+    offset += modeResult.bytesRead;
+    const mode = modeResult.value as RangeMode;
+
+    let payload: Uint8Array = new Uint8Array();
+    if (mode === 0) {
+    } else if (mode === 1) {
+      payload = buffer.subarray(offset, offset + 16);
+      offset += 16;
+    } else if (mode === 2) {
+      const lengthResult = decodeVarint(buffer, offset);
+      offset += lengthResult.bytesRead;
+      const idCount = lengthResult.value;
+      const ids: Uint8Array[] = [];
+      for (let i = 0; i < idCount; i++) {
+        const id = buffer.subarray(offset, offset + 32);
+        ids.push(id);
+        offset += 32;
+      }
+      payload = Buffer.concat([encodeVarint(idCount), ...ids]);
+    } else {
+      throw new Error(`Unknown mode: ${mode}`);
+    }
+
+    ranges.push({
+      upperBound,
+      mode,
+      payload,
+    });
+  }
+  return ranges;
+}
+
+export function encodeVarint(value: number): Uint8Array {
+  const buffer: number[] = [];
+  while (value >= 0x80) {
+    buffer.push((value & 0x7f) | 0x80);
+    value >>>= 7;
+  }
+  buffer.push(value & 0x7f);
+  return new Uint8Array(buffer);
+}
+  
+export function decodeVarint(buffer: Uint8Array, offset: number = 0): { value: number; bytesRead: number } {
+  let value = 0;
+  let shift = 0;
+  let bytesRead = 0;
+
+  while (true) {
+    if (offset + bytesRead >= buffer.length) {
+      throw new Error("Buffer underflow during varint decoding");
+    }
+    const byte = buffer[offset + bytesRead];
+    value |= (byte & 0x7f) << shift;
+    bytesRead++;
+    if ((byte & 0x80) === 0) break;
+    shift += 7;
+  }
+  return { value, bytesRead };
+}

package/src/utils/helpers.ts

@@ -0,0 +1,30 @@
+import crypto from 'crypto';
+import { RecordItem } from '../types';
+import { encodeVarint } from './encoding';
+
+export function compareUint8Arrays(a: Uint8Array, b: Uint8Array): number {
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return a.length - b.length;
+}
+
+export function computeFingerprint(rangeItems: RecordItem[]): Uint8Array {
+  const sum = rangeItems.reduce((acc, item) => {
+    const idBigInt = BigInt('0x' + Buffer.from(item.id).reverse().toString('hex'));
+    return (acc + idBigInt) % (BigInt(1) << BigInt(256));
+  }, BigInt(0));
+
+  const sumBuffer = Buffer.alloc(32);
+  sumBuffer.writeBigUInt64LE(sum & BigInt('0xffffffffffffffff'), 0);
+  sumBuffer.writeBigUInt64LE((sum >> BigInt(64)) & BigInt('0xffffffffffffffff'), 8);
+  sumBuffer.writeBigUInt64LE((sum >> BigInt(128)) & BigInt('0xffffffffffffffff'), 16);
+  sumBuffer.writeBigUInt64LE((sum >> BigInt(192)) & BigInt('0xffffffffffffffff'), 24);
+
+  const lengthVarint = encodeVarint(rangeItems.length);
+
+  const concatBuffer = Buffer.concat([sumBuffer, lengthVarint]);
+
+  const hash = crypto.createHash('sha256').update(concatBuffer).digest();
+  return hash.subarray(0, 16);
+}

package/src/utils/hex.ts

@@ -0,0 +1,16 @@
+export function hexToUint8Array(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error('Invalid hex string');
+  }
+  const array = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < array.length; i++) {
+    array[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return array;
+}
+
+export function uint8ArrayToHex(array: Uint8Array): string {
+  return Array.from(array)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './encoding';
+export * from './helpers';

package/src/utils/textEncoding.ts

@@ -0,0 +1,7 @@
+export function stringToUint8Array(str: string): Uint8Array {
+  return new TextEncoder().encode(str);
+}
+
+export function uint8ArrayToString(array: Uint8Array): string {
+  return new TextDecoder().decode(array);
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+export const PROTOCOL_VERSION = 0x61; // Version 1
+export default PROTOCOL_VERSION;