@gibs/bridge-indexer 1.13.0

package/dist/graphql.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reads a Gibs Finance bridge indexer.
+ *
+ * WHAT THIS PACKAGE IS FOR. The bridge's quote maths, chain metadata, ABIs and
+ * transaction building have been publishable for a long time; the ability to
+ * ask what happened to a transfer has not. That half lived inside the interface
+ * — and, independently, inside a second, older interface — so anybody building
+ * on the bridge could construct a crossing and then had no supported way to
+ * find out whether it landed. This package is that missing half.
+ *
+ * WHAT IT DOES NOT DO. It reads. Nothing here signs, broadcasts, or holds a
+ * wallet, and nothing here renders. A transfer's status arrives as data — a
+ * record, a count of affirmations, a delivery flag — and the words a person
+ * reads are the consumer's to choose, because a library cannot own somebody
+ * else's message catalogue.
+ *
+ * Point it somewhere with {@link setIndexerEndpoint} before the first query; it
+ * defaults to the next indexer (https://next-indexer.gibs.finance).
+ */
+export { DEFAULT_INDEXER_ENDPOINT, indexerClient, indexerEndpoint, setIndexerEndpoint } from './endpoint.js';
+export { bridgeStatuses, statusList, statusToIndex, type BridgeStatus, type ContinuedLiveBridgeStatusParams, type LiveBridgeStatusParams, } from './bridge-status.js';
+export { buildBridgeFilter, fetchBridgeTransactions, fetchDeliveredMessageHashes, forgetDeliveredMessageHashes, loadTokenMetadataForBridges, peekDeliveredMessageHashes, type BridgeData, type BridgeFilterMode, type DeliveredMessageHashes, type FeeData, type LoadBridgesParams, } from './transfers.js';
+export { liveBridgeStatusStageOne, liveBridgeStatusStageTwo } from './live-status.js';
+export type { UserRequest, UserRequestFilter } from './graphql.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Reads a Gibs Finance bridge indexer.
+ *
+ * WHAT THIS PACKAGE IS FOR. The bridge's quote maths, chain metadata, ABIs and
+ * transaction building have been publishable for a long time; the ability to
+ * ask what happened to a transfer has not. That half lived inside the interface
+ * — and, independently, inside a second, older interface — so anybody building
+ * on the bridge could construct a crossing and then had no supported way to
+ * find out whether it landed. This package is that missing half.
+ *
+ * WHAT IT DOES NOT DO. It reads. Nothing here signs, broadcasts, or holds a
+ * wallet, and nothing here renders. A transfer's status arrives as data — a
+ * record, a count of affirmations, a delivery flag — and the words a person
+ * reads are the consumer's to choose, because a library cannot own somebody
+ * else's message catalogue.
+ *
+ * Point it somewhere with {@link setIndexerEndpoint} before the first query; it
+ * defaults to the next indexer (https://next-indexer.gibs.finance).
+ */
+export { DEFAULT_INDEXER_ENDPOINT, indexerClient, indexerEndpoint, setIndexerEndpoint } from './endpoint.js';
+export { bridgeStatuses, statusList, statusToIndex, } from './bridge-status.js';
+export { buildBridgeFilter, fetchBridgeTransactions, fetchDeliveredMessageHashes, forgetDeliveredMessageHashes, loadTokenMetadataForBridges, peekDeliveredMessageHashes, } from './transfers.js';
+export { liveBridgeStatusStageOne, liveBridgeStatusStageTwo } from './live-status.js';

package/dist/live-status.d.ts

@@ -0,0 +1,18 @@
+import { type ContinuedLiveBridgeStatusParams, type LiveBridgeStatusParams } from './bridge-status.js';
+/** Clears the in-memory indexer cache. Exported for test isolation. */
+export declare const _clearLiveBridgeStatusCache: () => void;
+/**
+ * Stage one of the live bridge-status pipeline. Reads the origination receipt
+ * to decide between SUBMITTED (not yet mined) and MINED (receipt available).
+ * @param params - the hash, ticker block, and bridge key to inspect
+ * @returns the params extended with the resolved status (and receipt when mined)
+ */
+export declare const liveBridgeStatusStageOne: (params: LiveBridgeStatusParams) => Promise<ContinuedLiveBridgeStatusParams>;
+/**
+ * Stage two of the live bridge-status pipeline. Waits for finalization of the
+ * origination receipt, then reads the indexer to advance the status through
+ * FINALIZED, VALIDATING, and AFFIRMED.
+ * @param params - the stage-one output, or null when the pipeline was cleared
+ * @returns the params advanced to its next status, or unchanged when not ready
+ */
+export declare const liveBridgeStatusStageTwo: (params: ContinuedLiveBridgeStatusParams | null) => Promise<ContinuedLiveBridgeStatusParams | null>;

package/dist/live-status.js

@@ -0,0 +1,178 @@
+import { gql } from 'graphql-request';
+import { indexerClient } from './endpoint.js';
+import { clientFromChain } from '@gibs/bridge-client/client';
+import { bridgeStatuses, statusToIndex, } from './bridge-status.js';
+import { Cache } from '@gibs/bridge-client/cache';
+/** Single shared indexer client, mirroring the construction in history.ts. */
+/**
+ * Every request here goes through {@link indexerClient}, which is a FUNCTION
+ * rather than a held client: a consumer configures the address during startup,
+ * and a client captured at module-evaluation time would have frozen the default
+ * before they got the chance.
+ */
+const client = () => indexerClient();
+const liveBridgeStatusQuery = gql `
+  query LiveBridgeStatus($hash: String!) {
+    userRequests(where: { transactionHash: $hash }) {
+      items {
+        messageId
+        confirmedSignatures
+        finishedSigning
+        requiredSignatures {
+          value
+        }
+        delivery {
+          transactionHash
+        }
+        feeDirector {
+          feeType
+        }
+        type
+        encodedData
+        signatures
+        destinationAmbAddress
+      }
+    }
+  }
+`;
+/** Time-to-live cache that collapses identical indexer reads within five seconds. */
+const gqlCache = new Cache(5 * 1_000);
+/** Clears the in-memory indexer cache. Exported for test isolation. */
+export const _clearLiveBridgeStatusCache = () => {
+    gqlCache.cache.clear();
+};
+/**
+ * Requests the live bridge status for an origination transaction hash, reusing
+ * an in-flight or recently resolved promise within the cache time-to-live so
+ * repeated polls of the same hash collapse to a single network read.
+ * @param hash - the origination transaction hash to look up
+ * @returns the indexer's user-request payload for the hash
+ */
+const requestBridgeStatus = (hash) => {
+    const key = JSON.stringify(['live-bridge-status', hash]);
+    const now = gqlCache.clearStale();
+    const cached = gqlCache.cache.get(key);
+    if (cached) {
+        return cached.value;
+    }
+    const result = client().request(liveBridgeStatusQuery, { hash });
+    gqlCache.cache.set(key, { time: now, value: result });
+    return result;
+};
+/**
+ * Stage one of the live bridge-status pipeline. Reads the origination receipt
+ * to decide between SUBMITTED (not yet mined) and MINED (receipt available).
+ * @param params - the hash, ticker block, and bridge key to inspect
+ * @returns the params extended with the resolved status (and receipt when mined)
+ */
+export const liveBridgeStatusStageOne = async (params) => {
+    const { hash, bridgeKey } = params;
+    const [, fromChain] = bridgeKey;
+    const client = clientFromChain(Number(fromChain));
+    const receipt = await client
+        .getTransactionReceipt({
+        hash,
+    })
+        .catch(() => null);
+    if (!receipt) {
+        // transaction has not yet been mined — getTransaction may throw if the node
+        // hasn't propagated it yet (mempool lag), so we catch and still return SUBMITTED
+        await Promise.all([
+            client
+                .getTransaction({ hash })
+                .then((transaction) => {
+                client.getBlock({ blockTag: 'latest' }).then((latest) => {
+                    console.log('transaction has not yet been mined', hash, transaction?.maxFeePerGas ?? transaction?.gasPrice, latest.baseFeePerGas);
+                });
+            })
+                .catch(() => {
+                // transaction not yet visible to this node — normal during mempool propagation
+            }),
+        ]);
+        return {
+            ...params,
+            status: bridgeStatuses.SUBMITTED,
+        };
+    }
+    return {
+        ...params,
+        status: bridgeStatuses.MINED,
+        receipt,
+    };
+};
+/**
+ * Stage two of the live bridge-status pipeline. Waits for finalization of the
+ * origination receipt, then reads the indexer to advance the status through
+ * FINALIZED, VALIDATING, and AFFIRMED.
+ * @param params - the stage-one output, or null when the pipeline was cleared
+ * @returns the params advanced to its next status, or unchanged when not ready
+ */
+export const liveBridgeStatusStageTwo = async (params) => {
+    if (!params)
+        return null;
+    const { status, receipt, bridgeKey } = params;
+    if (statusToIndex(status) < statusToIndex(bridgeStatuses.MINED)) {
+        return params;
+    }
+    const client = clientFromChain(Number(bridgeKey[1]));
+    const finalizedBlock = await client.getBlock({ blockTag: 'finalized' });
+    params.finalizedBlock = finalizedBlock;
+    if (finalizedBlock.number < receipt.blockNumber) {
+        console.log('transaction has been mined, not yet finalized hash=%o current=%o finalized=%o receipt=%o', receipt?.transactionHash, params.ticker.number, finalizedBlock.number, receipt.blockNumber);
+        return params;
+    }
+    const result = await requestBridgeStatus(receipt.transactionHash);
+    const userRequest = result.userRequests.items?.[0];
+    if (!userRequest?.messageId)
+        return params;
+    const count = Number(userRequest.confirmedSignatures ?? 0);
+    const requiredSignatures = userRequest.requiredSignatures?.value != null
+        ? Number(userRequest.requiredSignatures.value)
+        : null;
+    const deliveryType = userRequest.feeDirector?.feeType ?? null;
+    if (userRequest.delivery?.transactionHash) {
+        // AFFIRMED here means DELIVERED — a delivery transaction hash exists. This
+        // is the canonical meaning: it matches the on-chain event that produces
+        // it (`HomeAMB:AffirmationCompleted`). `bridge-history-item-utils.ts`
+        // once used AFFIRMED for the opposite fact (signed but not delivered);
+        // that collision is fixed there in favor of THIS meaning — see the
+        // comment on `createBridgeStatusFromHistory` and docs/transfer-states.md
+        // section 1. Do not reintroduce a second meaning for this value.
+        return {
+            ...params,
+            messageId: userRequest.messageId,
+            status: bridgeStatuses.AFFIRMED,
+            deliveredHash: userRequest.delivery.transactionHash,
+            count,
+            requiredSignatures,
+            deliveryType,
+        };
+    }
+    if (userRequest.finishedSigning) {
+        return {
+            ...params,
+            messageId: userRequest.messageId,
+            status: bridgeStatuses.VALIDATING,
+            count,
+            requiredSignatures,
+            deliveryType,
+            // Only attached once the request is actually releasable (finished
+            // signing, not yet delivered) — the one lifecycle point a manual
+            // release calldata could be built and broadcast.
+            release: {
+                requestType: userRequest.type,
+                encodedData: userRequest.encodedData,
+                signatures: userRequest.signatures ?? [],
+                destinationAmbAddress: userRequest.destinationAmbAddress,
+            },
+        };
+    }
+    return {
+        ...params,
+        messageId: userRequest.messageId,
+        status: bridgeStatuses.FINALIZED,
+        count,
+        requiredSignatures,
+        deliveryType,
+    };
+};

package/dist/transfers.d.ts

@@ -0,0 +1,147 @@
+import type { TokenMetadata } from '@gibs/bridge-sdk/types';
+import { type Hex } from 'viem';
+import type { UserRequest, UserRequestFilter } from './graphql.js';
+export interface FeeData {
+    tokenAddress: Hex;
+    feeManagerContract: {
+        chainId: string;
+        address: Hex;
+        omnibridgeAddress: Hex;
+    };
+    feeUpdate: {
+        feeType: Hex;
+        fee: string;
+    };
+}
+export interface BridgeData {
+    userRequests: UserRequest[];
+    tokenMetadata: Map<string, TokenMetadata>;
+    feeData: FeeData[];
+    pageInfo?: {
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+        startCursor?: string | null;
+        endCursor?: string | null;
+    };
+    totalCount?: number;
+    /**
+     * How many bridges this account released FOR SOMEONE ELSE the archive could
+     * not be asked about, because the fold-in list is capped at
+     * {@link DELIVERED_HASHES_LIMIT}.
+     *
+     * Reported so the interface can SAY SO. The cap used to reach a
+     * `console.warn` and nothing else, so a delivery account whose released
+     * bridges run into the thousands was shown a page footer that read as the
+     * whole archive. A count that is silently short is worse than one that is
+     * absent: the reader trusts it.
+     */
+    releasedForOthersOmitted: number;
+}
+/**
+ * Loads token metadata for unique token/chain combinations found in a set of bridges.
+ * Exported for independent testability.
+ */
+export declare function loadTokenMetadataForBridges(bridges: UserRequest[]): Promise<Map<string, TokenMetadata>>;
+/**
+ * Which part of the archive a browse asks for.
+ *
+ * `pending` and `completed` are a genuine partition of every request, so
+ * switching always changes what is on screen. `all` asks for both and is
+ * coherent only BECAUSE of that partition — it carries no `delivered` filter at
+ * all rather than a third value of one.
+ */
+export type BridgeFilterMode = 'pending' | 'completed' | 'all';
+export type LoadBridgesParams = {
+    address: Hex | null | undefined;
+    hash?: Hex | null | undefined;
+    limit?: number;
+    after?: string;
+    before?: string;
+    filterMode?: BridgeFilterMode;
+    /**
+     * Chain ids whose transfers must not appear, sorted. Omit or leave empty to
+     * ask for every network.
+     *
+     * IT IS THE INDEXER THAT APPLIES THIS, not the browser, and that is the whole
+     * reason it is here. A network filter applied to the page after it arrives
+     * would draw three rows under a count of ten while thousands more matched on
+     * pages the reader never reached — a silently capped list reads as the whole
+     * answer.
+     */
+    hiddenChainIds?: readonly number[];
+};
+/**
+ * Builds the GraphQL filter for user request queries from bridge loading params.
+ * Pure function — no side effects, exported for independent testability.
+ */
+export declare function buildBridgeFilter(params: LoadBridgesParams, deliveredMessageHashes?: Hex[]): UserRequestFilter | undefined;
+/**
+ * What one account has released on behalf of other people, as the archive query
+ * needs it: the hashes to fold in, and how many did not fit.
+ */
+export interface DeliveredMessageHashes {
+    /** The lowercased message hashes, newest first, at most {@link DELIVERED_HASHES_LIMIT}. */
+    readonly hashes: Hex[];
+    /** How many further released bridges the cap left out. Zero when none. */
+    readonly omitted: number;
+}
+/**
+ * Drops one account's cached delivered-hash list, so the next history fetch
+ * resolves it again.
+ *
+ * Called when the reader's own transaction is mined. A release the READER just
+ * made is the one change this list can undergo while they are watching it, and
+ * making them wait out the cache to see it would defeat the burst poll that
+ * exists for exactly that moment.
+ *
+ * @param address - the account whose list to forget. No address forgets nothing.
+ */
+export declare const forgetDeliveredMessageHashes: (address: Hex | null | undefined) => void;
+/** Clears every cached delivered-hash list. Exported for test isolation. */
+export declare const _clearDeliveredHashesCache: () => void;
+/**
+ * One account's delivered-hash list IF it is already resolved and still fresh,
+ * without starting a fetch for it.
+ *
+ * WHY LOOKING IS A DIFFERENT QUESTION FROM ASKING. `fetchBridgeTransactions`
+ * needs to know whether waiting for this list is free before it decides whether
+ * to run the archive query alongside it or after it. A cached list costs
+ * nothing to wait for, so the archive query can be built widened straight away;
+ * an unresolved one costs a whole round trip, and that is the round trip the
+ * page used to sit through before it asked for a single transfer.
+ *
+ * A STALE ENTRY READS AS ABSENT. `fetchDeliveredMessageHashes` sweeps expired
+ * entries on its way past, so an entry can outlive its window between sweeps.
+ * Returning one would hand the caller a list it believes is current.
+ *
+ * @param address - the account to look up. No address has no list.
+ * @returns the resolved list's promise, or null when there is no fresh one.
+ */
+export declare const peekDeliveredMessageHashes: (address: Hex | null | undefined) => Promise<DeliveredMessageHashes> | null;
+/**
+ * Fetches the message hashes of bridges this account RELEASED on behalf of others —
+ * the on-chain `deliverer` (the account that submitted the release transaction).
+ * Those bridges never match the history query's from/to scope, so without this they
+ * are invisible in the account's history.
+ *
+ * Ponder stores hex columns lowercase but does not normalize the query side, so the
+ * deliverer is queried lowercased to match (the same normalization the from/to scope
+ * relies on). Returns lowercased message hashes; nothing when no address.
+ *
+ * The answer is cached per account for {@link DELIVERED_HASHES_CACHE_TTL}. See
+ * that constant for why: this is the query that was reading hundreds of records
+ * in front of every ten-row page.
+ *
+ * Resilient by design: a failure here returns an empty list rather than throwing, so
+ * a deliveries-query problem degrades history to the from/to scope instead of blanking
+ * the whole panel. A failure is NEVER cached — a reader whose network blipped once
+ * would otherwise lose their released bridges for the full minute.
+ */
+export declare function fetchDeliveredMessageHashes(address: Hex | null | undefined): Promise<DeliveredMessageHashes>;
+/** Clears the in-memory bridge cache. Exported for test isolation. */
+export declare const _clearBridgeCache: () => void;
+/**
+ * Inner fetching logic for loadBridgeTransactions.
+ * Exported so it can be tested independently of the Svelte loading store wrapper.
+ */
+export declare function fetchBridgeTransactions(rawParams: LoadBridgesParams, controller: AbortController): Promise<BridgeData | null>;