@karn_lat/protocol-sdk 0.1.0-alpha.1

package/src/__tests__/wallet/WalletManager.test.ts

@@ -0,0 +1,410 @@
+/**
+ * Tests for WalletManager
+ */
+
+import { WalletManager } from '../../wallet/WalletManager.js';
+import {
+  WalletType,
+  WalletEvent,
+  WalletErrorCode,
+  WalletError,
+} from '../../wallet/types.js';
+
+// Mock wallet APIs
+const mockFreighterAPI = {
+  isConnected: jest.fn(),
+  getPublicKey: jest.fn(),
+  signTransaction: jest.fn(),
+  getNetwork: jest.fn(),
+  getNetworkDetails: jest.fn(),
+};
+
+const mockAlbedoAPI = {
+  publicKey: jest.fn(),
+  tx: jest.fn(),
+  trust: jest.fn(),
+};
+
+const mockLobstrAPI = {
+  isConnected: jest.fn(),
+  getPublicKey: jest.fn(),
+  signTransaction: jest.fn(),
+};
+
+describe('WalletManager', () => {
+  let manager: WalletManager;
+
+  beforeEach(() => {
+    // Reset all mocks
+    jest.clearAllMocks();
+
+    // Reset window mocks
+    (global.window as any) = {
+      freighter: undefined,
+      albedo: undefined,
+      lobstrExtension: undefined,
+      xBullSDK: undefined,
+      rabet: undefined,
+      localStorage: {
+        getItem: jest.fn(),
+        setItem: jest.fn(),
+        removeItem: jest.fn(),
+        clear: jest.fn(),
+      },
+    };
+
+    manager = new WalletManager();
+  });
+
+  describe('Initialization', () => {
+    it('should initialize with default state', () => {
+      const state = manager.getState();
+
+      expect(state.isConnected).toBe(false);
+      expect(state.address).toBeNull();
+      expect(state.walletType).toBeNull();
+      expect(state.isConnecting).toBe(false);
+      expect(state.error).toBeNull();
+      expect(state.walletName).toBeNull();
+    });
+
+    it('should initialize all wallet adapters', async () => {
+      const wallets = manager.getAllWallets();
+
+      expect(wallets).toHaveLength(5);
+      expect(wallets.map(w => w.type)).toEqual([
+        WalletType.FREIGHTER,
+        WalletType.ALBEDO,
+        WalletType.LOBSTR,
+        WalletType.XBULL,
+        WalletType.RABET,
+      ]);
+    });
+  });
+
+  describe('getAvailableWallets', () => {
+    it('should return empty array when no wallets installed', async () => {
+      const available = await manager.getAvailableWallets();
+
+      expect(available).toEqual([]);
+    });
+
+    it('should return Freighter when installed', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      manager = new WalletManager();
+
+      const available = await manager.getAvailableWallets();
+
+      expect(available).toHaveLength(1);
+      expect(available[0].type).toBe(WalletType.FREIGHTER);
+      expect(available[0].name).toBe('Freighter');
+    });
+
+    it('should return Albedo (always available as web-based)', async () => {
+      // Albedo is web-based, so it's always "available"
+      const manager2 = new WalletManager();
+      const available = await manager2.getAvailableWallets();
+
+      // Albedo should be in the list (or at least detectable)
+      // Note: Actual implementation may vary
+      const hasAlbedo = available.some(w => w.type === WalletType.ALBEDO);
+      expect(hasAlbedo || available.length === 0).toBe(true);
+    });
+
+    it('should return multiple wallets when multiple installed', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      (global.window as any).lobstrExtension = mockLobstrAPI;
+      manager = new WalletManager();
+
+      const available = await manager.getAvailableWallets();
+
+      expect(available.length).toBeGreaterThanOrEqual(2);
+      const types = available.map(w => w.type);
+      expect(types).toContain(WalletType.FREIGHTER);
+      expect(types).toContain(WalletType.LOBSTR);
+    });
+  });
+
+  describe('connect', () => {
+    it('should connect to Freighter successfully', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      const connection = await manager.connect(WalletType.FREIGHTER);
+
+      expect(connection.walletType).toBe(WalletType.FREIGHTER);
+      expect(connection.address).toBe('GTEST123...');
+      expect(mockFreighterAPI.getPublicKey).toHaveBeenCalled();
+
+      const state = manager.getState();
+      expect(state.isConnected).toBe(true);
+      expect(state.address).toBe('GTEST123...');
+      expect(state.walletType).toBe(WalletType.FREIGHTER);
+      expect(state.walletName).toBe('Freighter');
+    });
+
+    it('should throw NOT_INSTALLED error when wallet not installed', async () => {
+      await expect(manager.connect(WalletType.FREIGHTER))
+        .rejects
+        .toThrow(WalletError);
+
+      try {
+        await manager.connect(WalletType.FREIGHTER);
+      } catch (error) {
+        expect(error).toBeInstanceOf(WalletError);
+        expect((error as WalletError).code).toBe(WalletErrorCode.NOT_INSTALLED);
+        expect((error as WalletError).walletType).toBe(WalletType.FREIGHTER);
+      }
+    });
+
+    it('should throw USER_REJECTED error when user declines', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('');
+      manager = new WalletManager();
+
+      await expect(manager.connect(WalletType.FREIGHTER))
+        .rejects
+        .toThrow(WalletError);
+
+      try {
+        await manager.connect(WalletType.FREIGHTER);
+      } catch (error) {
+        expect((error as WalletError).code).toBe(WalletErrorCode.USER_REJECTED);
+      }
+    });
+
+    it('should save connection to localStorage', async () => {
+      const setItem = jest.fn();
+      (global.window as any).localStorage.setItem = setItem;
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+
+      expect(setItem).toHaveBeenCalledWith(
+        'karn_wallet_connection',
+        expect.stringContaining('FREIGHTER')
+      );
+    });
+
+    it('should disconnect previous wallet before connecting new one', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      (global.window as any).lobstrExtension = mockLobstrAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GFREIGHTER...');
+      mockLobstrAPI.getPublicKey.mockResolvedValue('GLOBSTR...');
+      manager = new WalletManager();
+
+      // Connect to Freighter
+      await manager.connect(WalletType.FREIGHTER);
+      expect(manager.getState().walletType).toBe(WalletType.FREIGHTER);
+
+      // Connect to Lobstr (should disconnect Freighter first)
+      await manager.connect(WalletType.LOBSTR);
+      expect(manager.getState().walletType).toBe(WalletType.LOBSTR);
+      expect(manager.getState().address).toBe('GLOBSTR...');
+    });
+  });
+
+  describe('disconnect', () => {
+    it('should disconnect successfully', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+      await manager.disconnect();
+
+      const state = manager.getState();
+      expect(state.isConnected).toBe(false);
+      expect(state.address).toBeNull();
+      expect(state.walletType).toBeNull();
+      expect(state.walletName).toBeNull();
+    });
+
+    it('should clear localStorage on disconnect', async () => {
+      const removeItem = jest.fn();
+      (global.window as any).localStorage.removeItem = removeItem;
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+      await manager.disconnect();
+
+      expect(removeItem).toHaveBeenCalledWith('karn_wallet_connection');
+    });
+
+    it('should handle disconnect when not connected', async () => {
+      await expect(manager.disconnect()).resolves.not.toThrow();
+    });
+  });
+
+  describe('signTransaction', () => {
+    it('should sign transaction with connected wallet', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      mockFreighterAPI.signTransaction.mockResolvedValue('signed_xdr_123');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+      const signedXdr = await manager.signTransaction('unsigned_xdr_123');
+
+      expect(signedXdr).toBe('signed_xdr_123');
+      expect(mockFreighterAPI.signTransaction).toHaveBeenCalledWith(
+        'unsigned_xdr_123',
+        expect.any(Object)
+      );
+    });
+
+    it('should throw NOT_CONNECTED error when not connected', async () => {
+      await expect(manager.signTransaction('xdr'))
+        .rejects
+        .toThrow(WalletError);
+
+      try {
+        await manager.signTransaction('xdr');
+      } catch (error) {
+        expect((error as WalletError).code).toBe(WalletErrorCode.NOT_CONNECTED);
+      }
+    });
+
+    it('should pass network passphrase to wallet', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      mockFreighterAPI.signTransaction.mockResolvedValue('signed');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+      await manager.signTransaction('xdr', {
+        networkPassphrase: 'Test SDF Network ; September 2015',
+      });
+
+      expect(mockFreighterAPI.signTransaction).toHaveBeenCalledWith(
+        'xdr',
+        expect.objectContaining({
+          networkPassphrase: 'Test SDF Network ; September 2015',
+        })
+      );
+    });
+  });
+
+  describe('Event System', () => {
+    it('should emit CONNECT event when connecting', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      const connectListener = jest.fn();
+      manager.on(WalletEvent.CONNECT, connectListener);
+
+      await manager.connect(WalletType.FREIGHTER);
+
+      expect(connectListener).toHaveBeenCalledWith({
+        walletType: WalletType.FREIGHTER,
+        address: 'GTEST123...',
+      });
+    });
+
+    it('should emit DISCONNECT event when disconnecting', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      const disconnectListener = jest.fn();
+      manager.on(WalletEvent.DISCONNECT, disconnectListener);
+
+      await manager.connect(WalletType.FREIGHTER);
+      await manager.disconnect();
+
+      expect(disconnectListener).toHaveBeenCalledWith({
+        walletType: WalletType.FREIGHTER,
+      });
+    });
+
+    it('should allow removing event listeners', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      const listener = jest.fn();
+      manager.on(WalletEvent.CONNECT, listener);
+      manager.off(WalletEvent.CONNECT, listener);
+
+      await manager.connect(WalletType.FREIGHTER);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should support multiple listeners for same event', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      const listener1 = jest.fn();
+      const listener2 = jest.fn();
+      manager.on(WalletEvent.CONNECT, listener1);
+      manager.on(WalletEvent.CONNECT, listener2);
+
+      await manager.connect(WalletType.FREIGHTER);
+
+      expect(listener1).toHaveBeenCalled();
+      expect(listener2).toHaveBeenCalled();
+    });
+  });
+
+  describe('Auto-Reconnect', () => {
+    it('should attempt to restore connection from localStorage', async () => {
+      const getItem = jest.fn().mockReturnValue(
+        JSON.stringify({ walletType: WalletType.FREIGHTER, address: 'GTEST123...' })
+      );
+      (global.window as any).localStorage.getItem = getItem;
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+
+      // Wait a bit for auto-reconnect
+      manager = new WalletManager();
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      expect(getItem).toHaveBeenCalledWith('karn_wallet_connection');
+    });
+
+    it('should handle auto-reconnect failure gracefully', async () => {
+      const getItem = jest.fn().mockReturnValue(
+        JSON.stringify({ walletType: WalletType.FREIGHTER })
+      );
+      (global.window as any).localStorage.getItem = getItem;
+      // Freighter not installed
+
+      expect(() => new WalletManager()).not.toThrow();
+    });
+  });
+
+  describe('getNetwork', () => {
+    it('should return network from wallet that supports it', async () => {
+      (global.window as any).freighter = mockFreighterAPI;
+      mockFreighterAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      mockFreighterAPI.getNetwork.mockResolvedValue('TESTNET');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.FREIGHTER);
+      const network = await manager.getNetwork();
+
+      expect(network).toBe('TESTNET');
+    });
+
+    it('should throw UNSUPPORTED_METHOD for wallets without network support', async () => {
+      // Assuming Lobstr doesn't support getNetwork
+      (global.window as any).lobstrExtension = mockLobstrAPI;
+      mockLobstrAPI.getPublicKey.mockResolvedValue('GTEST123...');
+      manager = new WalletManager();
+
+      await manager.connect(WalletType.LOBSTR);
+
+      await expect(manager.getNetwork())
+        .rejects
+        .toThrow(WalletError);
+    });
+  });
+});

