chore: balance sdk method refactoring

[0xdeval]

What was changed?

• Introduced AddressBalance: balance is now returned as:{ overall: OverallAddressBalance; perVault: VaultBalance[] } instead of VaultBalance[]
• getBalances() (SparkProtocol, ProxyProtocol) now returns AddressBalance (overall totals plus per-vault list)
• getEarnBalances() on the wallet now returns AddressBalance instead of VaultBalance[]
• AddressBalance is exported from the SDK public types

Why was changed/added?

• Mycelium Cloud started to return a different format of data for the balance
• Callers need both an aggregated view (overall balance) and per-vault breakdown; a single type with overall and perVault supports both without extra requests
• Aligns protocol and wallet APIs and keeps balance shape consistent across the SDK

How to use the change?

Use the new return type: result.overall for aggregated numbers, result.perVault for the list of vault balances (same structure as before, but under perVault)

Example:

const { overall, perVault } = await wallet.getEarnBalances(); 

and then use perVault[0].balance, perVault[0].vaultInfo, etc. Replace any code that treated the result as a plain array (e.g. result[0]) with result.perVault[0] and use result.overall when you need totals

[Copilot]

Pull request overview

This PR refactors the balance-related methods across the SDK to return a new AddressBalance type that provides both aggregated (overall) balance information and per-vault breakdowns. This change aligns with a new data format from Mycelium Cloud and provides a better API for consumers who need both summary and detailed balance information.

Changes:

• Introduced AddressBalance and OverallAddressBalance types to replace direct VaultBalance[] returns
• Updated getBalances() methods in SparkProtocol, ProxyProtocol, and BaseProtocol to return AddressBalance
• Updated getEarnBalances() method in wallet classes to return AddressBalance
• Updated all tests to work with the new return type structure
• Updated CLI to access balance data via the new perVault property

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/sdk/src/types/protocols/general.ts	Added OverallAddressBalance and AddressBalance interfaces with aggregated and per-vault balance information
packages/sdk/src/public/types.ts	Exported AddressBalance type from the public SDK API
packages/sdk/src/protocols/base/BaseProtocol.ts	Updated abstract getBalances() method signature to return AddressBalance
packages/sdk/src/protocols/implementations/SparkProtocol.ts	Refactored getBalances() to return AddressBalance with overall totals and per-vault array
packages/sdk/src/protocols/implementations/ProxyProtocol.ts	Updated getBalances() return type and withdraw() method to access perVault property
packages/sdk/src/protocols/implementations/SparkProtocol.spec.ts	Updated tests to validate new AddressBalance structure with overall and perVault properties
packages/sdk/src/protocols/implementations/ProxyProtocol.spec.ts	Refactored tests to use helper function creating mock AddressBalance objects
packages/sdk/src/wallet/base/wallets/SmartWallet.ts	Updated abstract getEarnBalances() return type to AddressBalance | null
packages/sdk/src/wallet/DefaultSmartWallet.ts	Updated getEarnBalances() implementation to return AddressBalance
packages/sdk/src/wallet/DefaultSmartWallet.spec.ts	Updated tests to work with new return structure and added mock AddressBalance objects
packages/cli/src/cli.ts	Updated CLI to access balance data through perVault property of AddressBalance
.changeset/spotty-crabs-listen.md	Added changeset documenting the breaking changes as a major version bump

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.