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

sdk/README.md

@@ -398,6 +398,25 @@ await client.unpause(adminKeypair);
 
 ### Write Methods (require Keypair)
 
+## Wallet Adapter (Browser wallets)
+
+The SDK supports an optional `WalletAdapter` layer so consumers can plug-in browser wallets (Freighter, Albedo, WalletConnect).
+
+Example using a wallet adapter:
+
+```typescript
+import { bcForgeClient, FreighterAdapter } from '@bc-forge/sdk';
+
+const adapter = new FreighterAdapter();
+const client = new bcForgeClient({ rpcUrl, networkPassphrase, contractId, walletAdapter: adapter });
+
+await client.connectWallet();
+await client.mint('GRECIPIENT...', BigInt(1000), /* no Keypair */);
+```
+
+When a `walletAdapter` is configured and connected, write methods may be invoked without passing a `Keypair`; the SDK will build an unsigned transaction and ask the adapter to sign and submit it.
+
+
 | Method | Description |
 |--------|-------------|
 | `initialize(admin, decimals, name, symbol, source)` | One-time contract setup |

sdk/src/adapters/albedoAdapter.ts

@@ -0,0 +1,32 @@
+import { WalletAdapter } from '../walletAdapter';
+
+export class AlbedoAdapter implements WalletAdapter {
+  name = 'albedo';
+  connected = false;
+  publicKey?: string;
+
+  async connect(): Promise<void> {
+    const albedo = (globalThis as any).albedo;
+    if (!albedo) throw new Error('Albedo not available in this environment');
+    const resp = await albedo.publicKey();
+    if (!resp) throw new Error('Albedo did not return a public key');
+    this.publicKey = resp;
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    this.publicKey = undefined;
+    this.connected = false;
+  }
+
+  async signTransaction(unsignedTxXdr: string): Promise<string> {
+    const albedo = (globalThis as any).albedo;
+    if (!albedo) throw new Error('Albedo not available in this environment');
+    // Albedo's signing interface varies; attempt common patterns
+    const signed = await albedo.signTransaction?.(unsignedTxXdr) || (await albedo.signTx?.(unsignedTxXdr));
+    if (!signed) throw new Error('Albedo failed to sign transaction');
+    return signed.xdr || signed;
+  }
+}
+
+export default AlbedoAdapter;

sdk/src/adapters/freighterAdapter.ts

@@ -0,0 +1,32 @@
+import { WalletAdapter } from '../walletAdapter';
+
+export class FreighterAdapter implements WalletAdapter {
+  name = 'freighter';
+  connected = false;
+  publicKey?: string;
+
+  async connect(): Promise<void> {
+    const api = (globalThis as any).freighter;
+    if (!api) throw new Error('Freighter API not available in this environment');
+    const pk = await api.getPublicKey?.();
+    if (!pk) throw new Error('Freighter did not return a public key');
+    this.publicKey = pk;
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    this.publicKey = undefined;
+    this.connected = false;
+  }
+
+  async signTransaction(unsignedTxXdr: string): Promise<string> {
+    const api = (globalThis as any).freighter;
+    if (!api) throw new Error('Freighter API not available in this environment');
+    const resp = await api.signTransaction(unsignedTxXdr);
+    if (!resp) throw new Error('Freighter failed to sign transaction');
+    // Freighter returns an object in some versions; try to read xdr or raw
+    return resp.xdr || resp.signedXdr || resp;
+  }
+}
+
+export default FreighterAdapter;

sdk/src/adapters/walletConnectAdapter.ts

@@ -0,0 +1,28 @@
+import { WalletAdapter } from '../walletAdapter';
+
+/**
+ * Minimal stub for WalletConnect-based signing. Concrete implementation
+ * should be provided by consumers integrating WalletConnect + Stellar signing.
+ */
+export class WalletConnectAdapter implements WalletAdapter {
+  name = 'walletconnect';
+  connected = false;
+  publicKey?: string;
+
+  async connect(): Promise<void> {
+    // WalletConnect integration is app-specific. Provide a stub that
+    // instructs consumers to implement the actual flow.
+    throw new Error('WalletConnectAdapter.connect() not implemented');
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    this.publicKey = undefined;
+  }
+
+  async signTransaction(_unsignedTxXdr: string): Promise<string> {
+    throw new Error('WalletConnectAdapter.signTransaction() not implemented');
+  }
+}
+
+export default WalletConnectAdapter;