@gibs/bridge-client 1.12.0

package/dist/cache.d.ts

@@ -0,0 +1,9 @@
+export declare class Cache {
+    protected ttl: number;
+    cache: Map<string, {
+        time: number;
+        value: unknown;
+    }>;
+    constructor(ttl?: number);
+    clearStale(): number;
+}

package/dist/cache.js

@@ -0,0 +1,17 @@
+export class Cache {
+    ttl;
+    cache = new Map();
+    constructor(ttl = 1000 * 60) {
+        this.ttl = ttl;
+    }
+    clearStale() {
+        const now = Date.now();
+        for (const k of this.cache.keys()) {
+            const { time } = this.cache.get(k);
+            if (now - time > this.ttl) {
+                this.cache.delete(k);
+            }
+        }
+        return now;
+    }
+}

package/dist/chain-read.d.ts

@@ -0,0 +1,27 @@
+import { type Hex } from 'viem';
+/** Inputs identifying an ERC-20 allowance to read: which token, owner, and spender on which chain. */
+export type ApprovalParameters = {
+    /** The ERC-20 token contract address. */
+    token: Hex;
+    /** The address allowed to spend the owner's tokens. */
+    spender: Hex;
+    /** The chain the token lives on. */
+    chainId: number;
+    /** The token owner whose allowance is being read. */
+    account: Hex;
+};
+/**
+ * Reads an ERC-20 allowance for the given owner/spender pair on a chain.
+ *
+ * The native asset (`zeroAddress`) has no allowance concept, so it returns
+ * `maxUint256` (always sufficient). A missing or malformed owner address throws,
+ * matching the Svelte source — callers that may lack an account must guard first.
+ *
+ * Ported verbatim from `chain-read.svelte.ts`; the only change is sourcing
+ * {@link clientFromChain} from the framework-agnostic `wallet/clientFromChain`
+ * module instead of the Svelte `input.svelte` rune store.
+ *
+ * @param params The token, spender, chain, and owner to read.
+ * @returns The allowance in token base units.
+ */
+export declare const checkAllowance: ({ token, spender, chainId, account }: ApprovalParameters) => Promise<bigint>;

package/dist/chain-read.js

@@ -0,0 +1,31 @@
+import { erc20Abi, isAddress, maxUint256, zeroAddress } from 'viem';
+import { clientFromChain } from './client.js';
+/**
+ * Reads an ERC-20 allowance for the given owner/spender pair on a chain.
+ *
+ * The native asset (`zeroAddress`) has no allowance concept, so it returns
+ * `maxUint256` (always sufficient). A missing or malformed owner address throws,
+ * matching the Svelte source — callers that may lack an account must guard first.
+ *
+ * Ported verbatim from `chain-read.svelte.ts`; the only change is sourcing
+ * {@link clientFromChain} from the framework-agnostic `wallet/clientFromChain`
+ * module instead of the Svelte `input.svelte` rune store.
+ *
+ * @param params The token, spender, chain, and owner to read.
+ * @returns The allowance in token base units.
+ */
+export const checkAllowance = async ({ token, spender, chainId, account }) => {
+    if (token === zeroAddress) {
+        return maxUint256;
+    }
+    const client = clientFromChain(chainId);
+    if (!account || !isAddress(account)) {
+        throw new Error('No account');
+    }
+    return await client.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: 'allowance',
+        args: [account, spender],
+    });
+};

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { PublicClient } from 'viem';
+/**
+ * The request-batching setting for a chain's client: `false` to disable batching
+ * for chains that reject batch bodies (see {@link chainsWithoutRpcBatching}), or
+ * `undefined` to use the transport's default batching.
+ *
+ * @param chainId - the chain to resolve the batch setting for
+ * @returns `false` when batching must be disabled, otherwise `undefined`
+ */
+export declare const rpcBatchSetting: (chainId: number) => false | undefined;
+/**
+ * Returns a viem {@link PublicClient} for a chain, reusing the cached instance
+ * while the chain's endpoint list is unchanged. The cache key is derived from the
+ * chain id plus its urls, so editing the list yields a fresh client and lets the
+ * previous transport be garbage collected.
+ *
+ * The url source is the user-editable endpoint table; when it has no entry — or
+ * an EMPTY one — the chain's own defaults are used instead. The empty case is not
+ * hypothetical: the endpoint editor lets a user delete every entry for a chain,
+ * and an empty array is truthy, so a `||` fallback here quietly built a client
+ * with no transports at all and every read on that chain failed until the list
+ * was restored.
+ *
+ * @param chainId - the chain to build a client for
+ * @returns the cached or freshly built public client
+ */
+export declare const clientFromChain: (chainId: number) => PublicClient;

package/dist/client.js

