Merge pull request #451 from therealjhay/Resolve-issue-#412

Resolve issue #412

Author: Levi-Ojukwu

sdk/src/index.ts

@@ -79,6 +79,7 @@ export {
 } from "./methods/insurance.js";
 export type { InsurancePoolInfo } from "@invoice-liquidity/types";
 export { getDistributionAccrual } from "./methods/distribution.js";
+export { getReferralStats } from "./methods/referralStats.js";
 export { TokenRegistry, tokenRegistry } from "./utils/tokenRegistry.js";
 export type { TokenInfo, NetworkName } from "./utils/tokenRegistry.js";
 export {

sdk/src/methods/referralStats.ts

@@ -0,0 +1,102 @@
+/**
+ * getReferralStats — query referral statistics (referral count) for a given
+ * referral code hash from the on-chain ILN contract.
+ *
+ * Wraps the `get_referral_stats(BytesN<32>) -> u64` view function.
+ */
+
+import {
+  Contract,
+  SorobanRpc,
+  TransactionBuilder,
+  Account,
+  BASE_FEE,
+  scValToNative,
+  xdr,
+  Networks,
+} from "@stellar/stellar-sdk";
+import { retry } from "../utils/retry.js";
+
+// ---------------------------------------------------------------------------
+// Hex validation
+// ---------------------------------------------------------------------------
+
+const HEX64_RE = /^[0-9a-fA-F]{64}$/;
+
+// ---------------------------------------------------------------------------
+// getReferralStats
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the number of referrals attributed to a given referral code.
+ *
+ * Performs a read-only Soroban simulation — no on-chain mutation, no
+ * transaction fees, and no signer required.
+ *
+ * @param server              - Soroban RPC server for the target network
+ * @param contractId          - Deployed invoice-liquidity contract address
+ * @param referralCodeHex     - 64-character hex string (32 bytes) representing the referral code hash
+ * @param networkPassphrase   - Stellar network passphrase (default: TESTNET)
+ * @returns Number of referrals for the given code
+ *
+ * @throws When `referralCodeHex` is not a valid 64-character hex string
+ * @throws When the Soroban simulation fails (RPC unreachable, contract not found)
+ *
+ * @example
+ * ```ts
+ * const count = await getReferralStats(server, CONTRACT_ID, "ab12...cd34");
+ * console.log(`Referrals: ${count}`);
+ * ```
+ */
+export async function getReferralStats(
+  server: SorobanRpc.Server,
+  contractId: string,
+  referralCodeHex: string,
+  networkPassphrase: string = Networks.TESTNET
+): Promise<number> {
+  // Strip optional 0x prefix
+  const cleaned = referralCodeHex.startsWith("0x")
+    ? referralCodeHex.slice(2)
+    : referralCodeHex;
+
+  if (!HEX64_RE.test(cleaned)) {
+    throw new Error(
+      `Invalid referral code: "${referralCodeHex}". Expected a 64-character hex string (32 bytes) optionally prefixed with "0x".`
+    );
+  }
+
+  // Decode hex to raw 32-byte buffer
+  const referralCodeBytes = Buffer.from(cleaned, "hex");
+
+  const contract = new Contract(contractId);
+  const op = contract.call(
+    "get_referral_stats",
+    xdr.ScVal.scvBytes(referralCodeBytes)
+  );
+
+  const sourceAccount = new Account(
+    "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
+    "0"
+  );
+
+  const simTx = new TransactionBuilder(sourceAccount, {
+    fee: BASE_FEE,
+    networkPassphrase,
+  })
+    .addOperation(op)
+    .setTimeout(30)
+    .build();
+
+  const sim = await retry(() => server.simulateTransaction(simTx));
+
+  if (SorobanRpc.Api.isSimulationError(sim)) {
+    throw new Error(`get_referral_stats simulation failed: ${sim.error}`);
+  }
+
+  if (!sim.result?.retval) {
+    return 0;
+  }
+
+  const raw = scValToNative(sim.result.retval);
+  return Number(raw ?? 0n);
+}

sdk/tests/referralStats.test.ts

@@ -0,0 +1,142 @@
+import { vi, describe, it, expect, beforeEach } from "vitest";
+import { getReferralStats } from "../src/methods/referralStats.js";
+import {
+  SorobanRpc,
+  xdr,
+} from "@stellar/stellar-sdk";
+
+function mockSimulationResult(retval: xdr.ScVal | null) {
+  return {
+    result: retval ? { retval } : undefined,
+  };
+}
+
+describe("getReferralStats", () => {
+  const mockServer = {
+    simulateTransaction: vi.fn(),
+  } as unknown as SorobanRpc.Server;
+
+  const CONTRACT_ID = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4";
+  const VALID_HEX = "ab" + "01".repeat(31); // 64 hex chars (32 bytes)
+  const VALID_HEX_WITH_PREFIX = "0x" + VALID_HEX;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Success path
+  // ---------------------------------------------------------------------------
+
+  it("returns the referral count for a valid hex code", async () => {
+    const retval = xdr.ScVal.scvU64(xdr.Uint64.fromString("42"));
+    vi.mocked(mockServer.simulateTransaction).mockResolvedValue(
+      mockSimulationResult(retval) as any
+    );
+
+    const count = await getReferralStats(
+      mockServer,
+      CONTRACT_ID,
+      VALID_HEX
+    );
+
+    expect(count).toBe(42);
+    expect(mockServer.simulateTransaction).toHaveBeenCalledTimes(1);
+  });
+
+  it("strips the 0x prefix and returns the referral count", async () => {
+    const retval = xdr.ScVal.scvU64(xdr.Uint64.fromString("7"));
+    vi.mocked(mockServer.simulateTransaction).mockResolvedValue(
+      mockSimulationResult(retval) as any
+    );
+
+    const count = await getReferralStats(
+      mockServer,
+      CONTRACT_ID,
+      VALID_HEX_WITH_PREFIX
+    );
+
+    expect(count).toBe(7);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Zero default
+  // ---------------------------------------------------------------------------
+
+  it("returns 0 when the simulation returns no retval", async () => {
+    vi.mocked(mockServer.simulateTransaction).mockResolvedValue(
+      mockSimulationResult(null) as any
+    );
+
+    const count = await getReferralStats(
+      mockServer,
+      CONTRACT_ID,
+      VALID_HEX
+    );
+
+    expect(count).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Hex validation errors
+  // ---------------------------------------------------------------------------
+
+  it("throws when the hex string is too short", async () => {
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, "abc123")
+    ).rejects.toThrow(/invalid referral code/i);
+    expect(mockServer.simulateTransaction).not.toHaveBeenCalled();
+  });
+
+  it("throws when the hex string is too long", async () => {
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, VALID_HEX + "ff")
+    ).rejects.toThrow(/invalid referral code/i);
+    expect(mockServer.simulateTransaction).not.toHaveBeenCalled();
+  });
+
+  it("throws when the hex string contains non-hex characters", async () => {
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, "z" + "01".repeat(31) + "xy")
+    ).rejects.toThrow(/invalid referral code/i);
+    expect(mockServer.simulateTransaction).not.toHaveBeenCalled();
+  });
+
+  it("throws when the hex string is empty", async () => {
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, "")
+    ).rejects.toThrow(/invalid referral code/i);
+    expect(mockServer.simulateTransaction).not.toHaveBeenCalled();
+  });
+
+  it("throws when given an invalid 0x-prefixed hex string", async () => {
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, "0x123")
+    ).rejects.toThrow(/invalid referral code/i);
+    expect(mockServer.simulateTransaction).not.toHaveBeenCalled();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Simulation errors
+  // ---------------------------------------------------------------------------
+
+  it("throws when the simulation returns an error", async () => {
+    vi.mocked(mockServer.simulateTransaction).mockResolvedValue({
+      error: "Contract error: not found",
+    } as any);
+
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, VALID_HEX)
+    ).rejects.toThrow(/simulation failed/i);
+  });
+
+  it("throws when the simulation fails with a SorobanRPC error", async () => {
+    vi.mocked(mockServer.simulateTransaction).mockResolvedValue({
+      error: "Contract error #4",
+    } as any);
+
+    await expect(
+      getReferralStats(mockServer, CONTRACT_ID, VALID_HEX)
+    ).rejects.toThrow(/get_referral_stats simulation failed/i);
+  });
+});