@msgboard/relayer 0.0.1

package/README.md

@@ -0,0 +1,71 @@
+# @msgboard/relayer
+
+A controllable, safe-by-default pool-watcher engine for the msgboard board. Runs a heartbeat: poll a **Source**, record every item to an always-on **Sink**, filter by a **Condition**, dedup via a **Store**, then gate the **Action** based on mode.
+
+## Safe by default
+
+The engine has two modes:
+
+- **`observe`** (default): polls, records to the sink, and logs what it *would* do. No outbound side effect. A relayer constructed without an explicit `mode` never writes on chain.
+- **`live`**: executes the action when all conditions are met. Use `BRIDGE_LIVE=1`, `SPAM_OBSERVE=1` etc. to flip the mode from environment variables — never hardcode `live`.
+
+## The four contracts
+
+| Contract | Role | Retention |
+|---|---|---|
+| `RelayerSource<T>` | Reads the current batch of candidates from the watched pool | — |
+| `RelayerAction<T>` | Describes (observe) or executes (live) the outbound effect | — |
+| `RelayerStore<T>` | Action-level dedup: "have I already acted on this?" | Short (minutes–hours) |
+| `RelayerSink<T>` | Unconditional history/observability recording | Long (months–years) |
+
+Sink and Store are intentionally separate: the sink runs in **both** modes; the store only advances in live mode after a successful execute.
+
+## Minimal usage
+
+```ts
+import { Relayer, msgboardContentSource, noopAction } from '@msgboard/relayer'
+
+const relayer = new Relayer({
+  node: { rpcUrl: 'https://rpc.v4.testnet.pulsechain.com', chainId: 943 },
+  // mode defaults to 'observe' — no on-chain writes
+  source: msgboardContentSource({ category: 'myapp' }),
+  key: (msg) => msg.hash,
+  action: noopAction(),
+})
+
+relayer.start()
+// later: await relayer.stop()
+// or:    const report = await relayer.runOnce()
+```
+
+## Historical archive
+
+`postgresArchiveSink` records every message the relayer sees to a `message_archive` table with a default 1-year retention window. Run a dedicated **archivist** relayer (see `examples/archivist.ts`) to populate the archive from all board traffic, then query it:
+
+```ts
+const archive = postgresArchiveSink({ pool, retention: { days: 365 } })
+await archive.migrate()
+
+const recent = await archive.query({ chainId: 943, category: 'lorem', limit: 20 })
+```
+
+`query()` filters by `chainId`, `category` (hex or decoded text), `since`/`until`, `contains` (substring match on decoded content), `limit`, and `offset`.
+
+## Example relayers
+
+| Relayer | source | store | sink | action (live only) | demonstrates |
+|---|---|---|---|---|---|
+| Gas sponsor (`index.ts`) | content `gasmoneyplease` + address check | postgres | archive | `sendValueAction` 10 coins | durable dedup, value transfer |
+| Bridge watcher (`bridge.ts`) | `bridgeAffirmationSource` (per chain) | memory-ttl | — | `submitMessageAction` | finalized event source, multi-node |
+| Spam writer (`spam.ts`) | `generatedSource(sentence)` | noop | — | `submitMessageAction` | producer source, noop dedup |
+| Archivist | all content | — | `postgresArchiveSink` 1yr | `noopAction` | sink-only; records in observe mode |
+| Cross-chain mirror | content on 369 | memory-ttl | — | `submitMessageAction` on 943 | source node ≠ action node |
+| Moderation flagger | all content + blocklist predicate | — | `postgresSink('flagged')` | `noopAction` | condition + sink, no action |
+
+See `examples/` for runnable code for the archivist, mirror, and flagger.
+
+## Known limitations
+
+- **Difficulty sync**: `submitMessageAction` uses the `MsgBoardClient` default difficulty factors (10 000 / 1 000 000). If a board deployment uses non-standard difficulty, pass `difficultyFactors` when constructing your own `MsgBoardClient` and supply it via a custom action rather than `submitMessageAction`.
+- **Reorg handling**: sources read at the current head by default. The `bridgeAffirmationSource` reads at the finalized block, so it is reorg-safe. Other sources are best-effort; for strict reorg safety, build a checkpointed source using the `RelayerSource` contract.
+- **Multi-node fan-out**: construct one `Relayer` per node and call `start()` on each — no special machinery needed.

package/dist/actions/noop.d.ts

@@ -0,0 +1,4 @@
+import type { RelayerAction } from '../types.js';
+/** An action that does nothing. For sink-only relayers (archivist, flagger). */
+export declare const noopAction: <T>() => RelayerAction<T>;
+//# sourceMappingURL=noop.d.ts.map

package/dist/actions/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/actions/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,gFAAgF;AAChF,eAAO,MAAM,UAAU,GAAI,CAAC,OAAK,aAAa,CAAC,CAAC,CAG9C,CAAA"}

package/dist/actions/noop.js

@@ -0,0 +1,6 @@
+/** An action that does nothing. For sink-only relayers (archivist, flagger). */
+export const noopAction = () => ({
+    describe: () => 'noop',
+    execute: async () => ({ ok: true }),
+});
+//# sourceMappingURL=noop.js.map

package/dist/actions/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../src/actions/noop.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,GAAwB,EAAE,CAAC,CAAC;IACpD,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM;IACtB,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;CACpC,CAAC,CAAA"}

package/dist/actions/send-value.d.ts

