@karn_lat/protocol-sdk 0.1.0-alpha.1

package/src/wallet/adapters/xBullAdapter.ts

@@ -0,0 +1,123 @@
+/**
+ * xBull Wallet Adapter
+ *
+ * Modern Stellar wallet extension
+ * https://xbull.app
+ */
+
+import {
+  WalletAdapter,
+  WalletType,
+  WalletMetadata,
+  SignTransactionOptions,
+  WalletError,
+  WalletErrorCode,
+} from '../types.js';
+
+// xBull SDK types
+interface XBullAPI {
+  connect(): Promise<{ publicKey: string }>;
+  sign(params: { xdr: string; publicKey?: string; network?: string }): Promise<{ signedXDR: string }>;
+  isAvailable(): boolean;
+}
+
+declare global {
+  interface Window {
+    xBullSDK?: XBullAPI;
+  }
+}
+
+export class XBullAdapter implements WalletAdapter {
+  type = WalletType.XBULL;
+
+  metadata: WalletMetadata = {
+    type: WalletType.XBULL,
+    name: 'xBull',
+    url: 'https://xbull.app',
+    chromeUrl: 'https://chrome.google.com/webstore/detail/xbull-wallet/omajpeaffjgmlpmfejkepdlekgkglhhk',
+    description: 'Modern Stellar wallet with advanced features',
+    isAvailable: false,
+  };
+
+  private api: XBullAPI | null = null;
+  private currentAddress: string | null = null;
+
+  constructor() {
+    this.init();
+  }
+
+  private init() {
+    if (typeof window !== 'undefined' && window.xBullSDK) {
+      this.api = window.xBullSDK;
+      this.metadata.isAvailable = this.api.isAvailable();
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.metadata.isAvailable;
+  }
+
+  async connect(): Promise<string> {
+    if (!this.api) {
+      throw new WalletError(
+        'xBull is not installed',
+        WalletErrorCode.NOT_INSTALLED,
+        WalletType.XBULL
+      );
+    }
+
+    try {
+      const result = await this.api.connect();
+      this.currentAddress = result.publicKey;
+      return result.publicKey;
+    } catch (error: any) {
+      throw new WalletError(
+        `Failed to connect to xBull: ${error.message}`,
+        WalletErrorCode.USER_REJECTED,
+        WalletType.XBULL
+      );
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.currentAddress = null;
+    this.api = null;
+  }
+
+  async getAddress(): Promise<string | null> {
+    return this.currentAddress;
+  }
+
+  async isConnected(): Promise<boolean> {
+    return this.currentAddress !== null;
+  }
+
+  async signTransaction(
+    xdr: string,
+    options?: SignTransactionOptions
+  ): Promise<string> {
+    if (!this.api) {
+      throw new WalletError(
+        'xBull is not connected',
+        WalletErrorCode.NOT_CONNECTED,
+        WalletType.XBULL
+      );
+    }
+
+    try {
+      const result = await this.api.sign({
+        xdr,
+        publicKey: this.currentAddress || undefined,
+        network: options?.networkPassphrase,
+      });
+
+      return result.signedXDR;
+    } catch (error: any) {
+      throw new WalletError(
+        `Failed to sign transaction: ${error.message}`,
+        WalletErrorCode.SIGNING_FAILED,
+        WalletType.XBULL
+      );
+    }
+  }
+}

package/src/wallet/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Karn Protocol Multi-Wallet Support
+ *
+ * Provides unified interface for connecting to multiple Stellar wallets:
+ * - Freighter (official Stellar extension)
+ * - Albedo (web-based, no extension required)
+ * - Lobstr (popular mobile + extension)
+ * - xBull (modern wallet with advanced features)
+ * - Rabet (DeFi-focused wallet with built-in swap)
+ *
+ * - Rabet (DeFi-focused wallet with built-in swap)
+ */
+
+// Core wallet manager
+export { WalletManager } from './WalletManager.js';
+
+// Type definitions
+export {
+  WalletType,
+  WalletState,
+  WalletMetadata,
+  WalletAdapter,
+  WalletConnection,
+  WalletEvent,
+  WalletEventPayload,
+  WalletEventListener,
+  SignTransactionOptions,
+  WalletError,
+  WalletErrorCode,
+} from './types.js';
+
+// Individual wallet adapters (for advanced usage)
+export { FreighterAdapter } from './adapters/FreighterAdapter.js';
+export { AlbedoAdapter } from './adapters/AlbedoAdapter.js';
+export { LobstrAdapter } from './adapters/LobstrAdapter.js';
+export { XBullAdapter } from './adapters/xBullAdapter.js';
+export { RabetAdapter } from './adapters/RabetAdapter.js';

package/src/wallet/types.ts

@@ -0,0 +1,204 @@
+/**
+ * Multi-wallet support types for Karn Protocol SDK
+ *
+ * Supports: Freighter, Albedo, Lobstr, xBull, Rabet
+ */
+
+/**
+ * Supported wallet types
+ */
+export enum WalletType {
+  FREIGHTER = 'freighter',
+  ALBEDO = 'albedo',
+  LOBSTR = 'lobstr',
+  XBULL = 'xbull',
+  RABET = 'rabet',
+}
+
+/**
+ * Wallet connection state
+ */
+export interface WalletState {
+  /** Whether wallet is connected */
+  isConnected: boolean;
+
+  /** Connected wallet address (Stellar public key) */
+  address: string | null;
+
+  /** Currently active wallet type */
+  walletType: WalletType | null;
+
+  /** Connection in progress */
+  isConnecting: boolean;
+
+  /** Error message if any */
+  error: string | null;
+
+  /** Wallet display name */
+  walletName: string | null;
+}
+
+/**
+ * Wallet metadata for UI display
+ */
+export interface WalletMetadata {
+  /** Wallet type identifier */
+  type: WalletType;
+
+  /** Display name */
+  name: string;
+
+  /** Icon URL or data URI */
+  icon?: string;
+
+  /** Homepage URL */
+  url: string;
+
+  /** Chrome extension URL */
+  chromeUrl?: string;
+
+  /** Firefox addon URL */
+  firefoxUrl?: string;
+
+  /** Description */
+  description: string;
+
+  /** Is installed/available */
+  isAvailable: boolean;
+}
+
+/**
+ * Transaction signing options
+ */
+export interface SignTransactionOptions {
+  /** Network passphrase (default: Testnet) */
+  networkPassphrase?: string;
+
+  /** Optional account sequence */
+  accountToSign?: string;
+}
+
+/**
+ * Wallet adapter interface
+ *
+ * Each wallet provider implements this interface
+ */
+export interface WalletAdapter {
+  /** Wallet type */
+  type: WalletType;
+
+  /** Wallet metadata */
+  metadata: WalletMetadata;
+
+  /**
+   * Check if wallet is installed/available
+   */
+  isAvailable(): Promise<boolean>;
+
+  /**
+   * Connect to wallet and request access
+   * @returns Public key (Stellar address)
+   */
+  connect(): Promise<string>;
+
+  /**
+   * Disconnect from wallet
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Get current connected address
+   * @returns Public key or null if not connected
+   */
+  getAddress(): Promise<string | null>;
+
+  /**
+   * Check if wallet is currently connected
+   */
+  isConnected(): Promise<boolean>;
+
+  /**
+   * Sign a transaction
+   * @param xdr Transaction XDR string
+   * @param options Signing options
+   * @returns Signed transaction XDR
+   */
+  signTransaction(xdr: string, options?: SignTransactionOptions): Promise<string>;
+
+  /**
+   * Sign arbitrary message (if supported)
+   * @param message Message to sign
+   * @returns Signature
+   */
+  signMessage?(message: string): Promise<string>;
+
+  /**
+   * Get network (if supported)
+   * @returns Network name (e.g., 'TESTNET', 'PUBLIC')
+   */
+  getNetwork?(): Promise<string>;
+}
+
+/**
+ * Wallet connection result
+ */
+export interface WalletConnection {
+  /** Wallet type */
+  walletType: WalletType;
+
+  /** Connected address */
+  address: string;
+
+  /** Wallet adapter instance */
+  adapter: WalletAdapter;
+}
+
+/**
+ * Wallet event types
+ */
+export enum WalletEvent {
+  CONNECT = 'connect',
+  DISCONNECT = 'disconnect',
+  ACCOUNT_CHANGED = 'accountChanged',
+  NETWORK_CHANGED = 'networkChanged',
+}
+
+/**
+ * Wallet event payload
+ */
+export interface WalletEventPayload {
+  walletType: WalletType;
+  address?: string;
+  network?: string;
+}
+
+/**
+ * Wallet event listener
+ */
+export type WalletEventListener = (payload: WalletEventPayload) => void;
+
+/**
+ * Wallet error types
+ */
+export class WalletError extends Error {
+  constructor(
+    message: string,
+    public code: WalletErrorCode,
+    public walletType?: WalletType
+  ) {
+    super(message);
+    this.name = 'WalletError';
+  }
+}
+
+export enum WalletErrorCode {
+  NOT_INSTALLED = 'NOT_INSTALLED',
+  USER_REJECTED = 'USER_REJECTED',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  SIGNING_FAILED = 'SIGNING_FAILED',
+  NOT_CONNECTED = 'NOT_CONNECTED',
+  ALREADY_CONNECTED = 'ALREADY_CONNECTED',
+  UNSUPPORTED_METHOD = 'UNSUPPORTED_METHOD',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+    "compilerOptions": {
+        "target": "es2020",
+        "lib": [
+            "dom",
+            "es2020"
+        ],
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "noImplicitAny": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "module": "ES2020",
+        "moduleResolution": "node",
+        "allowSyntheticDefaultImports": true,
+        "jsx": "react",
+        "baseUrl": ".",
+        "paths": {
+            "@stellar/stellar-sdk/contract": [
+                "./node_modules/@stellar/stellar-sdk/lib/contract/index.d.ts"
+            ],
+            "@stellar/stellar-sdk/rpc": [
+                "./node_modules/@stellar/stellar-sdk/lib/rpc/index.d.ts"
+            ]
+        }
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "**/*.test.ts"
+    ]
+}