docs: websocket documentation for active quoting #3396
Conversation
WalkthroughThe pull request introduces significant enhancements to the documentation of the Quoter API, specifically adding a new section on the WebSocket API for quoters. This section details operations available via the Changes
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 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
Documentation and Community
|
Deploying sanguine-fe with
|
| Latest commit: |
932514b
|
| Status: | 🚫 Build failed. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Outside diff range and nitpick comments (4)
docs/bridge/docs/04-Routers/RFQ/API/index.md (4)
63-66: Add authentication and connection details to the WebSocket API introduction.Consider adding essential information about:
- Authentication requirements for the WebSocket connection
- Any rate limits or connection limits per quoter
- Connection timeout details
- Reconnection strategies
🧰 Tools
🪛 Markdownlint
63-63: null
Headings must start at the beginning of the line(MD023, heading-start-left)
67-71: Fix markdown list indentation.The unordered list items should start at the beginning of the line without indentation.
- - `ping` - sends a heartbeat to the API server to keep the connection alive (must be sent at least once per minute) - - `subscribe` - subscribes to quote requests for given chain(s) - - `unsubscribe` - unsubscribes to quote requests for given chain(s) - - `send_quote` - responds to a quote request + - `ping` - sends a heartbeat to the API server to keep the connection alive (must be sent at least once per minute) + - `subscribe` - subscribes to quote requests for given chain(s) + - `unsubscribe` - unsubscribes to quote requests for given chain(s) + - `send_quote` - responds to a quote request🧰 Tools
🪛 Markdownlint
68-68: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
69-69: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
70-70: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
71-71: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
67-71: Add examples for each WebSocket operation.Consider adding code examples showing the exact message format for each operation to make it clearer for integrators.
🧰 Tools
🪛 Markdownlint
68-68: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
69-69: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
70-70: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
71-71: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
63-110: Add error handling and recovery procedures.The WebSocket API documentation would benefit from a dedicated section on:
- Common error scenarios and their handling
- Connection recovery procedures
- Retry strategies with backoff recommendations
- Debugging tips
🧰 Tools
🪛 Markdownlint
68-68: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
69-69: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
70-70: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
71-71: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
74-74: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
75-75: Expected: 0; Actual: 2
Unordered list indentation(MD007, ul-indent)
63-63: null
Headings must start at the beginning of the line(MD023, heading-start-left)
78-78: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
88-88: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
103-103: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (1)
docs/bridge/docs/04-Routers/RFQ/API/index.md(1 hunks)
🧰 Additional context used
🪛 Markdownlint
docs/bridge/docs/04-Routers/RFQ/API/index.md
68-68: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
69-69: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
70-70: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
71-71: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
74-74: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
75-75: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
63-63: null
Headings must start at the beginning of the line
(MD023, heading-start-left)
78-78: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
88-88: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
| All websocket messages follow this format: | ||
| ``` | ||
| { | ||
| op: string, | ||
| content: json, | ||
| success: bool, | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Enhance message format specification.
The message format needs:
- Field descriptions and types
- Language specification for the code block
- Examples of success and error cases
- ```
+ ```json
{
- op: string,
- content: json,
- success: bool,
+ "op": "string", // Operation type (e.g., "ping", "subscribe")
+ "content": "json", // Operation-specific payload
+ "success": "bool" // Indicates if the operation was successful
}
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 Markdownlint</summary>
78-78: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
| Quote request content should have the following format: | ||
|
|
||
| ``` | ||
| { | ||
| data: { | ||
| origin_chain_id: number, | ||
| dest_chain_id: number, | ||
| origin_token_addr: string, | ||
| dest_token_addr: string, | ||
| origin_amount_exact: string, | ||
| expiration_window: number // number of ms since created_at until request should expire | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| Quote response content should have the following format: | ||
|
|
||
| ``` | ||
| { | ||
| request_id: string, | ||
| dest_amount: string, | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add field validations and improve format specifications.
Please enhance the content formats with:
- Field validations (e.g., allowed ranges, formats)
- Field descriptions
- Language specifications for code blocks
- ```
+ ```json
{
"data": {
- origin_chain_id: number,
- dest_chain_id: number,
- origin_token_addr: string,
- dest_token_addr: string,
- origin_amount_exact: string,
- expiration_window: number
+ "origin_chain_id": "number", // Source chain ID (e.g., 1 for Ethereum)
+ "dest_chain_id": "number", // Destination chain ID
+ "origin_token_addr": "string", // Token address on source chain (0x...)
+ "dest_token_addr": "string", // Token address on destination chain
+ "origin_amount_exact": "string", // Amount in wei (must be > 0)
+ "expiration_window": "number" // Must be between 1000 and 300000 ms
},
}-
{
- request_id: string,
- dest_amount: string,
- "request_id": "string", // Unique identifier for the quote request
- "dest_amount": "string" // Amount in wei (must be > 0)
}
🧰 Tools
🪛 Markdownlint
88-88: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
| The API server may respond with the following operations: | ||
| - `pong` - acknowleges a `ping` message | ||
| - `request_quote` - informs quoter of a new user quote request |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add error responses and examples.
Please enhance this section by:
- Adding possible error response types (e.g., invalid_request, unauthorized, etc.)
- Including examples of each response type
- Fixing the markdown list indentation
- - `pong` - acknowleges a `ping` message
- - `request_quote` - informs quoter of a new user quote request
+ - `pong` - acknowleges a `ping` message
+ - `request_quote` - informs quoter of a new user quote request
+ - `error` - indicates an error condition with detailsCommittable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 Markdownlint
74-74: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
75-75: Expected: 0; Actual: 2
Unordered list indentation
(MD007, ul-indent)
Summary by CodeRabbit
New Features
ping,subscribe,unsubscribe, andsend_quote.Documentation