feat(api): Swagger response docs, shared amount util, solver PATCH, race-safe idempotent create (#271-#274)

[Meshmulla]

Summary

• Closes Add typed Swagger response documentation to SorobanController and TokensController #271 — Typed Swagger response documentation for SorobanController and TokensController
• Closes Consolidate duplicated BigInt amount-parsing/formatting logic into a shared utility #272 — Consolidated duplicated BigInt amount parsing/formatting into src/common/amount.ts
• Closes Add a PATCH endpoint to update mutable solver profile fields #273 — PATCH /api/v1/solvers/:address to update mutable solver profile fields
• Closes Fix the idempotency-key check-then-set race in IntentsService.create() #274 — Fixed the idempotency-key check-then-set race in IntentsService.create()

Issues:

• Add typed Swagger response documentation to SorobanController and TokensController #271
• Consolidate duplicated BigInt amount-parsing/formatting logic into a shared utility #272
• Add a PATCH endpoint to update mutable solver profile fields #273
• Fix the idempotency-key check-then-set race in IntentsService.create() #274

Changes

#271 — Swagger response docs

• Every route in SorobanController (/api/v1/chain/health|ledger|network|account/:publicKey) and TokensController (/api/v1/tokens, /api/v1/tokens/stellar) now carries an @ApiOkResponse with an inline schema matching the actual return shape.
• The account route additionally documents @ApiBadRequestResponse (invalid key) and @ApiTooManyRequestsResponse (AccountRateLimitGuard's 429), plus @ApiParam.
• New src/tokens/dto/token-response.dto.ts (StellarTokenDto, StellarTokensResponseDto) gives /tokens/stellar a typed class.
• test/openapi-contract.e2e-spec.ts extended with assertions that all six routes expose a 200 schema and that the account route documents 400/429.
• src/generated/ regenerated via npm run generate:client — the new schemas appear in openapi.json/api-types.ts. Regeneration also picked up /intents/:id/audit and /intents/:id/quote, which had been added in earlier merged PRs without a client regen.

#272 — Shared amount utility

• New src/common/amount.ts: parseBaseUnits, toDecimalNumber, toBaseUnits, calculateProtocolFee (the documented 0.05% = dstAmount * 5 / 10000), varianceScaleFromPerfScore, applyVarianceScale. All arithmetic is BigInt; the only Number conversion is the final display-scaling step, and it splits whole/fraction as strings first so large amounts don't lose precision.
• IntentsController.quote() and fill() refactored onto the helpers. No behaviour change for valid inputs (fee %, variance formula and rounding preserved); large-amount paths are now precision-safe rather than lossy.
• src/common/amount.spec.ts — 39 unit tests covering amounts near/beyond Number.MAX_SAFE_INTEGER, zero amounts, decimals 0–18, round-trips, and reproduction of the original inline formulas.

#273 — Solver profile PATCH

• PATCH /api/v1/solvers/:address accepts a partial UpdateSolverDto (name, supportedChains, supportedTokens, avgFillTime — all optional) plus a required signature.
• Signature verified via the existing verifyStellarSignature convention against a new buildUpdateSolverMessage(address) → update-solver:<address>, before SolversService is touched.
• Immutable fields (address, bondAmount, fillsCompleted, fillsFailed, totalVolume, registeredAt, isActive) are not on the DTO, so the global ValidationPipe({ whitelist: true }) strips them silently.
• supportedChains/supportedTokens validated with the same @IsIn/@ArrayMaxSize rigor as RegisterSolverDto.
• SolversService.update() applies the patch, ignoring undefined values so an absent field never clears data.
• Docs: docs/solver-onboarding.md new section "1a. Updating Your Solver Profile"; Swagger decorators on the route; client SDK regenerated.

#274 — Race-safe idempotent create

• IntentsService.create() now takes a synchronous reserve-then-create claim: it checks and sets an idempotencyInFlight map with no await in between, so two concurrent requests with the same key can never both proceed — the loser awaits the winner's in-flight promise and returns its intent.
• The claim happens before the conditional registerOnChain() await (extracted into persistNewIntent()), so the window is closed, not shifted.
• On failure the claim is released (.finally) and nothing is cached, so a later retry succeeds.
• Comment documents the equivalent atomic INSERT ... ON CONFLICT (idempotency_key) DO NOTHING + read-back that issue feat: rebuild backend on NestJS, drop Express #1's Prisma adapter must use.
• src/intents/intents.service.idempotency.spec.ts — 7 unit tests (25-way concurrent same-key → 1 intent, widened race window, sequential replay, distinct keys, no-key path, failure/retry, claim-before-on-chain-await).
• test/load/concurrent-idempotent-create.test.ts — load test mirroring test/load/concurrent-accept.test.ts.

Incidental (merge-rot repairs, required to compile/run the above)

main currently does not type-check or build (pre-existing, ~46 tsc errors from earlier bad merges). This PR does not attempt a general fix, but four one-line drops in files it already touches were restored because the new code/tests can't compile otherwise:

• import { INTENTS_REPOSITORY, IIntentsRepository } in intents.service.ts (present in 42a8c89, lost in a later merge)
• import { Throttle } in intents.controller.ts (decorator was already in use)
• import { ConfigService } in test/utils/create-test-app.ts (symbol already in use)
• isActive: true (was bare isActive) in SolversService.reactivate()

intents.controller.ts net tsc error count goes 41 → 30; no new errors introduced (the two getPersistedQuote errors reported as "new" are the same pre-existing errors, shifted down by added import lines).

Testing / validation

• npm run lint — 0 errors (37 pre-existing warnings, unchanged).
• npm run typecheck — 30 pre-existing errors remain (down from 46 on main); none in files added or the regenerated client. Full green is blocked by unrelated pre-existing breakage in *.spec.ts, stats.service.ts, getPersistedQuote.
• New unit tests all pass:
  • src/common/amount.spec.ts — 39/39
  • src/intents/intents.service.idempotency.spec.ts — 7/7
  • src/solvers/solvers.service.update.spec.ts — 5/5
  • src/solvers/solvers.service.spec.ts — 8/8 (still green after the reactivate fix)
• npm run generate:client runs clean and the diff reflects the new endpoint + schemas.
• E2E suite (test/*.e2e-spec.ts) is not runnable on main — the shared test/__mocks__/@stellar/stellar-sdk.ts stub is missing most exports (Networks, Keypair, …). The e2e specs added here (test/solvers-update.e2e-spec.ts, the openapi-contract additions) follow the existing pattern and will pass once that harness is repaired; this PR deliberately does not touch the shared mock.

[drips-wave]

@Meshmulla Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits