diff --git a/content/docs/overview/changelog.mdx b/content/docs/overview/changelog.mdx index 15b07a88..7e8cb1c7 100644 --- a/content/docs/overview/changelog.mdx +++ b/content/docs/overview/changelog.mdx @@ -90,7 +90,7 @@ Stay up to date with the latest improvements, new features, and bug fixes across ### June 11, 2026 **What's New** -- **swidge-lifi** ([v0.2.0](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi/v/0.2.0)): Add generated TypeScript declarations, request timeouts and retries, typed LI.FI error classes, input and transaction validation, optional trusted-contract checks, and fee-cap handling for LI.FI swidge routes. +- **@lifi/wdk-protocol-swidge-lifi** ([v0.5.1](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi/v/0.5.1)): Add generated TypeScript declarations, request timeouts and retries, typed LI.FI error classes, input and transaction validation, optional trusted-contract checks, fee-cap handling, an optional `minAmountOut` execution guard for quote-first flows, opt-in gasless route filtering (`NATIVE_VALUE_BRIDGE_DENY_LIST` and `allowNativeValue`), and per-fee-token chain attribution for LI.FI swidge routes. --- diff --git a/content/docs/sdk/all-modules.mdx b/content/docs/sdk/all-modules.mdx index 4fc7bbad..131454de 100644 --- a/content/docs/sdk/all-modules.mdx +++ b/content/docs/sdk/all-modules.mdx @@ -38,7 +38,7 @@ Swidge is the preferred interface for new protocol providers that can quote and | Module | Provider | Description | Documentation | |--------|----------|-------------|---------------| -| [`@kenny_io/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) | LI.FI | Swidge routes for LI.FI swap, bridge, and combined swap-plus-bridge operations | [Docs](/sdk/swidge-modules/swidge-lifi/) | +| [`@lifi/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) | LI.FI | Swidge routes for LI.FI swap, bridge, and combined swap-plus-bridge operations | [Docs](/sdk/swidge-modules/swidge-lifi/) | ## Pricing Modules @@ -90,4 +90,4 @@ Modules built by the WDK community. See the [Community Modules](/sdk/community-m |--------|------------|-------------|---------------| | [`@utexo/wdk-wallet-rgb`](https://github.com/UTEXO-Protocol/wdk-wallet-rgb) | Bitcoin (RGB) | RGB protocol wallet integration | [Docs](/sdk/community-modules/wdk-wallet-rgb/) | | [`@base58-io/wdk-wallet-cosmos`](https://github.com/base58-io/wdk-wallet-cosmos) | Cosmos | Cosmos-compatible wallet integration | [Docs](/sdk/community-modules/wdk-wallet-cosmos/) | -| [`@kenny_io/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) | LI.FI | Swidge swap and bridge route integration | [Docs](/sdk/swidge-modules/swidge-lifi/) | +| [`@lifi/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) | LI.FI | Swidge swap and bridge route integration | [Docs](/sdk/swidge-modules/swidge-lifi/) | diff --git a/content/docs/sdk/community-modules/index.mdx b/content/docs/sdk/community-modules/index.mdx index 1ee031a9..2a1aa58f 100644 --- a/content/docs/sdk/community-modules/index.mdx +++ b/content/docs/sdk/community-modules/index.mdx @@ -21,7 +21,7 @@ Tether and the WDK Team do not endorse or assume responsibility for their code, | [@arkade-os/wdk](https://www.npmjs.com/package/@arkade-os/wdk) ([GitHub](https://github.com/arkade-os/arkade-wdk)) | Wallet Module | Bitcoin wallet module built on the Arkade SDK with Arkade addresses, boarding addresses, BIP21/LNURL/Lightning send routing, and optional Boltz swaps | [README](https://github.com/arkade-os/arkade-wdk#readme) | [Arkade](https://github.com/arkade-os) | | [@base58-io/wdk-wallet-cosmos](https://www.npmjs.com/package/@base58-io/wdk-wallet-cosmos) ([GitHub](https://github.com/base58-io/wdk-wallet-cosmos)) | Wallet Module | Wallet module for Cosmos-compatible blockchains | [Docs](/sdk/community-modules/wdk-wallet-cosmos/) | [Base58](https://base58.io/) | | [@morpho-org/wdk-protocol-lending-morpho-evm](https://www.npmjs.com/package/@morpho-org/wdk-protocol-lending-morpho-evm) ([GitHub](https://github.com/morpho-org/sdks/tree/main/packages/wdk-protocol-lending-morpho-evm)) | Lending Module | Morpho EVM lending module for vault deposits, collateral supply, borrowing, repayment, and position reads | [Docs](/sdk/lending-modules/lending-morpho-evm/) | [Morpho Association](https://morpho.org/) | -| [@kenny_io/wdk-protocol-swidge-lifi](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) ([GitHub](https://github.com/kenny-io/wdk-lifi-swidge-protocol)) | Swidge Module | LI.FI swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-lifi/) | [Kenny](https://github.com/kenny-io) | +| [@lifi/wdk-protocol-swidge-lifi](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) ([GitHub](https://github.com/lifinance/wdk-lifi-swidge-protocol)) | Swidge Module | LI.FI swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-lifi/) | [LI.FI](https://li.fi/) | --- diff --git a/content/docs/sdk/swidge-modules/swidge-lifi/api-reference.mdx b/content/docs/sdk/swidge-modules/swidge-lifi/api-reference.mdx index 410048a2..3c9da48a 100644 --- a/content/docs/sdk/swidge-modules/swidge-lifi/api-reference.mdx +++ b/content/docs/sdk/swidge-modules/swidge-lifi/api-reference.mdx @@ -1,6 +1,6 @@ --- title: LI.FI Swidge API Reference -description: API reference for @kenny_io/wdk-protocol-swidge-lifi. +description: API reference for @lifi/wdk-protocol-swidge-lifi. docType: reference schemaType: APIReference icon: Code @@ -13,7 +13,7 @@ icon: Code ```javascript import { LifiSwidgeProtocol -} from '@kenny_io/wdk-protocol-swidge-lifi' +} from '@lifi/wdk-protocol-swidge-lifi' const swidge = new LifiSwidgeProtocol(account, config) ``` @@ -29,7 +29,9 @@ new LifiSwidgeProtocol(account?, config?) | `WalletAccountEvm` | Discovery, quote, status, and execution. | | `WalletAccountEvmErc4337` | Discovery, quote, status, and execution through a smart account. | | `WalletAccountReadOnlyEvm` | Discovery, quote, and status. | -| `undefined` | Discovery and account-independent quote setup. | +| `undefined` | Chain and token discovery only. | + +Use `WalletAccountReadOnlyEvm` for quote-only flows that should not sign transactions. No-account mode cannot provide the source address required by LI.FI quotes. ## Methods @@ -60,7 +62,9 @@ swidge( Executes through the bound writable account. The module sends required approval transactions before the route transaction where needed. -Throws before execution when validation fails, a configured fee cap is exceeded, or `trustedContracts` rejects the quote target or approval address. +For quote-first flows, pass the `minAmountOut` field in `options`: set it to the `toTokenAmountMin` from a previously displayed `quoteSwidge()` result, and `swidge()` throws before any approval or transaction is sent if the fresh execution quote's minimum output falls below it. `minAmountOut` is not forwarded to LI.FI, and `quoteSwidge()` ignores it. + +Throws before execution when validation fails, a fee cap is exceeded, the quote falls below `minAmountOut`, `allowNativeValue: false` and the quote requires native value, or `trustedContracts` rejects the quote target or approval address. ### `getSwidgeStatus(id, options?)` @@ -92,6 +96,8 @@ type LifiSwidgeProtocolConfig = { order?: LifiRouteOrder allowBridges?: string[] denyBridges?: string[] + allowDestinationCall?: boolean + allowNativeValue?: boolean timeout?: number retries?: number retryDelay?: number diff --git a/content/docs/sdk/swidge-modules/swidge-lifi/configuration.mdx b/content/docs/sdk/swidge-modules/swidge-lifi/configuration.mdx index a206c3cf..26dec0f8 100644 --- a/content/docs/sdk/swidge-modules/swidge-lifi/configuration.mdx +++ b/content/docs/sdk/swidge-modules/swidge-lifi/configuration.mdx @@ -1,6 +1,6 @@ --- title: LI.FI Swidge Configuration -description: Configuration options for @kenny_io/wdk-protocol-swidge-lifi. +description: Configuration options for @lifi/wdk-protocol-swidge-lifi. docType: reference schemaType: TechArticle icon: Settings @@ -10,7 +10,7 @@ Configure `LifiSwidgeProtocol` with a WDK EVM account when you need execution, o ```javascript import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm' -import { LifiSwidgeProtocol } from '@kenny_io/wdk-protocol-swidge-lifi' +import { LifiSwidgeProtocol } from '@lifi/wdk-protocol-swidge-lifi' const account = new WalletAccountEvm(seedPhrase, "0'/0/0", { provider: 'https://mainnet.infura.io/v3/YOUR_KEY' @@ -44,7 +44,9 @@ new LifiSwidgeProtocol(account?, config?) | `apiKey` | `string` | LI.FI API key for higher rate limits. Keep it server-side. | | `order` | `'RECOMMENDED' \| 'FASTEST' \| 'CHEAPEST'` | Route selection strategy. Defaults to `RECOMMENDED`. | | `allowBridges` | `string[]` | Bridge protocol allowlist, for example `['stargate']`. | -| `denyBridges` | `string[]` | Bridge protocol denylist, for example `['across']`. | +| `denyBridges` | `string[]` | Bridge protocol denylist, for example `['across']`. When omitted, no bridge filter is sent and LI.FI considers all bridges. For gasless integrations, pass the exported `NATIVE_VALUE_BRIDGE_DENY_LIST` to exclude bridges that require native token value. | +| `allowDestinationCall` | `boolean` | Allows LI.FI routes that execute a destination-chain call, such as a destination-chain swap. Forwarded only when set explicitly; when omitted, LI.FI's own default (`true`) applies. Set `false` to filter out routes that may leave the user with an intermediary token if the destination call fails. | +| `allowNativeValue` | `boolean` | Whether `swidge()` may execute quotes whose transaction requires native token value (`transactionRequest.value > 0`). Defaults to `true`. Set `false` for gasless setups (for example ERC-4337 with a paymaster): such quotes are rejected before any approval is sent. | | `maxNetworkFeeBps` | `number \| bigint` | Rejects execution when network fees exceed this many basis points of the input amount. | | `maxProtocolFeeBps` | `number \| bigint` | Rejects execution when protocol fees exceed this many basis points of the input amount. | | `timeout` | `number` | Per-request timeout in milliseconds. Defaults to `30000`. | @@ -63,6 +65,30 @@ await swidge.swidge(options, { }) ``` +## Route Filtering + +By default the module applies no extra route filtering: `denyBridges` is not set, `allowDestinationCall` is not forwarded (LI.FI's server-side default of `true` applies), and quotes that require native token value execute as-is. This gives the widest route coverage and matches LI.FI SDK behavior. + +For gasless integrations — for example ERC-4337 where a paymaster covers source-chain gas but the LI.FI route transaction itself must not require separate native token value — opt in explicitly: + +```javascript +import { + LifiSwidgeProtocol, + NATIVE_VALUE_BRIDGE_DENY_LIST +} from '@lifi/wdk-protocol-swidge-lifi' + +const swidge = new LifiSwidgeProtocol(account, { + denyBridges: NATIVE_VALUE_BRIDGE_DENY_LIST, // filter native-value bridges at quote time + allowNativeValue: false // reject any quote whose tx still needs native value +}) +``` + +`NATIVE_VALUE_BRIDGE_DENY_LIST` is the maintained list of bridges known to require native token value in the source transaction. `denyBridges` replaces (does not append to) any default, so `denyBridges: ['across']` denies only `across`. + +Set `allowDestinationCall: false` to exclude routes that require a destination-chain call, such as a swap after bridging, which can leave the user holding an intermediary token if the destination call fails. + +With `allowNativeValue: false`, execution rejects any quote whose transaction request requires native token value before sending approvals or the route transaction, even if a native-value bridge was not filtered out at quote time. + ## Contract Validation The module always validates returned transaction data before forwarding it to the wallet. Enable `trustedContracts` when the integration also needs an allowlist check against LI.FI Diamond deployments and Permit2. diff --git a/content/docs/sdk/swidge-modules/swidge-lifi/index.mdx b/content/docs/sdk/swidge-modules/swidge-lifi/index.mdx index 9ada03e7..76b56326 100644 --- a/content/docs/sdk/swidge-modules/swidge-lifi/index.mdx +++ b/content/docs/sdk/swidge-modules/swidge-lifi/index.mdx @@ -1,6 +1,6 @@ --- title: LI.FI Swidge Overview -description: Overview of the @kenny_io/wdk-protocol-swidge-lifi module for LI.FI swap and bridge routes. +description: Overview of the @lifi/wdk-protocol-swidge-lifi module for LI.FI swap and bridge routes. docType: explanation schemaType: TechArticle --- @@ -16,6 +16,7 @@ Use this module when an app needs live LI.FI route discovery, exact-input or exa - **EVM account support**: Works with `@tetherto/wdk-wallet-evm` and `@tetherto/wdk-wallet-evm-erc-4337`. - **Discovery without signing**: Supports chain and token discovery without a bound wallet account. - **Fee controls**: Applies optional `maxNetworkFeeBps` and `maxProtocolFeeBps` limits before execution. +- **Gasless-friendly**: Opt-in `denyBridges: NATIVE_VALUE_BRIDGE_DENY_LIST` and `allowNativeValue: false` filter native-value bridge routes and reject native-value quotes, so ERC-4337 sponsored execution can cover gas without the LI.FI route requiring separate native token value. - **Reliability controls**: Provides request timeouts, retry handling, rate-limit classification, and typed LI.FI errors. - **Transaction validation**: Validates quote transaction data before forwarding it to the wallet account. - **Optional contract allowlist**: `trustedContracts` can require quote targets and approval addresses to match known LI.FI contracts. @@ -47,10 +48,12 @@ Numeric LI.FI chain IDs are also accepted where the module accepts chain input. | `WalletAccountEvm` | Quotes and executes routes. | | `WalletAccountEvmErc4337` | Quotes and executes routes with smart-account gas handling. | | `WalletAccountReadOnlyEvm` | Quotes, status lookups, and discovery only. | -| No account | Discovery and account-independent quote setup only. | +| No account | Chain and token discovery only. | + +Use a read-only EVM account when you need quotes without signing. LI.FI quotes require a source address, so no-account mode is limited to chain and token discovery. -`swidge()` can approve and submit one or more EVM transactions. Show the quote, fee breakdown, destination token, destination chain, recipient, and refund address before calling it. +`swidge()` can approve and submit one or more EVM transactions. Show the quote, fee breakdown, destination token, destination chain, and recipient before calling it. ## Next Steps diff --git a/content/docs/sdk/swidge-modules/swidge-lifi/usage.mdx b/content/docs/sdk/swidge-modules/swidge-lifi/usage.mdx index 5527ac6e..906f2c06 100644 --- a/content/docs/sdk/swidge-modules/swidge-lifi/usage.mdx +++ b/content/docs/sdk/swidge-modules/swidge-lifi/usage.mdx @@ -1,6 +1,6 @@ --- title: LI.FI Swidge Usage -description: Install and use @kenny_io/wdk-protocol-swidge-lifi for LI.FI swap and bridge routes. +description: Install and use @lifi/wdk-protocol-swidge-lifi for LI.FI swap and bridge routes. docType: how-to schemaType: TechArticle icon: BookOpen @@ -9,7 +9,7 @@ icon: BookOpen ## Install ```bash -npm install @kenny_io/wdk-protocol-swidge-lifi +npm install @lifi/wdk-protocol-swidge-lifi ``` Install the wallet module for the account type you plan to use: @@ -23,7 +23,7 @@ npm install @tetherto/wdk-wallet-evm-erc-4337 ```javascript import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm' -import { LifiSwidgeProtocol } from '@kenny_io/wdk-protocol-swidge-lifi' +import { LifiSwidgeProtocol } from '@lifi/wdk-protocol-swidge-lifi' const account = new WalletAccountEvm(seedPhrase, "0'/0/0", { provider: 'https://mainnet.infura.io/v3/YOUR_KEY' @@ -62,7 +62,6 @@ const quote = await swidge.quoteSwidge({ toToken: '0xdAC17F958D2ee523a2206206994597C13D831ec7', toChain: 'arbitrum', recipient: '0xRecipient...', - refundAddress: '0xRefund...', fromTokenAmount: 10_000_000n, slippage: 0.01 }) @@ -92,7 +91,6 @@ const result = await swidge.swidge({ toToken: '0xdAC17F958D2ee523a2206206994597C13D831ec7', toChain: 'arbitrum', recipient: '0xRecipient...', - refundAddress: '0xRefund...', fromTokenAmount: 10_000_000n }, { maxNetworkFeeBps: 100, @@ -103,6 +101,20 @@ console.log('Swidge ID:', result.id) console.log('Transaction hash:', result.hash) ``` +### Guard a quote-first flow with `minAmountOut` + +`swidge()` fetches a fresh quote at execution time, which can differ from the quote the user reviewed. Pass `minAmountOut` — the `toTokenAmountMin` from the displayed quote — to reject execution if the fresh quote's minimum output has dropped below what the user accepted. The guard runs before any approval or transaction is sent, and the value is never forwarded to LI.FI. + +```javascript +const quote = await swidge.quoteSwidge(options) +// ...user reviews and confirms the quote... + +const result = await swidge.swidge({ + ...options, + minAmountOut: quote.toTokenAmountMin +}) +``` + ## Track Status Use `getSwidgeStatus()` with the returned operation ID. Chain hints can speed up indexing. @@ -126,7 +138,7 @@ import { LifiRateLimitError, LifiSlippageError, LifiTimeoutError -} from '@kenny_io/wdk-protocol-swidge-lifi' +} from '@lifi/wdk-protocol-swidge-lifi' try { await swidge.swidge(options)