@@ -0,0 +1,17 @@
+import { type Account, type Address, type WalletClient } from 'viem';
+import type { RelayerAction, RelayerContext } from '../types.js';
+export type SendValueActionOptions<T> = {
+    /** The funding account (e.g. from `mnemonicToAccount`). */
+    account: Account;
+    /** Derives the recipient address for an item. */
+    recipient: (item: T, context: RelayerContext) => Address;
+    /** Amount to send, in wei. */
+    amount: bigint;
+    /** Gas limit for the transfer. */
+    gas: bigint;
+    /** Overridable wallet-client factory (injected in tests). */
+    walletFactory?: (context: RelayerContext) => WalletClient;
+};
+/** Sends native coin to an address derived from each item; waits for the receipt. */
+export declare const sendValueAction: <T>(options: SendValueActionOptions<T>) => RelayerAction<T>;
+//# sourceMappingURL=send-value.d.ts.map

package/dist/actions/send-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-value.d.ts","sourceRoot":"","sources":["../../src/actions/send-value.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,YAAY,EAIlB,MAAM,MAAM,CAAA;AACb,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEhE,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI;IACtC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAA;IACxD,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,6DAA6D;IAC7D,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,YAAY,CAAA;CAC1D,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,SAAS,sBAAsB,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAyBtF,CAAA"}

package/dist/actions/send-value.js

@@ -0,0 +1,27 @@
+import { createWalletClient, formatEther, http, } from 'viem';
+/** Sends native coin to an address derived from each item; waits for the receipt. */
+export const sendValueAction = (options) => {
+    const makeWallet = (context) => options.walletFactory?.(context) ??
+        createWalletClient({
+            account: options.account,
+            chain: context.chain,
+            transport: http(context.node.rpcUrl, { timeout: 30_000 }),
+        });
+    return {
+        describe: (item, context) => `send ${formatEther(options.amount)} to ${options.recipient(item, context)}`,
+        execute: async (item, context) => {
+            const wallet = makeWallet(context);
+            const to = options.recipient(item, context);
+            const hash = await wallet.sendTransaction({
+                account: options.account,
+                chain: context.chain,
+                to,
+                value: options.amount,
+                gas: options.gas,
+            });
+            await context.publicClient.waitForTransactionReceipt({ hash });
+            return { ok: true, ref: hash };
+        },
+    };
+};
+//# sourceMappingURL=send-value.js.map

package/dist/actions/send-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-value.js","sourceRoot":"","sources":["../../src/actions/send-value.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,kBAAkB,EAClB,WAAW,EACX,IAAI,GACL,MAAM,MAAM,CAAA;AAgBb,qFAAqF;AACrF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAI,OAAkC,EAAoB,EAAE;IACzF,MAAM,UAAU,GAAG,CAAC,OAAuB,EAAgB,EAAE,CAC3D,OAAO,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC;QAChC,kBAAkB,CAAC;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;SAC1D,CAAC,CAAA;IACJ,OAAO;QACL,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAC1B,QAAQ,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;QAC9E,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;YAC/B,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;YAClC,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YAC3C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC;gBACxC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,EAAE;gBACF,KAAK,EAAE,OAAO,CAAC,MAAM;gBACrB,GAAG,EAAE,OAAO,CAAC,GAAG;aACjB,CAAC,CAAA;YACF,MAAM,OAAO,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;YAC9D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/actions/submit-message.d.ts

@@ -0,0 +1,10 @@
+import type { RelayerAction, RelayerContext } from '../types.js';
+export type SubmitMessageActionOptions<T> = {
+    /** Derives the category (name or bytes32 hex) for an item. */
+    category: (item: T, context: RelayerContext) => string;
+    /** Derives the message data (text or hex) for an item. */
+    data: (item: T, context: RelayerContext) => string;
+};
+/** Posts a proof-of-work message to the board. No wallet or gas required. */
+export declare const submitMessageAction: <T>(options: SubmitMessageActionOptions<T>) => RelayerAction<T>;
+//# sourceMappingURL=submit-message.d.ts.map

package/dist/actions/submit-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-message.d.ts","sourceRoot":"","sources":["../../src/actions/submit-message.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEhE,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,8DAA8D;IAC9D,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,MAAM,CAAA;IACtD,0DAA0D;IAC1D,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,MAAM,CAAA;CACnD,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,GAAI,CAAC,EACnC,SAAS,0BAA0B,CAAC,CAAC,CAAC,KACrC,aAAa,CAAC,CAAC,CAUhB,CAAA"}

package/dist/actions/submit-message.js

@@ -0,0 +1,13 @@
+import { encodeData } from '@msgboard/sdk';
+/** Posts a proof-of-work message to the board. No wallet or gas required. */
+export const submitMessageAction = (options) => ({
+    describe: (item, context) => `post message category=${options.category(item, context)} data=${options.data(item, context)}`,
+    execute: async (item, context) => {
+        const category = options.category(item, context);
+        const data = encodeData(options.data(item, context));
+        const work = await context.client.doPoW(category, data);
+        const hash = await context.client.addMessage(work.message);
+        return { ok: true, ref: hash, meta: { stats: work.stats } };
+    },
+});
+//# sourceMappingURL=submit-message.js.map

package/dist/actions/submit-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-message.js","sourceRoot":"","sources":["../../src/actions/submit-message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAU1C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,OAAsC,EACpB,EAAE,CAAC,CAAC;IACtB,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAC1B,yBAAyB,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;IAChG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAChD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QACpD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QACvD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC1D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAA;IAC7D,CAAC;CACF,CAAC,CAAA"}

package/dist/actions/webhook.d.ts

