feat(spot-busts): add decoded reasonName/reasonArgs to SpotExecutionBust

[danigr99727]

Summary

Adds two optional sibling fields to the V2 SpotExecutionBust schema so consumers can read a decoded Solidity custom-error name + arguments instead of having to keccak-match a 4-byte selector themselves.

• reasonName: string | null — decoded error name (e.g. SignatureExpired, NegativeAccountRealBalance)
• reasonArgs: { [k: string]: string } | null — ABI-decoded arguments keyed by Solidity parameter name

Both are non-required and default to null for unknown selectors and pre-existing rows, so this is a strictly additive schema change.

Why

Today, a sample of the prod spot_execution_busts table looks like:

selector	decoded	count
0x0819bdcd	SignatureExpired()	58
0xf2a27bca	NegativeAccountRealBalance(uint128,int256)	21

Every consumer (frontends, market-maker bots, support) has to maintain a private selector→error map to do anything useful with this. Decoding once in the API removes that duplication.

Test plan

• CI passes (schema validation, generation parity)
• After merge, the auto-tagged version is pulled into the off-chain monorepo follow-up PR which wires the actual decoder

Follow-up

The off-chain monorepo PR will:

1. Bump the specs submodule to the auto-generated tag from this PR
2. Regenerate api-v2-sdk
3. Add a selector→error decoder in common-backend
4. Populate reasonName/reasonArgs in both transformSpotExecutionBust (REST) and convertToSpotExecutionBust (WS)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Trading execution error responses now include two new optional fields with decoded error information: custom error names and decoded error arguments, offering greater transparency into on-chain execution failures.

• Chores

  • Updated AsyncAPI and OpenAPI specification versions to 2.2.1.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c0cab19e-e725-4656-a8e0-e958b1c5fffc

📥 Commits

Reviewing files that changed from the base of the PR and between 1afa4df and 7318537.

📒 Files selected for processing (4)

• asyncapi-exec-v2.yaml
• asyncapi-trading-v2.yaml
• openapi-trading-v2.yaml
• trading-schemas.json

---

📝 Walkthrough

Walkthrough

Specification documents and trading schema are updated: three API spec files version bumped from 2.2.0 to 2.2.1, and SpotExecutionBust schema enriched with decoded custom error fields (reasonName and reasonArgs) alongside clarified raw hex-encoded reason field description.

Changes

API Specification v2.2.1 Release

Layer / File(s)	Summary
Specification version updates asyncapi-exec-v2.yaml, asyncapi-trading-v2.yaml, openapi-trading-v2.yaml	AsyncAPI execution and trading specs, and OpenAPI trading spec document versions all incremented from 2.2.0 to 2.2.1.
SpotExecutionBust error reason decoding fields trading-schemas.json	SpotExecutionBust schema enriched with decoded custom error metadata: reason field description tied to FailedFillBytes event raw hex revert bytes; new optional nullable fields reasonName (decoded error name) and reasonArgs (decoded arguments as string-keyed object or null) added.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Reya-Labs/reya-api-specs#30: Both PRs modify the SpotExecutionBust schema in trading-schemas.json to reshape or extend error reason field definitions.

Suggested reviewers

• arturbeg
• tomdevman

Poem

🐰 Spec versions hop from two-two-oh,
To two-two-one—a steady flow!
SpotExecutionBust now tells the tale,
Of revert reasons, never pale.
Error decoding, fields so new,
With reasonName and reasonArgs too! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding decoded reasonName and reasonArgs fields to the SpotExecutionBust schema, which is the primary purpose of this pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/spot-bust-decoded-reason

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🤖 API Specs Version Check

✅ Version automatically bumped to 2.2.1

• Previous version: 2.2.0
• OpenAPI, AsyncAPI, and ws-exec AsyncAPI specs updated