@gibs/bridge-indexer 1.13.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Gibs Finance
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @gibs/bridge-indexer
+
+Reads a Gibs Finance bridge indexer. It gives you the transfer archive, delivery receipts, and live crossing status. It only reads. It never signs or broadcasts.
+
+## Endpoint
+
+The package reads `https://next-indexer.gibs.finance` by default. This is the owner's choice "for now". The next indexer follows the current schema.
+
+Importing the package has no side effects. The package creates its GraphQL client on first use.
+
+To read another indexer, call `setIndexerEndpoint` before the first query:
+
+```ts
+import { setIndexerEndpoint, indexerEndpoint, DEFAULT_INDEXER_ENDPOINT } from '@gibs/bridge-indexer'
+
+setIndexerEndpoint('http://localhost:42069/graphql')
+indexerEndpoint() // the address now in force
+```
+
+The indexer serves GraphQL at `/` and at `/graphql`. It serves `GET /version` with the indexer package version, the Ponder schema name, and the git commit when the deploy sets `GIT_SHA`. The indexer no longer serves raw SQL.
+
+Production `https://indexer.gibs.finance` may lag the schema in this package. If a query fails there with an unknown field, point the package at the next indexer.
+
+## Known defects in the production data
+
+A batched re-index will fix these. Until it runs, work around them.
+
+- Five relations are always `null`. Do not read them:
+  - `AMBBridge.validatorContract`
+  - `Omnibridge.ambBridge`
+  - `Omnibridge.validatorContract`
+  - `UserRequest.destinationAMBBridge`
+  - `UserRequest.destinationOmnibridge`
+- The joins between a request and its `Completion` or `Delivery` work in one direction only. Query `Completion` or `Delivery` by `messageHash` instead of expecting the join on the request.
+- A message for a native pathway records the ERC-20 omnibridge, not the native one.
+- Read `delivered` (a boolean on the request). Do not read `delivery`. The `delivery` relation can be `null` for a request that landed.
+- Hex filters are lowercase. A checksummed address in a `where` clause matches nothing. Lowercase every address and hash first.
+
+## Units of fee fields
+
+- `FeeUpdate.fee` is a rate. It is a fraction scaled by 1e18. `10n ** 18n` means 100 percent. The amount is `amount * fee / 10n ** 18n`.
+- `UserRequest.feeAmount` is the fee the omnibridge took. It is in base units of the origin token. `null` means no fee log was seen, which in practice means the fee was zero.
+- Read `feeAmount` for the fee actually taken. `feeUpdate.fee` is the rate that was configured at the time. That is a different fact.
+- `BigInt` fields arrive as decimal strings. `Numeric` fields arrive as a number or a string.
+
+## Schema snapshot and codegen
+
+`schema.graphql` is a committed snapshot of the indexer schema. `src/graphql.ts` is generated from it. Codegen never contacts a live host.
+
+| Script | What it does |
+| --- | --- |
+| `yarn codegen` | Regenerates `src/graphql.ts` from `schema.graphql`. Offline. |
+| `yarn schema:update` | Introspects the live next indexer and rewrites `schema.graphql`. |
+| `yarn schema:check` | Exits 1 when the live schema differs from the snapshot. Not run in continuous integration. Run it by hand before a release. |
+
+To follow a schema change, run `yarn schema:update`, then `yarn codegen`, then the tests. A test fails when the snapshot and the generated types disagree. A schema change cannot ship without regenerating.
+
+`schema:update` and `schema:check` accept an address as a second word, for example `node scripts/schema-snapshot.mjs check https://indexer.gibs.finance/graphql`.
+
+## License
+
+ISC. See `LICENSE`.

package/dist/bridge-status.d.ts