package/src/clients/GovernorClient.ts

@@ -0,0 +1,23 @@
+import { Client as GeneratedGovernorClient } from '../generated/governor/src/index.js';
+
+export class GovernorClient {
+  private client: GeneratedGovernorClient;
+
+  constructor(
+    public readonly networkPassphrase: string,
+    public readonly rpcUrl: string,
+    public readonly contractId: string
+  ) {
+    this.client = new GeneratedGovernorClient({
+      networkPassphrase,
+      rpcUrl,
+      contractId,
+    });
+  }
+
+
+  async getProposal(proposalId: bigint): Promise<any> {
+    const tx = await this.client.get_proposal({ proposal_id: BigInt(proposalId) });
+    return tx.result;
+  }
+}

package/src/clients/TreasuryClient.ts

@@ -0,0 +1,23 @@
+import { Client as GeneratedTreasuryClient } from '../generated/treasury/src/index.js';
+
+export class TreasuryClient {
+  private client: GeneratedTreasuryClient;
+
+  constructor(
+    public readonly networkPassphrase: string,
+    public readonly rpcUrl: string,
+    public readonly contractId: string
+  ) {
+    this.client = new GeneratedTreasuryClient({
+      networkPassphrase,
+      rpcUrl,
+      contractId,
+    });
+  }
+
+
+  async getClaimableBalance(member: string): Promise<bigint> {
+    const tx = await this.client.get_claimable_balance({ member });
+    return tx.result;
+  }
+}

