refactor(billing): extract balance validation and improve accuracy

[ygrishajev]

Extract balance validation logic from executeDecodedTxByUserWallet into a dedicated #validateBalances method. The new method fetches balances from the chain when cached values are 0 to ensure accuracy, rather than relying solely on cached values. Use Promise.all for parallel fetching of fee and deployment allowances.

Also update insufficient funds error status codes from 403 to 402 (Payment Required) for better semantic accuracy.

closes #2338

Summary by CodeRabbit

• Refactor

  • Improved balance validation to check transaction fees and deployment costs together before processing.

• Bug Fixes

  • Insufficient-funds scenarios now consistently return a 402 error when fee or deployment allowances are lacking.

• Tests

  • Test expectations updated to reflect the new 402 error behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Exposes retrieveAndCalcFeeLimit (private → public) in balances service and centralizes balance/deployment allowance checks in managed-signer.service via a new private validator; tests updated to expect 402 for insufficient funds.

Changes

Cohort / File(s)	Summary
Managed-signer balance validation apps/api/src/billing/services/managed-signer/managed-signer.service.ts, apps/api/src/billing/services/managed-signer/managed-signer.service.spec.ts	Added private #validateBalances(userWallet, messages) and invoked it from executeDecodedTxByUserWallet. Consolidates fee and deployment allowance checks (parallel, cached-or-fresh via balances service). Deployment check runs only when a deployment message is present. Tests updated to expect 402 (Payment Required) for insufficient funds.
Balances service visibility apps/api/src/billing/services/balances/balances.service.ts	Changed retrieveAndCalcFeeLimit from private to public to allow reuse by managed-signer validation flow.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant ManagedSigner as ManagedSigner Service
    participant Balances as Balances Service
    participant RPC as Blockchain RPC

    Client->>ManagedSigner: executeDecodedTxByUserWallet(userWallet, messages)

    rect rgba(200,230,255,0.6)
    Note over ManagedSigner: Consolidated balance check
    ManagedSigner->>ManagedSigner: `#validateBalances`(userWallet, messages)
    end

    alt cache miss or deployment present
        ManagedSigner->>Balances: retrieveAndCalcFeeLimit(userWallet)
        Balances->>RPC: fetch live balance & fee data
        RPC-->>Balances: balance/fee info
        Balances-->>ManagedSigner: fee/deploy allowances
    else use cached allowances
        ManagedSigner->>ManagedSigner: use cached allowances
    end

    alt insufficient funds
        ManagedSigner-->>Client: 402 Payment Required
    else sufficient funds
        ManagedSigner->>ManagedSigner: continue validations & sign/execute tx
        ManagedSigner-->>Client: Transaction result
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(billing): prevent empty accounts to sign #1784: Modifies allowance/balance validation in managed-signer.service (similar area and checks).
• fix(billing): only check for deployment allowance tx when create #1804: Makes deployment-allowance assertion conditional for create-deployment messages (matches conditional check here).
• refactor(billing): removes autoReloadThreshold and autoReloadAmount from wallet settings #2319: Touches balances.service.ts (visibility/usage of fee calculation methods), related to exposing retrieveAndCalcFeeLimit.

Suggested reviewers

• stalniy

Poem

🐰 I hopped through ledgers, nibbling bytes of code,
I made the fee-checks bright along the road.
Cached or live, I fetch what's due,
I thump my paw — 402 says true.
A tiny rabbit cheers the flow.

Pre-merge checks and finishing touches

✅ 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 changes: extracting balance validation logic and improving accuracy through live chain queries.
Linked Issues check	✅ Passed	The PR addresses issue #2338 by implementing option 2: relying on live RPC data for balance checks when cached values are zero, fetching allowances in parallel, and using correct HTTP status codes.
Out of Scope Changes check	✅ Passed	The change to expose retrieveAndCalcFeeLimit as public is related to the balance validation refactoring, and all changes align with the stated objective of improving balance validation accuracy.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/tx-balances

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f9f573f and 868ae8e.

📒 Files selected for processing (3)

• apps/api/src/billing/services/balances/balances.service.ts
• apps/api/src/billing/services/managed-signer/managed-signer.service.spec.ts
• apps/api/src/billing/services/managed-signer/managed-signer.service.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• apps/api/src/billing/services/managed-signer/managed-signer.service.ts
• apps/api/src/billing/services/balances/balances.service.ts
• apps/api/src/billing/services/managed-signer/managed-signer.service.spec.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: validate / validate-app
• GitHub Check: test-build
• GitHub Check: Analyze (javascript-typescript)

---

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1a6728d and bf48afb.

📒 Files selected for processing (2)

• apps/api/src/billing/services/balances/balances.service.ts
• apps/api/src/billing/services/managed-signer/managed-signer.service.ts

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx,js}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

**/*.{ts,tsx,js}: Never use type any or cast to type any. Always define the proper TypeScript types.
Never use deprecated methods from libraries.
Don't add unnecessary comments to the code.

Files:

• apps/api/src/billing/services/balances/balances.service.ts
• apps/api/src/billing/services/managed-signer/managed-signer.service.ts

🧬 Code graph analysis (2)

apps/api/src/billing/services/balances/balances.service.ts (2)

apps/api/src/billing/services/managed-signer/managed-signer.service.ts (1)

• userWallet (169-180)

apps/api/src/billing/repositories/user-wallet/user-wallet.repository.ts (1)

• UserWalletOutput (18-22)

apps/api/src/billing/services/managed-signer/managed-signer.service.ts (1)

apps/api/src/billing/repositories/user-wallet/user-wallet.repository.ts (1)

• UserWalletOutput (18-22)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: validate / validate-app
• GitHub Check: test-build
• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (2)

apps/api/src/billing/services/balances/balances.service.ts (1)

63-72: LGTM! Method visibility change enables the new validation pattern.

Making retrieveAndCalcFeeLimit public is necessary to support the refactored balance validation in the managed-signer service. The method implementation remains sound and the exposure is appropriate for inter-service communication within the billing module.

apps/api/src/billing/services/managed-signer/managed-signer.service.ts (1)

112-112: LGTM! Clean refactoring that extracts balance validation.

The single call to #validateBalances replaces inline balance checks, improving code organization and maintainability while preserving the validation logic.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.94%. Comparing base (c861329) to head (6cdcc10).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2430      +/-   ##
==========================================
- Coverage   51.25%   50.94%   -0.31%     
==========================================
  Files        1072     1061      -11     
  Lines       29393    28933     -460     
  Branches     6472     6393      -79     
==========================================
- Hits        15065    14741     -324     
+ Misses      13998    13784     -214     
- Partials      330      408      +78     

Flag	Coverage Δ		*Carryforward flag
api	80.09% <100.00%> (+0.03%)	⬆️
deploy-web	31.21% <ø> (-0.18%)	⬇️	Carriedforward from b771771
log-collector	?
notifications	87.94% <ø> (ø)		Carriedforward from b771771
provider-console	81.48% <ø> (ø)		Carriedforward from b771771
provider-proxy	84.35% <ø> (ø)		Carriedforward from b771771

*This pull request uses carry forward flags. Click here to find out more.

Files with missing lines	Coverage Δ
.../src/billing/services/balances/balances.service.ts	79.16% <100.00%> (ø)
.../services/managed-signer/managed-signer.service.ts	97.75% <100.00%> (+0.13%)	⬆️

... and 86 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.