@gibs/bridge-sdk 1.13.1 → 1.17.0

package/README.md

@@ -11,24 +11,108 @@ response parsers. It does not sign or send anything. You bring a
 Every TypeScript sample in this file is compiled by the package's test suite
 (`src/compile-checks.test.ts`), so a sample that stops matching the code fails the build.
 
+## Integration guide
+
+To add Gibs routes to a wallet or app from start to end, read the integration
+guide. It shows how to search for routes, plan the transactions, send them with
+your own signer, track the transfer and claim it. It has two complete examples.
+
+- Online: <https://next.gibs.finance/docs/>
+- In this package: `docs/integration-guide.md`, with the example files in
+  `docs/examples/`. After you install, they are in
+  `node_modules/@gibs/bridge-sdk/docs/`.
+- For AI tools: <https://next.gibs.finance/llms-full.txt> holds the guide, the
+  examples and every package guide in one file.
+
 ## Install
 
 ```sh
 npm install @gibs/bridge-sdk viem
 ```
 
-- **ESM only.** The package is `"type": "module"` and ships no CommonJS build.
-  Use `import`, not `require`.
-- **Node.js 20 or later** (`engines.node` is `>=20`).
-- **viem is a peer dependency** (`>=2.37.0`).
-- **Browsers and `@gibs/bridge-sdk/ton-execution`.** That entry point uses
-  `@ton/core`, which expects a global `Buffer`. Node has one. In a browser,
-  install the `buffer` package and set `globalThis.Buffer` before you import it.
-  No other entry point needs `Buffer`.
+- **Node.js 20 or later** (`engines.node` is `>=20`), or React Native with Hermes.
+- **viem is a peer dependency** (`>=2.35.0 <3`).
 
 Import from the narrowest entry point you need (`@gibs/bridge-sdk/config`,
 `@gibs/bridge-sdk/chain-info`, and so on). The root `@gibs/bridge-sdk` exports
-everything.
+everything except TON.
+
+## Ways to use the package
+
+The package ships two builds of the same code, and picks one for you through
+the `exports` map. You need no extra configuration for any of these.
+
+| Option | What you write | What loads |
+|---|---|---|
+| ECMAScript modules | `import { pathway } from '@gibs/bridge-sdk/config'` | `dist/config.js` |
+| CommonJS | `const { pathway } = require('@gibs/bridge-sdk/config')` | `dist/cjs/config.js` |
+| React Native (Metro) | either of the above | `import` gets `dist/`, `require` gets `dist/cjs/` |
+| React Native (jest) | either of the above | `dist/cjs/` |
+
+**ECMAScript modules.** Node, Vite, webpack, esbuild, Rollup and Bun use the
+`import` condition.
+
+```ts
+import { Chains, pathway, Providers } from '@gibs/bridge-sdk/config'
+import { amountAfterBridgeFee, bridgeCost } from '@gibs/bridge-sdk/settings'
+
+const route = pathway([Providers.PULSECHAIN, Chains.PLS, Chains.ETH], true)
+const cost = bridgeCost({ amountToBridge: 10n ** 18n, bridgeFee: 3n * 10n ** 15n })
+const amountOut = amountAfterBridgeFee({ amountToBridge: 10n ** 18n, bridgeCost: cost })
+console.log(route?.from, amountOut)
+```
+
+**CommonJS.** `require` loads `dist/cjs/`, with its own declaration files.
+
+```js
+const { Chains, pathway, Providers } = require('@gibs/bridge-sdk/config')
+```
+
+**React Native.** The package works with the default Metro configuration of
+React Native 0.77 or later. You need no change to `metro.config.js`, no
+`resolveRequest` hook, no `transformIgnorePatterns` in jest, and no polyfill.
+It runs on React Native's own `URL` and `URLSearchParams`, which React Native
+0.77 implements only in part: no code in the package reads them.
+In React Native 0.79 or later, Metro reads the `exports` map.
+The `react-native` condition follows Metro's own choice: an `import` statement
+gets the ECMAScript module build, and a `require` call gets CommonJS. That
+keeps the SDK on the same build of viem as your own code, so Metro bundles
+viem once. The React Native jest preset loads `node_modules` untransformed, so
+it gets CommonJS. Hermes runs both builds.
+
+In React Native 0.77 and 0.78, or with `unstable_enablePackageExports: false`,
+Metro ignores `exports`. Every subpath still resolves: the package ships one
+folder per subpath, such as `config/package.json`, whose `main` and
+`react-native` fields point at the CommonJS build. Metro then loads CommonJS for
+every import, and viem's own CommonJS build with it, so viem is still bundled
+once.
+
+**Import only what you use.** Metro does not drop unused exports, so the entry
+point you pick decides what your bundle carries. Measured with React Native
+0.87.1 and viem 2.56.3, in a production ios bundle that already holds viem:
+
+| You import | Added to the bundle |
+|---|---|
+| `@gibs/bridge-sdk/config` and `/settings` (offline quoting) | about 24 kB (7 kB gzipped) |
+| `@gibs/bridge-sdk/chain-info` (live fee reads), with the above | about 1.16 MB, of which `viem/chains` is 1.12 MB |
+| `@gibs/bridge-sdk` (the root, everything but TON) | about 1.29 MB |
+
+If your app already imports `viem/chains`, `chain-info` adds about 41 kB and the
+root adds about 164 kB. In React Native 0.77 with viem 2.35.0, where Metro
+loads the CommonJS build, `config` and `settings` add about 28 kB.
+
+**TON.** TON lives behind its own entry points, so an app that bridges only
+between Ethereum-style chains never loads a TON library.
+
+- `@gibs/bridge-sdk/ton-connect` builds TON Connect requests and re-encodes
+  addresses. It needs no TON library, no `Buffer` and no polyfill.
+- `@gibs/bridge-sdk/ton` holds the same helpers plus `tonExternalMessageHash`,
+  which needs `@ton/core`. `@ton/core` expects a global `Buffer`: in a browser
+  or in React Native, install the `buffer` package and set `globalThis.Buffer`
+  before you import it. In React Native, `@ton/core`'s `@ton/crypto` dependency
+  also resolves to a build that requires `expo-crypto`, so Metro fails to
+  bundle this entry point unless the app installs `expo-crypto`.
+- `@gibs/bridge-sdk/ton-execution` is the old name of `@gibs/bridge-sdk/ton`.
 
 ## Chains and bridge keys
 