@@ -0,0 +1,78 @@
+import { chainKey, clientCache, clientFromChain as buildClient } from '@gibs/common/client';
+import * as _ from 'lodash-es';
+import { bsc } from 'viem/chains';
+import * as endpoints from './endpoints.js';
+import { evmChainsById } from './networks.js';
+/**
+ * Chains whose public nodes reject BATCH remote procedure call requests (an
+ * array-wrapped body). viem otherwise wraps even a single request in an array
+ * when batching is on, which those nodes refuse — so every call fails and is
+ * retried, burning through requests. Their clients are built with batching
+ * disabled so requests go out as plain objects the node accepts. Binance Smart
+ * Chain's `publicnode` endpoint is the known offender.
+ */
+const chainsWithoutRpcBatching = new Set([bsc.id]);
+/**
+ * The request-batching setting for a chain's client: `false` to disable batching
+ * for chains that reject batch bodies (see {@link chainsWithoutRpcBatching}), or
+ * `undefined` to use the transport's default batching.
+ *
+ * @param chainId - the chain to resolve the batch setting for
+ * @returns `false` when batching must be disabled, otherwise `undefined`
+ */
+export const rpcBatchSetting = (chainId) => chainsWithoutRpcBatching.has(chainId) ? false : undefined;
+/**
+ * A chain's own default endpoints, used when the editable table has no entry.
+ *
+ * @param chainId - the chain to look up
+ * @returns the chain's default endpoints (possibly empty)
+ */
+const defaultUrlsFor = (chainId) => {
+    if (!chainId) {
+        throw new Error('chainId is required');
+    }
+    const chain = evmChainsById.get(chainId);
+    if (!chain) {
+        return [];
+    }
+    const { http } = chain.rpcUrls.default;
+    return [...(http ?? [])];
+};
+/**
+ * Returns a viem {@link PublicClient} for a chain, reusing the cached instance
+ * while the chain's endpoint list is unchanged. The cache key is derived from the
+ * chain id plus its urls, so editing the list yields a fresh client and lets the
+ * previous transport be garbage collected.
+ *
+ * The url source is the user-editable endpoint table; when it has no entry — or
+ * an EMPTY one — the chain's own defaults are used instead. The empty case is not
+ * hypothetical: the endpoint editor lets a user delete every entry for a chain,
+ * and an empty array is truthy, so a `||` fallback here quietly built a client
+ * with no transports at all and every read on that chain failed until the list
+ * was restored.
+ *
+ * @param chainId - the chain to build a client for
+ * @returns the cached or freshly built public client
+ */
+export const clientFromChain = (chainId) => {
+    const stored = endpoints.get(chainId);
+    const urls = _.compact(stored?.length ? stored : defaultUrlsFor(chainId));
+    const key = chainKey(chainId, urls);
+    const existing = clientCache.get(chainId);
+    if (existing && existing.key === key) {
+        return existing.client;
+    }
+    const chain = evmChainsById.get(chainId);
+    if (!chain) {
+        // Previously this searched every chain viem ships and asserted a hit with a
+        // `!`. That answered for chains this application does not support, and did
+        // so badly: there are no endpoints for them, so the client was built with
+        // none and silently fell back to viem's own public node — or, for a chain
+        // viem had never heard of, died on an unreadable `undefined.id` several
+        // frames away. Both are worse than saying so here.
+        throw new Error(`Chain ${chainId} is not one of the supported networks.`);
+    }
+    const client = buildClient({ chain, urls, batch: rpcBatchSetting(chainId) });
+    clientCache.set(chainId, { key, client });
+    return client;
+};

package/dist/endpoints.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The user-editable table of remote procedure call endpoints, per chain.
+ *
+ * This is the single source every read in the application resolves through, so
+ * that replacing a blocked node in one place moves every balance read, every
+ * receipt poll and every contract call at once.
+ *
+ * It is a plain external store — `subscribe` plus `getSnapshot` — rather than a
+ * hook, so it can be consumed by React through `useSyncExternalStore`, by another
+ * framework, or by nothing at all. The React binding lives with the application;
+ * nothing here imports a rendering library.
+ */
+/** One chain's identifier paired with its endpoint list. */
+export type EndpointEntry = [chainId: number, urls: string[]];
+/**
+ * The minimal shape of browser storage this module needs.
+ *
+ * Injectable rather than reaching for `localStorage` directly: the store then
+ * works under a test runner, on a server, and in a host that keeps preferences
+ * somewhere other than the browser — and a test can assert what was persisted
+ * without installing a global.
+ */
+export type EndpointStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
+/**
+ * The storage key holding the endpoint table.
+ *
+ * The literal must not change: users have their own nodes saved under it, and a
+ * rename silently reverts every one of them to the defaults on the next load.
+ */
+export declare const ENDPOINTS_STORAGE_KEY = "rpcs";
+/** The bridge's production chains. */
+export declare const productionSeed: EndpointEntry[];
+/** The bridge's test chains, for a build that is not production. */
+export declare const testnetSeed: EndpointEntry[];
+/**
+ * Replaces the seed table and the persistence target.
+ *
+ * Both fields are optional so a host can override one without restating the
+ * other. The loaded table is discarded either way, so the next read rebuilds
+ * from the new seed merged with whatever is stored — which means this is safe to
+ * call after something has already read, not only at startup.
+ *
+ * @param options.seed - the entries to start from when storage holds nothing
+ * @param options.storage - where the table is persisted, or null for nowhere
+ */
+export declare const configureEndpoints: ({ seed: nextSeed, storage: nextStorage, }: {
+    seed?: EndpointEntry[];
+    storage?: EndpointStorage | null;
+}) => void;
+/** Serializes one chain's list the way it is persisted: `chainId,url,url`. */
+export declare const key: (chain: number, list: string[]) => string;
+/**
+ * Parses a stored blob back into a table, merged onto the seeded entries.
+ *
+ * @param entry - the persisted blob, or null when nothing is stored
+ * @returns the merged table, or null when there was nothing to parse
+ */
+export declare const parse: (entry: string | null) => Map<number, string[]> | null;
+/** Serializes every entry, one chain per line. */
+export declare const stringify: () => string;
+/**
+ * Subscribes to changes in the endpoint table.
+ *
+ * @param listener - called after any mutation
+ * @returns the unsubscribe function
+ */
+export declare const subscribe: (listener: () => void) => (() => void);
+/**
+ * The current table.
+ *
+ * The identity is stable until something changes it — every mutating accessor
+ * replaces the map rather than mutating in place — which is what lets a caller
+ * use this directly as a `useSyncExternalStore` snapshot without re-rendering
+ * forever.
+ */
+export declare const getSnapshot: () => Map<number, string[]>;
+/** The url list for a chain, or null when it has no entry. */
+export declare const get: (chain: number) => string[] | null;
+/** All `[chainId, urls]` entries as a fresh array. */
+export declare const entries: () => [number, string[]][];
+/** Replaces a chain's url list, persists it, and notifies subscribers. */
+export declare const setEndpoints: (chain: number, list: string[]) => void;
+/** Replaces the url at index `i`; a no-op when the value is unchanged. */
+export declare const update: (chain: number, i: number, url: string) => void;
+/** Removes the url at index `i`. */
+export declare const remove: (chain: number, i: number) => void;
+/**
+ * Applies `addition` to a chain's url list and stores the result, keeping only
+ * the first item if it is empty (the leading "add new" slot) and dropping every
+ * other empty. A no-op when the filtered list is unchanged.
+ */
+export declare const add: (chain: number, addition?: (urls: string[]) => string[]) => void;
+/** Whether `list` already contains the chain's canonical default endpoint. */
+export declare const hasDefault: (chain: number, list: string[]) => boolean;
+/** Appends the chain's canonical default endpoints back onto its list. */
+export declare const restoreDefault: (chain: number) => void;

