Add SDK balance model for multiple assets

[El-swaggerito]

Description

Difficulty: Expert

Type: Feature

Summary

Add or design a balance model that can represent multiple assets for one account.

Current Behaviour

A simple balance model may not scale when accounts hold XLM and issued assets.

Expected Behaviour

The SDK should expose balances in a typed structure that supports multiple assets and clear display metadata.

Suggested Implementation

Review account balance helpers and design a model for native, issued, unavailable, and unknown balance states.

Files or Areas Likely Affected

src/accounts/
src/wallet/
src/types/
tests/
docs/

Acceptance Criteria

• A multi-asset balance model is added or documented.
• Native and issued assets are represented distinctly.
• Unavailable and unknown states are handled.
• Tests cover multiple balance examples.
• Documentation explains the balance model for UI consumers.

Additional Notes

This should support future mobile asset display.

[TheDEV111]

Hi! I'd like to work on this issue.

I understand the goal is to design and implement a scalable, typed balance model that supports multiple assets while remaining easy for SDK consumers and UI applications to work with. The model should accommodate both current functionality and future expansion without introducing breaking changes.

My implementation would focus on:

• Reviewing the existing account, wallet, and balance helpers to ensure the new model integrates cleanly with the current SDK architecture.
• Designing a typed multi-asset balance model that clearly distinguishes between native assets (e.g., XLM) and issued assets, while remaining extensible for future asset types.
• Defining explicit balance states for available data, unavailable data, and unknown or indeterminate conditions so consumers can handle each scenario predictably.
• Including display-oriented metadata where appropriate (such as asset identifiers, issuer information, symbols, and formatting metadata) without coupling the model to a specific UI implementation.
• Adding comprehensive tests covering representative account states, including native-only accounts, mixed native and issued asset holdings, unavailable balance information, and unknown asset scenarios.
• Documenting the balance model, its intended usage, and best practices for UI consumers so future web and mobile clients have a consistent interface for rendering account balances.

I'll keep the implementation aligned with the existing SDK patterns, prioritize type safety and backward compatibility where appropriate, and ensure the model provides a solid foundation for future multi-asset support.

I'd be happy to take on this issue.

[grantfox-oss]

🦊 GrantFox — @TheDEV111 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #166)
2. Your PR will be reviewed by the Axionvera maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@TheDEV111's PR #230 was approved and merged by @El-swaggerito.

🏆 @TheDEV111: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (834 total points). Track your full progress on GrantFox.

👏 Great work, @TheDEV111! Keep contributing to Axionvera.