@@ -179,19 +263,21 @@ chain again. Call `clearChainInfoCaches()` to drop every cached answer.
 ## Aggregator quotes and your identity
 
 The request builders turn one `ConsolidatedQuoteRequest` into a provider's
-request. The package ships **no API key**. It sends a Gibs Finance label only
-where that costs you nothing.
+request. The package ships **no API key**, and it attributes nothing to Gibs
+Finance unless you pass Gibs Finance's values yourself.
 
 | Field | Default | Why |
 |---|---|---|
 | Relay `x-api-key` | none | Pass your own to `relayRequestHeaders`. A key carries a rate-limit budget. |
 | Relay `referrer` | **not sent** | Relay requires an API key from any request that names a referrer, so a default would break keyless callers. |
-| LI.FI `integrator` | `gibs.finance` | A free label. It changes neither the quote nor your rate limit. |
+| LI.FI `integrator` | **not sent** | LI.FI records your traffic under this label and pays any fee to the account behind it. Name your own. |
 | LI.FI `fee` | not sent | A fee needs your own `lifiIntegrator`, because LI.FI pays the fee to the integrator label. The builders throw otherwise. |
-| NEAR Intents `User-Agent` | `gibs-bridge/1.0 (+https://gibs.finance)` | No key and no budget, and browsers drop it. |
+| NEAR Intents `referral` | **not sent** | Pass `referral` in the quote context to tag your traffic. |
+| NEAR Intents `User-Agent` | `gibs-bridge/1.0 (+https://gibs.finance)` | Browsers drop it, so it reaches the service only from Node or React Native. Pass `{ userAgent: 'your-app/1.0' }`, or `{ userAgent: null }` to send none. |
 