package/dist/endpoints.js

@@ -0,0 +1,175 @@
+import { chainsMetadata } from '@gibs/bridge-sdk/chains';
+import { Chains, toChain } from '@gibs/bridge-sdk/config';
+import * as _ from 'lodash-es';
+/**
+ * The storage key holding the endpoint table.
+ *
+ * The literal must not change: users have their own nodes saved under it, and a
+ * rename silently reverts every one of them to the defaults on the next load.
+ */
+export const ENDPOINTS_STORAGE_KEY = 'rpcs';
+/** Builds a seed table from the bridge metadata for the given chains. */
+const seedFor = (chains) => chains.map((chain) => [Number(chain), [...chainsMetadata[chain].rpcUrls.default.http]]);
+/** The bridge's production chains. */
+export const productionSeed = seedFor([Chains.PLS, Chains.ETH, Chains.BNB]);
+/** The bridge's test chains, for a build that is not production. */
+export const testnetSeed = seedFor([Chains.V4PLS, Chains.SEP]);
+/** The seed the next load starts from. */
+let seed = productionSeed;
+/** Where the table is persisted, or null when there is nowhere. */
+let storage = typeof localStorage === 'undefined' ? null : localStorage;
+/** The live table, or null while it has not been loaded yet. */
+let value = null;
+const listeners = new Set();
+const emit = () => {
+    for (const listener of listeners) {
+        listener();
+    }
+};
+/**
+ * Replaces the seed table and the persistence target.
+ *
+ * Both fields are optional so a host can override one without restating the
+ * other. The loaded table is discarded either way, so the next read rebuilds
+ * from the new seed merged with whatever is stored — which means this is safe to
+ * call after something has already read, not only at startup.
+ *
+ * @param options.seed - the entries to start from when storage holds nothing
+ * @param options.storage - where the table is persisted, or null for nowhere
+ */
+export const configureEndpoints = ({ seed: nextSeed, storage: nextStorage, }) => {
+    if (nextSeed !== undefined) {
+        seed = nextSeed;
+    }
+    if (nextStorage !== undefined) {
+        storage = nextStorage;
+    }
+    value = null;
+    emit();
+};
+/** Serializes one chain's list the way it is persisted: `chainId,url,url`. */
+export const key = (chain, list) => `${chain},${list.join(',')}`;
+/**
+ * Parses a stored blob back into a table, merged onto the seeded entries.
+ *
+ * @param entry - the persisted blob, or null when nothing is stored
+ * @returns the merged table, or null when there was nothing to parse
+ */
+export const parse = (entry) => {
+    if (!entry) {
+        return null;
+    }
+    const stored = entry.split('\n').map((row) => {
+        const [chain, ...list] = row.split(',');
+        return [Number(chain), _.compact(list)];
+    });
+    return new Map([...seed, ...stored]);
+};
+/**
+ * Reads the persisted table, or null when there is nothing usable to read.
+ *
+ * Any failure falls back to the seeded defaults rather than propagating: a
+ * corrupt or unreadable entry must not be the reason the application cannot
+ * reach a chain at all.
+ */
+const readStored = () => {
+    if (!storage) {
+        return null;
+    }
+    try {
+        return parse(storage.getItem(ENDPOINTS_STORAGE_KEY));
+    }
+    catch (error) {
+        console.error('unable to read the stored endpoint list', error);
+        return null;
+    }
+};
+/** The table, loaded from storage the first time it is asked for. */
+const loaded = () => {
+    if (!value) {
+        value = readStored() ?? new Map(seed);
+    }
+    return value;
+};
+/** Serializes every entry, one chain per line. */
+export const stringify = () => [...loaded().entries()].map(([chainId, list]) => key(chainId, list)).join('\n');
+/**
+ * Subscribes to changes in the endpoint table.
+ *
+ * @param listener - called after any mutation
+ * @returns the unsubscribe function
+ */
+export const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+/**
+ * The current table.
+ *
+ * The identity is stable until something changes it — every mutating accessor
+ * replaces the map rather than mutating in place — which is what lets a caller
+ * use this directly as a `useSyncExternalStore` snapshot without re-rendering
+ * forever.
+ */
+export const getSnapshot = () => loaded();
+/** The url list for a chain, or null when it has no entry. */
+export const get = (chain) => loaded().get(chain) ?? null;
+/** All `[chainId, urls]` entries as a fresh array. */
+export const entries = () => [...loaded().entries()];
+/** Replaces a chain's url list, persists it, and notifies subscribers. */
+export const setEndpoints = (chain, list) => {
+    const next = new Map(loaded());
+    next.set(chain, list);
+    value = next;
+    storage?.setItem(ENDPOINTS_STORAGE_KEY, stringify());
+    emit();
+};
+/** Replaces the url at index `i`; a no-op when the value is unchanged. */
+export const update = (chain, i, url) => {
+    const list = get(chain) ?? [];
+    if (list[i] === url) {
+        return;
+    }
+    const next = list.slice(0);
+    next[i] = url;
+    setEndpoints(chain, next);
+};
+/** Removes the url at index `i`. */
+export const remove = (chain, i) => {
+    const next = (get(chain) ?? []).slice(0);
+    next.splice(i, 1);
+    setEndpoints(chain, next);
+};
+/**
+ * Applies `addition` to a chain's url list and stores the result, keeping only
+ * the first item if it is empty (the leading "add new" slot) and dropping every
+ * other empty. A no-op when the filtered list is unchanged.
+ */
+export const add = (chain, addition = (urls) => [''].concat(urls)) => {
+    const before = get(chain) ?? [];
+    const list = addition(before.slice(0));
+    const filteredList = list.filter((val, i) => {
+        // only the first item in the list may be empty
+        if (!val && !i) {
+            return true;
+        }
+        return !!val;
+    });
+    if (_.isEqual(before, filteredList)) {
+        return;
+    }
+    setEndpoints(chain, filteredList);
+};
+/** Whether `list` already contains the chain's canonical default endpoint. */
+export const hasDefault = (chain, list) => {
+    const defaultUrl = chainsMetadata[toChain(chain)].rpcUrls.default.http[0];
+    if (!defaultUrl)
+        return false;
+    return list.includes(defaultUrl);
+};
+/** Appends the chain's canonical default endpoints back onto its list. */
+export const restoreDefault = (chain) => {
+    add(chain, (l) => l.concat(chainsMetadata[toChain(chain)].rpcUrls.default.http));
+};

