docs(swidge): add BOB Gateway swidge module #208
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| --- | ||
| title: BOB Gateway Swidge Configuration | ||
| description: Configuration options for @gobob/wdk-protocol-swidge-gateway. | ||
| docType: reference | ||
| schemaType: TechArticle | ||
| icon: Settings | ||
| --- | ||
|
|
||
| `GatewaySwidge` works with no configuration beyond a source chain. The module ships a default API endpoint and a default attribution token, so a minimal setup is enough to quote and execute. | ||
|
|
||
| ```javascript | ||
| import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway' | ||
|
|
||
| const gateway = new GatewaySwidge(account, { | ||
| fromChain: 'bitcoin' | ||
| }) | ||
| ``` | ||
|
|
||
| ## Constructor | ||
|
|
||
| ```typescript | ||
| new GatewaySwidge(account?, config?) | ||
| ``` | ||
|
|
||
| | Parameter | Description | | ||
| |-----------|-------------| | ||
| | `account` | WDK wallet account for the source chain — a `@tetherto/wdk-wallet-btc` account for BTC sources, or a `@tetherto/wdk-wallet-evm` (or ERC-4337) account for token sources. Quoting and discovery work without a writable account. | | ||
| | `config` | Optional `GatewaySwidgeConfig`. Set `fromChain` here unless you pass it per call. | | ||
|
|
||
| ## Configuration Options | ||
|
|
||
| | Option | Type | Description | | ||
| |--------|------|-------------| | ||
| | `fromChain` | `string` | Source chain identifier, for example `'bitcoin'`, `'ethereum'`, or `'base'`. Required unless supplied in the route options. | | ||
| | `slippage` | `number` | Default slippage tolerance as a decimal. Defaults to `0.03` (3%). Override per call in the route options. | | ||
| | `affiliates` | `Array<{ address: string, bps: number }>` | Affiliate fee entries, in basis points, credited to each address. Applies to BTC to EVM and EVM to BTC routes only. | | ||
| | `feeRate` | `number` | Bitcoin fee rate in sat/vByte for onramp transactions. Defaults to a gateway-supplied estimate. | | ||
| | `paymasterToken` | `string` | ERC-20 token used to pay gas on ERC-4337 accounts. | | ||
| | `bearerToken` | `string` | Gateway API bearer token. Defaults to BOB's shared attribution key — see [API access](#api-access). | | ||
| | `apiUrl` | `string` | Gateway API base URL override. | | ||
| | `http` | `object` | Injectable HTTP transport. Useful for tests and custom runtimes. | | ||
| | `client` | `GatewayClient` | A pre-built client instance. Overrides `apiUrl`, `bearerToken`, and `http`. | | ||
|
|
||
| ## Source Chain | ||
|
|
||
| The module signs on the source chain, so `fromChain` decides which WDK account it needs. Create one `GatewaySwidge` instance per source chain. | ||
|
|
||
| ```javascript | ||
| // BTC as the source: pass a WDK Bitcoin account. | ||
| const fromBtc = new GatewaySwidge(btcAccount, { fromChain: 'bitcoin' }) | ||
|
|
||
| // A token as the source: pass a WDK EVM account. | ||
| const fromBase = new GatewaySwidge(evmAccount, { fromChain: 'base' }) | ||
| ``` | ||
|
|
||
| ## Slippage | ||
|
|
||
| Set a default in the constructor and override it for a single route when needed. | ||
|
|
||
| ```javascript | ||
| const gateway = new GatewaySwidge(account, { | ||
| fromChain: 'bitcoin', | ||
| slippage: 0.01 // 1% | ||
| }) | ||
|
|
||
| const quote = await gateway.quoteSwidge({ | ||
| ...options, | ||
| slippage: 0.005 // 0.5% for this route only | ||
| }) | ||
| ``` | ||
|
|
||
| ## Affiliate Fees | ||
|
|
||
| Charge a fee on BTC to EVM and EVM to BTC routes by crediting one or more addresses in basis points of the input amount. Affiliate fees are not supported on EVM-to-EVM routes. | ||
|
|
||
| ```javascript | ||
| const gateway = new GatewaySwidge(account, { | ||
| fromChain: 'bitcoin', | ||
| affiliates: [{ address: '0xYourFeeRecipient...', bps: 25 }] // 0.25% | ||
| }) | ||
| ``` | ||
|
|
||
| Affiliate fees appear in the quote's itemized `fees` array with type `affiliate`, so a UI can display them before the user confirms. | ||
|
|
||
| ## API Access | ||
|
|
||
| Every request carries a bearer token. If you do not set one, the module sends BOB's shared `gateway-wdk` attribution key, which costs nothing extra and attributes the volume to BOB. | ||
|
|
||
| ```javascript | ||
| // Uses BOB's default attribution key. | ||
| const gateway = new GatewaySwidge(account, { fromChain: 'bitcoin' }) | ||
|
|
||
| // Uses your own key. Set this only if you have a direct API agreement with BOB. | ||
| const gateway = new GatewaySwidge(account, { | ||
| fromChain: 'bitcoin', | ||
| bearerToken: process.env.GATEWAY_API_KEY | ||
| }) | ||
| ``` | ||
|
|
||
| <Callout type="info"> | ||
| The Gateway API applies a **country blocklist** that includes the United States and the United Kingdom alongside sanctioned jurisdictions. Requests from a blocked country receive a `403`. See the [Gateway FAQ](https://docs.gobob.xyz/gateway/faq#are-any-regions-blocked-from-using-gateway) for the current list. CI that exercises live quotes must run from a non-blocked region. | ||
| </Callout> | ||
|
|
||
| ## Bitcoin Fee Rate | ||
|
|
||
| Onramp transactions use a gateway-supplied fee estimate by default. Override it when your app already tracks mempool conditions. | ||
|
|
||
| ```javascript | ||
| const gateway = new GatewaySwidge(btcAccount, { | ||
| fromChain: 'bitcoin', | ||
| feeRate: 12 // sat/vByte | ||
| }) | ||
| ``` | ||
|
|
||
| ## ERC-4337 Accounts | ||
|
|
||
| Pass `paymasterToken` to pay gas in an ERC-20 when the source account is an ERC-4337 smart account from `@tetherto/wdk-wallet-evm-erc-4337`. | ||
|
|
||
| ```javascript | ||
| const gateway = new GatewaySwidge(smartAccount, { | ||
| fromChain: 'base', | ||
| paymasterToken: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2' // USDT on Base | ||
| }) | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| --- | ||
| title: BOB Gateway Swidge Overview | ||
| description: Overview of the @gobob/wdk-protocol-swidge-gateway module for native BTC swap and bridge routes. | ||
| docType: explanation | ||
| schemaType: TechArticle | ||
| --- | ||
|
|
||
| The BOB Gateway Swidge module lets WDK accounts quote and execute **native Bitcoin** swap and bridge routes through [BOB Gateway](https://gobob.xyz) using the shared `SwidgeProtocol` interface. | ||
|
|
||
| Use this module when an app needs to move real BTC in or out of tokens on EVM chains and Tron. Bitcoin is spent and received on Bitcoin L1 — there is no wrapped-BTC intermediary and no custodian, and keys never leave the WDK account. | ||
|
Contributor
There was a problem hiding this comment. Could we describe the observable mechanics here instead of using “real BTC”, “no custodian”, and “keys never leave”? “Native BTC on Bitcoin L1, signed through the WDK account, with settlement handled by Gateway” feels closer to the neutral style used elsewhere in the docs. |
||
|
|
||
| ## Features | ||
|
|
||
| - **Unified route interface**: Implements `quoteSwidge()`, `swidge()`, `getSwidgeStatus()`, `getSupportedChains()`, and `getSupportedTokens()`. | ||
| - **Native BTC routes**: Swaps native BTC to and from USDT, USDC, ETH, wBTC, cbBTC, and XAUT across Ethereum, Base, Arbitrum, and BSC. | ||
| - **BTC to Tron**: Sends BTC and receives USDT (or other supported tokens) on Tron. | ||
| - **EVM to EVM**: Same-chain swaps and cross-chain bridges through the inherited `swap()` and `bridge()` methods. | ||
| - **Non-custodial**: Signing is delegated to the WDK account. The module never touches private keys. | ||
| - **Affiliate fees**: Optional per-address basis-point fees on BTC to EVM and EVM to BTC routes. | ||
| - **Approval pre-flight**: `getRequiredApproval()` reports the exact ERC-20 approval an offramp needs before execution. | ||
| - **Multi-runtime**: Runs on Node.js, Bare (`bare.js`), and React Native. | ||
| - **Typed errors**: Exposes `GatewaySwidgeError` with stable `ERR` codes for HTTP, validation, unsupported route, and approval failures. | ||
|
|
||
| ## Supported Routes | ||
|
|
||
| Call `getSupportedChains()` and `getSupportedTokens()` at runtime — BOB Gateway controls the live route set and adds chains and tokens over time. | ||
|
|
||
| | Route | Source support | Notes | | ||
| |-------|----------------|-------| | ||
| | BTC to EVM (onramp) | Supported | Spends native BTC from a `@tetherto/wdk-wallet-btc` account. Supports affiliate fees. | | ||
| | EVM to BTC (offramp) | Supported | Spends an ERC-20 from a `@tetherto/wdk-wallet-evm` account. Requires an approval first. Supports affiliate fees. | | ||
| | BTC to Tron | Supported | Tron is a **destination only**. Tron as a source is not supported; see the [Tron source tracking issue](https://github.com/tetherto/wdk-wallet-tron/issues/48). | | ||
| | EVM to EVM | Supported | Use the inherited `swap()` and `bridge()` methods. Affiliate fees do not apply to this route. | | ||
| | Solana | Not yet available | Planned. | | ||
|
|
||
| ## Execution Model | ||
|
|
||
| The route direction determines which chain the module signs on. | ||
|
|
||
| **Onramp (BTC to a token).** `swidge()` builds and signs a Bitcoin transaction through the WDK BTC account, then hands it to the gateway. **The gateway broadcasts the Bitcoin transaction — the module does not.** The call resolves once the transaction is registered; the destination tokens settle asynchronously. | ||
|
|
||
| **Offramp (a token to BTC).** `swidge()` submits the source-chain EVM transaction after the required ERC-20 approval is in place. It resolves once that transaction is broadcast, and BTC settles on Bitcoin L1 asynchronously. | ||
|
|
||
| In both directions, use `getSwidgeStatus(result.id)` to track the route to completion. | ||
|
|
||
| <Callout type="warn"> | ||
| `swidge()` spends real funds and can submit a Bitcoin or EVM transaction. Show the quote, fee breakdown, recipient, source token, destination token, and destination chain, and ask for explicit user confirmation before calling it. | ||
| </Callout> | ||
|
|
||
| <Callout type="info"> | ||
| The Gateway API applies a **country blocklist** that includes the United States and the United Kingdom alongside sanctioned jurisdictions. Requests from a blocked country receive a `403`. See the [Gateway FAQ](https://docs.gobob.xyz/gateway/faq#are-any-regions-blocked-from-using-gateway) for the current list, and account for it in both production deployments and CI. | ||
| </Callout> | ||
|
|
||
| ## Next Steps | ||
|
|
||
| <Cards> | ||
| <Card title="Configuration" href="/sdk/swidge-modules/swidge-gateway/configuration"> | ||
| Configure the source chain, slippage, affiliate fees, BTC fee rate, and API access. | ||
| </Card> | ||
| <Card title="Usage" href="/sdk/swidge-modules/swidge-gateway/usage"> | ||
| Install the package, register the module, quote a route, approve, execute, and poll status. | ||
| </Card> | ||
| <Card title="API Reference" href="/sdk/swidge-modules/swidge-gateway/api-reference"> | ||
|
Contributor
There was a problem hiding this comment. Wouldn't it be better to include |
||
| Review constructor options, methods, route options, status mapping, and error codes. | ||
| </Card> | ||
| </Cards> | ||
|
|
||
| --- | ||
|
|
||
| ## Need Help? | ||
|
|
||
| <SupportCards /> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Wouldn't it be better to add the standard community-module warning used by the community index and Orchestra overview? This module is listed as community-maintained, so the overview should make that distinction clear.