@karn_lat/protocol-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,68 @@
+# @karn/protocol-sdk
+
+The official TypeScript SDK for interacting with the Karn Protocol (Valocracy) on Stellar/Soroban.
+
+## Installation
+
+```bash
+npm install @karn/protocol-sdk @stellar/stellar-sdk
+```
+
+## Quick Start
+
+```typescript
+import { 
+  ValocracyClient, 
+  GovernorClient, 
+  TreasuryClient, 
+  rpc 
+} from '@karn/protocol-sdk';
+
+// Configuration
+const NETWORK_PASSPHRASE = "Test SDF Network ; September 2015";
+const RPC_URL = "https://soroban-testnet.stellar.org";
+const CONTRACT_ID = "C..."; 
+
+async function main() {
+  const valocracy = new ValocracyClient(NETWORK_PASSPHRASE, RPC_URL, CONTRACT_ID);
+
+  // Read data
+  const level = await valocracy.getLevel("G...");
+  console.log("User Level:", level);
+
+  // Calculate Mana (client-side)
+  const mana = await valocracy.getMana("G...");
+  console.log("Voting Power:", mana);
+}
+
+main();
+```
+
+## Features
+
+- **Typed Clients**: Wrappers for Valocracy, Governor, and Treasury contracts.
+- **Mana Decay**: Client-side utility to calculate real-time voting power.
+- **React Hooks**: Ready-to-use hooks for React applications (`useValocracy`, `useWallet`).
+- **Multi-Wallet**: Helper for wallet connection (Freighter).
+
+## React Usage
+
+Wrap your app in `KarnProvider`:
+
+```tsx
+import { KarnProvider } from '@karn/protocol-sdk';
+
+const config = {
+  networkPassphrase: "...",
+  rpcUrl: "...",
+  contracts: { valocracy: "...", governor: "...", treasury: "..." }
+};
+
+function App() {
+  return (
+    <KarnProvider config={config}>
+      <MyComponent />
+    </KarnProvider>
+  );
+}
+```

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Jest Test Setup
+ *
+ * Global configuration and mocks for all tests
+ */
+export {};
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            toBeWithinRange(floor: number, ceiling: number): R;
+        }
+    }
+}
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC;AA2CV,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,IAAI,CAAC;QACb,UAAU,QAAQ,CAAC,CAAC;YAClB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC;SACpD;KACF;CACF"}

package/dist/__tests__/setup.js

@@ -0,0 +1,44 @@
+/**
+ * Jest Test Setup
+ *
+ * Global configuration and mocks for all tests
+ */
+// Mock window object for browser APIs
+global.window = {
+    localStorage: {
+        getItem: jest.fn(),
+        setItem: jest.fn(),
+        removeItem: jest.fn(),
+        clear: jest.fn(),
+    },
+};
+// Mock document for DOM operations
+global.document = {
+    createElement: jest.fn(() => ({
+        setAttribute: jest.fn(),
+        addEventListener: jest.fn(),
+    })),
+    head: {
+        appendChild: jest.fn(),
+    },
+};
+// Extend jest matchers
+expect.extend({
+    toBeWithinRange(received, floor, ceiling) {
+        const pass = received >= floor && received <= ceiling;
+        if (pass) {
+            return {
+                message: () => `expected ${received} not to be within range ${floor} - ${ceiling}`,
+                pass: true,
+            };
+        }
+        else {
+            return {
+                message: () => `expected ${received} to be within range ${floor} - ${ceiling}`,
+                pass: false,
+            };
+        }
+    },
+});
+export {};
+//# sourceMappingURL=setup.js.map

package/dist/__tests__/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,sCAAsC;AACtC,MAAM,CAAC,MAAM,GAAG;IACd,YAAY,EAAE;QACZ,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE;QAClB,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE;QAClB,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE;QACrB,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE;KACjB;CACK,CAAC;AAET,mCAAmC;AACnC,MAAM,CAAC,QAAQ,GAAG;IAChB,aAAa,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5B,YAAY,EAAE,IAAI,CAAC,EAAE,EAAE;QACvB,gBAAgB,EAAE,IAAI,CAAC,EAAE,EAAE;KAC5B,CAAC,CAAC;IACH,IAAI,EAAE;QACJ,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE;KACvB;CACK,CAAC;AAET,uBAAuB;AACvB,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,CAAC,QAAgB,EAAE,KAAa,EAAE,OAAe;QAC9D,MAAM,IAAI,GAAG,QAAQ,IAAI,KAAK,IAAI,QAAQ,IAAI,OAAO,CAAC;QACtD,IAAI,IAAI,EAAE,CAAC;YACT,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CACZ,YAAY,QAAQ,2BAA2B,KAAK,MAAM,OAAO,EAAE;gBACrE,IAAI,EAAE,IAAI;aACX,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE,CACZ,YAAY,QAAQ,uBAAuB,KAAK,MAAM,OAAO,EAAE;gBACjE,IAAI,EAAE,KAAK;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/clients/GovernorClient.d.ts

