feat(wallet): design and implement multi-asset balance model for accounts (Closes #166)

[TheDEV111]

Description

Closes #166

Adds a comprehensive, strongly typed Multi-Asset Balance Model to the SDK for representing accounts that hold native XLM as well as arbitrary issued credit assets (e.g. USDC, EURT, custom project tokens).

Simple balance models (like a single nativeBalance string) fail to scale for multi-asset mobile and web wallets. Moreover, Stellar accounts encumber balances for protocol base reserves (.0\text{ XLM} + 0.5\text{ XLM} \times \text{subentries}$), DEX selling liabilities, and issuer authorization constraints. This feature introduces a multi-asset balance structure with availability, reserve breakdowns, and status taxonomies.

Changes Included

1. Types (src/types/balance.ts & src/types/index.ts)

• MultiAssetBalance: Overall account balance object containing publicKey, accountState, native, issuedAssets, unknownAssets, and totalAssetCount.
• NativeAssetBalanceItem: Distinct model for native XLM with totalBalance, availableBalance, reservedBalance, sellingLiabilities, subentryCount, and state.
• IssuedAssetBalanceItem: Distinct model for issued assets with assetCode, issuer, totalBalance, availableBalance, reservedBalance, limit, isAuthorized, and state.
• UnknownAssetBalanceItem: Model for unparseable or unverified asset entries.
• AssetBalanceState: Status discriminant (available, reserved, unauthorized, unavailable, unknown).
• AccountBalanceState: Account status discriminant (funded, unfunded, unavailable, unknown).

2. Implementation (src/wallet/multi-asset.ts & src/wallet/index.ts)

• calculateNativeReserves(subentryCount): Pure function calculating minimum protocol XLM reserves based on subentries.
• parseMultiAssetBalance(publicKey, horizonAccountData, accountState): Pure parser mapping raw Horizon account objects into the MultiAssetBalance model.
• getMultiAssetBalance(publicKey, config?): Horizon query returning full multi-asset model (returns clean unfunded model on 404).
• safeGetMultiAssetBalance(publicKey, config?): Non-throwing wrapper returning PocketPayResult<MultiAssetBalance>.
• formatAssetBalanceDisplay(item, decimals?): Formatting utility for mobile/web UI consumers.
• findAssetInMultiBalance(multiBalance, assetCode, issuer?): Search helper for locating specific asset entries.

3. Documentation (docs/multi-asset-balance-model.md & README.md)

• Created docs/multi-asset-balance-model.md detailing model architecture, native vs issued representation, base reserve formulas, state taxonomy, and code examples for UI consumers.
• Updated README.md documentation links.

4. Tests (tests/multi-asset-balance.test.ts)

• Unit tests covering native XLM reserves, issued assets (authorized and unauthorized), selling liabilities, unknown assets, 404 unfunded accounts, safe wrappers, display formatting, and asset search helpers.

Verification

• Run npm run verify (tsc --noEmit, circular dependency check, vitest suite, build). All 553 unit tests pass cleanly.