-Each attribution field takes three states: leave it out for the default, pass
-`null` to omit it, or pass your own string.
+Each attribution field takes two states: leave it out (or pass `null`) to send
+nothing, or pass your own string. The NEAR Intents `User-Agent` is the one
+exception: leave it out and it names Gibs Finance.
 
 ```ts
 import {
@@ -227,6 +313,58 @@ const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/
 Relay quotes work without a key on its anonymous tier. Relay's `/requests/v3`
 status lookup does not: it answers 400 without `x-api-key`.
 
+## Which fees apply, and how you control each one
+
+The package adds no fee and no attribution on its own. A request carries one
+only when your code passes it. The test `src/no-default-fees.test.ts` builds a
+request with every builder and fails if any of them adds a fee, a payout
+address or a Gibs Finance label that the caller did not pass.
+
+| Fee | When it applies | Who receives it | How you see it | How you control it |
+|---|---|---|---|---|
+| Bridge fee | Every direct omnibridge crossing. It is an on-chain setting, per direction. | The bridge's fee manager | `loadBridgeFees`, then `bridgeCost` | You cannot turn it off. Read it, and show it before the user signs. |
+| Delivery fee | Only when you request delivery: `shouldDeliver: true` and a `feeDirectorStructEncoded` in `transactionInputs`. | Whoever executes the claim on the destination chain | `deliveryFee` | Choose the fee type and amount, or pass `shouldDeliver: false` and let the user claim. |
+| LI.FI referral fee | Only when you pass `lifiFee` and your own `lifiIntegrator` | The account behind your integrator label | The `fee` field of the built request | Leave `lifiFee` out to charge nothing. |
+| Relay application fee | Only when you pass `relayAppFee: { recipient, basisPoints }` | `recipient`, on the destination chain | The `appFees` field of the built request | Leave `relayAppFee` out to charge nothing. |
+| Provider fees (gas, solver, protocol) | Every aggregator route. The provider charges them. | LI.FI, Relay or NEAR Intents | `lifiQuoteFees`, `relayQuoteFees`, and the NEAR Intents quote parser | Not in your control. Show them. |
+| NEAR Intents key-less surcharge | Every NEAR Intents quote sent without a partner key: 25 basis points (`nearIntentsUnauthenticatedFeeBasisPoints`) | NEAR Intents | The NEAR Intents quote parser reports it as a charge | Get a partner key and pass it to `nearIntentsRequestHeaders`. |
+
+The `@gibs/bridge-sdk/referral` module holds **Gibs Finance's own values**:
+`referralIntegrator`, `relayReferralRecipient` (Gibs Finance's payout wallet)
+and `defaultReferralFeeBasisPoints` (10, a tenth of a percent).
+`lifiReferralFeePercent`, `lifiIntegrator` and `relayReferrer` repeat them for
+each provider. No builder reads any of them. The Gibs interface passes them
+explicitly. Do not pass them from your own wallet: they pay Gibs Finance.
+
+## RPC endpoints: the defaults are for demos only
+
+Every reader in this package takes your clients. `loadBridgeFees`,
+`tokenBridgeInfo`, `fetchPriceCorrective`, `minBridgeAmountIn`, the limit
+reads and the route carriers all take a viem `PublicClient` (or a
+`clientForChain` function) from you. None of them builds a client of its own.
+
+`chainsMetadata` carries only public endpoints. The Gibs interface also uses a
+shared valve.city proxy key, `vk_demo`. That key is published (it is listed on
+chainlist.org), so it is not a secret. But its rate budget is shared by
+everybody who uses it, and the Gibs Finance operator runs the proxy. It lives
+in `demoRpcUrls` and `demoRpcUrlsFor`, which exist **for demos only**. Use your
+own RPC provider in production.
+
+```ts
+import { demoRpcUrlsFor } from '@gibs/bridge-sdk/chains'
+import { createPublicClient, fallback, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+// Production: your own endpoint.
+const ethereumClient = createPublicClient({ chain: mainnet, transport: http('https://your-rpc.example') })
+
+// A demo, by explicit choice: the shared demo key first, public endpoints behind it.
+const demoClient = createPublicClient({
+  chain: mainnet,
+  transport: fallback(demoRpcUrlsFor(mainnet.id).map((url) => http(url))),
+})
+```
+
 ## Images
 
 Chain logos and token images come from [gib.show](https://gib.show). Point them
@@ -243,6 +381,90 @@ chainsMetadata[Chains.PLS].logoURI // 'https://images.example.org/image/369'
 image({ chainId: 1, address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' })
 ```
 
+## Execution plans
+
+`planCandidateExecution` turns a chosen route candidate into the ordered list of
+transactions a wallet sends. Each `PlannedTx` names its chain, its kind
+(`approve`, `bridge`, `swap`, `wrap`, `unwrap` or `claim`), its target, calldata,
+value and gas limit. Every transaction except the last has
+`waitForReceipt: true`, because the next one spends what it produced. When the
+next transaction is on another chain, a receipt is not enough: wait for the
+funds to arrive before you send it.
+
+```ts
+import {
+  type AllowanceReader,
+  type ResolveNodeToken,
+  type RouteCandidate,
+  type TokenBridgeInfo,
+  planCandidateExecution,
+} from '@gibs/bridge-sdk';
+import type { Hex } from 'viem';
+
+declare const candidate: RouteCandidate;
+declare const account: Hex;
+declare const recipient: Hex;
+declare const amountIn: bigint;
+declare const readAllowance: AllowanceReader;
+declare const resolveToken: ResolveNodeToken;
+declare const assetLink: TokenBridgeInfo;
+
+const plan = await planCandidateExecution({
+  candidate,               // a RouteCandidate, with or without an engine plan
+  account,                 // the wallet that signs
+  readAllowance,           // (chainId, token, owner, spender) => Promise<bigint>
+  resolveToken,            // the resolver the candidate was built with
+  sections: [{
+    amountIn,
+    recipient,
+    omnibridge: { isProd: true, assetLink, unwrap: false, delivery: { shouldDeliver: false } },
+  }],
+});
+if (plan.kind === 'refused') throw new Error(plan.refusal.reason);
+```
+
+- **Delivery is your choice, stated up front.** `delivery` is
+  `{ shouldDeliver: false }` or `{ shouldDeliver: true, fee }`, where `fee` holds
+  the quoted terms, including `maximumFee`, the most the router may take. There
+  is no default. The plan reports each delivery it buys in `deliveries`.
+- **Approvals are exact.** The plan approves only the amount a transaction
+  spends, and skips an approval the allowance on chain already covers. A short,
+  non-zero allowance is reset to zero first, because some tokens refuse to change
+  one non-zero allowance into another.
+- **Spenders come from fixed tables.** The plan approves only the omnibridge
+  mediator and the PulseX router from this package's configuration, LI.FI's
+  Diamond (`lifiDiamondAddressByChainId`, plus the LI.FI execution guard), and
+  Relay's depository (`relayDepositoryByChainId`). A quote that names any other
+  spender or deposit target is refused. NEAR Intents may name no spender at all.
+- **Only a live quote is signed.** An aggregator section needs the live quote
+  asked for your wallet, in `sections[i].aggregator`. The candidate's own quote
+  priced the route on screen and is never signed.
+
+## Manual claims
+
+A crossing from PulseChain to Ethereum or BNB Smart Chain ends with a release on
+the destination chain. When nobody delivers it, the reader claims it.
+`buildClaimTransaction` takes the bridge indexer's `UserRequest` record and
+returns a `claim` transaction, or a typed refusal: `wrong-type`,
+`already-delivered`, `not-signed-yet`, `signatures-incomplete` or
+`malformed-request`. `packSignatures`, `signatureToVRS`,
+`encodeReleaseWithoutTipData`, `encodeReleaseToRouterData` and `claimCall` are
+the parts it is built from.
+
+**An assumption about the indexer.** The indexer stores a validator's signature
+only when the validator sends `submitSignature` straight to the home bridge
+(`handleSignedFor` in `packages/indexer/src/index.ts` decodes the transaction's
+own input). A validator that signs through a multisig wallet, a proxy or a
+batching contract still emits `SignedForUserRequest`, so the indexer counts the
+signature in `confirmedSignatures`, but it does not store it in `signatures`.
+`CollectedSignatures` still sets `finishedSigning` to true. The record then says
+"signed" while it holds too few signatures, and a claim built from it reverts on
+the destination bridge. `buildClaimTransaction` catches this. When it stores
+fewer signatures than the threshold (`requiredSignatures.value`, or every counted
+signature when the record carries no threshold), it refuses with
+`signatures-incomplete`. Waiting does not fix that refusal. The indexer has to
+store the missing signature.
+
 ## Nulls, falses and throws
 
 The package follows one rule: **a question it cannot answer returns `null`,
@@ -272,18 +494,22 @@ The package writes nothing to the console.
 | Entry point | What it holds |
 |---|---|
 | `@gibs/bridge-sdk/config` | Chains, providers, pathways, native-asset tables |
-| `@gibs/bridge-sdk/chains` | viem chain objects with logos and RPC URLs |
+| `@gibs/bridge-sdk/chains` | viem chain objects with logos and public RPC URLs; `demoRpcUrls` for demos only |
 | `@gibs/bridge-sdk/chain-info` | On-chain reads: token mappings, fees, minimum amounts |
 | `@gibs/bridge-sdk/settings` | Fee and amount arithmetic, transaction inputs |
 | `@gibs/bridge-sdk/consolidated-quote` | LI.FI request builders and parsers |
 | `@gibs/bridge-sdk/relay-quote` | Relay request builders and parsers |
 | `@gibs/bridge-sdk/near-intents` | NEAR Intents requests and parsers |
 | `@gibs/bridge-sdk/pre-quote` | Forward-solving price checks before a binding quote |
-| `@gibs/bridge-sdk/referral` | Gibs Finance's own referral settings |
+| `@gibs/bridge-sdk/referral` | Gibs Finance's own referral values. No builder applies them. |
 | `@gibs/bridge-sdk/image-links` | Image URLs |
 | `@gibs/bridge-sdk/abis` | Contract ABIs |
-| `@gibs/bridge-sdk/ton-execution` | TON Connect requests (needs `Buffer`) |
+| `@gibs/bridge-sdk/ton-connect` | TON Connect requests, with no TON library |
+| `@gibs/bridge-sdk/ton` | TON Connect requests and the message hash (needs `@ton/core` and `Buffer`) |
+| `@gibs/bridge-sdk/ton-execution` | Old name of `@gibs/bridge-sdk/ton` |
 | `@gibs/bridge-sdk/routing` | Route search across carriers |
+| `@gibs/bridge-sdk/execution` | Execution plans: the transactions a chosen route signs, in order |
+| `@gibs/bridge-sdk/claims` | Manual claim transactions for a release nobody delivered |
 
 The API can still change in a minor version. Read the release notes before you
 upgrade.

package/abis/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/abis.js",
+  "module": "../dist/abis.js",
+  "types": "../dist/abis.d.ts",
+  "react-native": "../dist/cjs/abis.js"
+}

