@msgboard/history 0.0.30

package/README.md

@@ -0,0 +1,85 @@
+# @msgboard/history
+
+A durable historical archive for the msgboard board. The board itself is **ephemeral** — it retains
+only roughly the last 120 blocks of messages — so anything that needs durable history has to record
+messages as they flow by. This package is the storage core for that: a Postgres-backed archive plus a
+read-only HTTP query API.
+
+```sh
+npm i @msgboard/history
+```
+
+`pg` is an optional peer dependency — bring your own `Pool` (or any `{ query(text, params) }`).
+
+## What's in the box
+
+- **`createArchive({ pool, retention })`** — the storage core: `migrate()`, `record(message, chainId)`,
+  `prune()`, and `query(filter)` over a `message_archive` table.
+- **`archiveServer({ archive, port, host, token })`** — a read-only HTTP API over `query`.
+
+The same `createArchive` backs `@msgboard/relayer`'s `postgresArchiveSink`, which adapts it to the
+relayer's sink interface so an **archivist** relayer can populate the archive from live board traffic.
+
+## Recording history
+
+Run an archivist relayer (see `@msgboard/relayer` and `packages/examples/src/archivist.ts`) to write
+every message into the archive, or record directly:
+
+```ts
+import pg from 'pg'
+import { createArchive } from '@msgboard/history'
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
+const archive = createArchive({ pool, retention: { days: 365 } })
+await archive.migrate() // once at startup
+
+await archive.record(message, 943) // message: RPCMessage, 943: chainId
+```
+
+`record` is idempotent on `(hash, chain_id)`. The archive grows forever until `prune()` deletes rows
+older than the retention window.
+
+## Querying history
+
+```ts
+const recent = await archive.query({
+  chainId: 943,
+  category: 'lorem', // bytes32 hex or its decoded text
+  contains: 'hello', // substring match on decoded content
+  since: new Date('2026-01-01'),
+  limit: 20,
+})
+```
+
+`limit` is clamped to at most 1000; results come back newest-first. `since`/`until` filter on
+`first_seen_at`.
+
+## Serving history over HTTP
+
+```ts
+import { createArchive, archiveServer } from '@msgboard/history'
+
+const archive = createArchive({ pool, retention: { days: 365 } })
+await archive.migrate()
+const server = archiveServer({ archive, port: 4040 }) // loopback by default
+```
+
+- `GET /health` → `{ ok: true }`
+- `GET /messages?chainId=943&category=lorem&contains=hello&since=2026-01-01&limit=20&offset=0` →
+  `{ messages: [...] }`
+
+```sh
+curl 'http://localhost:4040/messages?chainId=943&category=lorem&limit=20'
+```
+
+### Security
+
+The server binds to `127.0.0.1` by default. To expose it on a public interface, set `host` **and** a
+`token` — a non-loopback bind without a token throws at startup. When `token` is set, `/messages`
+requires `Authorization: Bearer <token>` (`/health` stays open). Slow connections are bounded by 10 s
+header/request timeouts. `limit`/`offset` are coerced to bounded integers before they reach SQL.
+
+## A full example
+
+`packages/examples/src/history-server.ts` wires the whole flow end to end: an archivist relayer writes
+live board traffic into Postgres while `archiveServer` serves queries over it.

package/dist/archive.d.ts

