feat(sdk): add wallet adapter layer for browser wallet signing

[V1ctor-o]

Summary

This PR introduces a wallet adapter abstraction layer to the SDK, enabling unified support for browser-based wallet signing flows across Freighter, Albedo, and future WalletConnect integrations.

The goal is to decouple wallet-specific implementations from the core SDK and provide a consistent interface for transaction signing and wallet management.

---

What Changed

🧩 Wallet Abstraction

• Added a WalletAdapter interface to define a standard contract for wallet implementations.
• Standardized wallet operations:
  • Connection handling
  • Public key retrieval
  • Transaction signing

---

🔌 Wallet Adapter Implementations

• FreighterAdapter

  • Implements full signing and connection flow using Freighter API.

• AlbedoAdapter

  • Implements browser-based signing and key management via Albedo.

• WalletConnectAdapter (Stub)

  • Added placeholder implementation for future WalletConnect integration.
  • Methods currently throw or return default values due to app-specific signing requirements.

---

🔁 SDK Refactor

• Refactored bcForgeClient to accept an optional walletAdapter.
• Updated signing flow to use adapter-based abstraction when provided.
• Maintains backward compatibility with existing Keypair-based transaction flows.

---

🧠 Wallet State & Helpers

• Added wallet connection helper methods to standardize:

  • connect
  • disconnect
  • getPublicKey
  • signTransaction

• Introduced basic connection state handling through adapter interface.

---

🧪 Tests

• Added basic unit tests for wallet adapter structure and integration points.
• Ensures adapters conform to expected interface behavior.

---

📚 Documentation

• Updated SDK README to include:
  • Wallet adapter overview
  • Usage examples for Freighter and Albedo
  • Integration pattern for bcForgeClient with adapters

---

Backward Compatibility

• Existing Keypair-based transaction flows remain fully supported.
• Wallet adapter usage is optional and opt-in.
• No breaking changes introduced to existing SDK consumers.

---

Notes

• WalletConnectAdapter is intentionally left as a stub because WalletConnect signing flows are application-specific and require project-level configuration.
• This abstraction is designed to allow future expansion without modifying core SDK logic.

---

Future Improvements

• Full WalletConnect integration
• xBull wallet adapter support
• Enhanced error typing (WalletConnectionError, SigningError, etc.)
• Automatic wallet detection layer

Closes #172

[drips-wave]

@V1ctor-o 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