package/bridge-limits/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/bridge-limits.js",
+  "module": "../dist/bridge-limits.js",
+  "types": "../dist/bridge-limits.d.ts",
+  "react-native": "../dist/cjs/bridge-limits.js"
+}

package/chain-info/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/chain-info.js",
+  "module": "../dist/chain-info.js",
+  "types": "../dist/chain-info.d.ts",
+  "react-native": "../dist/cjs/chain-info.js"
+}

package/chain-names/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/chain-names.js",
+  "module": "../dist/chain-names.js",
+  "types": "../dist/chain-names.d.ts",
+  "react-native": "../dist/cjs/chain-names.js"
+}

package/chains/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/chains.js",
+  "module": "../dist/chains.js",
+  "types": "../dist/chains.d.ts",
+  "react-native": "../dist/cjs/chains.js"
+}

package/claims/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/claims.js",
+  "module": "../dist/claims.js",
+  "types": "../dist/claims.d.ts",
+  "react-native": "../dist/cjs/claims.js"
+}

package/config/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/config.js",
+  "module": "../dist/config.js",
+  "types": "../dist/config.d.ts",
+  "react-native": "../dist/cjs/config.js"
+}

package/consolidated-quote/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/consolidated-quote.js",
+  "module": "../dist/consolidated-quote.js",
+  "types": "../dist/consolidated-quote.d.ts",
+  "react-native": "../dist/cjs/consolidated-quote.js"
+}

