docs: Offramp Docs #585
docs: Offramp Docs #585
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
WalkthroughThe documentation for the BOB Gateway has been significantly expanded and clarified. The changes introduce explicit separation and detailed descriptions of both Gateway-Onramp and Gateway-Offramp flows, including step-by-step guides, architecture diagrams, and user/LP interactions. New code examples and SDK usage instructions for offramp operations are provided. An additional audit entry is included for the Offramp Registry Smart Contract, and a new Excalidraw diagram visually represents the offramp architecture. No changes were made to public or exported code entities; all updates are strictly to documentation and diagrams. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Gateway SDK
participant Offramp Registry Contract
participant Liquidity Provider (LP)
participant Solver
participant Relayer
User->>Gateway SDK: createOfframpOrder()
Gateway SDK->>Offramp Registry Contract: Submit order (lock wBTC)
LP->>Gateway SDK: Monitor orders
LP->>Solver: Accept order, prepare BTC transfer
Solver->>User: Send BTC with OP_RETURN (order hash)
Relayer->>Offramp Registry Contract: Prove BTC transfer (Merkle proof)
Offramp Registry Contract->>LP: Unlock wBTC to solver
Gateway SDK->>User: Notify order completion
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
docs/docs/learn/builder-guides/gateway.md (6)
7-7: Clarify "intent bridge" terminology: The term “Bitcoin intent bridge” may not be immediately clear to readers. Consider linking to a brief definition or adding a short parenthetical explanation of “intent bridge” to improve clarity.
14-18: Maintain consistent phrasing and casing in step list: The Onramp steps are clear, but for style consistency:
- Capitalize “Providers” or keep it lowercase in all instances (“Liquidity Providers” vs “liquidity providers”).
- Consider using an imperative verb form (e.g., “Request wrapped Bitcoin” instead of “A user makes a request”).
20-20: Map SDK methods to numbered steps: This line mentions that the SDK provides helpers for steps 2–4; consider naming the actual methods (getQuote,startOrder,finalizeOrder) inline or linking to their detailed descriptions so readers can directly connect steps to API calls.
24-27: Unify capitalization in Offramp step titles: Similar to the Onramp section, ensure consistent casing for “Liquidity Providers” vs “liquidity providers” across all steps to maintain a uniform style.
52-52: Clarify network parameter naming: The code usesnew GatewaySDK('bob')with a comment// or "signet". It may be helpful to clarify that'bob'refers to the production mainnet and'signet'is the test network, to prevent confusion for developers integrating the SDK.
231-253: Avoid hardcoding private keys in examples: For security best practices, demonstrate reading the private key from an environment variable (e.g.,process.env.PRIVATE_KEY) instead of hardcoding it in the sample. This helps prevent accidental leaks in published examples.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/learn/builder-guides/gateway.md(4 hunks)
🔇 Additional comments (4)
docs/docs/learn/builder-guides/gateway.md (4)
22-22: New Offramp section header: The “Offramp (BOB → Bitcoin)” header correctly introduces the reverse flow.
63-63: New Onramp Methods header: This header clearly delineates the Onramp SDK methods section.
206-208: New Offramp Methods introduction: The added header and introductory sentence effectively outline the Offramp SDK methods.
214-223: Verify parameter and return types for Offramp order creation: The snippet definesconst quoteParams: GatewayQuoteParamsand then usesOfframpCreateOrderParamsfor the output. Please confirm thatcreateOfframpOrderacceptsGatewayQuoteParams(as opposed to a dedicatedOfframpQuoteParams) and that the correct types (OfframpCreateOrderParams) are imported and used.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (6)
docs/docs/learn/builder-guides/gateway.md (5)
14-18: Ensure consistent linking style for Light Client reference
Onramp step 4 links to/learn/builder-guides/relay.md. To match the rest of our docs (which generally omit the.mdextension), consider updating this to/learn/builder-guides/relay.
63-63: Adjust header level for consistency
This sub-section is nested under “Step-by-Step Integration Guide” and should use###instead of##(e.g.### Gateway-Onramp Methods).
206-206: Adjust header level for Offramp Methods
Under “Step-by-Step Integration Guide,” this should be### Gateway-Offramp Methodsto maintain a consistent header hierarchy.
210-210: Refine sub-section title
Consider renaming to “### Create an Offramp Order” (or splitting into “Get an Offramp Quote” and “Start Offramp Order”) to mirror the onramp section structure more closely.
230-252: Add error handling to Viem transaction call
The example broadcasts a contract write withwalletClient.writeContract(...)but doesn’t show how to catch or handle errors. Consider wrapping this in atry/catchor logging failures to improve robustness in production code.docs/docs/learn/introduction/gateway/index.md (1)
71-71: Replace “at the moment” with an adverb for conciseness
Consider rewriting to “This is currently permissioned because BOB pays the transaction’s gas.” to streamline the phrasing.🧰 Tools
🪛 LanguageTool
[style] ~71-~71: For conciseness, consider replacing this expression with an adverb.
Context: ...w for their funds. This is permissioned at the moment because BOB pays the transaction's gas....(AT_THE_MOMENT)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/docs/learn/introduction/gateway/offramp.pngis excluded by!**/*.png
📒 Files selected for processing (3)
docs/docs/learn/builder-guides/gateway.md(4 hunks)docs/docs/learn/introduction/gateway/index.md(2 hunks)docs/docs/learn/introduction/gateway/offramp.excalidraw(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/docs/learn/introduction/gateway/offramp.excalidraw
🧰 Additional context used
🪛 LanguageTool
docs/docs/learn/introduction/gateway/index.md
[style] ~71-~71: For conciseness, consider replacing this expression with an adverb.
Context: ...w for their funds. This is permissioned at the moment because BOB pays the transaction's gas....
(AT_THE_MOMENT)
🔇 Additional comments (16)
docs/docs/learn/builder-guides/gateway.md (11)
7-9: Approve improved Gateway introduction
The added overview clearly summarizes the Gateway’s onramp and offramp capabilities, improving discoverability.
20-20: Approve SDK helper functions note
Great call-out that steps 2–4 are exposed via SDK helper functions for front-end integration.
22-22: Approve new Offramp section header
Adding a distinct “Gateway-Offramp (BOB → Bitcoin)” header helps builders quickly locate the reverse flow.
24-27: Approve detailed Offramp flow steps
The 4-step offramp flow is clearly enumerated and aligns well with the onramp section structure.
52-52: Clarify environment parameter for GatewaySDK constructor
Please verify that'bob'is the correct default network identifier. It may be helpful to explicitly mention that'bob'targets mainnet and'signet'targets testnet in the comment to avoid confusion.
65-65: Approve onboarding methods introduction
The description sets the expectation for the upcoming onramp method details nicely.
208-208: Approve Offramp methods overview
Good addition describing the purpose of the upcoming SDK methods for the offramp flow.
212-212: Approve Offramp order creation instruction
Clear guidance on callingcreateOfframpOrderwith examplequoteParams.
214-223: Verify types and return value of createOfframpOrder
The snippet types the output asOfframpCreateOrderParams, which suggests it’s the input shape. Please confirm thatcreateOfframpOrderactually returns this type and update variable/type names if necessary to avoid confusion between input params and response.
263-273: Approve fee bumping example
This section clearly shows how to detect and bump fees on pending Offramp orders—great for LP awareness of dynamic fee environments.
275-287: Approve unlock funds example
The unlock flow example neatly completes the Offramp methods, demonstrating how to safely refund or reclaim funds after the claim delay.docs/docs/learn/introduction/gateway/index.md (5)
9-10: Approve refined introduction
Great expansion to explicitly mention that no Ethereum assets are needed and link to BOB BTC Bridge and BOB Stake.
15-16: Approve new navigation links
Adding direct links to Onramp and Offramp applications improves UX for end-users and builders.
45-51: Approve detailed Gateway-Onramp steps
The split “How Gateway-Onramp Works” section with a numbered flow clarifies each handoff between users, relayer, and on-chain verification.
75-82: Approve Gateway-Offramp overview
The new “How Gateway-Offramp Works” flow is comprehensive and mirrors the onramp pattern, making the bidirectional swap mechanism clear.
84-89: Approve architecture diagram inclusion
Great addition of the Offramp architecture diagram, providing visual clarity on component interactions.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (11)
docs/docs/learn/builder-guides/gateway.md (6)
7-7: Clarify description of Gateway
Consider rephrasing “Bitcoin intent bridge” to “intent-based bridge” to improve readability and align terminology with other sections.
20-20: Add Offramp helper-functions note
For consistency, you might mirror the SDK helper-functions callout used in the Onramp section by adding a similar line before the Offramp steps:This SDK exposes helper functions for steps 1–4 of the Offramp flow to use in your app's front end.
22-27: Unify arrow and capitalization style
The Onramp heading uses “->” and the Offramp heading uses “→”. Standardize to one arrow character (preferably “→”) and ensure title-case consistency across both headings.
235-236: Capitalize comment and add punctuation
For consistency with other comments, capitalize the verb and end with a period:-// create wallet client +// Create wallet client.
270-272: Pluralize variable for array content
ThebumpFeevariable holds an array (OfframpBumpFeeParams[]). Consider renaming tobumpFeesor handling a single bump‐fee object per call to avoid confusion.
284-286: Clarify unlock function parameter
The example usesOfframpUnlockFundsParams[]but passes a singleorderId. If only one unlock is supported at a time, use a singular type; otherwise, demonstrate passing multiple IDs.docs/docs/learn/introduction/gateway/index.md (5)
9-9: Clarify “Hybrid L2” term
Consider adding a brief definition or link for “Hybrid L2” to help readers unfamiliar with BOB’s architecture immediately understand the reference.
48-48: Streamline step description
In step 2, you could shorten “makes a request to the off-chain relayer to reserve some of the available liquidity” to “requests liquidity reservation from the off-chain relayer” for brevity and active voice.
49-51: Split long sentence for readability
Step 4 is very long. Consider breaking it into two sentences at the bolded clause to improve comprehension and emphasize the trustless verification point.
77-82: Ensure consistent terminology
Across the Offramp steps, you alternate between “submits” and “locks”/“sends.” Standardize verbs (e.g., always “lock,” “submit,” or “send”) to reduce cognitive load on readers.
70-70: Replace verbose phrase
For conciseness, swap “at the moment” with “currently”:- This is permissioned at the moment because BOB pays the transaction's gas. + This is permissioned currently because BOB pays the transaction's gas.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/docs/learn/introduction/gateway/offramp_architecture.pngis excluded by!**/*.png
📒 Files selected for processing (3)
docs/docs/learn/builder-guides/gateway.md(4 hunks)docs/docs/learn/introduction/gateway/index.md(2 hunks)docs/docs/learn/introduction/gateway/offramp_architecture.excalidraw(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/docs/learn/introduction/gateway/offramp_architecture.excalidraw
🧰 Additional context used
🪛 LanguageTool
docs/docs/learn/introduction/gateway/index.md
[style] ~71-~71: For conciseness, consider replacing this expression with an adverb.
Context: ...w for their funds. This is permissioned at the moment because BOB pays the transaction's gas....
(AT_THE_MOMENT)
🔇 Additional comments (6)
docs/docs/learn/builder-guides/gateway.md (4)
52-52: Verify correct network identifier
The example initializes with'bob'and comments “or 'signet'”. Please confirm that'bob'refers to mainnet and clarify when to use"signet"or other environments to avoid confusion.
63-63: Skip clear section header
The new “## Gateway-Onramp Methods” header is descriptive and needs no changes.
206-206: Skip clear section header
The new “## Gateway-Offramp Methods” header is descriptive and needs no changes.
215-223: Check Offramp parameter types
You declarequoteParamsasGatewayQuoteParamsbut then use it withcreateOfframpOrder, which returns anOfframpCreateOrderParamstype. Consider defining the input as a dedicated Offramp params interface (e.g.,OfframpOrderParams) for clarity and type safety.docs/docs/learn/introduction/gateway/index.md (2)
45-45: Skip clear section header
The “## How Gateway-Onramp Works” heading clearly introduces the Onramp flow; no changes needed.
75-75: Skip clear section header
The “## How Gateway-Offramp Works” heading clearly introduces the Offramp flow; no changes needed.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/docs/learn/introduction/gateway/index.md (5)
9-10: Clarify "BOB Hybrid L2" and link to overview
The term "Hybrid L2" appears here without definition. Consider adding a parenthetical or hyperlink to the BOB architecture overview so readers understand what makes it hybrid. For example:Bitcoin users can easily onboard to the [BOB Hybrid L2](/learn/introduction/architecture) without needing to hold any Ethereum assets.Also ensure consistent naming for "BOB BTC Bridge" vs. "BOB Gateway-Onramp" if they refer to the same component.
48-48: Tighten phrasing for step 2
Instead of “makes a request to the off-chain relayer,” consider shortening to “requests the off-chain relayer” or “asks the off-chain relayer” for a more concise style.
64-64: Link to smart contract reference
When mentioning “Gateway smart contract,” add a hyperlink to the builder guide or API reference so readers can quickly access ABI details or deployment instructions.
77-82: Clarify participant roles in Offramp steps
Steps 1–6 introduce “LPs,” “solvers,” and “relayers” quickly. To avoid confusion, consider noting that a solver is an off-chain agent run by LPs or consolidating terminology (e.g., “solvers (LPs)”) on first use.🧰 Tools
🪛 LanguageTool
[uncategorized] ~81-~81: The preposition ‘for’ seems more likely in this position.
Context: ... Bitcoin, transferring it to the solver as reimbursement. 6. If the order is not f...(AI_HYDRA_LEO_REPLACE_AS_FOR)
85-88: Improve image accessibility
Thealtattribute is currently generic. Update it to be more descriptive and consider adding atitleor caption:<img - alt="architecture" + alt="Gateway-Offramp Architecture" + title="Gateway-Offramp Architecture" />
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/docs/learn/introduction/gateway/offramp_architecture.pngis excluded by!**/*.png
📒 Files selected for processing (3)
docs/docs/learn/builder-guides/gateway.md(4 hunks)docs/docs/learn/introduction/gateway/index.md(2 hunks)docs/docs/learn/introduction/gateway/offramp_architecture.excalidraw(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/docs/learn/introduction/gateway/offramp_architecture.excalidraw
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/docs/learn/builder-guides/gateway.md
🧰 Additional context used
🪛 LanguageTool
docs/docs/learn/introduction/gateway/index.md
[style] ~71-~71: For conciseness, consider replacing this expression with an adverb.
Context: ...w for their funds. This is permissioned at the moment because BOB pays the transaction's gas....
(AT_THE_MOMENT)
[uncategorized] ~81-~81: The preposition ‘for’ seems more likely in this position.
Context: ... Bitcoin, transferring it to the solver as reimbursement. 6. If the order is not f...
(AI_HYDRA_LEO_REPLACE_AS_FOR)
🔇 Additional comments (7)
docs/docs/learn/introduction/gateway/index.md (7)
45-45: Approve Onramp section header
The new “How Gateway-Onramp Works” header clearly delineates the onramp flow.
53-53: Approve Onramp architecture subheader
The “Gateway-Onramp Architecture” subheader aligns well with the diagram that follows.
61-61: Approve Onramp user flow header
The “Gateway-Onramp User Flow” heading is clear and consistent with the preceding architecture section.
67-67: Approve relayer verification detail
Excellent clarity around Merkle proof submission and matchingOP_RETURNdata for trustless on-chain verification.
69-69: Approve LP flow header
“Gateway-Onramp Liquidity Provider (LP) Flow” is descriptive and consistent with prior sections.
75-75: Approve Offramp section header
Introducing “How Gateway-Offramp Works” cleanly separates the reverse flow from the onramp documentation.
84-84: Approve Offramp architecture subheader
The “Gateway-Offramp Architecture” heading correctly precedes the new diagram.
| Example: | ||
|
|
||
| ```ts | ||
| import { createWalletClient, http, privateKeyToAccount } from 'viem'; |
There was a problem hiding this comment.
change to: import { privateKeyToAccount } from 'viem/accounts'
Summary by CodeRabbit