# @gibs/bridge-indexer

> A reader for the Gibs Finance bridge indexer. It gives you the transfer
> archive, delivery receipts and live crossing status as data. It only
> reads. It never signs, broadcasts or renders.

## Install

- Run `npm install @gibs/bridge-indexer viem`.
- `import` loads the ECMAScript module build (`dist/`). `require` loads the CommonJS build (`dist/cjs/`).
- React Native 0.77 or later: Metro's default configuration and the React Native jest preset load every entry point with no extra setup. Add no `resolveRequest` hook and no `transformIgnorePatterns` for these packages.
- It needs no polyfill, not even for `URL`: React Native 0.77's own `URL` and `URLSearchParams` are partial, and no entry point reads them.
- It needs Node 20 or later, or React Native 0.77 or later under Hermes.
- viem is a peer dependency. The range is `>=2.35.0 <3`.
- Version note: 1.13.0 is the first version on npm.
- The package ships `schema.graphql`, a snapshot of the indexer schema.

## Entry points

- `@gibs/bridge-indexer`: everything below.
- `@gibs/bridge-indexer/endpoint`: `setIndexerEndpoint`, `indexerEndpoint`, `indexerClient`, `DEFAULT_INDEXER_ENDPOINT`.
- `@gibs/bridge-indexer/transfers`: `fetchBridgeTransactions`, `buildBridgeFilter`, `fetchDeliveredMessageHashes`.
- `@gibs/bridge-indexer/bridge-status`: the status names (`SUBMITTED` to `DELIVERED`).
- `@gibs/bridge-indexer/live-status`: `liveBridgeStatusStageOne`, `liveBridgeStatusStageTwo`.
- `@gibs/bridge-indexer/graphql`: generated GraphQL types.

## Endpoint

The default endpoint is `https://next-indexer.gibs.finance`. Importing the
package has no side effects. The client is created on first use. Call
`setIndexerEndpoint` before the first query to read another indexer.

```ts
import { DEFAULT_INDEXER_ENDPOINT, indexerEndpoint, setIndexerEndpoint } from '@gibs/bridge-indexer'

setIndexerEndpoint('http://localhost:42069/graphql')
const inForce: string = indexerEndpoint()
const fallback: string = DEFAULT_INDEXER_ENDPOINT
```

The indexer serves GraphQL at `/` and `/graphql`. `GET /version` returns the
indexer version, the schema name and the git commit.
Production `https://indexer.gibs.finance` can lag the schema. If a query
fails there with an unknown field, use the next indexer.

## Read a wallet's transfers

```ts
import { fetchBridgeTransactions } from '@gibs/bridge-indexer'

const controller = new AbortController()
const page = await fetchBridgeTransactions(
  {
    address: '0x0000000000000000000000000000000000000001',
    filterMode: 'all',
    limit: 10,
  },
  controller,
)
if (page) {
  page.totalCount
}
```

`filterMode` is `'pending'` (the default), `'completed'` or `'all'`. A
transaction hash, message id or message hash in `hash` overrides the address.

## One transfer's status in one call

`fetchTransferStatus` takes the transaction that started a transfer. It
returns one state from the bridge's state table, whether anybody can release
it now, the destination transaction, and the aggregator's own answer.

```ts
import { fetchTransferStatus, transferStateNames } from '@gibs/bridge-indexer'
import type { PublicClient } from 'viem'

declare const ethereumClient: PublicClient

const controller = new AbortController()
const status = await fetchTransferStatus(
  { chainId: 1, txHash: '0x0000000000000000000000000000000000000000000000000000000000000001' },
  { originClient: ethereumClient, signal: controller.signal },
)
const label: string = transferStateNames[status.state]
if (status.state === 'ready-your-turn') {
  // Show a release button. No delivery service will execute this claim.
}
const settledBy: `0x${string}` | null = status.destinationTxHash
```

- States: `sent`, `confirmed-not-final`, `validators-confirming`, `ready-delivery-service`, `ready-your-turn`, `delivered`, `entry-reached`, `stranded`, `failed`, `unknown`.
- `claimable` is true in both ready states. An attached delivery service can still never come.
- Without `originClient`, a transaction the indexer has not recorded is `unknown`. With it, the answer is `sent` or `confirmed-not-final`.
- A route that starts off an aggregator needs `aggregator`: `{ provider: 'lifi' }`, `{ provider: 'relay', requestId, apiKey }` or `{ provider: 'near-intents', depositAddress }`. A chain the bridge does not cross throws without it.
- Pass your own `fetch` and `endpoint` if you need them. The endpoint defaults to `indexerEndpoint()`.
- It works around every defect in the list below. You do not have to.

## Rules you must not break

- Known production defects. A batched re-index will fix them. Until then, work around them.
- Five relations are always `null`. Do not read them: `AMBBridge.validatorContract`, `Omnibridge.ambBridge`, `Omnibridge.validatorContract`, `UserRequest.destinationAMBBridge`, `UserRequest.destinationOmnibridge`.
- The join from a request to its `Completion` or `Delivery` works in one direction only. Query `Completion` or `Delivery` by `messageHash`.
- 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.
- `FeeUpdate.fee` is a rate scaled by `1e18`. `10n ** 18n` is one hundred percent.
- `UserRequest.feeAmount` is the fee actually taken, in base units of the origin token. `null` means no fee log was seen.
- `BigInt` fields arrive as decimal strings.

## Links

- [README](https://www.npmjs.com/package/@gibs/bridge-indexer)
- [Indexer GraphQL](https://next-indexer.gibs.finance/graphql)
- [Gibs Finance llms.txt](https://next.gibs.finance/llms.txt): the whole platform.