docs: Offramp Docs

docs/docs/learn/builder-guides/gateway.md

@@ -4,19 +4,28 @@ sidebar_position: 2
 
 # Integrate BOB Gateway in Your App
 
-[BOB Gateway](https://docs.gobob.xyz/learn/guides/bitcoin-bridge/) is a Bitcoin intent bridge that unlocks Bitcoin liquidity by reducing the number of steps to onboard users to your app, saving time and money. For example, users can go from **BTC** on Bitcoin to **staked BTC LSTs** with a single Bitcoin transaction.
+BOB Gateway is a Bitcoin intent bridge that unlocks Bitcoin liquidity by reducing the number of steps needed to onboard users to your app, saving time and money.
+For example, users can go from BTC on Bitcoin to staked BTC LSTs with a single Bitcoin transaction via the onramp.
+Users can also easily move from BOB back to Bitcoin using the offramp.
 
 Our SDK makes it possible for you to bring this UX directly into your app.
 
 ## How Gateway Works
+### Gateway-Onramp (Bitcoin -> BOB)
+1. Liquidity providers (LPs) temporarily lock wrapped Bitcoin (WBTC or tBTC) in escrow smart contracts on BOB. 
+2. A user makes a request for wrapped or staked Bitcoin (e.g. WBTC, tBTC, or a Bitcoin LST/LRT). 
+3. The user sends BTC to the liquidity provider's Bitcoin address. A hash of the user's order is included in the `OP_RETURN` of the transaction. 
+4. Gateway finalizes the transaction. After trustlessly verifying the user's Bitcoin transaction with an on-chain [Light Client](/learn/builder-guides/relay.md), Gateway sends the LP's wrapped Bitcoin to the user's EVM address. If the user requested a Bitcoin LST/LRT, that token is minted using the LP's wrapped Bitcoin before it is sent to the user.
 
-1. Liquidity providers (LPs) temporarily lock wrapped Bitcoin (WBTC or tBTC) in escrow smart contracts on BOB.
-1. A user makes a request for wrapped or staked Bitcoin (e.g. WBTC, tBTC, or a Bitcoin LST/LRT).
-1. The user sends BTC to the liquidity provider's Bitcoin address. A hash of the user's order is included in the `OP_RETURN` of the transaction.
+This SDK exposes helper functions for steps 2, 3, and 4 to be used in your application's front end.
 
-1. Gateway finalizes the transaction. After trustlessly verifying the user's Bitcoin transaction with an on-chain [Light Client](/learn/builder-guides/relay.md), Gateway sends the LP's wrapped Bitcoin to the user's EVM address. If the user requested a Bitcoin LST/LRT, that token is minted using the LP's wrapped Bitcoin before it is sent to the user.
+### Gateway-Offramp (BOB → Bitcoin)
+
+1. Users lock their wrapped Bitcoin (WBTC or tBTC) into a smart contract on BOB.
+2. Liquidity Providers (LPs) accept the user's order directly through the smart contract.
+3. The LP sends Bitcoin to the user's Bitcoin address, including proof in the transaction’s `OP_RETURN`.
+4. The Gateway finalizes the transaction by trustlessly verifying, using an on-chain [Light Client](/learn/builder-guides/relay.md), that the LP’s Bitcoin transfer matches the user's address and that the `OP_RETURN` matches the order data — unlocking the user's wrapped Bitcoin on BOB to the LP.
 
-This SDK exposes helper functions for steps 2, 3, and 4 to be used in your application's front end.
 :::info Learn More
 Discover the architecture of BOB Gateway and how it simplifies Bitcoin transactions by visiting our [BOB Gateway introduction page](../introduction/gateway).
 :::
@@ -40,7 +49,7 @@ Import the `GatewaySDK` class from `@gobob/bob-sdk` and create an instance of it
 ```ts title="/src/utils/gateway.ts"
 import { GatewayQuoteParams, GatewaySDK } from '@gobob/bob-sdk';
 
-const gatewaySDK = new GatewaySDK('bob'); // or "testnet"
+const gatewaySDK = new GatewaySDK('bob'); // or "signet"
 ```
 
 ### Get Available Tokens
@@ -51,6 +60,10 @@ Returns an array of available output tokens for you to offer the user. Typically
 const outputTokens = await gatewaySDK.getTokens();
 ```
 
+## Gateway-Onramp Methods
+
+The following methods onboard users from Bitcoin to BOB through a simple and secure flow.
+
 ### Get a Quote
 
 Call the `getQuote` method with your `quoteParams`. Example values shown here.
@@ -190,6 +203,90 @@ https://github.com/bob-collective/sats-wagmi/blob/ae876d96bb2e54e5a24e0f3e1aaa67
 </TabItem>
 </Tabs>
 
+## Gateway-Offramp Methods
+
+The following methods allow users to transfer wrapped Bitcoin from BOB to Bitcoin through a seamless and secure process.
+
+### Get a Quote and Start an Order
+
+Call the `createOfframpOrder` method with your `quoteParams`. Example values are shown below:
+
+```ts
+const quoteParams: GatewayQuoteParams = {
+  bitcoinUserAddress: 'tb1qcwcjsc0mltyt293877552grdktjhnvnnqyv83c', 
+  fromUserAddress: '0x2D2E86236a5bC1c8a5e5499C517E17Fb88Dbc18c', 
+  toToken: 'bobBTC',
+  amount: 4000000, // Amount should be in token decimals
+};
+
+const quote: OfframpCreateOrderParams = await gatewaySDK.createOfframpOrder(quoteParams);
+```
+
+Next, sign and send the transaction using the received quote details along with the ABI.
+The example below shows how to do this using Viem.  
+See more documentation on creating a [Viem client](https://viem.sh/docs/clients/wallet).
+
+Example: 
+
+```ts
+import { createWalletClient, http, privateKeyToAccount } from 'viem';
+import { bobSepolia } from 'viem/chains';
+
+// create wallet client
+const PRIVATE_KEY = '0xYOUR_PRIVATE_KEY'; // Make sure it has the 0x prefix
+const account = privateKeyToAccount(PRIVATE_KEY);
+const walletClient = createWalletClient({
+    account,
+    chain: bobSepolia,
+    transport: http(), // or custom(yourProvider) if needed
+});
+
+// Send the transaction using the received quote
+const txHash = await walletClient.writeContract({
+    address: quote.quote.registryAddress as `0x${string}`, // The registryAddress from the quote
+    abi: quote.offrampABI,
+    functionName: quote.offrampFunctionName,
+    args: quote.offrampArgs,
+});
+
+console.log('Transaction Hash:', txHash);
+```
+
+### Monitor the User's Orders
+
+Get an array of pending and completed orders for a specific EVM address. It .
+
+```ts
+const orders: OfframpOrderDetails = await gatewaySDK.getOfframpOrders(userEvmAddress);
+```
+
+### Bump Fees for User Order
+
+When monitoring user orders, if `shouldFeesBeBumped` is set to `true`, it indicates that the transaction fees need to be increased.  
+This can happen if the fee rate increased between the time the original quote was created and when the Liquidity Provider (LP) was processing the order.
+
+Example:
+```ts
+const bumpFee: OfframpBumpFeeParams[] = await gatewaySDK.bumpFeeForOfframpOrder(orderId);
+
+// Next, create and send the updated transaction via Viem
+```
+
+### Unlock User Order
+
+When monitoring an offramp order, if `canOrderBeUnlocked` returns `true`, it means the order can now be unlocked.  
+This happens when the order is still `Active`, or `Accepted` but not processed within the claim delay period.  
+Unlocking refunds the user's funds.
+
+Example:
+
+```ts
+const orderUnlock: OfframpUnlockFundsParams[] = await gatewaySDK.unlockOfframpOrder(orderId, receiverEvmAddress);
+
+// Next, create and send the unlock transaction via Viem
+```
+
+
 ## Conclusion
 
 BOB Gateway enables staking, swapping, lending, and bridging Bitcoin with a single transaction. The BOB SDK makes it possible for you to bring Gateway and Bitcoin LSTs directly to your users.

docs/docs/learn/introduction/gateway/index.md

@@ -6,9 +6,17 @@ sidebar_position: 2
 
 ## Introduction
 
-Bitcoin users can easily onboard to the BOB Hybrid L2 without previously holding any Ethereum assets. This page explains the technology behind [BOB BTC Bridge](https://app.gobob.xyz/en?type=deposit&network=bitcoin&receive=WBTC) and [BOB Stake](https://app.gobob.xyz/en/stake): _BOB Gateway_ is an intent-based bridge that coordinates peer-to-peer swaps between users and liquidity providers (LPs).
+Bitcoin users can easily onboard to the BOB Hybrid L2 without needing to hold any Ethereum assets.  
+This page explains the technology behind BOB BTC Bridge and BOB Stake.
 
-Cross-chain transfers are secured by verifying Bitcoin transaction proofs with an [on-chain light client](/learn/builder-guides/relay), avoiding the need for an oracle. Optional intents, such as staking, lending, and swapping tokens can all be accomplished while only requiring a single Bitcoin transaction from the user.
+**BOB Gateway** is an intent-based bridge that coordinates peer-to-peer swaps between users and liquidity providers (LPs).  
+It has two main components:
+
+- [**Gateway-Onramp**](https://app.gobob.xyz/en?type=deposit&network=bitcoin&receive=WBTC): Enables users to move from Bitcoin to BOB in a single transaction.
+- [**Gateway-Offramp**](https://app.gobob.xyz/en?type=withdraw): Allows users to move from BOB back to Bitcoin, unlocking wrapped Bitcoin (such as WBTC or tBTC).
+
+Cross-chain transfers are secured by verifying Bitcoin transaction proofs with an [on-chain light client](/learn/builder-guides/relay), avoiding the need for an external oracle.  
+Optional intents — such as staking, lending, and swapping tokens — can all be fulfilled with just a single Bitcoin transaction from the user.
 
 ## Bridge or Stake BTC on BOB
 
@@ -34,36 +42,69 @@ These are some of the features we're working on for Gateway's next upgrade, with
 [See our Builder Guide](/learn/builder-guides/gateway) to learn more about our SDK and extending BOB Gateway's functionality to bring Bitcoiners one transaction away from your use-case.
 :::
 
-## How Gateway Works
+## How Gateway-Onramp Works
 
 1. Liquidity providers (LPs) temporarily lock wrapped Bitcoin (WBTC or tBTC) in escrow smart contracts on BOB.
-1. A user makes a request to the off-chain relayer to reserve some of the available liquidity.
-1. The user sends BTC to the liquidity provider's Bitcoin address. A hash of the user's order is included in the `OP_RETURN` of their transaction, including data such as the recipient's EVM address on BOB and their desired strategy (i.e. their intent).
-1. The relayer submits a Merkle proof of the user's Bitcoin transaction to an on-chain [Light Client](/learn/builder-guides/relay), granting the relayer permission to withdraw the LP's wrapped Bitcoin. **Encoding the user's order in their Bitcoin transaction makes it possible to trustlessly verify and complete the user's intent without using an oracle.**
-1. Gateway sends the LP's wrapped Bitcoin to the user's EVM address. If the user requested a Bitcoin LST/LRT, that token is minted using the LP's wrapped Bitcoin _before_ it is sent to the user.
+2. A user makes a request to the off-chain relayer to reserve some of the available liquidity.
+3. The user sends BTC to the liquidity provider's Bitcoin address. A hash of the user's order is included in the `OP_RETURN` of their transaction, including data such as the recipient's EVM address on BOB and their desired strategy (i.e. their intent).
+4. The relayer submits a Merkle proof of the user's Bitcoin transaction to an on-chain [Light Client](/learn/builder-guides/relay), granting the relayer permission to withdraw the LP's wrapped Bitcoin. **Encoding the user's order in their Bitcoin transaction makes it possible to trustlessly verify and complete the user's intent without using an oracle.**
+5. Gateway sends the LP's wrapped Bitcoin to the user's EVM address. If the user requested a Bitcoin LST/LRT, that token is minted using the LP's wrapped Bitcoin _before_ it is sent to the user.
 
-## Architecture
+### Gateway-Onramp Architecture
 
 <img
 src={require("./architecture.png").default}
 style={{ width: "100%", maxWidth: "100%", height: "auto" }}
 alt="architecture"
 />
 
-### User Flow
+### Gateway-Onramp User Flow
 
-1. A user requests to swap BTC for wrapped BTC (e.g. WBTC, tBTC, or FBTC) or staked BTC (e.g. xSolvBTC, uniBTC).
-1. The user gets a "quote" of which Gateway smart contract is an available route (i.e. which LP they can swap with).
-1. The user creates an "order" with the relayer to reserve the LP's liquidity.
-1. The user creates a Bitcoin transaction, updating the order with their txid. Gateway's SDK creates a hash of the user's intent, which is included in the `OP_RETURN` of the transaction. This hash includes metadata such as the user's EVM address, which strategy they are using (i.e. their intent), and how many sats to convert to ETH for gas, among other data. By including a deterministic hash of the user's order, we lay the groundwork for making Gateway trustless in the future by decentralizing the relayer set.
-1. The relayer monitors the Bitcoin chain and sends the LP's wrapped BTC to the user after the txid is seen on Bitcoin. Specifically, the relayer submits a Merkle proof of the user's Bitcoin tx to an [on-chain light client](/learn/builder-guides/relay) for trustless verification of the user's intent. It accomplishes this by requiring that the recipient's EVM address, sequence of smart contract calls, and other order data exactly match the hash in the `OP_RETURN` of the user's Bitcoin transaction.
+1. A user requests to swap wrapped Bitcoin (e.g. tBTC, WBTC) for native Bitcoin (BTC).
+2. The user receives an "offramp quote," including estimated fees and available liquidity.
+3. The user creates an "offramp order" by interacting with the `OfframpRegistry` smart contract, locking their wrapped Bitcoin.
+4. The liquidity provider (LP) monitors the order, accepts it, and sends the corresponding BTC to the user's Bitcoin address. The Bitcoin transaction includes the order's metadata in the `OP_RETURN`, enabling trustless verification.
+5. If the order is not accepted in time, the user can either bump the transaction fee to attract solvers (LPs) or unlock their funds back to their EVM address after a claim delay.
 
-### Liquidity Provider (LP) Flow
+### Gateway-Onramp Liquidity Provider (LP) Flow
 
 1. An LP asks the relayer to deploy a new Gateway contract, which functions as an escrow for their funds. This is permissioned at the moment because BOB pays the transaction's gas. See the [Trust Assumptions](#trust-assumptions) section below for more information.
 2. The LP deposits wrapped Bitcoin (e.g. WBTC, tBTC, FBTC) in their Gateway contract.
 3. The LP can only withdraw their funds or update their swap fees after a delay so that the relayer has time to finish open orders. The relayer will not accept new orders during this delay until reset.
 
+## How Gateway-Offramp Works
+
+1. Liquidity providers (LPs) register their solver and fund them with native Bitcoin (BTC).
+2. A user requests a quote for swapping wrapped Bitcoin (e.g., tBTC, WBTC) to native Bitcoin.
+3. The user submits an "offramp order" to the `OfframpRegistry` smart contract, locking their wrapped Bitcoin and specifying their Bitcoin address.
+4. A solver (LP) monitors open orders, accepts one, and broadcasts a Bitcoin transaction to the user's specified address. The transaction includes metadata (e.g., order ID) in the `OP_RETURN` field to enable trustless verification.
+5. The solver notifies the relayer, which then submits a Merkle proof of the Bitcoin transaction to the on-chain `OfframpRegistry`. This proof unlocks the wrapped Bitcoin, transferring it to the solver as reimbursement.
+6. If the order is not fulfilled, users can bump transaction fees to incentivize LPs or unlock their locked assets after a claim delay period.
+
+### Gateway-Offramp Architecture
+<img
+src={require("./offramp.png").default}
+style={{ width: "100%", maxWidth: "100%", height: "auto" }}
+alt="architecture"
+/>
+
+### Gateway-Offramp User Flow
+
+1. A user requests to swap wrapped Bitcoin (e.g., tBTC, WBTC) for native Bitcoin (BTC).
+2. The user receives an "offramp quote," including estimated fees and liquidity availability.
+3. The user creates an offramp order by locking wrapped Bitcoin in `OfframpRegistry.sol`.
+4. A liquidity provider (solver) accepts the order, sends the Bitcoin transaction to the user’s Bitcoin address, and attaches the order metadata in `OP_RETURN`.
+5. If the order is not accepted within a reasonable time, the user can either bump transaction fees or unlock their funds.
+
+### Gateway-Offramp Liquidity Provider (LP) Flow
+
+1. An LP registers their solver address in `OfframpRegistry.sol` and configures it to accept user orders.
+2. The LP runs an `offramp-solver` binary and funds it with Bitcoin (BTC) to fulfill user requests.
+3. The solver continuously scans for open user orders and matches those that meet acceptable fee thresholds.
+4. Upon finding a matching order, the solver broadcasts a Bitcoin transaction to the user’s address, embedding the necessary metadata.
+5. After confirmation, the solver notifies the relayer via API. The relayer submits a Merkle proof to `OfframpRegistry.sol`, unlocking the user's locked wrapped Bitcoin and transferring it to the solver as settlement.
+
+
 ## Adoption and Fees
 
 You can find the current liquidity, LPs, and usage of Gateway on the [BOB Gateway Dune dashboard](https://dune.com/bob_collective/gateway).