@@ -0,0 +1,61 @@
+import type { RPCMessage } from '@msgboard/sdk';
+/** The minimal `pg`-compatible surface this package needs — a `Pool` or `Client` satisfies it. */
+export type Queryable = {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+};
+export type ArchiveRetention = {
+    /** Rows older than this many days are pruned. */
+    days: number;
+};
+export type ArchiveOptions = {
+    pool: Queryable;
+    retention: ArchiveRetention;
+};
+/** Filters for querying the historical archive. */
+export type ArchiveQuery = {
+    chainId?: number;
+    /** A bytes32 hex category or its decoded text. */
+    category?: string;
+    since?: Date;
+    until?: Date;
+    /** Substring match on decoded content. */
+    contains?: string;
+    limit?: number;
+    offset?: number;
+};
+/** A row of the historical archive. */
+export type ArchivedMessage = {
+    hash: string;
+    chain_id: number;
+    category: string | null;
+    category_text: string | null;
+    data: string | null;
+    content: string | null;
+    block_number: string | null;
+    block_hash: string | null;
+    first_seen_at: string;
+};
+/** The archive's read/write surface. */
+export type Archive = {
+    /** Creates the table and indexes. Call once at startup. */
+    migrate(): Promise<void>;
+    /** Records a message seen on `chainId`. Idempotent on `(hash, chain_id)`. */
+    record(message: RPCMessage, chainId: number): Promise<void>;
+    /** Deletes rows older than the retention window. */
+    prune(): Promise<void>;
+    /** Returns matching rows, newest first, bounded to at most 1000. */
+    query(filter: ArchiveQuery): Promise<ArchivedMessage[]>;
+};
+/**
+ * The historical index of every message seen flowing through the board. An
+ * ever-growing table, pruned to a retention window (default one year). `record`
+ * is idempotent on `(hash, chain_id)`. Call `migrate()` once at startup.
+ *
+ * This is the storage core behind `@msgboard/relayer`'s `postgresArchiveSink`
+ * (which adapts it to the relayer's sink interface) and `archiveServer` (which
+ * exposes `query` over HTTP).
+ */
+export declare const createArchive: (options: ArchiveOptions) => Archive;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE/C,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAA;CACtE,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,SAAS,EAAE,gBAAgB,CAAA;CAC5B,CAAA;AAED,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,OAAO,GAAG;IACpB,2DAA2D;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,6EAA6E;IAC7E,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,oEAAoE;IACpE,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;CACxD,CAAA;AAeD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,cAAc,KAAG,OAyEvD,CAAA"}

package/dist/archive.js