package/destination-calldata/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/cjs/destination-calldata.js",
+  "module": "../dist/destination-calldata.js",
+  "types": "../dist/destination-calldata.d.ts",
+  "react-native": "../dist/cjs/destination-calldata.js"
+}

package/dist/chain-info.d.ts

@@ -40,7 +40,7 @@ type LinksInputs = {
 export declare const links: ((inputs: LinksInputs) => Promise<[Hex, Hex]>) & {
     cache: {
         delete: (key: string) => boolean;
-        clear?: () => void;
+        clear: () => void;
     };
 };
 /**

package/dist/chain-info.js

@@ -1,5 +1,5 @@
+import { memoizeByKey } from '@gibs/common/cache';
 import { multicallRead } from '@gibs/common/multicall';
-import * as _ from 'lodash-es';
 import { encodeFunctionData, getContract, multicall3Abi, zeroAddress, } from 'viem';
 import * as abis from './abis.js';
 import { chainsMetadata } from './chains.js';
@@ -30,12 +30,9 @@ const isUnmappedAnswer = ([bridged, native]) => bridged === zeroAddress && nativ
  * @param inputs.client - a client for that chain
  * @returns the bridged token address and native token address
  */
-// The annotation is required, not stylistic: `@types/lodash-es` re-exports its
-// `MemoizedFunction` type from a nested `@types/lodash` that a generated
-// declaration file cannot name (TS2742). The body reaches for `links.cache` to
-// evict an answer, so the cache surface is spelled out to the extent this file
-// uses it.
-export const links = _.memoize(async (inputs) => {
+// The body reaches for `links.cache` to evict an answer, so the cache surface
+// is spelled out to the extent this file uses it.
+export const links = memoizeByKey(async (inputs) => {
     const { chainId, target, address, client } = inputs;
     const evict = () => links.cache.delete(linksCacheKey(inputs));
     const pair = await multicallRead({
@@ -65,8 +62,7 @@ export const links = _.memoize(async (inputs) => {
  * a fresh view, or between tests.
  */
 export const clearChainInfoCaches = () => {
-    // lodash types mark `clear` optional; the default MapCache always has it
-    links.cache.clear?.();
+    links.cache.clear();
 };
 /**
  * Returns the token bridge info for the given bridge key, asset in, is prod, from chain client, and to chain client
@@ -180,7 +176,8 @@ const readAmountOut = ({ amountIn, chain, paths, client, uniV2Router, }) => {
         client,
         abi: abis.univ2Router,
         // pulsex router
-        calls: _.flatMap(uniV2Router ? [uniV2Router] : uniV2Routers[chain], (target) => paths.map((path) => ({
+        // a chain with no router reads nothing, as lodash's flatMap over undefined did
+        calls: (uniV2Router ? [uniV2Router] : (uniV2Routers[chain] ?? [])).flatMap((target) => paths.map((path) => ({
             functionName: 'getAmountsOut',
             allowFailure: true,
             args: [amountIn, path],
@@ -244,7 +241,7 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
         },
         reduceResults: ({ results, oneToken, }) => {
             const outputFromRouter = (result) => {
-                if (_.isString(result)) {
+                if (typeof result === 'string') {
                     // the router failed to return a result
                     return 0n;
                 }
@@ -257,7 +254,9 @@ export const fetchPriceCorrective = ({ bridgeKeyPartner, assetOut, measurementTo
                 return (last * oneToken) / amountIn;
             };
             const max = (amountsOut) => {
-                return _.compact(amountsOut).reduce((max, current) => (max < current ? current : max), 0n);
+                return amountsOut
+                    .filter((amount) => amount !== undefined)
+                    .reduce((max, current) => (max < current ? current : max), 0n);
             };
             // could do with a refactor to unify the results
             const [outputs, inputs] = results;

package/dist/chains.d.ts

@@ -1,3 +1,4 @@
+import { Chains } from './config.js';
 import type { ChainsMetadata } from './types.js';
 /**
  * all of the chains that are enabled in this dapp
@@ -16,6 +17,30 @@ import type { ChainsMetadata } from './types.js';
  * was at that moment.
  */
 export declare const chainsMetadata: ChainsMetadata;
+/**
+ * The RPC endpoints the Gibs interface uses, FOR DEMOS ONLY.
+ *
+ * Each proxied chain's list starts with valve.city's shared `vk_demo` key and
+ * falls through to that chain's public endpoints in {@link chainsMetadata}.
+ * Binance Smart Chain has no valve.city entry, so its list is the public one.
+ *
+ * WHY IT IS A SEPARATE, NAMED LIST. The key is public, so shipping it discloses
+ * nothing. But its rate budget is shared by everybody who uses it, and the proxy
+ * belongs to the Gibs Finance operator. A wallet that inherits it without
+ * choosing it puts its users' reads on somebody else's budget and uptime. So no
+ * reader in this package uses it, and `chainsMetadata` does not carry it. A
+ * caller who wants it asks for it by this name.
+ *
+ * Production callers: pass your own viem clients to every reader.
+ */
+export declare const demoRpcUrls: Readonly<Record<Chains, readonly string[]>>;
+/**
+ * The demo endpoints for one chain, FOR DEMOS ONLY. See {@link demoRpcUrls}.
+ *
+ * @param chainId - a decimal chain id
+ * @returns a copy of the chain's demo endpoints, or an empty list for a chain the bridge does not cross
+ */
+export declare const demoRpcUrlsFor: (chainId: number) => string[];
 /**
  * Every chain this bridge itself carries funds across, in the order the
  * metadata declares them.

package/dist/chains.js

@@ -3,7 +3,7 @@
 // same module would be loaded twice, once as source and once as build output,
 // and `Chains.PLS` from one would not be the same object as from the other.
 import { chainDisplayName } from './chain-names.js';
-import { Chains } from './config.js';
+import { Chains, toChain } from './config.js';
 import * as imageLinks from './image-links.js';
 // Chain definitions come from viem, not from a wallet-connection library. These
 // five objects are identical in `@reown/appkit/networks`, which is where they used
@@ -14,6 +14,12 @@ import { bsc, mainnet, pulsechain, pulsechainV4, sepolia } from 'viem/chains';
 /**
  * Builds an endpoint on valve.city, which proxies four of this dapp's chains.
  *
+ * DEMO ONLY. These endpoints live in {@link demoRpcUrls}, never in
+ * {@link chainsMetadata}. A third party that hands `chainsMetadata` to viem with
+ * a bare `http()` gets the public endpoints below, not this shared key. The Gibs
+ * interface asks for the demo list by name (`@gibs/bridge-client`'s
+ * `clientFromChain`). Any other caller should pass its own clients.
+ *
  * The key in this URL is `vk_demo`, and it is MEANT to be here. It is the
  * proxy's published demo key — it is already listed on chainlist.org, so it is
  * public knowledge and shipping it in a browser bundle discloses nothing. The
@@ -99,7 +105,7 @@ export const chainsMetadata = {
         alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
         rpcUrls: {
             default: {
-                http: [valveCity(pulsechain.id), 'https://rpc.pulsechain.com'],
+                http: ['https://rpc.pulsechain.com'],
             },
         },
         contracts: {
@@ -123,13 +129,13 @@ export const chainsMetadata = {
         alt: 'two pyramids joined on one side',
         rpcUrls: {
             default: {
-                // THREE, because the middle one is the only real fallback. On
-                // 2026-08-25 g4mm4 answered nothing at all for hours, and this list
-                // was g4mm4 then valve.city — so every read fell through a dead host
-                // onto a key that rejects four requests in five. publicnode measured
-                // 40 of 40 on 2026-08-27 and costs nothing to carry.
+                // TWO PUBLIC ENDPOINTS, and {@link demoRpcUrls} puts valve.city in
+                // front of them. Both are needed behind it. On 2026-08-25 g4mm4
+                // answered nothing at all for hours, and the list was g4mm4 then
+                // valve.city — so every read fell through a dead host onto a key that
+                // rejects four requests in five. publicnode measured 40 of 40 on
+                // 2026-08-27 and costs nothing to carry.
                 http: [
-                    valveCity(mainnet.id),
                     'https://rpc-ethereum.g4mm4.io',
                     'https://ethereum-rpc.publicnode.com',
                 ],
@@ -180,20 +186,18 @@ export const chainsMetadata = {
                 // Ordered deliberately, by the operational rule that the most reliable
                 // endpoint goes FIRST.
                 //
-                // valve.city led this list on the belief that it "is ours and is not
-                // rate limited against us". The first half is true and the second is
-                // not: the SHARED DEMO KEY is what ships here, and it answered 429 for
-                // 32 of 40 burst requests against Sepolia on 2026-08-27. Being ours
-                // does not buy a budget, so it goes last with the rest.
+                // valve.city is not here. It sits in front of these three only in
+                // {@link demoRpcUrls}. Being ours does not buy it a budget: the SHARED
+                // DEMO KEY answered 429 for 32 of 40 burst requests against Sepolia on
+                // 2026-08-27, which is why nothing may depend on it alone.
                 //
-                // The other three keep the order an earlier browser measurement earned
+                // These three keep the order an earlier browser measurement earned
                 // them. publicnode stays last of the public three because it is the one
                 // observed returning 403 under a browser's load — five times on one
                 // page render — which a `curl` burst does not reproduce and therefore
                 // cannot overturn. It answers fine when the others are busy, so it is
                 // demoted rather than dropped.
                 http: [
-                    valveCity(sepolia.id),
                     'https://sepolia.gateway.tenderly.co',
                     'https://1rpc.io/sepolia',
                     'https://ethereum-sepolia-rpc.publicnode.com',
@@ -211,12 +215,11 @@ export const chainsMetadata = {
         alt: 'a pink blue and purple hexagon with an ekg line running horizontally',
         rpcUrls: {
             default: {
-                // Three for the reason Ethereum is three: g4mm4 is a single host
-                // that has gone away before, and valve.city alone behind it is not a
-                // fallback. The official testnet node measured 40 of 40 on
-                // 2026-08-27.
+                // Two, for the reason Ethereum has two: g4mm4 is a single host that
+                // has gone away before, and valve.city ({@link demoRpcUrls}) alone in
+                // front of it is not a fallback. The official testnet node measured 40
+                // of 40 on 2026-08-27.
                 http: [
-                    valveCity(pulsechainV4.id),
                     'https://rpc-testnet-pulsechain.g4mm4.io',
                     'https://rpc.v4.testnet.pulsechain.com',
                 ],
@@ -233,6 +236,38 @@ export const chainsMetadata = {
         },
     },
 };
+/**
+ * The RPC endpoints the Gibs interface uses, FOR DEMOS ONLY.
+ *
+ * Each proxied chain's list starts with valve.city's shared `vk_demo` key and
+ * falls through to that chain's public endpoints in {@link chainsMetadata}.
+ * Binance Smart Chain has no valve.city entry, so its list is the public one.
+ *
+ * WHY IT IS A SEPARATE, NAMED LIST. The key is public, so shipping it discloses
+ * nothing. But its rate budget is shared by everybody who uses it, and the proxy
+ * belongs to the Gibs Finance operator. A wallet that inherits it without
+ * choosing it puts its users' reads on somebody else's budget and uptime. So no
+ * reader in this package uses it, and `chainsMetadata` does not carry it. A
+ * caller who wants it asks for it by this name.
+ *
+ * Production callers: pass your own viem clients to every reader.
+ */
+export const demoRpcUrls = Object.freeze({
+    [Chains.PLS]: [valveCity(pulsechain.id), ...chainsMetadata[Chains.PLS].rpcUrls.default.http],
+    [Chains.ETH]: [valveCity(mainnet.id), ...chainsMetadata[Chains.ETH].rpcUrls.default.http],
+    [Chains.BNB]: [...chainsMetadata[Chains.BNB].rpcUrls.default.http],
+    [Chains.SEP]: [valveCity(sepolia.id), ...chainsMetadata[Chains.SEP].rpcUrls.default.http],
+    [Chains.V4PLS]: [valveCity(pulsechainV4.id), ...chainsMetadata[Chains.V4PLS].rpcUrls.default.http],
+});
+/**
+ * The demo endpoints for one chain, FOR DEMOS ONLY. See {@link demoRpcUrls}.
+ *
+ * @param chainId - a decimal chain id
+ * @returns a copy of the chain's demo endpoints, or an empty list for a chain the bridge does not cross
+ */
+export const demoRpcUrlsFor = (chainId) => [
+    ...(demoRpcUrls[toChain(chainId)] ?? []),
+];
 /**
  * Every chain this bridge itself carries funds across, in the order the
  * metadata declares them.

package/dist/cjs/abis.d.ts

@@ -0,0 +1 @@
+export * from '@gibs/abis';