@xyo-network/event-kit-xl1 0.0.1

package/README.md

@@ -0,0 +1,42 @@
+# `@xyo-network/event-kit-xl1`
+
+XL1 chain adapters for Event Kit.
+
+- `createXl1FinalizedHeadSource` — reads the finalized XL1 head for publisher
+  filters and for the receiver's grant-freshness check
+
+```ts
+const gateway = await new GatewayBuilder().name('local').rpcUrl(RPC).build()
+const headSource = createXl1FinalizedHeadSource({ viewer: gateway.connection.viewer })
+```
+
+The result satisfies both the publisher's `FinalizedHeadSource` and the
+receiver's `TrustedFinalizedHeadSource` — structurally identical ports, declared
+locally so this package depends on neither.
+
+## Why it validates rather than forwards
+
+Both sides treat this number as trusted: the publisher decides which range to
+emit, and the gate computes grant lag from it. So the reading is checked, not
+passed through.
+
+- A head that is not a nonnegative JSON safe integer is rejected here, rather
+  than surfacing later as an opaque `grant-view-invalid`.
+- A head lower than one already observed is rejected by default. Finalized
+  heights are immutable, so a regression means the endpoint was rolled back,
+  swapped, or is lying — failing closed beats admitting against a rewound view.
+  Disable with `rejectRegression: false` only when a caller genuinely tolerates
+  it.
+
+## Evidence
+
+Offline specs cover the validation and regression guard. Live specs under
+`src/spec/api-local/` run against a real local XL1 chain booted by the
+`api-local` vitest project: the head reads conforming, advances through real
+block production, and never regresses.
+
+Run them with `pnpm test:live` from the repository root. They are opt-in — the
+default suite stays offline.
+
+This qualifies the adapter against a local dev chain, which uses simplified dev
+consensus and in-memory storage. It is not Sequence or mainnet qualification.

package/dist/neutral/finalizedHeadSource.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structural shape shared by the publisher's `FinalizedHeadSource` and the
+ * receiver's `TrustedFinalizedHeadSource`. Declared here so this adapter depends
+ * on neither package.
+ */
+export interface FinalizedHeadReader {
+    headNumber: () => Promise<number>;
+}
+/** The slice of the XL1 viewer this adapter reads. */
+export interface Xl1FinalizationViewer {
+    readonly finalization: {
+        headNumber: () => Promise<number>;
+    };
+}
+export interface Xl1FinalizedHeadSourceOptions {
+    /**
+     * Reject a head lower than one already observed.
+     *
+     * Finalized heights are immutable, so a regression means the endpoint was
+     * rolled back, swapped, or is lying. Defaults to `true`: admission and cursor
+     * decisions both treat this value as trusted, and failing closed is safer than
+     * admitting against a rewound view.
+     */
+    readonly rejectRegression?: boolean;
+    readonly viewer: Xl1FinalizationViewer;
+}
+/**
+ * Reads the finalized XL1 head for publisher filters and receiver grant
+ * freshness.
+ *
+ * The value is validated rather than forwarded: D-002 requires nonnegative JSON
+ * safe integers for every head input, and a non-conforming reading is rejected
+ * here instead of surfacing later as an opaque `grant-view-invalid`.
+ */
+export declare function createXl1FinalizedHeadSource(options: Xl1FinalizedHeadSourceOptions): FinalizedHeadReader;
+//# sourceMappingURL=finalizedHeadSource.d.ts.map

package/dist/neutral/finalizedHeadSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalizedHeadSource.d.ts","sourceRoot":"","sources":["../../src/finalizedHeadSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAClC;AAED,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE;QAAE,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAA;CAC7D;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,mBAAmB,CAiBrB"}

package/dist/neutral/index.d.ts

@@ -0,0 +1,3 @@
+export type { FinalizedHeadReader, Xl1FinalizationViewer, Xl1FinalizedHeadSourceOptions, } from './finalizedHeadSource.ts';
+export { createXl1FinalizedHeadSource } from './finalizedHeadSource.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/neutral/index.mjs

@@ -0,0 +1,22 @@
+// src/finalizedHeadSource.ts
+function createXl1FinalizedHeadSource(options) {
+  const rejectRegression = options.rejectRegression ?? true;
+  let highest = -1;
+  return {
+    async headNumber() {
+      const head = await options.viewer.finalization.headNumber();
+      if (typeof head !== "number" || !Number.isSafeInteger(head) || head < 0) {
+        throw new TypeError(`XL1 finalized head must be a nonnegative safe integer, received ${String(head)}`);
+      }
+      if (rejectRegression && head < highest) {
+        throw new RangeError(`XL1 finalized head regressed from ${highest} to ${head}`);
+      }
+      if (head > highest) highest = head;
+      return head;
+    }
+  };
+}
+export {
+  createXl1FinalizedHeadSource
+};
+//# sourceMappingURL=index.mjs.map