@@ -0,0 +1,9 @@
+export declare class GovernorClient {
+    readonly networkPassphrase: string;
+    readonly rpcUrl: string;
+    readonly contractId: string;
+    private client;
+    constructor(networkPassphrase: string, rpcUrl: string, contractId: string);
+    getProposal(proposalId: bigint): Promise<any>;
+}
+//# sourceMappingURL=GovernorClient.d.ts.map

package/dist/clients/GovernorClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GovernorClient.d.ts","sourceRoot":"","sources":["../../src/clients/GovernorClient.ts"],"names":[],"mappings":"AAEA,qBAAa,cAAc;aAIP,iBAAiB,EAAE,MAAM;aACzB,MAAM,EAAE,MAAM;aACd,UAAU,EAAE,MAAM;IALpC,OAAO,CAAC,MAAM,CAA0B;gBAGtB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM;IAU9B,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;CAIpD"}

package/dist/clients/GovernorClient.js

@@ -0,0 +1,18 @@
+import { Client as GeneratedGovernorClient } from '../generated/governor/src/index.js';
+export class GovernorClient {
+    constructor(networkPassphrase, rpcUrl, contractId) {
+        this.networkPassphrase = networkPassphrase;
+        this.rpcUrl = rpcUrl;
+        this.contractId = contractId;
+        this.client = new GeneratedGovernorClient({
+            networkPassphrase,
+            rpcUrl,
+            contractId,
+        });
+    }
+    async getProposal(proposalId) {
+        const tx = await this.client.get_proposal({ proposal_id: BigInt(proposalId) });
+        return tx.result;
+    }
+}
+//# sourceMappingURL=GovernorClient.js.map

package/dist/clients/GovernorClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GovernorClient.js","sourceRoot":"","sources":["../../src/clients/GovernorClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAEvF,MAAM,OAAO,cAAc;IAGzB,YACkB,iBAAyB,EACzB,MAAc,EACd,UAAkB;QAFlB,sBAAiB,GAAjB,iBAAiB,CAAQ;QACzB,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAElC,IAAI,CAAC,MAAM,GAAG,IAAI,uBAAuB,CAAC;YACxC,iBAAiB;YACjB,MAAM;YACN,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAGD,KAAK,CAAC,WAAW,CAAC,UAAkB;QAClC,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,EAAE,CAAC,MAAM,CAAC;IACnB,CAAC;CACF"}

package/dist/clients/TreasuryClient.d.ts

@@ -0,0 +1,9 @@
+export declare class TreasuryClient {
+    readonly networkPassphrase: string;
+    readonly rpcUrl: string;
+    readonly contractId: string;
+    private client;
+    constructor(networkPassphrase: string, rpcUrl: string, contractId: string);
+    getClaimableBalance(member: string): Promise<bigint>;
+}
+//# sourceMappingURL=TreasuryClient.d.ts.map

package/dist/clients/TreasuryClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreasuryClient.d.ts","sourceRoot":"","sources":["../../src/clients/TreasuryClient.ts"],"names":[],"mappings":"AAEA,qBAAa,cAAc;aAIP,iBAAiB,EAAE,MAAM;aACzB,MAAM,EAAE,MAAM;aACd,UAAU,EAAE,MAAM;IALpC,OAAO,CAAC,MAAM,CAA0B;gBAGtB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM;IAU9B,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAI3D"}

package/dist/clients/TreasuryClient.js

@@ -0,0 +1,18 @@
+import { Client as GeneratedTreasuryClient } from '../generated/treasury/src/index.js';
+export class TreasuryClient {
+    constructor(networkPassphrase, rpcUrl, contractId) {
+        this.networkPassphrase = networkPassphrase;
+        this.rpcUrl = rpcUrl;
+        this.contractId = contractId;
+        this.client = new GeneratedTreasuryClient({
+            networkPassphrase,
+            rpcUrl,
+            contractId,
+        });
+    }
+    async getClaimableBalance(member) {
+        const tx = await this.client.get_claimable_balance({ member });
+        return tx.result;
+    }
+}
+//# sourceMappingURL=TreasuryClient.js.map