package/dist/image.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Chain-logo resolution, in one place.
+ *
+ * Two image services are involved and neither covers every chain a route can
+ * start from, which is why this is a module rather than an inline template
+ * string: gib.show keys on real chain ids, while the non-Ethereum origins reach
+ * us under Relay's own pseudo identifiers (Solana, Bitcoin, Tron, The Open
+ * Network, Eclipse). Asking gib.show for one of those returns a 404, and a 404
+ * in an `<img src>` is drawn by the browser as a broken-image glyph — so the
+ * mistake surfaces as a visual blemish on the token pill rather than as an
+ * error anyone would go looking for.
+ */
+/**
+ * Relay's public chain-icon service, keyed on Relay's own chain identifiers —
+ * the authority for the ids it invented.
+ *
+ * The `light` variant is the full-colour brand mark (the pair is light/dark
+ * BACKGROUND, not a monochrome inversion), so one variant serves both of our
+ * themes. Not every id is populated — The Open Network currently answers 403 —
+ * which is why callers must tolerate a badge that fails to load.
+ *
+ * @param chainId - a Relay chain identifier
+ * @returns the icon url
+ */
+export declare const relayChainIconUrl: (chainId: number) => string;
+/**
+ * Resolves the logo url for a chain, choosing the service that can actually
+ * serve it.
+ *
+ * A chain we bundle the mark for wins outright ({@link bundledChainLogoUri}).
+ * Otherwise Ethereum-Virtual-Machine chains go to gib.show, honouring the
+ * configured image root (so a self-hosted deployment is respected) rather than
+ * hard-coding the public host, and everything else is a Relay identifier and
+ * goes to Relay.
+ *
+ * @param chainId - the decimal chain id, Relay's pseudo identifiers included
+ * @param displayPx - the CSS pixel size the logo renders at; when supplied,
+ *   gib.show is asked for twice that in webp per its retina guidance. Ignored
+ *   for a Relay-served icon and for a bundled asset, neither of which takes
+ *   sizing parameters.
+ * @returns an image url for the chain
+ */
+export declare const chainLogoUrl: ({ chainId, displayPx, }: {
+    chainId: number;
+    displayPx?: number;
+}) => string;

package/dist/image.js