package/src/clients/ValocracyClient.ts

@@ -0,0 +1,48 @@
+import { Client as GeneratedValocracyClient } from '../generated/valocracy/src/index.js';
+import type { AssembledTransaction, Result } from '@stellar/stellar-sdk/contract';
+import type { u64 } from '@stellar/stellar-sdk/contract';
+
+export class ValocracyClient {
+  private client: GeneratedValocracyClient;
+
+  constructor(
+    public readonly networkPassphrase: string,
+    public readonly rpcUrl: string,
+    public readonly contractId: string
+  ) {
+    this.client = new GeneratedValocracyClient({
+      networkPassphrase,
+      rpcUrl,
+      contractId,
+    });
+  }
+
+
+  async getLevel(address: string): Promise<number> {
+    const tx = await this.client.level_of({ account: address });
+    return Number(tx.result);
+  }
+
+  // Get voting power (Mana) with decay
+
+  async getMana(address: string): Promise<number> {
+    const tx = await this.client.get_votes({ account: address });
+    return Number(tx.result);
+  }
+
+  // Self-register with backend signature
+
+  async selfRegister(
+    caller: string,
+    signature: Buffer,
+    nonce: bigint,
+    expiry: bigint
+  ): Promise<AssembledTransaction<Result<u64>>> {
+    return await this.client.self_register({
+      caller,
+      signature,
+      nonce: BigInt(nonce),
+      expiry: BigInt(expiry),
+    });
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,3 @@
+export * from './ValocracyClient.js';
+export * from './GovernorClient.js';
+export * from './TreasuryClient.js';

package/src/generated/governor/README.md

@@ -0,0 +1,54 @@
+# governor JS
+
+JS library for interacting with [Soroban](https://soroban.stellar.org/) smart contract `governor` via Soroban RPC.
+
+This library was automatically generated by Soroban CLI using a command similar to:
+
+```bash
+soroban contract bindings ts \
+  --rpc-url INSERT_RPC_URL_HERE \
+  --network-passphrase "INSERT_NETWORK_PASSPHRASE_HERE" \
+  --contract-id INSERT_CONTRACT_ID_HERE \
+  --output-dir ./path/to/governor
+```
+
+The network passphrase and contract ID are exported from [index.ts](./src/index.ts) in the `networks` constant. If you are the one who generated this library and you know that this contract is also deployed to other networks, feel free to update `networks` with other valid options. This will help your contract consumers use this library more easily.
+
+# To publish or not to publish
+
+This library is suitable for publishing to NPM. You can publish it to NPM using the `npm publish` command.
+
+But you don't need to publish this library to NPM to use it. You can add it to your project's `package.json` using a file path:
+
+```json
+"dependencies": {
+  "governor": "./path/to/this/folder"
+}
+```
+
+However, we've actually encountered [frustration](https://github.com/stellar/soroban-example-dapp/pull/117#discussion_r1232873560) using local libraries with NPM in this way. Though it seems a bit messy, we suggest generating the library directly to your `node_modules` folder automatically after each install by using a `postinstall` script. We've had the least trouble with this approach. NPM will automatically remove what it sees as erroneous directories during the `install` step, and then regenerate them when it gets to your `postinstall` step, which will keep the library up-to-date with your contract.
+
+```json
+"scripts": {
+  "postinstall": "soroban contract bindings ts --rpc-url INSERT_RPC_URL_HERE --network-passphrase \"INSERT_NETWORK_PASSPHRASE_HERE\" --id INSERT_CONTRACT_ID_HERE --name governor"
+}
+```
+
+Obviously you need to adjust the above command based on the actual command you used to generate the library.
+
+# Use it
+
+Now that you have your library up-to-date and added to your project, you can import it in a file and see inline documentation for all of its exported methods:
+
+```js
+import { Contract, networks } from "governor"
+
+const contract = new Contract({
+  ...networks.futurenet, // for example; check which networks this library exports
+  rpcUrl: '...', // use your own, or find one for testing at https://soroban.stellar.org/docs/reference/rpc#public-rpc-providers
+})
+
+contract.|
+```
+
+As long as your editor is configured to show JavaScript/TypeScript documentation, you can pause your typing at that `|` to get a list of all exports and inline-documentation for each. It exports a separate [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) function for each method in the smart contract, with documentation for each generated from the comments the contract's author included in the original source code.

package/src/generated/governor/package.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.0",
+  "name": "governor",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^14.1.1",
+    "buffer": "6.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  }
+}