package/dist/neutral/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/finalizedHeadSource.ts"],
+  "sourcesContent": ["/**\n * Structural shape shared by the publisher's `FinalizedHeadSource` and the\n * receiver's `TrustedFinalizedHeadSource`. Declared here so this adapter depends\n * on neither package.\n */\nexport interface FinalizedHeadReader {\n  headNumber: () => Promise<number>\n}\n\n/** The slice of the XL1 viewer this adapter reads. */\nexport interface Xl1FinalizationViewer {\n  readonly finalization: { headNumber: () => Promise<number> }\n}\n\nexport interface Xl1FinalizedHeadSourceOptions {\n  /**\n   * Reject a head lower than one already observed.\n   *\n   * Finalized heights are immutable, so a regression means the endpoint was\n   * rolled back, swapped, or is lying. Defaults to `true`: admission and cursor\n   * decisions both treat this value as trusted, and failing closed is safer than\n   * admitting against a rewound view.\n   */\n  readonly rejectRegression?: boolean\n  readonly viewer: Xl1FinalizationViewer\n}\n\n/**\n * Reads the finalized XL1 head for publisher filters and receiver grant\n * freshness.\n *\n * The value is validated rather than forwarded: D-002 requires nonnegative JSON\n * safe integers for every head input, and a non-conforming reading is rejected\n * here instead of surfacing later as an opaque `grant-view-invalid`.\n */\nexport function createXl1FinalizedHeadSource(\n  options: Xl1FinalizedHeadSourceOptions,\n): FinalizedHeadReader {\n  const rejectRegression = options.rejectRegression ?? true\n  let highest = -1\n\n  return {\n    async headNumber(): Promise<number> {\n      const head = await options.viewer.finalization.headNumber()\n      if (typeof head !== 'number' || !Number.isSafeInteger(head) || head < 0) {\n        throw new TypeError(`XL1 finalized head must be a nonnegative safe integer, received ${String(head)}`)\n      }\n      if (rejectRegression && head < highest) {\n        throw new RangeError(`XL1 finalized head regressed from ${highest} to ${head}`)\n      }\n      if (head > highest) highest = head\n      return head\n    },\n  }\n}\n"],
+  "mappings": ";AAmCO,SAAS,6BACd,SACqB;AACrB,QAAM,mBAAmB,QAAQ,oBAAoB;AACrD,MAAI,UAAU;AAEd,SAAO;AAAA,IACL,MAAM,aAA8B;AAClC,YAAM,OAAO,MAAM,QAAQ,OAAO,aAAa,WAAW;AAC1D,UAAI,OAAO,SAAS,YAAY,CAAC,OAAO,cAAc,IAAI,KAAK,OAAO,GAAG;AACvE,cAAM,IAAI,UAAU,mEAAmE,OAAO,IAAI,CAAC,EAAE;AAAA,MACvG;AACA,UAAI,oBAAoB,OAAO,SAAS;AACtC,cAAM,IAAI,WAAW,qCAAqC,OAAO,OAAO,IAAI,EAAE;AAAA,MAChF;AACA,UAAI,OAAO,QAAS,WAAU;AAC9B,aAAO;AAAA,IACT;AAAA,EACF;AACF;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@xyo-network/event-kit-xl1",
+  "version": "0.0.1",
+  "description": "XL1 chain adapters for Event Kit (finalized head source)",
+  "keywords": [
+    "xyo",
+    "xl1",
+    "event-kit",
+    "typescript"
+  ],
+  "bugs": {
+    "url": "https://github.com/XYOracleNetwork/event-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XYOracleNetwork/event-kit.git",
+    "directory": "packages/xl1"
+  },
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/neutral/index.d.ts",
+      "default": "./dist/neutral/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./README.md": "./README.md"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@ariestools/lib-neutral": "~9.1.0",
+    "@ariestools/sdk": "~8.1.9",
+    "@ariestools/toolchain": "~9.1.0",
+    "@ariestools/tsconfig": "~9.1.0",
+    "@opentelemetry/api": "~1.9.1",
+    "@xyo-network/sdk": "~7.2.3",
+    "@xyo-network/sdk-protocol": "~7.2.4",
+    "@xyo-network/xl1-sdk": "~5.3.1",
+    "async-mutex": "~0.5.0",
+    "eslint": "~10.8.1",
+    "eslint-import-resolver-typescript": "~4.4.5",
+    "ethers": "~6.17.0",
+    "typescript": "~6.0.3",
+    "vite": "~8.2.1",
+    "vitest": "~4.1.11",
+    "zod": "~4.4.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}