[adams813]

Summary

Implements automated eager balance and RBAC role polling when a wallet transitions to the 'connected' state.

Closes #1179
Closes #1178
Closes #1177
Closes #1176

Changes Made

• Automated Balance & Role Polling (react/src/hooks.ts):
  • Enhanced useBalance(address?, options?) to automatically subscribe to useWallet() when no explicit address is passed, dispatching eager concurrent queries for both the forge token balance and native XLM balance immediately upon transitioning to 'connected'.
  • Added useWalletBalancePolling(options?) hook to eagerly fetch and periodically poll forge token balances, native XLM balances, and RBAC RoleHierarchy (getRoleHierarchy) while connected (defaulting to DEFAULT_BALANCE_POLL_INTERVAL_MS = 15_000).
  • Added isValidStellarAddress() to validate Stellar G... and C... addresses prior to RPC invocation.
  • Added withRpcTimeout() guard (DEFAULT_BALANCE_TIMEOUT_MS = 10_000) to prevent hung Soroban RPC requests.
  • Reset cached balances, roles, and active polling timers immediately when the wallet disconnects or transitions to 'wrong-network' / 'error'.
  • Surfaced a human-readable alertMessage via parseWalletError() for seamless integration with UI <Alert> components.
• Unit Tests (react/src/hooks.test.tsx):
  • Added unit tests covering eager balance/XLM/role queries on wallet connect transition, state cleanup on disconnect, background interval polling and unmount cleanup, invalid Stellar address rejection, RPC timeout handling, and network mismatch error surfacing.
• Documentation (react/README.md):
  • Documented the new useWalletBalancePolling and isValidStellarAddress exports.

Acceptance Criteria Checklist

• Balance indicators populate within 1 second of connection without requiring manual page navigation.
• Fully typed interfaces (UseBalanceOptions, WalletBalancesSnapshot, UseBalanceResult) and exports with strict TypeScript compliance.
• Edge cases (disconnected states, invalid addresses, RPC timeouts, wrong network) trigger helpful UI alert messages rather than unhandled exceptions.
• Clean JSDoc documentation on all new hooks, options, and helpers.
• Unit tests pass cleanly.

Testing

npm run build --workspace @bc-forge/sdk
npm test --workspace @bc-forge/react
npm run build --workspace @bc

[drips-wave]

@adams813 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[adams813]

@p3ris0n , pls review pr