Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: websocket documentation for active quoting #3396

Merged
merged 1 commit into from
Nov 16, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions docs/bridge/docs/04-Routers/RFQ/API/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,54 @@ Please note that end-users and solvers will not need to run their own version of

- [`PUT /rfq`](./put-rfq-request.api.mdx) - Initiate an RFQ and receive the best available quote.

## Websocket API for Quoters

The websocket API allows quoters to interact with user quote requests once connected to the `GET /rfq_stream` endpoint.

The websocket API exposes several operations for quoters:
- `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

The API server may respond with the following operations:
- `pong` - acknowleges a `ping` message
- `request_quote` - informs quoter of a new user quote request
Comment on lines +73 to +75
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add error responses and examples.

Please enhance this section by:

  1. Adding possible error response types (e.g., invalid_request, unauthorized, etc.)
  2. Including examples of each response type
  3. 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 details

Committable 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)


All websocket messages follow this format:
```
{
op: string,
content: json,
success: bool,
}
```
Comment on lines +77 to +84
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Enhance message format specification.

The message format needs:

  1. Field descriptions and types
  2. Language specification for the code block
  3. 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,
}
```
Comment on lines +86 to +108
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add field validations and improve format specifications.

Please enhance the content formats with:

  1. Field validations (e.g., allowed ranges, formats)
  2. Field descriptions
  3. 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)


Subscribe / Unsubscribe content should be an array of chain ids.


**API Version Changes**
Expand Down
Loading