@@ -0,0 +1,83 @@
+import * as imageLinks from '@gibs/bridge-sdk/image-links';
+import { ecosystemByChainId, relayChainIds } from '@gibs/bridge-sdk/relay-quote';
+/**
+ * Chain-logo resolution, in one place.
+ *
+ * Two image services are involved and neither covers every chain a route can
+ * start from, which is why this is a module rather than an inline template
+ * string: gib.show keys on real chain ids, while the non-Ethereum origins reach
+ * us under Relay's own pseudo identifiers (Solana, Bitcoin, Tron, The Open
+ * Network, Eclipse). Asking gib.show for one of those returns a 404, and a 404
+ * in an `<img src>` is drawn by the browser as a broken-image glyph — so the
+ * mistake surfaces as a visual blemish on the token pill rather than as an
+ * error anyone would go looking for.
+ */
+/**
+ * Relay's public chain-icon service, keyed on Relay's own chain identifiers —
+ * the authority for the ids it invented.
+ *
+ * The `light` variant is the full-colour brand mark (the pair is light/dark
+ * BACKGROUND, not a monochrome inversion), so one variant serves both of our
+ * themes. Not every id is populated — The Open Network currently answers 403 —
+ * which is why callers must tolerate a badge that fails to load.
+ *
+ * @param chainId - a Relay chain identifier
+ * @returns the icon url
+ */
+export const relayChainIconUrl = (chainId) => `https://assets.relay.link/icons/${chainId}/light.png`;
+/**
+ * Chains we ship the mark for ourselves, because neither service will serve it.
+ *
+ * The Open Network is the only entry today: gib.show does not know Relay's
+ * pseudo id, and Relay's own service answers 403 for it — the one chain its
+ * authority does not actually cover. Between the two, the badge had no source at
+ * all and rendered as nothing via the hide-on-error path, which reads as a
+ * missing chain rather than a missing image.
+ *
+ * The paths are RELATIVE (no leading slash): the reference deployment publishes
+ * to the InterPlanetary File System, where a leading slash resolves against the
+ * gateway root instead of the deployed directory.
+ *
+ * A CONSUMER CONTRACT: this package names the asset but cannot ship it. An
+ * application using these urls must serve a file at each path from its own
+ * static root, or the badge silently renders as nothing. The application-side
+ * check is `ui/src/lib/tokens/bundledChainLogo.test.ts`.
+ *
+ * This is checked BEFORE either service, so an entry here is the last word — the
+ * point is to stop depending on a service that has already been observed to fail
+ * for the chain.
+ */
+const bundledChainLogoUri = {
+    [relayChainIds.ton]: 'images/networks/ton.png',
+};
+/**
+ * Resolves the logo url for a chain, choosing the service that can actually
+ * serve it.
+ *
+ * A chain we bundle the mark for wins outright ({@link bundledChainLogoUri}).
+ * Otherwise Ethereum-Virtual-Machine chains go to gib.show, honouring the
+ * configured image root (so a self-hosted deployment is respected) rather than
+ * hard-coding the public host, and everything else is a Relay identifier and
+ * goes to Relay.
+ *
+ * @param chainId - the decimal chain id, Relay's pseudo identifiers included
+ * @param displayPx - the CSS pixel size the logo renders at; when supplied,
+ *   gib.show is asked for twice that in webp per its retina guidance. Ignored
+ *   for a Relay-served icon and for a bundled asset, neither of which takes
+ *   sizing parameters.
+ * @returns an image url for the chain
+ */
+export const chainLogoUrl = ({ chainId, displayPx, }) => {
+    const bundled = bundledChainLogoUri[chainId];
+    if (bundled !== undefined) {
+        return bundled;
+    }
+    if (ecosystemByChainId(chainId) !== 'evm') {
+        return relayChainIconUrl(chainId);
+    }
+    const base = imageLinks.network(chainId);
+    if (displayPx === undefined) {
+        return base;
+    }
+    return `${base}?w=${displayPx * 2}&h=${displayPx * 2}&format=webp`;
+};

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Browser-side machinery for talking to the chains the bridge supports.
+ *
+ * Everything here is framework-free. It is the layer between `@gibs/bridge-sdk`,
+ * which knows about pathways, quotes and fees but performs no input or output,
+ * and an application, which renders. Endpoint resolution, public clients, chain
+ * reads, token metadata, caching and logo resolution all live here so that a
+ * second application does not have to rebuild them — and so that the rules they
+ * encode (which node answers for a chain, which image service knows a chain's
+ * mark) have exactly one home.
+ *
+ * Subpath exports are the intended way in — `@gibs/bridge-client/client`,
+ * `/endpoints`, `/image` and so on — so that importing one does not pull the
+ * rest. This barrel exists for consumers that would rather not think about it.
+ */
+export { Cache } from './cache.js';
+export { checkAllowance, type ApprovalParameters } from './chain-read.js';
+export { clientFromChain, rpcBatchSetting } from './client.js';
+export { add, configureEndpoints, ENDPOINTS_STORAGE_KEY, entries, get, getSnapshot, hasDefault, key, parse, productionSeed, remove, restoreDefault, setEndpoints, stringify, subscribe, testnetSeed, update, type EndpointEntry, type EndpointStorage, } from './endpoints.js';
+export { chainLogoUrl, relayChainIconUrl } from './image.js';
+export { evmChains, evmChainsById, isSupportedEvmChain } from './networks.js';
+export { getBridgeTokenMetadata, getStoreKey, getStoreSize, getTokenAddressFromBridge, getTokenChainIdFromBridge, getTokenMetadata, loadTokenMetadata, parseChainScopedAddress, parseTokenKey, type ChainScopedAddress, } from './token-metadata.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Browser-side machinery for talking to the chains the bridge supports.
+ *
+ * Everything here is framework-free. It is the layer between `@gibs/bridge-sdk`,
+ * which knows about pathways, quotes and fees but performs no input or output,
+ * and an application, which renders. Endpoint resolution, public clients, chain
+ * reads, token metadata, caching and logo resolution all live here so that a
+ * second application does not have to rebuild them — and so that the rules they
+ * encode (which node answers for a chain, which image service knows a chain's
+ * mark) have exactly one home.
+ *
+ * Subpath exports are the intended way in — `@gibs/bridge-client/client`,
+ * `/endpoints`, `/image` and so on — so that importing one does not pull the
+ * rest. This barrel exists for consumers that would rather not think about it.
+ */
+export { Cache } from './cache.js';
+export { checkAllowance } from './chain-read.js';
+export { clientFromChain, rpcBatchSetting } from './client.js';
+export { add, configureEndpoints, ENDPOINTS_STORAGE_KEY, entries, get, getSnapshot, hasDefault, key, parse, productionSeed, remove, restoreDefault, setEndpoints, stringify, subscribe, testnetSeed, update, } from './endpoints.js';
+export { chainLogoUrl, relayChainIconUrl } from './image.js';
+export { evmChains, evmChainsById, isSupportedEvmChain } from './networks.js';
+export { getBridgeTokenMetadata, getStoreKey, getStoreSize, getTokenAddressFromBridge, getTokenChainIdFromBridge, getTokenMetadata, loadTokenMetadata, parseChainScopedAddress, parseTokenKey, } from './token-metadata.js';