package/dist/clients/TreasuryClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreasuryClient.js","sourceRoot":"","sources":["../../src/clients/TreasuryClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAEvF,MAAM,OAAO,cAAc;IAGzB,YACkB,iBAAyB,EACzB,MAAc,EACd,UAAkB;QAFlB,sBAAiB,GAAjB,iBAAiB,CAAQ;QACzB,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAElC,IAAI,CAAC,MAAM,GAAG,IAAI,uBAAuB,CAAC;YACxC,iBAAiB;YACjB,MAAM;YACN,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAGD,KAAK,CAAC,mBAAmB,CAAC,MAAc;QACtC,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,CAAC,MAAM,CAAC;IACnB,CAAC;CACF"}

package/dist/clients/ValocracyClient.d.ts

@@ -0,0 +1,13 @@
+import type { AssembledTransaction, Result } from '@stellar/stellar-sdk/contract';
+import type { u64 } from '@stellar/stellar-sdk/contract';
+export declare class ValocracyClient {
+    readonly networkPassphrase: string;
+    readonly rpcUrl: string;
+    readonly contractId: string;
+    private client;
+    constructor(networkPassphrase: string, rpcUrl: string, contractId: string);
+    getLevel(address: string): Promise<number>;
+    getMana(address: string): Promise<number>;
+    selfRegister(caller: string, signature: Buffer, nonce: bigint, expiry: bigint): Promise<AssembledTransaction<Result<u64>>>;
+}
+//# sourceMappingURL=ValocracyClient.d.ts.map

package/dist/clients/ValocracyClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValocracyClient.d.ts","sourceRoot":"","sources":["../../src/clients/ValocracyClient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAEzD,qBAAa,eAAe;aAIR,iBAAiB,EAAE,MAAM;aACzB,MAAM,EAAE,MAAM;aACd,UAAU,EAAE,MAAM;IALpC,OAAO,CAAC,MAAM,CAA2B;gBAGvB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM;IAU9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO1C,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOzC,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;CAQ9C"}

package/dist/clients/ValocracyClient.js

@@ -0,0 +1,32 @@
+import { Client as GeneratedValocracyClient } from '../generated/valocracy/src/index.js';
+export class ValocracyClient {
+    constructor(networkPassphrase, rpcUrl, contractId) {
+        this.networkPassphrase = networkPassphrase;
+        this.rpcUrl = rpcUrl;
+        this.contractId = contractId;
+        this.client = new GeneratedValocracyClient({
+            networkPassphrase,
+            rpcUrl,
+            contractId,
+        });
+    }
+    async getLevel(address) {
+        const tx = await this.client.level_of({ account: address });
+        return Number(tx.result);
+    }
+    // Get voting power (Mana) with decay
+    async getMana(address) {
+        const tx = await this.client.get_votes({ account: address });
+        return Number(tx.result);
+    }
+    // Self-register with backend signature
+    async selfRegister(caller, signature, nonce, expiry) {
+        return await this.client.self_register({
+            caller,
+            signature,
+            nonce: BigInt(nonce),
+            expiry: BigInt(expiry),
+        });
+    }
+}
+//# sourceMappingURL=ValocracyClient.js.map

package/dist/clients/ValocracyClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValocracyClient.js","sourceRoot":"","sources":["../../src/clients/ValocracyClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAIzF,MAAM,OAAO,eAAe;IAG1B,YACkB,iBAAyB,EACzB,MAAc,EACd,UAAkB;QAFlB,sBAAiB,GAAjB,iBAAiB,CAAQ;QACzB,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAElC,IAAI,CAAC,MAAM,GAAG,IAAI,wBAAwB,CAAC;YACzC,iBAAiB;YACjB,MAAM;YACN,UAAU;SACX,CAAC,CAAC;IACL,CAAC;IAGD,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5D,OAAO,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,qCAAqC;IAErC,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7D,OAAO,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,uCAAuC;IAEvC,KAAK,CAAC,YAAY,CAChB,MAAc,EACd,SAAiB,EACjB,KAAa,EACb,MAAc;QAEd,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;YACrC,MAAM;YACN,SAAS;YACT,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;YACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;SACvB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/clients/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ValocracyClient.js';
+export * from './GovernorClient.js';
+export * from './TreasuryClient.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/clients/index.js

@@ -0,0 +1,4 @@
+export * from './ValocracyClient.js';
+export * from './GovernorClient.js';
+export * from './TreasuryClient.js';
+//# sourceMappingURL=index.js.map

package/dist/clients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}