Improvement / Feature: Split balances into `reserved` and `ready`

[Egge21M]

We need to expose reserved vs ready balances without breaking the existing WalletApi.getBalances() public API. The current API returns a total balances, which hides reservations made by operations. We will add new breakdown APIs and deprecate the old ones while preserving behavior.

Scope / Plan:

• Types:
  • Add BalanceBreakdown and BalancesBreakdownByMint in packages/core/types.ts.
  • Export new types from packages/core/index.ts.
• Core services:
  • Add ProofService.getBalanceBreakdown(mintUrl) and ProofService.getBalancesBreakdown() to compute ready, reserved, total.
  • Add ProofService.getTrustedBalancesBreakdown() for trusted mint filtering.
  • Change getBalance()/getBalances() to return ready-only;
• Public API:
  • Add WalletApi.getBalancesBreakdown() and WalletApi.getTrustedBalancesBreakdown() (public).
  • Keep WalletApi.getBalances() intact but have it return ready-only.
• Internal consumers:
  • Update PaymentRequestService to use getTrustedBalancesBreakdown() and compare against ready.
  • Update React hook useTrustedBalance to consume breakdown for ready/reserved totals and have it return ready-only.
• Docs:
  • Update packages/core/README.md and docs examples to show getBalancesBreakdown().
• Tests:
  • Add unit tests for breakdown calculation in ProofService.
  • Update PaymentRequestService tests/mocks to return breakdowns.
  • Keep existing integration tests that rely on getBalances() unless they should assert reserved/ready explicitly.

Notes:

• Breakdown shape: { [mintUrl]: { ready: number; reserved: number; total: number } } with total = ready + reserved.
• Reserved definition: proofs with state === 'ready' and usedByOperationId set.
• Ready definition: proofs with state === 'ready' and no reservation.

Acceptance criteria:

• No breaking changes to existing getBalances() calls.
• New breakdown methods available in WalletApi.
• PaymentRequest mint selection uses ready balances only.
• Docs reflect new API and deprecation notice.
• Tests cover ready/reserved/total computation.

[igbopharaoh]

Hello Egge, I'll like to tackle this