@gibs/bridge-sdk 1.13.1 → 1.18.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

@@ -9,19 +9,49 @@
 ## Install
 
 - Run `npm install @gibs/bridge-sdk viem`.
-- The package is ESM only. Use `import`, not `require`.
-- It needs Node 20 or later (`engines.node` is `>=20`).
-- viem is a peer dependency. The range is `>=2.37.0 <3`.
+- 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.
-- In a browser, `@gibs/bridge-sdk/ton-execution` needs a global `Buffer`. No other entry point does.
+
+## 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.
+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 RPC URLs.
+- `@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.
@@ -29,8 +59,12 @@ Import from the narrowest subpath. The root `@gibs/bridge-sdk` exports everythin
 - `@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
 
@@ -120,8 +154,8 @@ if (info && info.assetOutAddress === null) {
 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`. A positive `lifiFee` without your own integrator throws.
-- NEAR Intents: no key is needed. Pass your own `userAgent` if you want one.
+- 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 {
@@ -154,6 +188,36 @@ if (relayBody) {
 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`.
@@ -164,6 +228,7 @@ const nearHeaders = nearIntentsRequestHeaders(undefined, { userAgent: 'your-app/
 
 ## Links
 
-- [README](https://github.com/gibsfinance/bridge/blob/staging/packages/bridge-sdk/README.md): the full guide.
+- [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://github.com/gibsfinance/bridge/blob/staging/packages/quotes/llms.txt): live multi-provider quotes.
+- [@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"
+}