@@ -0,0 +1,90 @@
+import { hexToString } from 'viem';
+/** Decodes a hex blob to text, stripping null padding and returning null if not printable. */
+const tryDecodeText = (hex) => {
+    try {
+        const text = hexToString(hex).replace(/\0+$/g, '').trim();
+        if (text.length === 0)
+            return null;
+        // Reject blobs with non-printable control characters
+        if (/[\x00-\x1f\x7f]/u.test(text))
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The historical index of every message seen flowing through the board. An
+ * ever-growing table, pruned to a retention window (default one year). `record`
+ * is idempotent on `(hash, chain_id)`. Call `migrate()` once at startup.
+ *
+ * This is the storage core behind `@msgboard/relayer`'s `postgresArchiveSink`
+ * (which adapts it to the relayer's sink interface) and `archiveServer` (which
+ * exposes `query` over HTTP).
+ */
+export const createArchive = (options) => {
+    const { pool } = options;
+    const retentionDays = options.retention.days;
+    const migrate = async () => {
+        await pool.query(`CREATE TABLE IF NOT EXISTS message_archive (
+        hash          TEXT NOT NULL,
+        chain_id      INTEGER NOT NULL,
+        category      TEXT,
+        category_text TEXT,
+        data          TEXT,
+        content       TEXT,
+        block_number  BIGINT,
+        block_hash    TEXT,
+        first_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (hash, chain_id)
+      )`);
+        await pool.query(`CREATE INDEX IF NOT EXISTS message_archive_seen_idx ON message_archive (first_seen_at)`);
+        await pool.query(`CREATE INDEX IF NOT EXISTS message_archive_chain_seen ON message_archive (chain_id, first_seen_at)`);
+        await pool.query(`CREATE INDEX IF NOT EXISTS message_archive_category_idx ON message_archive (category)`);
+    };
+    const record = async (message, chainId) => {
+        await pool.query(`INSERT INTO message_archive
+        (hash, chain_id, category, category_text, data, content, block_number, block_hash)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       ON CONFLICT (hash, chain_id) DO NOTHING`, [
+            message.hash,
+            chainId,
+            message.category,
+            tryDecodeText(message.category),
+            message.data,
+            tryDecodeText(message.data),
+            BigInt(message.blockNumber).toString(),
+            message.blockHash,
+        ]);
+    };
+    const prune = async () => {
+        await pool.query(`DELETE FROM message_archive WHERE first_seen_at < now() - INTERVAL '${retentionDays} days'`);
+    };
+    const query = async (filter) => {
+        const clauses = [];
+        const params = [];
+        const add = (clause, value) => {
+            params.push(value);
+            clauses.push(clause.replace(/\$\?/g, `$${params.length}`));
+        };
+        if (filter.chainId !== undefined)
+            add('chain_id = $?', filter.chainId);
+        if (filter.category !== undefined)
+            add('(category = $? OR category_text = $?)', filter.category);
+        if (filter.since)
+            add('first_seen_at >= $?', filter.since.toISOString());
+        if (filter.until)
+            add('first_seen_at <= $?', filter.until.toISOString());
+        if (filter.contains)
+            add('content ILIKE $?', `%${filter.contains}%`);
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        // limit/offset are interpolated, so coerce to bounded integers (never user SQL).
+        const limit = Math.min(Math.max(Number.parseInt(String(filter.limit ?? 100), 10) || 100, 1), 1000);
+        const offset = Math.max(Number.parseInt(String(filter.offset ?? 0), 10) || 0, 0);
+        const { rows } = await pool.query(`SELECT hash, chain_id, category, category_text, data, content, block_number, block_hash, first_seen_at FROM message_archive ${where} ORDER BY first_seen_at DESC LIMIT ${limit} OFFSET ${offset}`, params);
+        return rows;
+    };
+    return { migrate, record, prune, query };
+};
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createArchive } from './archive.js';
+export type { Archive, ArchiveOptions, ArchiveQuery, ArchiveRetention, ArchivedMessage, Queryable, } from './archive.js';
+export { archiveServer } from './server.js';
+export type { ArchiveServer, ArchiveServerOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EACV,OAAO,EACP,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,SAAS,GACV,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createArchive } from './archive.js';
+export { archiveServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAU5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+import type { Archive } from './archive.js';
+export type ArchiveServerOptions = {
+    /** The archive to serve. */
+    archive: Archive;
+    /** Port to listen on. Defaults to 4040. */
+    port?: number;
+    /**
+     * Host / interface to bind. Defaults to `'127.0.0.1'` (loopback only).
+     * Set to `'0.0.0.0'` for LAN/Internet exposure — requires `token`, or the
+     * server refuses to start (the archive is read-only, but still yours to gate).
+     */
+    host?: string;
+    /**
+     * Optional bearer token. When set, `/messages` requests without
+     * `Authorization: Bearer <token>` receive a 401.
+     */
+    token?: string;
+};
+export type ArchiveServer = {
+    /** Closes the HTTP server. */
+    close(): Promise<void>;
+};
+/**
+ * Serves an {@link Archive} over HTTP, read-only:
+ *
+ * - `GET /health`   → `{ ok: true }`
+ * - `GET /messages` → `{ messages: ArchivedMessage[] }`, filtered by query params:
+ *   `chainId`, `category` (hex or decoded text), `since`/`until` (ISO dates),
+ *   `contains` (substring on decoded content), `limit` (≤ 1000), `offset`.
+ *
+ * Security defaults mirror the relayer's push source: binds to `127.0.0.1`
+ * unless `host` is set, and a non-loopback bind requires `token`. Slow
+ * connections are bounded by 10 s header/request timeouts.
+ */
+export declare const archiveServer: (options: ArchiveServerOptions) => ArchiveServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,cAAc,CAAA;AAEzD,MAAM,MAAM,oBAAoB,GAAG;IACjC,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,8BAA8B;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA;AAoCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,oBAAoB,KAAG,aA2C7D,CAAA"}

package/dist/server.js

@@ -0,0 +1,79 @@
+import { createServer } from 'node:http';
+const respond = (res, status, body) => {
+    const json = JSON.stringify(body);
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(json) });
+    res.end(json);
+};
+/** Parses the `/messages` query string into an ArchiveQuery, ignoring unparseable values. */
+const parseQuery = (params) => {
+    const query = {};
+    const chainId = params.get('chainId');
+    if (chainId !== null && Number.isFinite(Number(chainId)))
+        query.chainId = Number(chainId);
+    const category = params.get('category');
+    if (category)
+        query.category = category;
+    const contains = params.get('contains');
+    if (contains)
+        query.contains = contains;
+    const since = params.get('since');
+    if (since && !Number.isNaN(Date.parse(since)))
+        query.since = new Date(since);
+    const until = params.get('until');
+    if (until && !Number.isNaN(Date.parse(until)))
+        query.until = new Date(until);
+    const limit = params.get('limit');
+    if (limit !== null && Number.isFinite(Number(limit)))
+        query.limit = Number(limit);
+    const offset = params.get('offset');
+    if (offset !== null && Number.isFinite(Number(offset)))
+        query.offset = Number(offset);
+    return query;
+};
+/**
+ * Serves an {@link Archive} over HTTP, read-only:
+ *
+ * - `GET /health`   → `{ ok: true }`
+ * - `GET /messages` → `{ messages: ArchivedMessage[] }`, filtered by query params:
+ *   `chainId`, `category` (hex or decoded text), `since`/`until` (ISO dates),
+ *   `contains` (substring on decoded content), `limit` (≤ 1000), `offset`.
+ *
+ * Security defaults mirror the relayer's push source: binds to `127.0.0.1`
+ * unless `host` is set, and a non-loopback bind requires `token`. Slow
+ * connections are bounded by 10 s header/request timeouts.
+ */
+export const archiveServer = (options) => {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 4040;
+    const isNonLoopback = host !== '127.0.0.1' && host !== 'localhost' && host !== '::1';
+    if (isNonLoopback && !options.token) {
+        throw new Error(`archiveServer: non-loopback bind (${host}) requires a token to be set — pass token or set host to '127.0.0.1'`);
+    }
+    const authorized = (req) => !options.token || req.headers['authorization'] === `Bearer ${options.token}`;
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${host}:${port}`);
+        if (req.method === 'GET' && url.pathname === '/health') {
+            return respond(res, 200, { ok: true });
+        }
+        if (req.method === 'GET' && url.pathname === '/messages') {
+            if (!authorized(req))
+                return respond(res, 401, { ok: false, error: 'unauthorized' });
+            try {
+                const messages = await options.archive.query(parseQuery(url.searchParams));
+                return respond(res, 200, { messages });
+            }
+            catch (error) {
+                return respond(res, 500, { ok: false, error: error instanceof Error ? error.message : 'query failed' });
+            }
+        }
+        return respond(res, 404, { ok: false, error: 'not found' });
+    });
+    // Bound slow connections.
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 10_000;
+    server.listen(port, host);
+    return {
+        close: () => new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+    };
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@msgboard/history",
+  "version": "0.0.30",
+  "description": "Historical archive for the msgboard board: durable storage and an HTTP query API",
+  "repository": "github:valve-tech/msgboard",
+  "author": "MsgBoard",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": ["msgboard", "history", "archive", "indexer", "pulsechain"],
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "prettier --check ."
+  },
+  "files": ["dist/"],
+  "dependencies": {
+    "@msgboard/sdk": "^0.0.30",
+    "viem": "^2.25.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.14.1"
+  },
+  "peerDependenciesMeta": {
+    "pg": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.11",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  }
+}