@@ -0,0 +1,9 @@
+import type { RelayerAction } from '../types.js';
+export type WebhookActionOptions = {
+    url: string;
+    /** Overridable fetch implementation (injected in tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+};
+/** Posts each item as JSON to a webhook. Demonstrates a non-on-chain gated action. */
+export declare const webhookAction: <T>(options: WebhookActionOptions) => RelayerAction<T>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/actions/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/actions/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,SAAS,oBAAoB,KAAG,aAAa,CAAC,CAAC,CAa/E,CAAA"}

package/dist/actions/webhook.js

@@ -0,0 +1,16 @@
+/** Posts each item as JSON to a webhook. Demonstrates a non-on-chain gated action. */
+export const webhookAction = (options) => {
+    const doFetch = options.fetchImpl ?? fetch;
+    return {
+        describe: (_item) => `POST to ${options.url}`,
+        execute: async (item) => {
+            const response = await doFetch(options.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(item),
+            });
+            return { ok: response.ok, meta: { status: response.status } };
+        },
+    };
+};
+//# sourceMappingURL=webhook.js.map

package/dist/actions/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/actions/webhook.ts"],"names":[],"mappings":"AAQA,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAI,OAA6B,EAAoB,EAAE;IAClF,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAA;IAC1C,OAAO;QACL,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,OAAO,CAAC,GAAG,EAAE;QAC7C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC1C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aAC3B,CAAC,CAAA;YACF,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAA;QAC/D,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/chains.d.ts

@@ -0,0 +1,7 @@
+import type { Chain } from 'viem';
+/**
+ * Resolves a viem chain from its numeric id.
+ * @throws if the chain id is not one of the supported networks
+ */
+export declare const resolveChain: (chainId: number) => Chain;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAA;AAUjC;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,KAO9C,CAAA"}

package/dist/chains.js

@@ -0,0 +1,20 @@
+import { mainnet, pulsechain, pulsechainV4 } from 'viem/chains';
+/** The networks a relayer can target, keyed by chain id. */
+const chainsById = {
+    [mainnet.id]: mainnet,
+    [pulsechain.id]: pulsechain,
+    [pulsechainV4.id]: pulsechainV4,
+};
+/**
+ * Resolves a viem chain from its numeric id.
+ * @throws if the chain id is not one of the supported networks
+ */
+export const resolveChain = (chainId) => {
+    const chain = chainsById[chainId];
+    if (!chain) {
+        const supported = Object.keys(chainsById).join(', ');
+        throw new Error(`unsupported chainId ${chainId} (expected one of ${supported})`);
+    }
+    return chain;
+};
+//# sourceMappingURL=chains.js.map

package/dist/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/D,4DAA4D;AAC5D,MAAM,UAAU,GAA0B;IACxC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO;IACrB,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,UAAU;IAC3B,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,YAAY;CAChC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAS,EAAE;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpD,MAAM,IAAI,KAAK,CAAC,uBAAuB,OAAO,qBAAqB,SAAS,GAAG,CAAC,CAAA;IAClF,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { Relayer } from './relayer.js';
+export { defaultLogger } from './logger.js';
+export type { Logger } from './logger.js';
+export { resolveChain } from './chains.js';
+export type { ActionResult, RelayerAction, RelayerCondition, RelayerConfig, RelayerContext, RelayerKey, RelayerMode, RelayerNode, RelayerSink, RelayerSource, RelayerStore, TickReport, } from './types.js';
+export { memoryTtlStore } from './stores/memory-ttl.js';
+export { noopStore } from './stores/noop.js';
+export { postgresStore } from './stores/postgres.js';
+export type { Queryable } from './stores/postgres.js';
+export { postgresArchiveSink } from './sinks/postgres-archive.js';
+export type { ArchiveQuery, ArchivedMessage, ArchiveRetention } from './sinks/postgres-archive.js';
+export { postgresSink } from './sinks/postgres.js';
+export { msgboardContentSource } from './sources/msgboard-content.js';
+export { bridgeAffirmationSource } from './sources/bridge-affirmation.js';
+export { generatedSource } from './sources/generated.js';
+export { submitMessageAction } from './actions/submit-message.js';
+export { sendValueAction } from './actions/send-value.js';
+export { webhookAction } from './actions/webhook.js';
+export { noopAction } from './actions/noop.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,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,16 @@
+export { Relayer } from './relayer.js';
+export { defaultLogger } from './logger.js';
+export { resolveChain } from './chains.js';
+export { memoryTtlStore } from './stores/memory-ttl.js';
+export { noopStore } from './stores/noop.js';
+export { postgresStore } from './stores/postgres.js';
+export { postgresArchiveSink } from './sinks/postgres-archive.js';
+export { postgresSink } from './sinks/postgres.js';
+export { msgboardContentSource } from './sources/msgboard-content.js';
+export { bridgeAffirmationSource } from './sources/bridge-affirmation.js';
+export { generatedSource } from './sources/generated.js';
+export { submitMessageAction } from './actions/submit-message.js';
+export { sendValueAction } from './actions/send-value.js';
+export { webhookAction } from './actions/webhook.js';
+export { noopAction } from './actions/noop.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,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAgB1C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/logger.d.ts

@@ -0,0 +1,5 @@
+/** A minimal structured logger; printf-style, matching the SDK's logger shape. */
+export type Logger = (formatter: string, ...args: unknown[]) => void;
+/** The default logger writes to the console with a fixed prefix. */
+export declare const defaultLogger: (prefix: string) => Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;AAEpE,oEAAoE;AACpE,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,MAI9C,CAAA"}

package/dist/logger.js

