@gibs/bridge-sdk 1.12.0 → 1.13.0

package/README.md

@@ -1,487 +1,289 @@
-# Bridge SDK
+# @gibs/bridge-sdk
 
-A comprehensive toolkit for facilitating cross-chain bridge operations across multiple blockchain networks. This SDK provides low-level building blocks for implementing bridge functionality in decentralized applications.
+Build and price transfers across the PulseChain omnibridges (PulseChain and
+Ethereum, PulseChain and Binance Smart Chain), and the aggregator routes
+(LI.FI, Relay, NEAR Intents) that reach those bridges from other chains.
 
-## 🎯 Use Cases
+The package gives you pathway configuration, fee reads, request builders and
+response parsers. It does not sign or send anything. You bring a
+[viem](https://viem.sh) client and a wallet.
 
-### Primary Use Cases
-- **Cross-Chain Bridge Implementation**: Build applications that move tokens between different blockchain networks
-- **Multi-Chain DApp Development**: Create applications that operate across PulseChain, Ethereum, Binance Smart Chain, and other supported networks
-- **Bridge Provider Integration**: Integrate with multiple bridge providers (PulseChain native bridges, TokenSex, etc.)
-- **Token Metadata Management**: Access standardized token information, logos, and network-specific addresses
-- **Fee Calculation**: Calculate and manage bridge fees across different providers and networks
+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.
 
-### Target Applications
-- Cross-chain DEX interfaces
-- Bridge aggregator platforms
-- Multi-chain portfolio management tools
-- DeFi applications requiring cross-chain functionality
-- Wallet applications with bridge features
-
-## 🔧 Core Functionality
-
-### Chain Management
-- **Supported Networks**: PulseChain (0x171), Ethereum (0x1), Binance Smart Chain (0x38), and testnets
-- **Chain Metadata**: Complete chain configurations including RPC URLs, native tokens, and visual assets
-- **Chain Utilities**: Convert between chain IDs and human-readable chain keys
-
-### Token & Bridge Configuration
-- **Token Types**: Standardized token metadata with cross-chain bridge information
-- **Bridge Providers**: Support for multiple bridge providers with different fee structures
-- **Asset Mapping**: Native asset addresses and wrapped token configurations across chains
-
-### Smart Contract Integration
-- **ABIs**: Pre-configured contract ABIs for bridge operations
-- **Contract Addresses**: Deployed contract addresses across supported networks
-- **Type Safety**: Full TypeScript support with strongly typed contract interactions
-
-## 📦 Installation
+## Install
 
 ```sh
-npm install @gibs/bridge-sdk
-# or
-yarn add @gibs/bridge-sdk
+npm install @gibs/bridge-sdk viem
 ```
 
-## 📖 API Examples
-
-### Types (`@gibs/bridge-sdk/types`)
-
-```typescript
-import type {
-  Token,
-  BridgeKey,
-  TokenList,
-  TokenOut,
-  PerNetworkBridgeLink,
-  Extensions,
-  TokenMetadata,
-  VisualChain
-} from '@gibs/bridge-sdk/types'
-
-// Core token metadata
-const tokenMetadata: TokenMetadata = {
-  name: "Wrapped Ethereum",
-  symbol: "WETH",
-  decimals: 18
-}
+- **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`.
 
-// Bridge link information
-const bridgeLink: PerNetworkBridgeLink = {
-  tokenAddress: "0x..." // Address on destination chain
-}
+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.
 
-// Token extensions for cross-chain info
-const extensions: Extensions = {
-  wrapped: { address: "0x..." },
-  bridgeInfo: {
-    369: { tokenAddress: "0x..." } // PulseChain mapping
-  }
-}
+## Chains and bridge keys
 
-// Complete token with bridge metadata
-const token: Token = {
-  ...tokenMetadata,
-  address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
-  chainId: 1,
-  logoURI: "https://example.com/weth.png",
-  extensions
-}
+A chain is a hex chain id from the `Chains` enum. A route is a `BridgeKey`:
+`[provider, fromChain, toChain]`.
 
-// Token for output (address can be null)
-const tokenOut: TokenOut = {
-  ...tokenMetadata,
-  address: null, // Can be null for native tokens
-  chainId: 369,
-  logoURI: null
-}
+```ts
+import { Chains, Providers, toChain, toChainKey, validBridgeKeys } from '@gibs/bridge-sdk/config'
+import type { BridgeKey } from '@gibs/bridge-sdk/types'
 
-// Bridge route definition
-const bridgeKey: BridgeKey = [
-  'pulsechain',  // Provider
-  '0x1',        // From chain (Ethereum)
-  '0x171'       // To chain (PulseChain)
-]
-
-// Visual chain with logo info
-const visualChain: VisualChain = {
-  id: 369,
-  name: 'PulseChain',
-  chainId: '0x171' as any,
-  logoURI: 'https://example.com/pls.png',
-  alt: 'PulseChain logo'
-  // ... other Chain properties
-}
-```
+const ethereumToPulsechain: BridgeKey = [Providers.PULSECHAIN, Chains.ETH, Chains.PLS]
+const binanceToPulsechain: BridgeKey = [Providers.TOKENSEX, Chains.BNB, Chains.PLS]
 
-### Config (`@gibs/bridge-sdk/config`)
+toChain(369) // Chains.PLS, which is '0x171'
+toChainKey(369) // 'PLS'
 
-```typescript
-import {
-  Chains,
-  Provider,
-  toChain,
-  toChainKey,
-  pathways,
-  validBridgeKeys,
-  inferBridgeKey,
-  pathway,
-  isNative,
-  canChangeUnwrap,
-  defaultAssetIn
-} from '@gibs/bridge-sdk/config'
-
-// Chain enum usage
-console.log(Chains.PLS)    // "0x171"
-console.log(Chains.ETH)    // "0x1"
-
-// Provider enum usage
-console.log(Provider.PULSECHAIN) // "pulsechain"
-
-// Convert numeric chain ID to hex
-const chainHex = toChain(369)     // "0x171"
-const chainHex2 = toChain("369")  // "0x171"
-
-// Convert chain ID to human-readable key
-const chainKey = toChainKey(369)  // "PLS"
-
-// Get all valid bridge routes for environment
-const bridgeRoutes = validBridgeKeys(true) // Production routes
-const testRoutes = validBridgeKeys(false)  // Include testnets
-
-// Find bridge provider for chain pair
-const bridgeKey = inferBridgeKey({
-  fromChain: Chains.ETH,
-  toChain: Chains.PLS,
-  isProd: true
-}) // Returns: ['pulsechain', '0x1', '0x171']
-
-// Get pathway configuration for a bridge route
-const pathwayConfig = pathway(['pulsechain', '0x1', '0x171'], true)
-console.log(pathwayConfig?.from)      // Bridge contract on Ethereum
-console.log(pathwayConfig?.to)        // Bridge contract on PulseChain
-
-// Check if token is native to chain
-const native = isNative(token, bridgeKey) // boolean
-
-// Check if unwrapping is allowed
-const canUnwrap = canChangeUnwrap(bridgeKey, token) // boolean
-
-// Get default asset for bridge route
-const defaultToken = defaultAssetIn(bridgeKey, true) // Default token address
+// Mainnet keys only. Pass false to add the testnet pair (Sepolia and PulseChain testnet V4).
+const mainnetKeys: BridgeKey[] = validBridgeKeys(true)
 ```
 
-```typescript
-import {
-  nativeAssetOut,
-  nativeTokenSymbol,
-  nativeTokenName,
-  uniV2Routers
-} from '@gibs/bridge-sdk/config'
-
-// Get native wrapped token address for a chain
-const wethAddress = nativeAssetOut[Chains.ETH] // "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
-const wplsAddress = nativeAssetOut[Chains.PLS] // "0xA1077a294dDE1B09bB078844df40758a5D0f9a27"
-
-// Get native token symbols and names
-const ethSymbol = nativeTokenSymbol[Chains.ETH] // "ETH"
-const plsName = nativeTokenName[Chains.PLS]     // "Pulse"
-
-// Get UniV2 router addresses for chain
-const plsRouters = uniV2Routers[Chains.PLS] // Array of router addresses
-```
+`isProd` means "mainnet only" everywhere in this package. With `isProd: false`,
+lookups read the mainnet map first and then the testnet map.
 
-### Settings (`@gibs/bridge-sdk/settings`)
+`inferBridgeKey` repairs a key after the reader changes provider or chain. It
+returns `null` when no pathway can serve the request. It never answers a
+testnet pair with a mainnet key.
 
-```typescript
-import {
-  oneEther,
-  basisPoints,
-  bridgePathway,
-  amountToBridge,
-  bridgeCost,
-  estimatedAmountOut,
-  estimatedFee,
-  oneTokenInt,
-  assetOutKey,
-  assetOut
-} from '@gibs/bridge-sdk/settings'
-
-// Common constants
-console.log(oneEther)    // 1000000000000000000n (1e18)
-console.log(basisPoints) // 10000n
-
-// Calculate actual amount to bridge
-const amount = amountToBridge({
-  amountIn: 1000000000000000000n, // 1 ETH
-  assetIn: token,
-}) // Returns 1000000000000000000n or 0n if invalid
-
-// Calculate bridge cost
-const cost = bridgeCost({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  amountIn: oneEther,
-  // ... other parameters
-})
+```ts
+import { Chains, inferBridgeKey, Providers } from '@gibs/bridge-sdk/config'
 
-// Estimate output amount after fees
-const outputAmount = estimatedAmountOut({
-  amountIn: oneEther,
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  // ... fee parameters
-})
+const repaired = inferBridgeKey({
+  currentKey: [Providers.PULSECHAIN, Chains.SEP, Chains.ETH],
+  provider: Providers.PULSECHAIN,
+}) // [pulsechain, Sepolia, PulseChain testnet V4]
 
-// Calculate fee amount
-const feeAmount = estimatedFee({
-  amountIn: oneEther,
-  feeType: 'percent',
-  // ... other parameters
-})
-
-// Convert amount to "one token" representation
-const oneToken = oneTokenInt({
-  decimals: 18,
-  amount: oneEther
-}) // 1000000000000000000n
-
-// Generate asset out key for caching
-const cacheKey = assetOutKey({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  assetIn: token
-}) // String key for asset lookup
-
-// Get output asset configuration
-const outputAsset = assetOut({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  assetIn: token,
-  // ... other parameters
-})
+const refused = inferBridgeKey({
+  currentKey: [Providers.PULSECHAIN, Chains.SEP, Chains.V4PLS],
+  provider: Providers.PULSECHAIN,
+  isProd: true,
+}) // null: testnets are off
 ```
 
-### Chain Info (`@gibs/bridge-sdk/chain-info`)
-
-```typescript
-import {
-  loadBridgeFees,
-  nativeSymbol,
-  tokenBridgeInfo,
-  fetchPriceCorrective,
-  minBridgeAmountIn,
-  chainMulticall
-} from '@gibs/bridge-sdk/chain-info'
-
-// Load bridge fees for a route
-const fees = await loadBridgeFees({
-  pathway: pathwayConfig,
-  fromChainClient: ethClient,
-  toChainClient: plsClient
-})
-
-// Get native symbol for token, with unwrap logic
-const symbol = nativeSymbol(token, false) // "WETH" or "ETH" if unwrapped
-
-// Get token bridge information
-const bridgeInfo = await tokenBridgeInfo({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  client: ethClient,
-  target: token.address,
-  // ... other parameters
-})
+## Pathways and native assets
 
-// Fetch price corrective data
-const priceData = fetchPriceCorrective({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  // ... other parameters
-})
+```ts
+import { Chains, isNative, isUnwrappable, pathway, Providers } from '@gibs/bridge-sdk/config'
+import type { BridgeKey, Token } from '@gibs/bridge-sdk/types'
 
-// Get minimum bridge amount
-const minAmount = await minBridgeAmountIn({
-  bridgeKey: ['pulsechain', '0x1', '0x171'],
-  client: ethClient,
-  // ... other parameters
-})
+const bridgeKey: BridgeKey = [Providers.PULSECHAIN, Chains.ETH, Chains.PLS]
+const route = pathway(bridgeKey, true)
+if (route) {
+  route.from // the mediator on Ethereum, where the funds enter
+  route.feeManager // 'to': the PulseChain mediator owns the fee manager
+}
 
-// Create multicall helper for chain
-const multicall = chainMulticall(ethClient)
-// Use for batched contract calls
+declare const token: Token
+const native: boolean = isNative(token, bridgeKey, { isProd: true })
+const unwrappable: boolean = isUnwrappable(bridgeKey, token, { isProd: true })
 ```
 
-### Image Links (`@gibs/bridge-sdk/image-links`)
-
-```typescript
-import * as imageLinks from '@gibs/bridge-sdk/image-links'
-
-// Configure image root URL
-imageLinks.setImageRoot('https://cdn.example.com/images/')
-const currentRoot = imageLinks.getImageRoot() // Current root URL
-
-// Get network image URL
-const networkImage = imageLinks.network(1)    // Ethereum logo URL
-const plsImage = imageLinks.network(369)      // PulseChain logo URL
-
-// Get single token image
-const tokenImage = imageLinks.image({
-  chainId: 1,
-  address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
-})
-
-// Get token images for multiple sources
-const tokenImages = imageLinks.images([
-  "1/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH on Ethereum
-  "369/0xA1077a294dDE1B09bB078844df40758a5D0f9a27"  // WPLS on PulseChain
-])
-
-// List available images in a directory
-const availableImages = imageLinks.list('tokens/') // Array of image paths
+`isNative` and `isUnwrappable` never throw. They answer `false` for a token with
+a `null` address, a malformed address, or a bridge key with no pathway. Leave
+out the options and they read both maps, as before the option existed.
+
+## Fees and units
+
+Two unit systems appear, and they are not the same:
+
+- **Bridge fees are a rate per `1e18`.** `1e18` is one hundred percent.
+  `loadBridgeFees` returns `feeH2F` and `feeF2H` in this unit, and `bridgeCost`
+  divides by `oneEther` (`10n ** 18n`).
+- **Aggregator referral fees are basis points.** `10_000n` is one hundred
+  percent, so `10n` is a tenth of a percent. LI.FI takes the same fee as a
+  decimal fraction (`0.001`).
+
+**Direction decides which fee applies.** PulseChain is the home side of both
+omnibridges.
+
+- Foreign to home (`feeF2H`): **entering** PulseChain.
+- Home to foreign (`feeH2F`): **leaving** PulseChain.
+
+The pathway's `feeManager` field names the side whose mediator owns the fee
+manager (`'from'` or `'to'`). `loadBridgeFees` reads it on that side.
+
+When this file was written, entering PulseChain over Ethereum charged nothing
+and leaving charged 0.3%. The Binance Smart Chain bridge charged 2.97% each
+way. These are on-chain settings, so read them; do not hard-code them.
+
+```ts
+import { loadBridgeFees } from '@gibs/bridge-sdk/chain-info'
+import { Chains, pathway, Providers } from '@gibs/bridge-sdk/config'
+import { amountAfterBridgeFee, bridgeCost } from '@gibs/bridge-sdk/settings'
+import type { PublicClient } from 'viem'
+
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const route = pathway([Providers.PULSECHAIN, Chains.ETH, Chains.PLS], true)
+if (route) {
+  const { feeF2H } = await loadBridgeFees({
+    pathway: route,
+    fromChainClient: ethereumClient,
+    toChainClient: pulsechainClient,
+  })
+  const amountToBridge = 1_000_000n
+  const cost = bridgeCost({ amountToBridge, bridgeFee: feeF2H })
+  const received = amountAfterBridgeFee({ amountToBridge, bridgeCost: cost })
+}
 ```
 
-### ABIs (`@gibs/bridge-sdk/abis`)
+`loadBridgeFees` reads the fee manager's default rate (`getFee(key, address(0))`).
+A fee manager can also hold a rate for one token. This package does not read
+per-token rates yet.
 
-```typescript
-import * as abis from '@gibs/bridge-sdk/abis'
+## Tokens that are not bridged yet
 
-// Bridge contract ABIs
-const inputBridgeAbi = abis.inputBridge         // Input bridge contract
-const outputBridgeAbi = abis.outputBridge       // Output bridge contract
-const outputRouterAbi = abis.outputRouter       // Output router contract
+`tokenBridgeInfo` asks both mediators how a token maps across the bridge.
 
-// Token contract ABIs
-const erc677Abi = abis.erc677                   // ERC677 token contract
-const erc677ExtraAbi = abis.erc677ExtraInput    // With extra input functions
+```ts
+import { tokenBridgeInfo } from '@gibs/bridge-sdk/chain-info'
+import { Chains, Providers } from '@gibs/bridge-sdk/config'
+import type { Token } from '@gibs/bridge-sdk/types'
+import type { PublicClient } from 'viem'
 
-// Router and fee ABIs
-const nativeRouterAbi = abis.nativeRouter       // Native token router
-const feeManagerAbi = abis.feeManager           // Fee management contract
-const univ2RouterAbi = abis.univ2Router         // UniswapV2 router
+declare const assetIn: Token
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
 
-// Utility ABIs and types
-const feeDeliveryStruct = abis.feeDeliveryStruct // Fee delivery struct ABI
-const homeAmbAbi = abis.homeAmb                  // Home AMB contract
-const pairAbi = abis.pair                        // Pair contract
-
-// Use with viem contract calls
-const contract = getContract({
-  address: bridgeAddress,
-  abi: inputBridgeAbi,
-  client: publicClient
+const info = await tokenBridgeInfo({
+  bridgeKey: [Providers.PULSECHAIN, Chains.ETH, Chains.PLS],
+  assetIn,
+  isProd: true,
+  fromChainClient: ethereumClient,
+  toChainClient: pulsechainClient,
 })
-
-const bridgeFunction = contract.read.someFunction()
+if (info && info.assetOutAddress === null) {
+  // Not bridged yet: the first transfer creates the token on the far side.
+}
 ```
 
-### Fee Types (`@gibs/bridge-sdk/fee-type`)
+A `null` `assetOutAddress` is a normal answer, not an error. The token gets an
+address on the far side when its first transfer arrives.
 
-```typescript
-import { FeeType, feeTypeValToKeyMap, type FeeTypeKeys } from '@gibs/bridge-sdk/fee-type'
+The package caches a mapping once it exists, because a mediator never changes
+one. It does not cache the "not bridged yet" answer, so the next call reads the
+chain again. Call `clearChainInfoCaches()` to drop every cached answer.
 
-// Fee type enum
-console.log(FeeType.PERCENT)  // "%"
-console.log(FeeType.GAS_TIP)  // "gas+%"
-console.log(FeeType.FIXED)    // "fixed"
+## Aggregator quotes and your identity
 
-// Fee type keys
-const percentKey: FeeTypeKeys = 'PERCENT'
-const gasTipKey: FeeTypeKeys = 'GAS_TIP'
+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.
 
-// Convert fee type value back to key
-const feeTypeKey = feeTypeValToKeyMap.get('%') // "PERCENT"
-const gasKey = feeTypeValToKeyMap.get('gas+%') // "GAS_TIP"
-```
-
-### Chains (`@gibs/bridge-sdk/chains`)
+| 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 `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. |
 
-```typescript
-import { chainsMetadata } from '@gibs/bridge-sdk/chains'
-import { Chains } from '@gibs/bridge-sdk/config'
+Each attribution field takes three states: leave it out for the default, pass
+`null` to omit it, or pass your own string.
 
-// Get complete chain configuration
-const pulseChain = chainsMetadata[Chains.PLS]
-console.log(pulseChain.name)        // "PulseChain"
-console.log(pulseChain.chainId)     // "0x171"
-console.log(pulseChain.logoURI)     // Chain logo URL
-console.log(pulseChain.rpcUrls.default.http[0]) // Default RPC URL
-
-// Access native currency info
-console.log(pulseChain.nativeCurrency.name)     // "Pulse"
-console.log(pulseChain.nativeCurrency.symbol)   // "PLS"
-console.log(pulseChain.nativeCurrency.decimals) // 18
-
-// Access contract addresses
-console.log(pulseChain.contracts?.multicall3?.address) // Multicall3 address
-console.log(pulseChain.contracts?.ensRegistry?.address) // ENS registry if available
-```
-
-## 📋 API Reference
-
-### Exports
-
-| Export Path | Description |
-|-------------|-------------|
-| `@gibs/bridge-sdk` | Main entry point with all exports |
-| `@gibs/bridge-sdk/types` | TypeScript type definitions |
-| `@gibs/bridge-sdk/config` | Chain IDs, providers, and core configuration |
-| `@gibs/bridge-sdk/chains` | Chain metadata and network configurations |
-| `@gibs/bridge-sdk/abis` | Smart contract ABIs |
-| `@gibs/bridge-sdk/image-links` | Network and token image utilities |
-| `@gibs/bridge-sdk/fee-type` | Fee calculation types and utilities |
-| `@gibs/bridge-sdk/settings` | Bridge settings and configuration |
-| `@gibs/bridge-sdk/chain-info` | Chain-specific bridge information |
-
-### Key Types
-
-```typescript
-// Core chain identifier
-enum Chains {
-  PLS = '0x171',     // PulseChain
-  ETH = '0x1',       // Ethereum
-  BNB = '0x38',      // Binance Smart Chain
-  SEP = '0xaa36a7',  // Sepolia Testnet
-  V4PLS = '0x3af'    // PulseChain V4 Testnet
+```ts
+import {
+  buildLifiContractCallsRequest,
+  type ConsolidatedQuoteRequest,
+} from '@gibs/bridge-sdk/consolidated-quote'
+import { nearIntentsRequestHeaders } from '@gibs/bridge-sdk/near-intents'
+import { buildRelayQuoteRequest, relayQuoteUrl, relayRequestHeaders } from '@gibs/bridge-sdk/relay-quote'
+
+declare const baseRequest: ConsolidatedQuoteRequest
+declare const myRelayApiKey: string
+
+const request: ConsolidatedQuoteRequest = {
+  ...baseRequest,
+  lifiIntegrator: 'your-app.example',
+  lifiFee: 0.001, // a tenth of a percent, paid to your LI.FI integrator account
+  relayReferrer: 'your-app.example',
 }
 
-// Bridge providers
-enum Provider {
-  PULSECHAIN = 'pulsechain',
-  TOKENSEX = 'tokensex'
+const lifiBody = buildLifiContractCallsRequest(request)
+const relayBody = buildRelayQuoteRequest(request)
+if (relayBody) {
+  await fetch(relayQuoteUrl, {
+    method: 'POST',
+    body: JSON.stringify(relayBody),
+    headers: relayRequestHeaders(myRelayApiKey),
+  })
 }
 
-// Bridge route: [Provider, FromChain, ToChain]
-type BridgeKey = [Provider, Chains, Chains]
-
-// Token with bridge metadata
-interface Token {
-  name: string
-  symbol: string
-  decimals: number
-  address: string
-  chainId: number
-  logoURI: string | null
-  extensions?: {
-    wrapped?: { address: Hex }
-    bridgeInfo?: Record<number, PerNetworkBridgeLink>
-  }
-}
+const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/1.0' })
 ```
 
-## ⚠️ Important Notes
-
-- **Beta Stage**: This SDK is in active development. APIs may change between versions.
-- **Version Sync**: All packages in this monorepo maintain synchronized versions.
-- **Low-Level Tools**: These are building blocks that require careful integration.
-- **Dependencies**: Built on top of `@gibs/common` utilities and `viem` for Ethereum interactions.
-
-## 🔗 Dependencies
+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`.
 
-- `@gibs/common`: Shared utilities for RPC clients, caching, and ERC20 operations
-- `viem`: Type-safe Ethereum library for contract interactions
-- `lodash`: Utility functions for data manipulation
+## Images
 
-## 📝 Development Status
+Chain logos and token images come from [gib.show](https://gib.show). Point them
+at your own host with `setImageRoot`. Chain logos in `chainsMetadata` read the
+root each time you access them, so a later call still takes effect.
 
-This package is actively maintained and used in production bridge applications. However, as it's in beta:
+```ts
+import { chainsMetadata } from '@gibs/bridge-sdk/chains'
+import { Chains } from '@gibs/bridge-sdk/config'
+import { image, setImageRoot } from '@gibs/bridge-sdk/image-links'
 
-- APIs may change in minor version updates
-- New bridge providers and chains are regularly added
-- Breaking changes will be documented in release notes
+setImageRoot('https://images.example.org')
+chainsMetadata[Chains.PLS].logoURI // 'https://images.example.org/image/369'
+image({ chainId: 1, address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' })
+```
 
-For the most up-to-date information, check the package version and changelog.
+## Nulls, falses and throws
+
+The package follows one rule: **a question it cannot answer returns `null`,
+`undefined` or `false`; a caller mistake or a failed read throws.**
+
+Returns without throwing:
+
+- `pathway` and `defaultAssetIn` return `undefined` or `null` for a key with no pathway.
+- `inferBridgeKey` returns `null` when no pathway fits.
+- `isNative`, `isUnwrappable` and `canChangeUnwrap` return `false`.
+- `tokenBridgeInfo` returns `null` without an asset or a pathway.
+- Every request builder returns `null` for a request its provider cannot express.
+- Every response parser returns `null` for a response of an unexpected shape.
+
+Throws:
+
+- `buildLifiQuoteRequest` and `buildLifiContractCallsRequest`, for a positive
+  `lifiFee` without your own `lifiIntegrator`.
+- `chainMulticall`, for a client with no chain or a chain without Multicall3.
+- `loadBridgeFees`, `links` and `minBridgeAmountIn`, when the chain read fails.
+- `pathway`, for an `assetInAddress` that is not an address.
+
+The package writes nothing to the console.
+
+## Entry points
+
+| 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/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/image-links` | Image URLs |
+| `@gibs/bridge-sdk/abis` | Contract ABIs |
+| `@gibs/bridge-sdk/ton-execution` | TON Connect requests (needs `Buffer`) |
+| `@gibs/bridge-sdk/routing` | Route search across carriers |
+
+The API can still change in a minor version. Read the release notes before you
+upgrade.