package/dist/networks.d.ts

@@ -0,0 +1,30 @@
+import type { Chain } from 'viem';
+/**
+ * Every Ethereum-Virtual-Machine chain this client can build a public client for.
+ *
+ * The leading entries are the bridge's own chains; the rest are the routing
+ * destinations reachable through the aggregators. Ordering is preserved because
+ * chain pickers render it directly.
+ *
+ * Solana and Bitcoin are deliberately absent. They are supported ORIGINS, but
+ * they are not Ethereum-style chains: they are keyed by a genesis hash and by
+ * their own string rather than by a number, and nothing here can build a client
+ * for them. Anything wallet-facing that needs them keys off the aggregator's
+ * chain identifiers instead.
+ */
+export declare const evmChains: readonly Chain[];
+/**
+ * Lookup from a chain id to its viem chain definition, for supported chains only.
+ *
+ * Keyed as `string | number` because callers hold ids that have been through a
+ * url, a wallet, or a quote response, and a lookup that silently misses on a
+ * numeric-versus-string mismatch reads as "chain not supported".
+ */
+export declare const evmChainsById: Map<string | number, Chain>;
+/**
+ * Whether this client can reach a chain over Ethereum-style remote procedure calls.
+ *
+ * @param chainId - the chain id to test
+ * @returns true when the chain has a definition here
+ */
+export declare const isSupportedEvmChain: (chainId: number) => boolean;

package/dist/networks.js

@@ -0,0 +1,72 @@
+// NAMED imports, deliberately, and never `import * as chains from 'viem/chains'`.
+// A namespace import that is read dynamically (`Object.values`, or indexing by a
+// computed key) defeats tree-shaking outright: all ~700 chain definitions viem
+// ships get emitted to answer a question about the few dozen below, which
+// measured 255 kB of an application entry chunk. Naming each one keeps only what
+// is named.
+import { abstract, arbitrum, aurora, avalanche, base, berachain, blast, boba, bsc, celo, cronos, cronoszkEVM, fantom, fraxtal, fuse, gnosis, gravity, immutableZkEvm, linea, mainnet, mantle, optimism, polygon, polygonZkEvm, pulsechain, pulsechainV4, rootstock, scroll, sei, sepolia, sonic, taiko, unichain, worldchain, zksync, } from 'viem/chains';
+/**
+ * Every Ethereum-Virtual-Machine chain this client can build a public client for.
+ *
+ * The leading entries are the bridge's own chains; the rest are the routing
+ * destinations reachable through the aggregators. Ordering is preserved because
+ * chain pickers render it directly.
+ *
+ * Solana and Bitcoin are deliberately absent. They are supported ORIGINS, but
+ * they are not Ethereum-style chains: they are keyed by a genesis hash and by
+ * their own string rather than by a number, and nothing here can build a client
+ * for them. Anything wallet-facing that needs them keys off the aggregator's
+ * chain identifiers instead.
+ */
+export const evmChains = [
+    mainnet,
+    pulsechain,
+    sepolia,
+    pulsechainV4,
+    bsc,
+    arbitrum,
+    base,
+    blast,
+    avalanche,
+    polygon,
+    scroll,
+    optimism,
+    linea,
+    zksync,
+    polygonZkEvm,
+    gnosis,
+    fantom,
+    fuse,
+    boba,
+    unichain,
+    aurora,
+    sei,
+    immutableZkEvm,
+    sonic,
+    gravity,
+    taiko,
+    cronos,
+    cronoszkEVM,
+    fraxtal,
+    abstract,
+    rootstock,
+    celo,
+    worldchain,
+    mantle,
+    berachain,
+];
+/**
+ * Lookup from a chain id to its viem chain definition, for supported chains only.
+ *
+ * Keyed as `string | number` because callers hold ids that have been through a
+ * url, a wallet, or a quote response, and a lookup that silently misses on a
+ * numeric-versus-string mismatch reads as "chain not supported".
+ */
+export const evmChainsById = new Map(evmChains.map((chain) => [chain.id, chain]));
+/**
+ * Whether this client can reach a chain over Ethereum-style remote procedure calls.
+ *
+ * @param chainId - the chain id to test
+ * @returns true when the chain has a definition here
+ */
+export const isSupportedEvmChain = (chainId) => evmChainsById.has(chainId);

package/dist/token-metadata.d.ts

@@ -0,0 +1,21 @@
+import type { TokenMetadata } from '@gibs/bridge-sdk/types';
+import type { Hex } from 'viem';
+export type ChainScopedAddress = `${number}:${Hex}`;
+export declare function getStoreKey(chainId: number, tokenAddress: string): ChainScopedAddress;
+export declare function parseChainScopedAddress(key: ChainScopedAddress): {
+    chainId: number;
+    address: Hex;
+};
+export declare function parseTokenKey(key: string): {
+    chainId: number;
+    address: Hex;
+};
+export declare function getTokenMetadata(chainId: number, tokenAddress: string): TokenMetadata | null;
+export declare function loadTokenMetadata(tokens: Array<{
+    chainId: number;
+    address: Hex;
+}>): Promise<void>;
+export declare function getStoreSize(): number;
+export declare function getTokenAddressFromBridge(bridge: any): string;
+export declare function getTokenChainIdFromBridge(bridge: any): number;
+export declare function getBridgeTokenMetadata(bridge: any): TokenMetadata | null;

package/dist/token-metadata.js