@@ -0,0 +1,7 @@
+/** The default logger writes to the console with a fixed prefix. */
+export const defaultLogger = (prefix) => {
+    return (formatter, ...args) => {
+        console.log(`[${prefix}] ${formatter}`, ...args);
+    };
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAc,EAAU,EAAE;IACtD,OAAO,CAAC,SAAiB,EAAE,GAAG,IAAe,EAAE,EAAE;QAC/C,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,KAAK,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA;IAClD,CAAC,CAAA;AACH,CAAC,CAAA"}

package/dist/relayer.d.ts

@@ -0,0 +1,31 @@
+import type { RelayerConfig, RelayerMode, TickReport } from './types.js';
+/**
+ * A controllable pool-watcher. Safe by default: in `observe` mode it records and
+ * logs what it would do, but performs no outbound side effect.
+ */
+export declare class Relayer<T> {
+    private readonly config;
+    private readonly logger;
+    private readonly context;
+    private readonly intervalMs;
+    private readonly pruneEveryTicks;
+    private tickCount;
+    private running;
+    private loopPromise;
+    private abort;
+    constructor(config: RelayerConfig<T>);
+    get mode(): RelayerMode;
+    /** Runs a single tick and returns a report. Used by tests and one-shot runs. */
+    runOnce(): Promise<TickReport>;
+    /** Begins the poll loop. Idempotent — a second call is a no-op while running. */
+    start(): void;
+    /** Stops the loop and awaits the in-flight tick. */
+    stop(): Promise<void>;
+    private loop;
+    private handleItem;
+    private recordItem;
+    private isEligible;
+    private actOnItem;
+    private maybePrune;
+}
+//# sourceMappingURL=relayer.d.ts.map

package/dist/relayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayer.d.ts","sourceRoot":"","sources":["../src/relayer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAkB,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAuCxF;;;GAGG;AACH,qBAAa,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,KAAK,CAA+B;gBAEhC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAQpC,IAAI,IAAI,IAAI,WAAW,CAEtB;IAED,gFAAgF;IAC1E,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAmBpC,iFAAiF;IACjF,KAAK,IAAI,IAAI;IAQb,oDAAoD;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YASb,IAAI;YAYJ,UAAU;YAWV,UAAU;YAMV,UAAU;YAcV,SAAS;YAiBT,UAAU;CAKzB"}

package/dist/relayer.js

@@ -0,0 +1,169 @@
+import { createPublicClient, http } from 'viem';
+import { MsgBoardClient } from '@msgboard/sdk';
+import { resolveChain } from './chains.js';
+import { defaultLogger } from './logger.js';
+const DEFAULT_INTERVAL_MS = 30_000;
+const DEFAULT_PRUNE_EVERY_TICKS = 30;
+/** Builds the runtime context (viem + SDK clients) for a relayer config. */
+const buildContext = (config, logger) => {
+    const chain = resolveChain(config.node.chainId);
+    const publicClient = createPublicClient({
+        chain,
+        transport: http(config.node.rpcUrl, { timeout: 30_000 }),
+    });
+    const client = new MsgBoardClient(publicClient);
+    return {
+        node: config.node,
+        mode: config.mode ?? 'observe',
+        chain,
+        publicClient,
+        client,
+        logger,
+    };
+};
+/** Resolves after `ms`, or immediately if the signal aborts. */
+const sleep = (ms, signal) => {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+};
+/**
+ * A controllable pool-watcher. Safe by default: in `observe` mode it records and
+ * logs what it would do, but performs no outbound side effect.
+ */
+export class Relayer {
+    config;
+    logger;
+    context;
+    intervalMs;
+    pruneEveryTicks;
+    tickCount = 0;
+    running = false;
+    loopPromise = null;
+    abort = null;
+    constructor(config) {
+        this.config = config;
+        this.logger = config.logger ?? defaultLogger('relayer');
+        this.context = buildContext(config, this.logger);
+        this.intervalMs = config.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.pruneEveryTicks = config.pruneEveryTicks ?? DEFAULT_PRUNE_EVERY_TICKS;
+    }
+    get mode() {
+        return this.context.mode;
+    }
+    /** Runs a single tick and returns a report. Used by tests and one-shot runs. */
+    async runOnce() {
+        const report = {
+            polled: 0,
+            recorded: 0,
+            eligible: 0,
+            executed: 0,
+            described: 0,
+            deduped: 0,
+        };
+        const items = await this.config.source.poll(this.context);
+        report.polled = items.length;
+        for (const item of items) {
+            await this.handleItem(item, report);
+        }
+        this.tickCount += 1;
+        await this.maybePrune();
+        return report;
+    }
+    /** Begins the poll loop. Idempotent — a second call is a no-op while running. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.abort = new AbortController();
+        const signal = this.abort.signal;
+        this.loopPromise = this.loop(signal);
+    }
+    /** Stops the loop and awaits the in-flight tick. */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.abort?.abort();
+        await this.loopPromise;
+        this.loopPromise = null;
+        this.abort = null;
+    }
+    async loop(signal) {
+        while (!signal.aborted) {
+            try {
+                await this.runOnce();
+            }
+            catch (error) {
+                this.logger('tick failed: %o', error instanceof Error ? error.message : error);
+            }
+            if (signal.aborted)
+                return;
+            await sleep(this.intervalMs, signal);
+        }
+    }
+    async handleItem(item, report) {
+        await this.recordItem(item, report);
+        const eligible = await this.isEligible(item);
+        if (!eligible.proceed) {
+            if (eligible.reason === 'deduped')
+                report.deduped += 1;
+            return;
+        }
+        report.eligible += 1;
+        await this.actOnItem(item, report);
+    }
+    async recordItem(item, report) {
+        if (!this.config.sink)
+            return;
+        await this.config.sink.record(item, this.context);
+        report.recorded += 1;
+    }
+    async isEligible(item) {
+        if (this.config.condition) {
+            const ok = await this.config.condition(item, this.context);
+            if (!ok)
+                return { proceed: false, reason: 'condition' };
+        }
+        if (this.config.store) {
+            const seen = await this.config.store.has(this.config.key(item));
+            if (seen)
+                return { proceed: false, reason: 'deduped' };
+        }
+        return { proceed: true };
+    }
+    async actOnItem(item, report) {
+        if (this.context.mode === 'observe') {
+            this.logger('observe: %s', this.config.action.describe(item, this.context));
+            report.described += 1;
+            return;
+        }
+        try {
+            const result = await this.config.action.execute(item, this.context);
+            report.executed += 1;
+            if (this.config.store) {
+                await this.config.store.remember(this.config.key(item), result);
+            }
+        }
+        catch (error) {
+            this.logger('action failed: %o', error instanceof Error ? error.message : error);
+        }
+    }
+    async maybePrune() {
+        if (this.tickCount % this.pruneEveryTicks !== 0)
+            return;
+        await this.config.store?.prune?.();
+        await this.config.sink?.prune?.();
+    }
+}
+//# sourceMappingURL=relayer.js.map