@@ -0,0 +1,58 @@
+import type { BridgeKey } from '@gibs/bridge-sdk/types';
+import type { Block, Hex } from 'viem';
+export declare const bridgeStatuses: {
+    readonly SUBMITTED: "SUBMITTED";
+    readonly MINED: "MINED";
+    readonly FINALIZED: "FINALIZED";
+    readonly VALIDATING: "VALIDATING";
+    readonly AFFIRMED: "AFFIRMED";
+    readonly DELIVERED: "DELIVERED";
+};
+export type BridgeStatus = keyof typeof bridgeStatuses;
+export type LiveBridgeStatusParams = {
+    hash: Hex;
+    ticker: Block;
+    bridgeKey: BridgeKey;
+};
+export type ContinuedLiveBridgeStatusParams = LiveBridgeStatusParams & {
+    status: BridgeStatus;
+    statusIndex: number;
+    receipt?: {
+        blockNumber: bigint;
+        transactionHash: Hex;
+    };
+    finalizedBlock: {
+        number: bigint;
+    };
+    messageId?: Hex;
+    deliveredHash?: Hex;
+    count?: number;
+    requiredSignatures?: number | null;
+    /** null = main bridge; 'gas+' | 'fixed' | 'percentage' = gibs-routed */
+    deliveryType?: string | null;
+    /**
+     * The fields a manual release needs to build its calldata, present only
+     * once the live poll has resolved a `messageId` (stage two). A history row
+     * replayed through `createBridgeStatusFromHistory` never sets these — that
+     * path only feeds `bridgeETA.calculateETA`, which reads `status` alone.
+     */
+    release?: {
+        requestType: string;
+        encodedData: Hex;
+        signatures: string[];
+        destinationAmbAddress: Hex;
+    };
+};
+/**
+ * The ordered list of bridge statuses, mirroring insertion order of
+ * {@link bridgeStatuses}. Its index positions encode lifecycle progression so a
+ * later status compares greater than an earlier one.
+ */
+export declare const statusList: ("SUBMITTED" | "MINED" | "FINALIZED" | "VALIDATING" | "AFFIRMED" | "DELIVERED")[];
+/**
+ * Returns the lifecycle position of a bridge status within {@link statusList}.
+ * Used to compare two statuses by progression rather than by name.
+ * @param status - the status to locate
+ * @returns the zero-based index of the status, or -1 when unknown
+ */
+export declare const statusToIndex: (status: BridgeStatus) => number;

package/dist/bridge-status.js

@@ -0,0 +1,23 @@
+export const bridgeStatuses = {
+    SUBMITTED: 'SUBMITTED',
+    MINED: 'MINED',
+    FINALIZED: 'FINALIZED',
+    VALIDATING: 'VALIDATING',
+    AFFIRMED: 'AFFIRMED',
+    DELIVERED: 'DELIVERED',
+};
+/**
+ * The ordered list of bridge statuses, mirroring insertion order of
+ * {@link bridgeStatuses}. Its index positions encode lifecycle progression so a
+ * later status compares greater than an earlier one.
+ */
+export const statusList = Object.values(bridgeStatuses);
+/**
+ * Returns the lifecycle position of a bridge status within {@link statusList}.
+ * Used to compare two statuses by progression rather than by name.
+ * @param status - the status to locate
+ * @returns the zero-based index of the status, or -1 when unknown
+ */
+export const statusToIndex = (status) => {
+    return statusList.indexOf(status);
+};

package/dist/endpoint.d.ts