@@ -0,0 +1,245 @@
+import { nativeTokenName, nativeTokenSymbol, toChain } from '@gibs/bridge-sdk/config';
+import * as _ from 'lodash-es';
+import { erc20Abi, erc20Abi_bytes32, hexToString, zeroAddress } from 'viem';
+import { clientFromChain } from './client.js';
+import { evmChainsById } from './networks.js';
+const bytes32Whitelist = new Set();
+// In-memory store for token metadata (loaded once, no persistence)
+const tokenMetadataStore = new Map();
+// Generate store key
+export function getStoreKey(chainId, tokenAddress) {
+    return `${chainId}:${tokenAddress.toLowerCase()}`;
+}
+// Parse a ChainScopedAddress into its components
+export function parseChainScopedAddress(key) {
+    const [chainIdStr, address] = key.split(':');
+    const chainId = parseInt(chainIdStr ?? '', 10);
+    if (isNaN(chainId)) {
+        throw new Error(`Invalid chain ID in ChainScopedAddress: ${chainIdStr}`);
+    }
+    if (!address || !address.startsWith('0x')) {
+        throw new Error(`Invalid address in ChainScopedAddress: ${address}`);
+    }
+    return {
+        chainId,
+        address: address,
+    };
+}
+// Parse a string key (chainId:address format) into its components with proper types
+export function parseTokenKey(key) {
+    const [chainIdStr, address] = key.split(':');
+    const chainId = parseInt(chainIdStr ?? '', 10);
+    if (isNaN(chainId)) {
+        throw new Error(`Invalid chain ID in token key: ${chainIdStr}`);
+    }
+    if (!address) {
+        throw new Error(`Invalid address in token key: ${address}`);
+    }
+    // Ensure address is properly formatted as Hex
+    const hexAddress = address.startsWith('0x') ? address : `0x${address}`;
+    return {
+        chainId,
+        address: hexAddress,
+    };
+}
+// Get native token metadata
+function getNativeTokenMetadata(chainId) {
+    const chain = evmChainsById.get(chainId);
+    // Safely get native token info from SDK
+    let name = chain?.nativeCurrency?.name || 'Ether';
+    let symbol = chain?.nativeCurrency?.symbol || 'ETH';
+    const decimals = chain?.nativeCurrency?.decimals || 18;
+    // Try to get more specific info from SDK if available
+    try {
+        const chainKey = toChain(chainId);
+        const sdkName = nativeTokenName[chainKey];
+        const sdkSymbol = nativeTokenSymbol[chainKey];
+        if (sdkName) {
+            name = sdkName;
+        }
+        if (sdkSymbol) {
+            symbol = sdkSymbol;
+        }
+    }
+    catch {
+        // Fallback to viem chain info
+    }
+    return { name, symbol, decimals };
+}
+// Batch fetch token metadata for multiple tokens on the same chain
+async function batchFetchTokenMetadata(chainId, tokenAddresses) {
+    const results = new Map();
+    if (tokenAddresses.length === 0)
+        return results;
+    // Get the chain and client
+    const chain = evmChainsById.get(chainId);
+    if (!chain) {
+        throw new Error(`Chain not found for chainId: ${chainId}`);
+    }
+    const client = clientFromChain(chainId);
+    // Separate native tokens from ERC20 tokens
+    const nativeTokens = [];
+    const erc20Tokens = [];
+    tokenAddresses.forEach((address) => {
+        if (address === zeroAddress || address.toLowerCase() === zeroAddress.toLowerCase()) {
+            nativeTokens.push(address);
+        }
+        else {
+            erc20Tokens.push(address);
+        }
+    });
+    // Handle native tokens
+    const nativeMetadata = getNativeTokenMetadata(chainId);
+    nativeTokens.forEach((address) => {
+        results.set(address.toLowerCase(), nativeMetadata);
+    });
+    // Handle ERC20 tokens with batch multicall
+    if (erc20Tokens.length === 0) {
+        // console.log(`No ERC20 tokens to process for chain ${chainId}`)
+        return results;
+    }
+    // console.log(`Processing ${erc20Tokens.length} ERC20 tokens for chain ${chainId}:`, erc20Tokens)
+    const addressChunks = _.chunk(erc20Tokens, 100);
+    const methods = ['symbol', 'name', 'decimals'];
+    const addressChunksToCallChunks = (addressChunks, abi) => addressChunks.map((chunk) => chunk.map((address) => methods.map((functionName) => ({
+        functionName,
+        address,
+        abi: abi(address),
+        allowFailure: true,
+        args: [],
+    }))));
+    // Try with standard ERC20 ABI first
+    const chunkedCalls = addressChunksToCallChunks(addressChunks, (address) => bytes32Whitelist.has(getStoreKey(chainId, address)) ? erc20Abi_bytes32 : erc20Abi);
+    const fallback = [];
+    for (const chunk of chunkedCalls) {
+        // console.log(`Executing multicall for chain ${chainId} with ${_.flatten(chunk).length} contracts`)
+        try {
+            const batchResults = await client.multicall({
+                allowFailure: true,
+                contracts: _.flatten(chunk),
+            });
+            // console.log(`Multicall results for chain ${chainId}:`, batchResults.length, 'results')
+            _.chunk(batchResults, 3).forEach((batch, index) => {
+                const tokenAddress = erc20Tokens[index];
+                const symbol = batch[0].result;
+                const name = batch[1].result;
+                const decimals = Number(batch[2].result);
+                // console.log(`Token ${tokenAddress} results:`, { symbol, name, decimals, errors: [batch[0].error, batch[1].error, batch[2].error] })
+                if (name && symbol && !isNaN(decimals)) {
+                    results.set(tokenAddress.toLowerCase(), { name, symbol, decimals });
+                }
+                else {
+                    console.log(`Adding ${tokenAddress} to fallback due to missing data`);
+                    fallback.push(tokenAddress);
+                }
+            });
+        }
+        catch (error) {
+            console.error(`Multicall failed for chain ${chainId}:`, error);
+            // Add all tokens to fallback if multicall fails completely
+            fallback.push(...erc20Tokens);
+        }
+    }
+    if (fallback.length === 0) {
+        return results;
+    }
+    console.log(`Processing ${fallback.length} tokens in fallback with bytes32 ABI for chain ${chainId}:`, fallback);
+    const fallbackAddressChunks = _.chunk(fallback, 100);
+    const fallbackChunkedCalls = addressChunksToCallChunks(fallbackAddressChunks, () => erc20Abi_bytes32);
+    for (const chunk of fallbackChunkedCalls) {
+        try {
+            console.log(`Executing fallback multicall for chain ${chainId} with ${_.flatten(chunk).length} contracts`);
+            const batchResults = await client.multicall({
+                allowFailure: false,
+                contracts: _.flatten(chunk),
+            });
+            console.log(`Fallback multicall results for chain ${chainId}:`, batchResults.length, 'results');
+            _.chunk(batchResults, 3).forEach((batch, index) => {
+                const tokenAddress = fallback[index];
+                const symbol = batch[0];
+                const name = batch[1];
+                const decimals = Number(batch[2]);
+                const symbolString = hexToString(symbol);
+                const nameString = hexToString(name);
+                console.log(`Fallback token ${tokenAddress} results:`, {
+                    symbolString,
+                    nameString,
+                    decimals,
+                });
+                results.set(tokenAddress.toLowerCase(), {
+                    name: nameString,
+                    symbol: symbolString,
+                    decimals,
+                });
+                // Add to bytes32 whitelist for future optimization
+                bytes32Whitelist.add(getStoreKey(chainId, tokenAddress));
+            });
+        }
+        catch (error) {
+            console.error(`Fallback multicall failed for chain ${chainId}:`, error);
+        }
+    }
+    return results;
+}
+// Get token metadata synchronously (from store only)
+export function getTokenMetadata(chainId, tokenAddress) {
+    const storeKey = getStoreKey(chainId, tokenAddress);
+    return tokenMetadataStore.get(storeKey) || null;
+}
+// Load token metadata for multiple tokens (called once on page load)
+export async function loadTokenMetadata(tokens) {
+    // Group tokens by chain ID for batching
+    const tokensByChain = new Map();
+    tokens.forEach(({ chainId, address }) => {
+        if (!tokensByChain.has(chainId)) {
+            tokensByChain.set(chainId, []);
+        }
+        tokensByChain.get(chainId).push(address);
+    });
+    // Batch fetch for each chain
+    const batchPromises = Array.from(tokensByChain.entries()).map(async ([chainId, addresses]) => {
+        try {
+            // console.log(`Loading token metadata for chain ${chainId} (${addresses.length} tokens):`, addresses)
+            const results = await batchFetchTokenMetadata(chainId, addresses);
+            // console.log(`Loaded ${results.size} token metadata results for chain ${chainId}:`, Array.from(results.entries()))
+            // Store the results
+            results.forEach((metadata, address) => {
+                if (metadata) {
+                    const storeKey = getStoreKey(chainId, address);
+                    tokenMetadataStore.set(storeKey, metadata);
+                    // console.log(`Stored metadata for ${storeKey}:`, metadata)
+                }
+            });
+        }
+        catch (error) {
+            console.error(`Failed to load tokens for chain ${chainId}:`, error);
+        }
+    });
+    await Promise.allSettled(batchPromises);
+}
+// Get store size
+export function getStoreSize() {
+    return tokenMetadataStore.size;
+}
+// Utility functions for bridge transactions
+export function getTokenAddressFromBridge(bridge) {
+    return (bridge.originationToken?.address ||
+        bridge.destinationToken?.address ||
+        bridge.originationTokenAddress ||
+        bridge.destinationTokenAddress ||
+        '');
+}
+export function getTokenChainIdFromBridge(bridge) {
+    return Number(bridge.originationToken?.chainId ||
+        bridge.destinationToken?.chainId ||
+        bridge.originationTokenChainId ||
+        bridge.destinationTokenChainId ||
+        1);
+}
+export function getBridgeTokenMetadata(bridge) {
+    const address = getTokenAddressFromBridge(bridge);
+    const chainId = getTokenChainIdFromBridge(bridge);
+    if (!address)
+        return null;
+    return getTokenMetadata(chainId, address);
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@gibs/bridge-client",
+  "version": "1.12.0",
+  "description": "Browser-side data loading, caching and endpoint resolution for the Gibs Finance bridge",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "gibs-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cache": {
+      "gibs-source": "./src/cache.ts",
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./image": {
+      "gibs-source": "./src/image.ts",
+      "types": "./dist/image.d.ts",
+      "default": "./dist/image.js"
+    },
+    "./networks": {
+      "gibs-source": "./src/networks.ts",
+      "types": "./dist/networks.d.ts",
+      "default": "./dist/networks.js"
+    },
+    "./endpoints": {
+      "gibs-source": "./src/endpoints.ts",
+      "types": "./dist/endpoints.d.ts",
+      "default": "./dist/endpoints.js"
+    },
+    "./client": {
+      "gibs-source": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./chain-read": {
+      "gibs-source": "./src/chain-read.ts",
+      "types": "./dist/chain-read.d.ts",
+      "default": "./dist/chain-read.js"
+    },
+    "./token-metadata": {
+      "gibs-source": "./src/token-metadata.ts",
+      "types": "./dist/token-metadata.d.ts",
+      "default": "./dist/token-metadata.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npx tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^24",
+    "typescript": "~5.7.2",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "@gibs/bridge-sdk": "^1.12.0",
+    "@gibs/common": "^1.12.0",
+    "lodash-es": "^4.17.21",
+    "viem": "^2.46.3"
+  }
+}