@gibs/bridge-sdk 1.13.0 → 1.17.0

package/lifi-execution-guard/package.json

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

package/llms.txt

@@ -0,0 +1,234 @@
+# @gibs/bridge-sdk
+
+> A TypeScript library that prices and builds transfers across the Gibs
+> Finance omnibridges (PulseChain with Ethereum, PulseChain with BNB Smart
+> Chain). It also builds the requests for the aggregator routes (LI.FI,
+> Relay, NEAR Intents) that reach those bridges from other chains. It does
+> not sign or send anything. You bring a viem client and a wallet.
+
+## Install
+
+- Run `npm install @gibs/bridge-sdk viem`.
+- It runs on Node 20 or later (`engines.node` is `>=20`), in browsers, and in React Native under Hermes.
+- viem is a peer dependency. The range is `>=2.35.0 <3`.
+- Version note: 1.12.0 and older on npm are broken. 1.13.0 is the first usable version.
+
+## Ways to use the package
+
+The `exports` map picks the build. No consumer configuration is needed.
+
+- ECMAScript modules: `import { pathway } from '@gibs/bridge-sdk/config'` loads `dist/config.js`.
+- CommonJS: `require('@gibs/bridge-sdk/config')` loads `dist/cjs/config.js`, with its own declaration files.
+- React Native 0.77 or later, default `metro.config.js`. Add no `resolveRequest` hook. In 0.79 or later, Metro reads `exports`: the `react-native` condition gives an `import` statement the ECMAScript module build and a `require` call the CommonJS build. The SDK then shares your build of viem, so Metro bundles viem once.
+- React Native jest preset: loads the CommonJS build. Do not add `transformIgnorePatterns` for these packages.
+- Metro with package exports off (the default in React Native 0.77 and 0.78): every subpath resolves through a folder the package ships for it, such as `config/package.json`, which points at the CommonJS build. Import the subpath as usual, never a `dist` path.
+- No entry point except `@gibs/bridge-sdk/ton` needs a polyfill. That includes a `URL` polyfill: React Native 0.77's own `URL` and `URLSearchParams` are partial, and no entry point reads them.
+
+```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 })
+console.log(route?.from, amountAfterBridgeFee({ amountToBridge: 10n ** 18n, bridgeCost: cost }))
+```
+
+Bundle weight. Metro does not drop unused exports, so the entry point decides the weight. Measured in a React Native 0.87.1 production bundle that already holds viem:
+
+- `/config` and `/settings` (offline quoting): about 24 kB.
+- `/chain-info` (live fee reads) with the above: about 1.16 MB, because it loads `viem/chains` (1.12 MB). About 41 kB if the app already imports `viem/chains`.
+- The root entry point: about 1.29 MB. About 164 kB if the app already imports `viem/chains`.
+
+TON:
+
+- `@gibs/bridge-sdk/ton-connect`: TON Connect requests and address re-encoding. No TON library, no `Buffer`.
+- `@gibs/bridge-sdk/ton`: the same, plus `tonExternalMessageHash`, which needs `@ton/core`. Set `globalThis.Buffer` (the `buffer` package) before importing it in a browser or React Native. In React Native, Metro also needs `expo-crypto` installed, because `@ton/crypto` requires it there.
+- `@gibs/bridge-sdk/ton-execution`: the old name of `@gibs/bridge-sdk/ton`.
+
+## Entry points
+
+Import from the narrowest subpath. The root `@gibs/bridge-sdk` exports everything except TON.
+
+- `@gibs/bridge-sdk/config`: chains, providers, pathways, native-asset tables.
+- `@gibs/bridge-sdk/types`: shared types such as `BridgeKey` and `Token`.
+- `@gibs/bridge-sdk/chains`: viem chain objects with logos and public RPC URLs. `demoRpcUrls` is for demos only.
+- `@gibs/bridge-sdk/chain-info`: on-chain reads (token mappings, fees, minimum amounts).
+- `@gibs/bridge-sdk/settings`: fee and amount arithmetic.
+- `@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`: price checks before a binding quote.
+- `@gibs/bridge-sdk/routing`: route search across carriers.
+- `@gibs/bridge-sdk/execution`: execution plans (`planExecution`, `planCandidateExecution`, `PlannedTx`, `DeliveryChoice`, `AllowanceReader`, `assumeNoAllowance`).
+- `@gibs/bridge-sdk/claims`: manual claim transactions (`buildClaimTransaction`, `claimCall`, `packSignatures`, `signatureToVRS`, `encodeReleaseWithoutTipData`, `encodeReleaseToRouterData`).
+- `@gibs/bridge-sdk/image-links`: image URLs from gib.show.
+- `@gibs/bridge-sdk/abis`: contract ABIs.
+- `@gibs/bridge-sdk/ton-connect`: TON Connect requests, with no TON library.
+- `@gibs/bridge-sdk/ton`: TON Connect requests and the external message hash (needs `@ton/core`).
+
+## Chains and pathways
+
+A chain is a hex id from the `Chains` enum. A route is a `BridgeKey`:
+`[provider, fromChain, toChain]`. `pathway` returns the contract addresses
+for a key, or `undefined` when no pathway exists.
+
+```ts
+import { Chains, Providers, pathway } from '@gibs/bridge-sdk/config'
+import type { BridgeKey } from '@gibs/bridge-sdk/types'
+
+const bridgeKey: BridgeKey = [Providers.PULSECHAIN, Chains.ETH, Chains.PLS]
+const route = pathway(bridgeKey, true) // true: mainnet only
+if (route) {
+  route.from // the mediator on Ethereum, where funds enter
+  route.feeManager // 'to': the PulseChain mediator owns the fee manager
+}
+```
+
+## Fees: direction and units
+
+These rules must hold in every integration.
+
+- PulseChain is the home side of both omnibridges.
+- Foreign to home (`feeF2H`) means entering PulseChain.
+- Home to foreign (`feeH2F`) means leaving PulseChain.
+- Use the fee for your direction. Do not use one fee for both.
+- Bridge fees are a rate per `1e18`. `1e18` is one hundred percent.
+- Aggregator referral fees are basis points. `10_000n` is one hundred percent.
+- LI.FI takes its fee as a decimal fraction (`0.001` is a tenth of a percent).
+- Fees are on-chain settings. 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 })
+}
+```
+
+`loadBridgeFees` reads the default rate. It does not read per-token rates.
+
+## Tokens that are not bridged yet
+
+`tokenBridgeInfo` asks both mediators how a token maps across the bridge.
+A `null` `assetOutAddress` is a normal answer. The token gets an address on
+the far side when its first transfer arrives. Always check for `null`.
+
+```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'
+
+declare const assetIn: Token
+declare const ethereumClient: PublicClient
+declare const pulsechainClient: PublicClient
+
+const info = await tokenBridgeInfo({
+  bridgeKey: [Providers.PULSECHAIN, Chains.ETH, Chains.PLS],
+  assetIn,
+  isProd: true,
+  fromChainClient: ethereumClient,
+  toChainClient: pulsechainClient,
+})
+if (info && info.assetOutAddress === null) {
+  // Not bridged yet. Do not treat this as an error.
+}
+```
+
+## Aggregator identity: pass your own
+
+The package ships no API key. Pass your own.
+
+- Relay: pass your own `apiKey` to `relayRequestHeaders`. Name your own `relayReferrer`. The package sends no referrer by default, because Relay rejects a referrer without a key.
+- LI.FI: set your own `lifiIntegrator`. The package sends no integrator by default. A positive `lifiFee` without your own integrator throws.
+- NEAR Intents: no key is needed. No `referral` is sent unless you pass one. The `User-Agent` names Gibs Finance unless you pass your own `userAgent`, or `null` for none. Browsers drop it; Node and React Native send it.
+
+```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,
+  relayReferrer: 'your-app.example',
+}
+
+const lifiBody = buildLifiContractCallsRequest(request)
+const relayBody = buildRelayQuoteRequest(request)
+if (relayBody) {
+  await fetch(relayQuoteUrl, {
+    method: 'POST',
+    body: JSON.stringify(relayBody),
+    headers: relayRequestHeaders(myRelayApiKey),
+  })
+}
+
+const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/1.0' })
+```
+
+## Fees: nothing is added for you
+
+- No builder adds a fee, a payout address or a Gibs Finance label. A request carries one only when you pass it.
+- Bridge fee: on-chain, on every direct crossing. Read it with `loadBridgeFees`. You cannot turn it off.
+- Delivery fee: only with `shouldDeliver: true` and a fee director. See it with `deliveryFee`.
+- LI.FI fee: only with `lifiFee` and your own `lifiIntegrator`.
+- Relay application fee: only with `relayAppFee: { recipient, basisPoints }`.
+- Provider fees (gas, solver, protocol): charged by LI.FI, Relay or NEAR Intents. Read them with `lifiQuoteFees`, `relayQuoteFees` and the NEAR Intents quote parser.
+- NEAR Intents adds 25 basis points to a quote sent without a partner key.
+- `@gibs/bridge-sdk/referral` holds Gibs Finance's own values (`referralIntegrator`, `relayReferralRecipient`, `defaultReferralFeeBasisPoints`). They pay Gibs Finance. Do not pass them from your own app.
+
+## RPC endpoints: the defaults are for demos only
+
+- Every reader takes your viem clients. None builds its own.
+- `chainsMetadata` carries public endpoints only.
+- `demoRpcUrls` and `demoRpcUrlsFor` add a shared valve.city key, `vk_demo`. They are for demos only. The key is public, but its rate budget is shared and the Gibs Finance operator runs the proxy.
+- In production, use your own RPC provider.
+
+```ts
+import { demoRpcUrlsFor } from '@gibs/bridge-sdk/chains'
+import { createPublicClient, fallback, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+const ethereumClient = createPublicClient({ chain: mainnet, transport: http('https://your-rpc.example') })
+const demoOnly = createPublicClient({
+  chain: mainnet,
+  transport: fallback(demoRpcUrlsFor(mainnet.id).map((url) => http(url))),
+})
+```
+
+## Nulls and throws
+
+- A question the package cannot answer returns `null`, `undefined` or `false`.
+- A caller mistake or a failed chain read throws.
+- Every request builder returns `null` for a request its provider cannot express.
+- Every response parser returns `null` for an unexpected response shape.
+- Check each return value before you use it.
+
+## Links
+
+- [Integrate Gibs into a wallet or app](https://next.gibs.finance/docs/): search, plan, send, track and claim, with two complete examples. The same guide ships in this package as `docs/integration-guide.md`.
+- [README](https://www.npmjs.com/package/@gibs/bridge-sdk): the full reference.
+- [Gibs Finance llms.txt](https://next.gibs.finance/llms.txt): the whole platform.
+- [@gibs/quotes](https://next.gibs.finance/docs/packages/quotes/llms.txt): live multi-provider quotes.

package/near-intents/package.json

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

package/near-intents-route/package.json

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

package/origin-deposit/package.json

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