@@ -0,0 +1,49 @@
+import { GraphQLClient } from 'graphql-request';
+/**
+ * WHICH INDEXER THIS PACKAGE READS, AND HOW A CONSUMER CHANGES IT.
+ *
+ * The interface this code came from held the address as a build-time constant
+ * substituted at bundle time, which is the right shape for one application and
+ * the wrong shape for a library: a package cannot be rebuilt per consumer, and
+ * somebody running against their own indexer, a fork, or a local Ponder has no
+ * way to say so.
+ *
+ * So the address is state with a setter rather than a constant. ONE client is
+ * held rather than one per call because `GraphQLClient` is a thin wrapper whose
+ * construction is not free, and every query in this package goes to the same
+ * host.
+ *
+ * THE DEFAULT IS THE NEXT INDEXER, "for now" (owner decision), so a consumer who
+ * configures nothing still reads real data rather than failing against an empty
+ * address. It tracks the current schema; production `indexer.gibs.finance` may
+ * lag it.
+ *
+ * NOTHING RUNS AT MODULE LOAD. The client is created on first use, so importing
+ * this package has no side effects.
+ */
+export declare const DEFAULT_INDEXER_ENDPOINT = "https://next-indexer.gibs.finance";
+/**
+ * Points this package at an indexer.
+ *
+ * Call it once, before any query. Calling it again drops the cached client, which
+ * abandons nothing — a request already in flight keeps the client that issued
+ * it and settles normally.
+ *
+ * Returns early on an unchanged address so a consumer may call this from a
+ * render or an effect without discarding a warm client on every pass.
+ *
+ * @param url - the indexer's GraphQL address.
+ */
+export declare const setIndexerEndpoint: (url: string) => void;
+/** The indexer address currently in force. */
+export declare const indexerEndpoint: () => string;
+/**
+ * The client every query in this package uses.
+ *
+ * A FUNCTION RATHER THAN THE CLIENT ITSELF, so a module that imports this at
+ * load time still sees a later {@link setIndexerEndpoint}. Exporting the value
+ * would freeze whichever host happened to be configured at the moment the
+ * importing module was first evaluated — which, for a consumer that configures
+ * the address during startup, is reliably the wrong one.
+ */
+export declare const indexerClient: () => GraphQLClient;

package/dist/endpoint.js

@@ -0,0 +1,59 @@
+import { GraphQLClient } from 'graphql-request';
+/**
+ * WHICH INDEXER THIS PACKAGE READS, AND HOW A CONSUMER CHANGES IT.
+ *
+ * The interface this code came from held the address as a build-time constant
+ * substituted at bundle time, which is the right shape for one application and
+ * the wrong shape for a library: a package cannot be rebuilt per consumer, and
+ * somebody running against their own indexer, a fork, or a local Ponder has no
+ * way to say so.
+ *
+ * So the address is state with a setter rather than a constant. ONE client is
+ * held rather than one per call because `GraphQLClient` is a thin wrapper whose
+ * construction is not free, and every query in this package goes to the same
+ * host.
+ *
+ * THE DEFAULT IS THE NEXT INDEXER, "for now" (owner decision), so a consumer who
+ * configures nothing still reads real data rather than failing against an empty
+ * address. It tracks the current schema; production `indexer.gibs.finance` may
+ * lag it.
+ *
+ * NOTHING RUNS AT MODULE LOAD. The client is created on first use, so importing
+ * this package has no side effects.
+ */
+export const DEFAULT_INDEXER_ENDPOINT = 'https://next-indexer.gibs.finance';
+let endpoint = DEFAULT_INDEXER_ENDPOINT;
+let client = null;
+/**
+ * Points this package at an indexer.
+ *
+ * Call it once, before any query. Calling it again drops the cached client, which
+ * abandons nothing — a request already in flight keeps the client that issued
+ * it and settles normally.
+ *
+ * Returns early on an unchanged address so a consumer may call this from a
+ * render or an effect without discarding a warm client on every pass.
+ *
+ * @param url - the indexer's GraphQL address.
+ */
+export const setIndexerEndpoint = (url) => {
+    if (url === endpoint)
+        return;
+    endpoint = url;
+    client = null;
+};
+/** The indexer address currently in force. */
+export const indexerEndpoint = () => endpoint;
+/**
+ * The client every query in this package uses.
+ *
+ * A FUNCTION RATHER THAN THE CLIENT ITSELF, so a module that imports this at
+ * load time still sees a later {@link setIndexerEndpoint}. Exporting the value
+ * would freeze whichever host happened to be configured at the moment the
+ * importing module was first evaluated — which, for a consumer that configures
+ * the address during startup, is reliably the wrong one.
+ */
+export const indexerClient = () => {
+    client ??= new GraphQLClient(endpoint);
+    return client;
+};