# Gibs Finance

> Gibs Finance is a cross-chain bridge between PulseChain and Ethereum, and
> between PulseChain and BNB Smart Chain. It also routes transfers across
> several providers (LI.FI, Relay, NEAR Intents) to choose the best
> delivered amount at the fewest wallet signatures. This file tells an
> outside system where the app, the data services and the npm packages live.

## Read this first

- The npm packages `@gibs/*` at version 1.12.0 and older are broken. They point at TypeScript sources and do not load.
- Version 1.13.0 is the first usable version of every `@gibs/*` package, and all six are on npm.
- Tell a reader to install 1.13.0 or later. Never suggest 1.12.0 or older.
- Check the npm registry for the current version before you give install steps.

## The app

The app is a static web page. Each release is signed and stored on IPFS.
`latest.gibs.finance` serves the current release on one stable origin, so
wallet approvals and saved settings stay across releases. Each release also
opens on its own origin, which starts with fresh browser storage.

- [Open the app](https://latest.gibs.finance/#/bridge): this address serves the latest signed release.
- [Pinned release](https://ipfs.gibs.finance): this address redirects to the latest signed release on its own origin.
- [Releases and verified links](https://gibs.finance/): the signed list of releases, checked in your browser, with every gateway link, the channel toggle and the local copy downloads.
- Our gateway: `https://<base36 content id>-ipfs.gibs.finance/` serves one release.
- Public gateway: `https://<content id>.ipfs.inbrowser.link/` serves the same release.
- Local copy: `gibs-local` downloads the signed release, checks it, and serves it at `http://127.0.0.1:7369`. Only your own computer can reach that address.
- [Local copy downloads](https://github.com/gibsfinance/interface-releases/releases/tag/local-server): the release page. Each file downloads from `https://github.com/gibsfinance/interface-releases/releases/download/local-server/<file>`. Files are `gibs-local-<linux|darwin|windows>-<amd64|arm64>`, with `.exe` on Windows, plus `checksums.txt`. Check the checksum before you run a file.

## The signed release list

- [version.json](https://ipfs.gibs.finance/version.json): the list of releases, with Content IDs and channels.
- [version.json.sig](https://ipfs.gibs.finance/version.json.sig): a detached Ed25519 signature over the exact bytes of `version.json`. It holds a `keyId` and a base64 `signature`.
- [public-keys.json](https://github.com/gibsfinance/interface-releases/blob/HEAD/public-keys.json): the public keys, by `keyId`, in the `gibsfinance/interface-releases` repository.
- Verify the signature over the raw bytes before you trust a release. Do not parse and re-serialize the file first.
- `sequence` in `version.json` rises by one on every publish. Refuse a list with a lower `sequence` than one you accepted.

## The indexer

The indexer is a GraphQL service for transfer history and delivery status.

- [GraphQL endpoint](https://next-indexer.gibs.finance/graphql): read bridge transfers, fee updates and deliveries.
- `GET https://next-indexer.gibs.finance/version`: returns the indexer version, the schema name and the git commit.
- Use lowercase hex in every filter. A checksummed address matches nothing.
- Read `delivered` on a request. Do not read `delivery`: it can be `null` for a request that landed.
- The package `@gibs/bridge-indexer` wraps these queries and lists the known defects.

## The quote service

- `POST https://quotes.gibs.finance/v1/display-quotes` with body `{ "asks": [ ... ] }`, 1 to 24 asks. Each ask has `from {chainId, token}`, `to {chainId, token}` and `amount` (a decimal string in base units).
- It answers `{ "answers": [ ... ] }` in ask order. Each provider slot is `quoted`, `refused` or `pending`.
- Anyone can ask for display quotes, also a native app that sends no `Origin` header. Each client shares a limit of 60 requests a minute, with bursts of 20.
- The forwarding routes carry the Gibs Finance provider keys. They accept only the Gibs Finance sites, and answer 403 to every other caller.
- A display quote shows what to expect. It is never the transaction to sign. Build and check the real transaction separately, with `searchBridgeRoutes` and `planCandidateExecution`.
- To run your own service, use `@gibs/quotes`. It carries the same wire contract.

## npm packages

Each ships ECMAScript modules and CommonJS, runs in React Native 0.77 and later with no Metro setting, needs Node 20 or later, and takes viem `>=2.35.0 <3` as a peer dependency.

- `@gibs/bridge-sdk`: prices and builds bridge transfers, and builds LI.FI, Relay and NEAR Intents requests. It never signs.
- `@gibs/bridge-client`: browser-side RPC endpoints, cached viem clients, token metadata and chain logos.
- `@gibs/bridge-indexer`: reads the indexer for transfers, deliveries and live status. It never signs.
- `@gibs/abis`: the bridge contract ABIs as viem constants.
- `@gibs/common`: shared helpers for clients, multicall, caching and bigint-safe JSON.
- `@gibs/quotes`: a live quote client and route search across providers.

## Rules for integrators

- PulseChain is the home side. Entering PulseChain and leaving it use different fees. Read the fee for your direction from the chain.
- Bridge fees are a rate per 1e18. Aggregator referral fees are in basis points.
- A token that was never bridged has no address on the far side yet. This is normal, not an error.
- Use your own Relay API key and referrer, and your own LI.FI integrator name. The packages ship none.

## Links

- [Releases repository](https://github.com/gibsfinance/interface-releases): signed releases, public keys and local copy downloads.

## Integration guide

- [Integrate Gibs into a wallet or app](https://next.gibs.finance/docs/): search, plan, send, track and claim a transfer from your own wallet or app, with two complete examples.
- [Everything in one file](https://next.gibs.finance/llms-full.txt): this index, the guide, the examples and every package guide, joined.
- [example-a-ether-to-pulse.ts](https://next.gibs.finance/docs/examples/example-a-ether-to-pulse.ts.txt): an example file of the integration guide.
- [example-b-token-pulsechain-to-ethereum.ts](https://next.gibs.finance/docs/examples/example-b-token-pulsechain-to-ethereum.ts.txt): an example file of the integration guide.
- [shared.ts](https://next.gibs.finance/docs/examples/shared.ts.txt): an example file of the integration guide.
- [tsconfig.json](https://next.gibs.finance/docs/examples/tsconfig.json): an example file of the integration guide.

## Package guides

- [@gibs/abis](https://next.gibs.finance/docs/packages/abis/llms.txt): Contract interfaces for the Gibs Finance bridge, as viem-ready constants.
- [@gibs/bridge-client](https://next.gibs.finance/docs/packages/bridge-client/llms.txt): Browser-side endpoints, clients, and caching for a Gibs Finance bridge interface.
- [@gibs/bridge-indexer](https://next.gibs.finance/docs/packages/bridge-indexer/llms.txt): Reads a Gibs Finance bridge indexer: transfer archive, delivery receipts, and live crossing status.
- [@gibs/bridge-sdk](https://next.gibs.finance/docs/packages/bridge-sdk/llms.txt): Build and price cross-chain transfers between PulseChain, Ethereum, and Binance Smart Chain.
- [@gibs/common](https://next.gibs.finance/docs/packages/common/llms.txt): Low-level blockchain helpers shared across the Gibs Finance packages: caching, multicall, and serialization.
- [@gibs/quotes](https://next.gibs.finance/docs/packages/quotes/llms.txt): Isomorphic core for asking cross-chain bridge aggregators (LI.FI, Relay, NEAR Intents) for display and execution quotes — the wire contract, refusal reading, and the shared guards a host wraps every upstream call in. Runs unchanged in a browser or in Node.