package/dist/relayer.js.map

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

package/dist/sinks/postgres-archive.d.ts

@@ -0,0 +1,45 @@
+import type { RPCMessage } from '@msgboard/sdk';
+import type { RelayerSink } from '../types.js';
+import type { Queryable } from '../stores/postgres.js';
+export type ArchiveRetention = {
+    /** Rows older than this many days are pruned. */
+    days: number;
+};
+export type PostgresArchiveOptions = {
+    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 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.
+ */
+export declare const postgresArchiveSink: (options: PostgresArchiveOptions) => RelayerSink<RPCMessage> & {
+    migrate(): Promise<void>;
+    query(filter: ArchiveQuery): Promise<ArchivedMessage[]>;
+};
+//# sourceMappingURL=postgres-archive.d.ts.map

package/dist/sinks/postgres-archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-archive.d.ts","sourceRoot":"","sources":["../../src/sinks/postgres-archive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEtD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,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;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAS,sBAAsB,KAC9B,WAAW,CAAC,UAAU,CAAC,GAAG;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;CA+ExD,CAAA"}

package/dist/sinks/postgres-archive.js

@@ -0,0 +1,85 @@
+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.
+ */
+export const postgresArchiveSink = (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, context) => {
+        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,
+            context.node.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 ')}` : '';
+        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 { record, prune, migrate, query };
+};
+//# sourceMappingURL=postgres-archive.js.map

package/dist/sinks/postgres-archive.js.map

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

package/dist/sinks/postgres.d.ts

@@ -0,0 +1,16 @@
+import type { RelayerContext, RelayerSink } from '../types.js';
+import type { Queryable } from '../stores/postgres.js';
+export type PostgresSinkOptions<T> = {
+    pool: Queryable;
+    table: string;
+    /** Maps an item to a durable row: a stable key and a JSON payload. */
+    toRow: (item: T, context: RelayerContext) => {
+        key: string;
+        payload: unknown;
+    };
+};
+/** A generic durable record sink: one upserted row per item, keyed and JSON-bodied. */
+export declare const postgresSink: <T>(options: PostgresSinkOptions<T>) => RelayerSink<T> & {
+    migrate(): Promise<void>;
+};
+//# sourceMappingURL=postgres.d.ts.map

package/dist/sinks/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/sinks/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEtD,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;CAC/E,CAAA;AAED,uFAAuF;AACvF,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,SAAS,mBAAmB,CAAC,CAAC,CAAC,KAC9B,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAqB7C,CAAA"}

package/dist/sinks/postgres.js

@@ -0,0 +1,19 @@
+/** A generic durable record sink: one upserted row per item, keyed and JSON-bodied. */
+export const postgresSink = (options) => {
+    const { pool, table, toRow } = options;
+    return {
+        migrate: async () => {
+            await pool.query(`CREATE TABLE IF NOT EXISTS ${table} (
+          key TEXT PRIMARY KEY,
+          payload JSONB,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )`);
+        },
+        record: async (item, context) => {
+            const row = toRow(item, context);
+            await pool.query(`INSERT INTO ${table} (key, payload) VALUES ($1, $2)
+         ON CONFLICT (key) DO UPDATE SET payload = $2`, [row.key, JSON.stringify(row.payload)]);
+        },
+    };
+};
+//# sourceMappingURL=postgres.js.map

package/dist/sinks/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/sinks/postgres.ts"],"names":[],"mappings":"AAUA,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAA+B,EACgB,EAAE;IACjD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IACtC,OAAO;QACL,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,IAAI,CAAC,KAAK,CACd,8BAA8B,KAAK;;;;UAIjC,CACH,CAAA;QACH,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;YAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YAChC,MAAM,IAAI,CAAC,KAAK,CACd,eAAe,KAAK;sDAC0B,EAC9C,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CACvC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/sources/bridge-affirmation.d.ts

@@ -0,0 +1,15 @@
+import { type Address } from 'viem';
+import type { RelayerSource } from '../types.js';
+export type BridgeAffirmationSourceOptions = {
+    /** The Arbitrary Message Bridge contract address on the watched chain. */
+    bridgeAddress: Address;
+    /** How many blocks back from finalized to scan. Defaults to 1000. */
+    lookback?: bigint;
+};
+/**
+ * Watches an Arbitrary Message Bridge for completed affirmations and yields the
+ * recipient of the most recent bridged transfer (zero or one address per poll).
+ * Reads at the finalized block, so results are reorg-safe.
+ */
+export declare const bridgeAffirmationSource: (options: BridgeAffirmationSourceOptions) => RelayerSource<Address>;
+//# sourceMappingURL=bridge-affirmation.d.ts.map

package/dist/sources/bridge-affirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-affirmation.d.ts","sourceRoot":"","sources":["../../src/sources/bridge-affirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,MAAM,CAAA;AACb,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,MAAM,MAAM,8BAA8B,GAAG;IAC3C,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAA;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAWD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,8BAA8B,KACtC,aAAa,CAAC,OAAO,CAsBvB,CAAA"}

package/dist/sources/bridge-affirmation.js

@@ -0,0 +1,38 @@
+import { getAbiItem, parseAbi, parseEventLogs, } from 'viem';
+const bridgeAbi = parseAbi([
+    'event AffirmationCompleted(address sender, address executor, bytes32 messageId, bool status)',
+]);
+const transferAbi = parseAbi([
+    'event Transfer(address indexed from, address indexed to, uint256 amount)',
+    'event Mint(address indexed to, uint256 amount)',
+]);
+/**
+ * Watches an Arbitrary Message Bridge for completed affirmations and yields the
+ * recipient of the most recent bridged transfer (zero or one address per poll).
+ * Reads at the finalized block, so results are reorg-safe.
+ */
+export const bridgeAffirmationSource = (options) => {
+    const lookback = options.lookback ?? 1000n;
+    return {
+        poll: async (context) => {
+            const provider = context.publicClient;
+            const finalized = await provider.getBlock({ blockTag: 'finalized' });
+            const logs = await provider.getLogs({
+                address: options.bridgeAddress,
+                event: getAbiItem({ abi: bridgeAbi, name: 'AffirmationCompleted' }),
+                fromBlock: finalized.number - lookback,
+                toBlock: finalized.number,
+            });
+            if (logs.length === 0)
+                return [];
+            const latestTx = logs[logs.length - 1].transactionHash;
+            const receipt = await provider.getTransactionReceipt({ hash: latestTx });
+            const transfers = parseEventLogs({ abi: transferAbi, logs: receipt.logs });
+            const recipient = transfers
+                .map((event) => ('to' in event.args ? event.args.to : undefined))
+                .find((address) => Boolean(address));
+            return recipient ? [recipient] : [];
+        },
+    };
+};
+//# sourceMappingURL=bridge-affirmation.js.map

package/dist/sources/bridge-affirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-affirmation.js","sourceRoot":"","sources":["../../src/sources/bridge-affirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,UAAU,EACV,QAAQ,EACR,cAAc,GACf,MAAM,MAAM,CAAA;AAUb,MAAM,SAAS,GAAG,QAAQ,CAAC;IACzB,8FAA8F;CAC/F,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,QAAQ,CAAC;IAC3B,0EAA0E;IAC1E,gDAAgD;CACjD,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,OAAuC,EACf,EAAE;IAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAM,CAAA;IAC3C,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,YAA4B,CAAA;YACrD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAA;YACpE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;gBAClC,OAAO,EAAE,OAAO,CAAC,aAAa;gBAC9B,KAAK,EAAE,UAAU,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;gBACnE,SAAS,EAAE,SAAS,CAAC,MAAM,GAAG,QAAQ;gBACtC,OAAO,EAAE,SAAS,CAAC,MAAM;aAC1B,CAAC,CAAA;YACF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,eAAsB,CAAA;YAC7D,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAA;YACxE,MAAM,SAAS,GAAG,cAAc,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;YAC1E,MAAM,SAAS,GAAG,SAAS;iBACxB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,KAAK,CAAC,IAAI,CAAC,EAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;iBAC7E,IAAI,CAAC,CAAC,OAAO,EAAsB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;YAC1D,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QACrC,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/sources/generated.d.ts

@@ -0,0 +1,4 @@
+import type { RelayerContext, RelayerSource } from '../types.js';
+/** A source that produces exactly one fresh item per poll. For producers like spam writers. */
+export declare const generatedSource: <T>(produce: (context: RelayerContext) => T | Promise<T>) => RelayerSource<T>;
+//# sourceMappingURL=generated.d.ts.map

package/dist/sources/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/sources/generated.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhE,+FAA+F;AAC/F,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,SAAS,CAAC,OAAO,EAAE,cAAc,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KACnD,aAAa,CAAC,CAAC,CAEhB,CAAA"}

package/dist/sources/generated.js

@@ -0,0 +1,5 @@
+/** A source that produces exactly one fresh item per poll. For producers like spam writers. */
+export const generatedSource = (produce) => ({
+    poll: async (context) => [await produce(context)],
+});
+//# sourceMappingURL=generated.js.map

package/dist/sources/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../../src/sources/generated.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAoD,EAClC,EAAE,CAAC,CAAC;IACtB,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD,CAAC,CAAA"}

package/dist/sources/msgboard-content.d.ts

@@ -0,0 +1,9 @@
+import type { RPCMessage } from '@msgboard/sdk';
+import type { RelayerSource } from '../types.js';
+export type MsgboardContentSourceOptions = {
+    /** A category name (zero-padded to bytes32) or bytes32 hex. Omit to watch all categories. */
+    category?: string;
+};
+/** Polls msgboard content. With no category, flattens messages across every category. */
+export declare const msgboardContentSource: (options?: MsgboardContentSourceOptions) => RelayerSource<RPCMessage>;
+//# sourceMappingURL=msgboard-content.d.ts.map

package/dist/sources/msgboard-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgboard-content.d.ts","sourceRoot":"","sources":["../../src/sources/msgboard-content.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,MAAM,MAAM,4BAA4B,GAAG;IACzC,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAQD,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,GAChC,UAAS,4BAAiC,KACzC,aAAa,CAAC,UAAU,CAS1B,CAAA"}

package/dist/sources/msgboard-content.js

@@ -0,0 +1,19 @@
+import { stringToHex } from 'viem';
+/** Normalizes a category name or hex into a bytes32 hex category. */
+const toCategoryHex = (category) => {
+    if (category.startsWith('0x') && category.length === 66)
+        return category;
+    return stringToHex(category, { size: 32 });
+};
+/** Polls msgboard content. With no category, flattens messages across every category. */
+export const msgboardContentSource = (options = {}) => {
+    const category = options.category ? toCategoryHex(options.category) : undefined;
+    return {
+        poll: async (context) => {
+            const content = await context.client.content(category ? { category } : {});
+            const groups = Object.values(content);
+            return groups.flat();
+        },
+    };
+};
+//# sourceMappingURL=msgboard-content.js.map

package/dist/sources/msgboard-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgboard-content.js","sourceRoot":"","sources":["../../src/sources/msgboard-content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,WAAW,EAAE,MAAM,MAAM,CAAA;AAS5C,qEAAqE;AACrE,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAO,EAAE;IAC9C,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,QAAe,CAAA;IAC/E,OAAO,WAAW,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;AAC5C,CAAC,CAAA;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,UAAwC,EAAE,EACf,EAAE;IAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC/E,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACtB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YACrC,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;QACtB,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/stores/memory-ttl.d.ts

@@ -0,0 +1,11 @@
+import type { RelayerStore } from '../types.js';
+export type MemoryTtlStoreOptions = {
+    /** How long a remembered key stays known, in milliseconds. */
+    ttlMs: number;
+};
+/**
+ * An in-memory dedup store that forgets a key after `ttlMs`. Doubles as a
+ * per-key rate limiter. State is process-local and lost on restart.
+ */
+export declare const memoryTtlStore: <T>(options: MemoryTtlStoreOptions) => RelayerStore<T>;
+//# sourceMappingURL=memory-ttl.d.ts.map

package/dist/stores/memory-ttl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-ttl.d.ts","sourceRoot":"","sources":["../../src/stores/memory-ttl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,SAAS,qBAAqB,KAAG,YAAY,CAAC,CAAC,CAoBhF,CAAA"}

package/dist/stores/memory-ttl.js

@@ -0,0 +1,29 @@
+/**
+ * An in-memory dedup store that forgets a key after `ttlMs`. Doubles as a
+ * per-key rate limiter. State is process-local and lost on restart.
+ */
+export const memoryTtlStore = (options) => {
+    const seenAt = new Map();
+    const isLive = (timestamp) => Date.now() - timestamp <= options.ttlMs;
+    return {
+        has: async (key) => {
+            const at = seenAt.get(key);
+            if (at === undefined)
+                return false;
+            if (isLive(at))
+                return true;
+            seenAt.delete(key);
+            return false;
+        },
+        remember: async (key) => {
+            seenAt.set(key, Date.now());
+        },
+        prune: async () => {
+            for (const [key, at] of seenAt) {
+                if (!isLive(at))
+                    seenAt.delete(key);
+            }
+        },
+    };
+};
+//# sourceMappingURL=memory-ttl.js.map

package/dist/stores/memory-ttl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-ttl.js","sourceRoot":"","sources":["../../src/stores/memory-ttl.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAI,OAA8B,EAAmB,EAAE;IACnF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,OAAO,CAAC,KAAK,CAAA;IACtF,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjB,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC1B,IAAI,EAAE,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAA;YAClC,IAAI,MAAM,CAAC,EAAE,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC3B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAClB,OAAO,KAAK,CAAA;QACd,CAAC;QACD,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACtB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QAC7B,CAAC;QACD,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;gBAC/B,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/stores/noop.d.ts

@@ -0,0 +1,4 @@
+import type { RelayerStore } from '../types.js';
+/** A dedup store that never deduplicates — for producers that intend to repost. */
+export declare const noopStore: <T>() => RelayerStore<T>;
+//# sourceMappingURL=noop.d.ts.map

package/dist/stores/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/stores/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,mFAAmF;AACnF,eAAO,MAAM,SAAS,GAAI,CAAC,OAAK,YAAY,CAAC,CAAC,CAG5C,CAAA"}

package/dist/stores/noop.js

@@ -0,0 +1,6 @@
+/** A dedup store that never deduplicates — for producers that intend to repost. */
+export const noopStore = () => ({
+    has: async () => false,
+    remember: async () => { },
+});
+//# sourceMappingURL=noop.js.map

package/dist/stores/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../src/stores/noop.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAuB,EAAE,CAAC,CAAC;IAClD,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK;IACtB,QAAQ,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;CACzB,CAAC,CAAA"}

package/dist/stores/postgres.d.ts

@@ -0,0 +1,19 @@
+import type { RelayerStore } from '../types.js';
+/** The minimal database surface the Postgres store needs (a `pg.Pool` satisfies it). */
+export type Queryable = {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+};
+export type PostgresStoreOptions = {
+    pool: Queryable;
+    /** Table name for the dedup rows. */
+    table: string;
+    /** Rows older than this are removed by `prune`, in milliseconds. */
+    maxAgeMs: number;
+};
+/** A durable dedup store backed by a Postgres table. Call `migrate()` once at startup. */
+export declare const postgresStore: <T>(options: PostgresStoreOptions) => RelayerStore<T> & {
+    migrate(): Promise<void>;
+};
+//# sourceMappingURL=postgres.d.ts.map

package/dist/stores/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/stores/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,aAAa,CAAA;AAE7D,wFAAwF;AACxF,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,oBAAoB,GAAG;IACjC,IAAI,EAAE,SAAS,CAAA;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,SAAS,oBAAoB,KAC5B,YAAY,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CA8B9C,CAAA"}

package/dist/stores/postgres.js

@@ -0,0 +1,26 @@
+/** A durable dedup store backed by a Postgres table. Call `migrate()` once at startup. */
+export const postgresStore = (options) => {
+    const { pool, table } = options;
+    const maxAgeSeconds = Math.floor(options.maxAgeMs / 1000);
+    return {
+        migrate: async () => {
+            await pool.query(`CREATE TABLE IF NOT EXISTS ${table} (
+          key TEXT PRIMARY KEY,
+          ref TEXT,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )`);
+        },
+        has: async (key) => {
+            const { rows } = await pool.query(`SELECT key FROM ${table} WHERE key = $1 LIMIT 1`, [key]);
+            return rows.length > 0;
+        },
+        remember: async (key, result) => {
+            await pool.query(`INSERT INTO ${table} (key, ref) VALUES ($1, $2)
+         ON CONFLICT (key) DO UPDATE SET ref = $2`, [key, result.ref ?? null]);
+        },
+        prune: async () => {
+            await pool.query(`DELETE FROM ${table} WHERE created_at < now() - INTERVAL '${maxAgeSeconds} seconds'`);
+        },
+    };
+};
+//# sourceMappingURL=postgres.js.map

package/dist/stores/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/stores/postgres.ts"],"names":[],"mappings":"AAeA,0FAA0F;AAC1F,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,OAA6B,EACmB,EAAE;IAClD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAC/B,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IACzD,OAAO;QACL,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,IAAI,CAAC,KAAK,CACd,8BAA8B,KAAK;;;;UAIjC,CACH,CAAA;QACH,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,mBAAmB,KAAK,yBAAyB,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;YAC3F,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;QACxB,CAAC;QACD,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAoB,EAAE,EAAE;YAC5C,MAAM,IAAI,CAAC,KAAK,CACd,eAAe,KAAK;kDACsB,EAC1C,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,CAC1B,CAAA;QACH,CAAC;QACD,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,IAAI,CAAC,KAAK,CACd,eAAe,KAAK,yCAAyC,aAAa,WAAW,CACtF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+import type { MsgBoardClient } from '@msgboard/sdk';
+import type { Chain, PublicClient } from 'viem';
+import type { Logger } from './logger.js';
+/** The two operating modes. `observe` never produces an outbound side effect. */
+export type RelayerMode = 'observe' | 'live';
+/** Identifies the msgboard node a relayer watches. */
+export type RelayerNode = {
+    /** The JSON-RPC URL of the msgboard node. */
+    rpcUrl: string;
+    /** The chain id of the node (1, 369, or 943). */
+    chainId: number;
+};
+/** Everything a source, action, or sink may need at runtime. */
+export type RelayerContext = {
+    node: RelayerNode;
+    mode: RelayerMode;
+    chain: Chain;
+    /** A viem public client over `node.rpcUrl`. */
+    publicClient: PublicClient;
+    /** A msgboard SDK client wrapping `publicClient`. */
+    client: MsgBoardClient;
+    logger: Logger;
+};
+/** The outcome of a live action. */
+export type ActionResult = {
+    /** True if the action's effect succeeded. */
+    ok: boolean;
+    /** An identifying reference, e.g. a transaction hash or message hash. */
+    ref?: string;
+    /** Optional structured detail for logging or storage. */
+    meta?: Record<string, unknown>;
+};
+/** Reads the current batch of candidate items from the watched pool. */
+export type RelayerSource<T> = {
+    poll(context: RelayerContext): Promise<readonly T[]>;
+};
+/** A side-effecting operation, split so observe mode can describe without doing. */
+export type RelayerAction<T> = {
+    /** Pure description of the intended effect; used for observe-mode logging. */
+    describe(item: T, context: RelayerContext): string;
+    /** The real outbound effect; only ever called in live mode. */
+    execute(item: T, context: RelayerContext): Promise<ActionResult>;
+};
+/** Action-level idempotency: "have I already acted on this?". Short retention. */
+export type RelayerStore<_T> = {
+    has(key: string): Promise<boolean>;
+    remember(key: string, result: ActionResult): Promise<void>;
+    prune?(): Promise<void>;
+};
+/** Unconditional recording for history/observability. Long retention. Runs in BOTH modes. */
+export type RelayerSink<T> = {
+    record(item: T, context: RelayerContext): Promise<void>;
+    prune?(): Promise<void>;
+};
+/** Derives a stable dedup key for an item. */
+export type RelayerKey<T> = (item: T) => string;
+/** Decides whether a candidate should be acted on, beyond dedup. */
+export type RelayerCondition<T> = (item: T, context: RelayerContext) => boolean | Promise<boolean>;
+/** Construction options for a Relayer. */
+export type RelayerConfig<T> = {
+    node: RelayerNode;
+    /** Safety switch. Defaults to 'observe' — performs no outbound side effect. */
+    mode?: RelayerMode;
+    /** Poll cadence in milliseconds. Defaults to 30_000. */
+    intervalMs?: number;
+    source: RelayerSource<T>;
+    action: RelayerAction<T>;
+    key: RelayerKey<T>;
+    /** Action-level dedup. Defaults to an in-memory time-to-live store. */
+    store?: RelayerStore<T>;
+    /** Historical recording; runs in observe and live modes. */
+    sink?: RelayerSink<T>;
+    condition?: RelayerCondition<T>;
+    logger?: Logger;
+    /** Run `store.prune` / `sink.prune` every N ticks. Defaults to 30. */
+    pruneEveryTicks?: number;
+};
+/** What happened during one tick — returned by `runOnce()` for tests and one-shots. */
+export type TickReport = {
+    /** Total items polled from the source. */
+    polled: number;
+    /** Items recorded to the sink. */
+    recorded: number;
+    /** Items that passed the condition and were not deduped. */
+    eligible: number;
+    /** Items whose action executed (live mode only). */
+    executed: number;
+    /** Items whose action was only described (observe mode). */
+    described: number;
+    /** Items skipped by the dedup store. */
+    deduped: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@msgboard/relayer",
+  "version": "0.0.1",
+  "description": "Controllable, safe-by-default pool-watcher relayer for the msgboard board",
+  "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": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": ["msgboard", "relayer", "pool-watcher", "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.28",
+    "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"
+  }
+}