feat: perpOB support#35
Open
arturbeg wants to merge 25 commits into
Open
Conversation
Documents the public REST + WebSocket surface for unified (spot + perp) execution busts introduced by the feat/perpOB migration in Reya-Labs/reya-off-chain-monorepo#2575. Scoped to the additive surface of PRs 1–7; PR 8's breaking AMM cleanup will ship as a later spec bump. - trading-schemas.json: new ExecutionBust + ExecutionBustList schemas (structural clones of the spot variants; no marketType field, since clients can derive spot vs perp from the symbol suffix) - openapi-trading-v2.yaml: new GET /market/{symbol}/executionBusts and GET /wallet/{address}/executionBusts; components.schemas aliases; description tweaks on /depth, /createOrder, /cancelOrder, /cancelAll to reflect perp support; version 2.1.9 → 2.2.0 - asyncapi-trading-v2.yaml: new marketExecutionBusts + walletExecutionBusts channels, receive* operations, Market/WalletExecutionBustUpdate messages, channel patterns, body + payload schemas; version 2.1.9 → 2.2.0 - docs/asyncapi-trading-v2-docs.md: channel list entries + full sections for the two new WS channels with ExecutionBust data type block Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughVersion bumped to 2.2.0. Added two new WebSocket subscription channels ( Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Server
participant DataStore as Data Store
rect rgba(76, 175, 80, 0.5)
Note over Client,Server: WebSocket Subscription Flow
Client->>Server: Subscribe to /v2/market/{symbol}/executionBusts
Server->>Server: Register subscription
Note over Server: Execution bust occurs
Server->>Client: Publish MarketExecutionBustUpdate
end
rect rgba(33, 150, 243, 0.5)
Note over Client,DataStore: REST Query Flow
Client->>Server: GET /market/{symbol}/executionBusts?startTime=X&endTime=Y
Server->>DataStore: Fetch execution busts in time range
DataStore-->>Server: Return ExecutionBust records
Server-->>Client: Return ExecutionBustList (paginated response)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/asyncapi-trading-v2-docs.md (1)
596-947:⚠️ Potential issue | 🟡 MinorFix markdownlint spacing regressions in the new executionBusts sections.
Line 596 and Line 903 headings, plus nearby fenced blocks (Line 603, Line 611, Line 910, Line 918), are missing required surrounding blank lines (MD022/MD031).
🧹 Suggested markdown spacing fix
#### `/v2/market/{symbol}/executionBusts` + **Purpose**: Real-time execution busts (failed fills) for a specific market, covering both spot and perp **Parameters**: - `symbol`: Trading symbol (e.g., `BTCRUSDPERP`, `ETHRUSD`). Clients can distinguish spot vs perp entries from the suffix (`*RUSDPERP` for perp, `*RUSD` for spot) **Subscription**: + ```json { "type": "subscribe", "channel": "/v2/market/BTCRUSDPERP/executionBusts" }Message Structure:
+{ "type": "channel_data", @@ }@@
/v2/wallet/{address}/executionBusts
Purpose: Real-time execution bust updates (failed fills) for a wallet, covering both spot and perp
Parameters:
address: Ethereum wallet addressSubscription:
+{ "type": "subscribe", "channel": "/v2/wallet/0x6c51275fd01d5dbd2da194e92f920f8598306df2/executionBusts" }Message Structure:
+{ "type": "channel_data",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/asyncapi-trading-v2-docs.md` around lines 596 - 947, The markdown is failing MD022/MD031 due to missing blank lines around headings and fenced code blocks in the new executionBusts sections; fix by adding a single blank line before and after the "#### `/v2/market/{symbol}/executionBusts`" heading and its surrounding fenced json blocks (the subscription block and the message-structure ```json``` block) and likewise add blank lines before and after the "#### `/v2/wallet/{address}/executionBusts`" heading and its subscription and message-structure fenced blocks so each heading and fenced code block is separated by an empty line; locate these sections by the unique headings `/v2/market/{symbol}/executionBusts` and `/v2/wallet/{address}/executionBusts` and adjust spacing accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openapi-trading-v2.yaml`:
- Around line 389-413: The new public operation getMarketExecutionBusts (path
/market/{symbol}/executionBusts) is exposed before backend handlers exist—either
block merge until handlers are implemented or mark the operation as
rollout-pending: update the operation (operationId: getMarketExecutionBusts) to
add an availability note in the description stating "rollout-pending" and add a
temporary '501' response (e.g., reference a components/responses/NotImplemented
or create one) so clients receive a clear 501 until handlers are live; apply the
same change for the other pending endpoint referenced in the PR (the one around
line 482) to keep the contract consistent.
---
Outside diff comments:
In `@docs/asyncapi-trading-v2-docs.md`:
- Around line 596-947: The markdown is failing MD022/MD031 due to missing blank
lines around headings and fenced code blocks in the new executionBusts sections;
fix by adding a single blank line before and after the "####
`/v2/market/{symbol}/executionBusts`" heading and its surrounding fenced json
blocks (the subscription block and the message-structure ```json``` block) and
likewise add blank lines before and after the "####
`/v2/wallet/{address}/executionBusts`" heading and its subscription and
message-structure fenced blocks so each heading and fenced code block is
separated by an empty line; locate these sections by the unique headings
`/v2/market/{symbol}/executionBusts` and `/v2/wallet/{address}/executionBusts`
and adjust spacing accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 32852e20-51cc-473e-9ba6-27162d6064b5
📒 Files selected for processing (4)
asyncapi-trading-v2.yamldocs/asyncapi-trading-v2-docs.mdopenapi-trading-v2.yamltrading-schemas.json
danigr99727
reviewed
Apr 12, 2026
Aligns PerpExecution with SpotExecution by adding order ID and counterparty fields. All three are optional to maintain backward compatibility with legacy V2 executions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
danigr99727
reviewed
Apr 13, 2026
arturbeg
changed the title
Remove longOiQty, shortOiQty, fundingRateVelocity fields and rename throttledOraclePrice to throttledMarkPrice, throttledPoolPrice to throttledMidPrice. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
(cherry picked from commit cb547f2)
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Aligns REST property, EIP-712 typehash, docs and field table with the on-chain rename (reya-network feat/perpOB@0dd62068 renamed OrderDetails.orderExpiry -> expiresAfter). No semantic change; breaking name change only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Collaborator
|
apr 20th: lgtm |
danigr99727
reviewed
Apr 20, 2026
Drops the "assumes perp for backwards compatibility" fallback on CancelOrderRequest and makes symbol explicit on both request schemas so clients can no longer rely on implicit market inference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Collaborator
|
LGTM, but there are conflicts |
danigr99727
reviewed
May 1, 2026
Collaborator
There was a problem hiding this comment.
@arturbeg all docs should be in the new reya-doc repo https://github.com/Reya-Labs/reya-docs/
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
# Conflicts: # asyncapi-trading-v2.yaml # openapi-trading-v2.yaml
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ❌ Version mismatch detected!
|
# Conflicts: # asyncapi-trading-v2.yaml # openapi-trading-v2.yaml
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
…sAfter (#46) * docs(ws-exec): clarify EIP-712 envelope field is deadline, not expiresAfter The asyncapi-exec-v2.yaml description listed `expiresAfter` as one of the per-message EIP-712 signature fields, but on feat/perpOB the signed envelope deadline is `deadline` (sig validity, server-enforced at entry) while `expiresAfter` carries `OrderDetails.orderExpiry` (order lifetime, on-chain enforced) and only appears on `createOrder` payloads. Doc-only change: no schemas updated, no generated types affected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump API specs version to 2.3.1 * docs(ws-exec): drop stale spot-only / no-perp-mass-cancel claim from sendCancelAll On feat/perpOB the off-chain mass-cancel handler dispatches both spot and perp through the matching engine via the unified `marketId` namespace (perpOB design). The asyncapi-exec-v2.yaml description was inherited from main, where the matching engine was spot-only and perp mass-cancel went through a different path; that claim is no longer accurate. The REST counterpart (`openapi-trading-v2.yaml`, /cancelAll) already documents this as supporting both spot and perp — bringing the WS spec in line. Doc-only change: no schemas updated, no generated types affected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: GitHub Action <action@github.com>
Realigns the in-file version with the git tag sequence on feat/perpOB. Prior tag at `dadfebf` is `2.3.2`; in-file version was at `2.3.1` (auto-bumped from `2.3.0` during PR #46). Bumping straight to `2.3.3` to skip the conflicting `2.3.2` slot. No schema changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reconcile main into the perpOB feature branch ahead of PR #35. Conflict resolution: - version: set to 3.0.0 across all three spec files. The 2.3.x tags already exist (auto-bumps on feat/perpOB), so 3.0.0 starts a fresh line and lets post-merge-tag cut a clean tag + release on merge to main. - StartTimeParam / EndTimeParam descriptions: kept main's corrected wording (inclusive bounds, on-chain block timestamp, "capped at a maximum that varies by endpoint" from #36/#48), dropping feat/perpOB's stale "sequence number" text. Validated: redocly bundle (openapi) clean; asyncapi validate trading + exec 0 errors; trading-schemas.json parses. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
Re-reconcile after main advanced to 2.3.4 (#50, PRO-107 version bump). Conflict: version line only — kept 3.0.0 across all three spec files (higher than 2.3.4, no tag collision). Descriptions + perp* aliases auto-merged cleanly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
…52) * feat(order): add postOnly to CreateOrderRequest and GTT to TimeInForce The on-chain OrderDetails struct gained a postOnly field (after reduceOnly) and TimeInForce gained GTT. Surface both in the shared trading schema so the REST createOrder body and the ws-exec createOrder frame (which $refs CreateOrderRequest) carry postOnly, and clients can request GTT. - CreateOrderRequest: add optional postOnly (boolean; maker-only, valid on GTC/GTT, rejected on IOC) after reduceOnly. - TimeInForce enum: add GTT (maps to on-chain timeInForce = 2). - Clarify the expiresAfter rule: GTC/IOC use 0; only GTT sets a non-zero expiresAfter, which must exceed the deadline. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: bump API specs version to 3.0.1 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: GitHub Action <action@github.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
… GitBook render) (#53) * fix(spec): strip invalid $id / x-parser-schema-id from trading-schemas.json The served OpenAPI bundle carried 48 `$id` keys (e.g. `$id: '#MarketDefinition'`), inlined from trading-schemas.json by the redocly bundle step. `$id` is invalid in OpenAPI 3.0 schema objects (an AsyncAPI-parser artifact) and breaks GitBook's published renderer: it silently drops operations whose response schema carries a `$id`. Concretely `/perpMarketDefinitions` (an alias of the deprecated `/marketDefinitions`, sharing the `MarketDefinition` schema) disappears from the published REST reference while still showing in the editor. GitBook flags all 48 as "Property $id is not expected to be here". - Strip `$id` + `x-parser-schema-id` from all 50 definitions (101 line-deletions). Safe: refs are path-based (`#/definitions/...`), not `$id`-based; pure-deletion diff, valid JSON, all paths + schemas intact, bundle now has 0 `$id`. - Add `.github/workflows/lint-spec.yml`: bundles the spec and asserts the bundle has no `$id` (regression guard) + `redocly lint` (informational). The existing CI only version-bumps/tags and never validated the spec. Refs PRO-216. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: bump API specs version to 3.0.2 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: GitHub Action <action@github.com>
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Comment on lines
+26
to
+52
| name: Lint API Specs | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout code | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Setup Node.js | ||
| uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: '18' | ||
|
|
||
| # Pinned to the same redocly version the off-chain `build:specs` step uses | ||
| # to produce the served bundle, so this reproduces what GitBook ingests. | ||
| - name: Bundle OpenAPI spec | ||
| run: npx --yes @redocly/cli@2.0.8 bundle openapi-trading-v2.yaml -o /tmp/openapi-bundled.yaml | ||
|
|
||
| - name: Assert bundle has no `$id` keys (invalid in OpenAPI 3.0; breaks GitBook) | ||
| run: | | ||
| if grep -nE '^[[:space:]]*\$id:' /tmp/openapi-bundled.yaml; then | ||
| echo "::error::Bundled OpenAPI contains \$id keys. They are invalid in OpenAPI 3.0 schema objects and break GitBook's published renderer (it drops operations). Strip \$id / x-parser-schema-id from trading-schemas.json." | ||
| exit 1 | ||
| fi | ||
| echo "OK - no \$id keys in the bundled spec." | ||
|
|
||
| - name: redocly lint (informational) | ||
| continue-on-error: true | ||
| run: npx --yes @redocly/cli@2.0.8 lint openapi-trading-v2.yaml |
Removes the deprecated /marketDefinitions path so /perpMarketDefinitions (now the sole owner of the MarketDefinition schema) renders in GitBook; converts plural `examples` -> `example` to clear OpenAPI 3.0 anomalies. Route still works on the API for back-compat.
Contributor
|
🤖 API Specs Version Check 📝 Manual version changes detected ✅ Version consistency verified: |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Summary
Documents the public REST + WebSocket surface introduced by the feat/perpOB migration in
Reya-Labs/reya-off-chain-monorepo(tracked in Reya-Labs/reya-off-chain-monorepo#2575).Scoped to PRs 1–7 (additive, non-breaking). PR 8 (AMM cleanup) will ship as a separate, breaking spec bump once the on-chain AMM is fully deprecated.
Changes
GET /market/{symbol}/executionBusts,GET /wallet/{address}/executionBusts)/v2/market/{symbol}/executionBusts,/v2/wallet/{address}/executionBusts)ExecutionBust,ExecutionBustList(structural clones of the spot variants; nomarketTypefield — clients can derive spot vs perp from the symbol suffix)/createOrder,/cancelOrder,/cancelAll,/market/{symbol}/depthto reflect perp support (no schema changes)2.1.9→2.2.0in both openapi and asyncapi filesdocs/asyncapi-trading-v2-docs.mdupdated with the two new channel sections +ExecutionBustdata type blockLinks
What this PR is NOT doing (and why)
poolPrice/throttledPoolPrice/fundingPnl/openingFee/realizedPnl/priceVariationPnl— these are removed in Reya-Labs/reya-off-chain-monorepo#2590 (PR 8, AMM cleanup), which only ships after on-chain AMM deprecation. Keeping the fields preserves backward compatibility during the transition.protocolFeeCredit,exchangeFeeCredit,makerFeeCredit,makerFeeDebit,referrerFeeCredit) — these live in the DB but are not yet surfaced bytransformTrade(Known Gap H3 on the parent issue). Will follow as a separate spec bump once the backend transformer is updated./v2/market/{symbol}/markPriceor/v2/market/{symbol}/fundingRateWS channels — payload shape is still TBD per author TODO inpackages/bun-socket/lib.ts. Follow-up item on the parent issue.DUTCH_LIQUIDATION,RANKED_LIQUIDATION,BACKSTOP_LIQUIDATION) —transformTradecurrently collapses all liquidations to'LIQUIDATION'. Follow-up item on the parent issue.Test plan
npx @redocly/cli bundle openapi-trading-v2.yaml— bundles cleanlynpx @asyncapi/cli bundle asyncapi-trading-v2.yaml— bundles cleanlynpx @asyncapi/cli validate asyncapi-trading-v2.yaml— 0 errors, 0 warnings (only the pre-existing info notice about AsyncAPI 3.1.0)trading-schemas.jsonparses as valid JSON;ExecutionBust+ExecutionBustListpresent;SpotExecutionBustpreserved@redocly/cli linterror count matches main except for the 4 new errors from the pre-existingsecurity-definedrule on the 2 new endpoints + 2 schema entries (consistent with repo convention)GET /v2/market/BTCRUSDPERP/executionBustsvalidates againstExecutionBustList; WS subscription to/v2/market/BTCRUSDPERP/executionBustsreceives a bust matchingMarketExecutionBustUpdatePayloadreya-python-sdk, regenerate the client, confirmExecutionBust,ExecutionBustList,get_market_execution_busts,get_wallet_execution_bustsare generated🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation