diff --git a/.gitignore b/.gitignore
index 3c36ea1..1da13b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,39 @@
+# Build output
 node_modules/
 dist/
+
+# Environment
 .env
 .env.local
+*.env.*
+
+# TypeScript incremental build info
 *.tsbuildinfo
+
+# OS metadata
 .DS_Store
 Thumbs.db
+
+# Task / scratch files
 task1.md
+task2.md
+task3.md
+task4.md
 somzilla.md
+
+# Test snapshots & temporary output
+**/__snapshots__/
+*.snap
+/tmp/
+*.profile.json
+*.speedscope.json
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
diff --git a/examples/profile-session.ts b/examples/profile-session.ts
new file mode 100644
index 0000000..939b1fb
--- /dev/null
+++ b/examples/profile-session.ts
@@ -0,0 +1,165 @@
+/**
+ * examples/profile-session.ts
+ *
+ * Demonstrates ProfilerSession against a mock StellarSplitClient.
+ *
+ * Run with:
+ *   npx vite-node examples/profile-session.ts
+ * or after building:
+ *   node --loader ts-node/esm examples/profile-session.ts
+ */
+
+import { ProfilerSession, StellarSplitClient } from "../src/index.js";
+import type {
+  Invoice,
+  InvoiceReceipt,
+  Payment,
+  CreateInvoiceParams,
+  PayParams,
+  PaginatedResult,
+  PaginationOptions,
+} from "../src/index.js";
+
+// ---------------------------------------------------------------------------
+// Build a mock RPC client that resolves instantly without a real network call
+// ---------------------------------------------------------------------------
+
+const MOCK_INVOICE_ID = "42";
+const MOCK_TX_HASH = "abc123deadbeef";
+
+/** Minimal fake invoice for demonstration purposes. */
+function fakeinvoice(id = MOCK_INVOICE_ID): Invoice {
+  return {
+    id,
+    creator: "GCREATOR" + "X".repeat(49),
+    recipients: [{ address: "GRECIPIENT" + "Y".repeat(47), amount: 100_000_000n }],
+    token: "GUSDC" + "Z".repeat(52),
+    deadline: Math.floor(Date.now() / 1000) + 86_400,
+    funded: 100_000_000n,
+    status: "Released",
+    payments: [{ payer: "GPAYER" + "W".repeat(51), amount: 100_000_000n }],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Patch StellarSplitClient with mock implementations
+// ---------------------------------------------------------------------------
+
+// We monkey-patch the prototype so the profiler can capture the calls.
+
+StellarSplitClient.prototype.createInvoice = async (
+  _params: CreateInvoiceParams
+): Promise<{ invoiceId: string; txHash: string }> => {
+  // Simulate a small delay representative of an RPC round-trip
+  await new Promise((r) => setTimeout(r, 5));
+  return { invoiceId: MOCK_INVOICE_ID, txHash: MOCK_TX_HASH };
+};
+
+StellarSplitClient.prototype.pay = async (
+  _params: PayParams
+): Promise<{ txHash: string }> => {
+  await new Promise((r) => setTimeout(r, 3));
+  return { txHash: MOCK_TX_HASH };
+};
+
+StellarSplitClient.prototype.getInvoice = async (
+  _id: string
+): Promise<Invoice> => {
+  await new Promise((r) => setTimeout(r, 2));
+  return fakeinvoice();
+};
+
+StellarSplitClient.prototype.getPayments = async (
+  _invoiceId: string,
+  _options?: PaginationOptions
+): Promise<PaginatedResult<Payment>> => {
+  await new Promise((r) => setTimeout(r, 2));
+  return {
+    items: [{ payer: "GPAYER" + "W".repeat(51), amount: 100_000_000n }],
+    nextCursor: null,
+    total: 1,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Run the profiling session
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log("=== ProfilerSession Example ===\n");
+
+  // 1. Create the client (no real RPC — we patched the methods above)
+  const client = new StellarSplitClient({
+    rpcUrl: "https://soroban-testnet.stellar.org",
+    networkPassphrase: "Test SDF Network ; September 2015",
+    contractId: "CCJXQVNZQJHFWQKTQBDVUAGPJNIJFQB5DRPYTBRHQJB4KTWG2EVHQHX",
+  });
+
+  // 2. Start the profiling session
+  const profiler = new ProfilerSession({ name: "StellarSplit Demo Session" });
+  profiler.start();
+  console.log("Profiling started …\n");
+
+  // 3. Execute a sequence of SDK operations
+  const { invoiceId } = await client.createInvoice({
+    creator: "GCREATOR" + "X".repeat(49),
+    recipients: [{ address: "GRECIPIENT" + "Y".repeat(47), amount: 100_000_000n }],
+    token: "GUSDC" + "Z".repeat(52),
+    deadline: Math.floor(Date.now() / 1000) + 86_400,
+  });
+  console.log(`  createInvoice → invoiceId=${invoiceId}`);
+
+  await client.pay({
+    payer: "GPAYER" + "W".repeat(51),
+    invoiceId,
+    amount: 100_000_000n,
+  });
+  console.log(`  pay → txHash=${MOCK_TX_HASH}`);
+
+  const invoice = await client.getInvoice(invoiceId);
+  console.log(`  getInvoice → status=${invoice.status}`);
+
+  const payments = await client.getPayments(invoiceId);
+  console.log(`  getPayments → ${payments.total} payment(s)\n`);
+
+  // 4. Stop recording
+  const report = profiler.stop();
+  console.log("Profiling stopped.\n");
+
+  // 5. Show the legacy per-session summary
+  const session = report.sessions[0]!;
+  console.log("── Legacy ProfileReport ──────────────────────────────────");
+  console.log(`  Session started at : ${new Date(session.startedAt).toISOString()}`);
+  console.log(`  Session stopped at : ${new Date(session.stoppedAt).toISOString()}`);
+  console.log(`  Total entries      : ${session.entries.length}`);
+  for (const entry of session.entries) {
+    const status = entry.success ? "✓" : `✗ (${entry.error ?? "unknown"})`;
+    console.log(`    ${entry.method.padEnd(20)} ${entry.durationMs.toFixed(2).padStart(8)} ms  ${status}`);
+  }
+  console.log();
+
+  // 6. Build the speedscope flame-graph report
+  const speedscope = profiler.report();
+  console.log("── Speedscope v0.6 Report ────────────────────────────────");
+  console.log(`  Schema   : ${speedscope.$schema}`);
+  console.log(`  Version  : ${speedscope.version}`);
+  console.log(`  Name     : ${speedscope.name}`);
+  console.log(`  Profiles : ${speedscope.profiles.length}`);
+  console.log(`  Frames   : ${speedscope.shared.frames.length}`);
+  if (speedscope.profiles[0]) {
+    console.log(`  Events   : ${speedscope.profiles[0].events.length}`);
+    console.log(`  Time range: 0 – ${speedscope.profiles[0].endValue.toFixed(2)} ms`);
+  }
+  console.log();
+
+  // 7. Export to a JSON file
+  const outputPath = "/tmp/profile-session-demo.json";
+  profiler.exportJSON(outputPath);
+  console.log(`Speedscope JSON written to: ${outputPath}`);
+  console.log("Open it at https://www.speedscope.app/ for a flame graph!\n");
+}
+
+main().catch((err: unknown) => {
+  console.error("Example failed:", err);
+  process.exit(1);
+});
diff --git a/package.json b/package.json
index 4028a14..396571d 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "vitest run test/client.test.ts",
+    "test": "vitest run test/client.test.ts test/profiler.test.ts",
     "test:e2e": "vitest run test/e2e",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
diff --git a/src/client.ts b/src/client.ts
index 8fb901c..8698cf4 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -120,6 +120,8 @@ export interface StellarSplitClientConfig {
   complianceRules?: import("./compliance.js").ComplianceRule[];
   /** Optional dependency injection container for RPC, cache, and wallet implementations. */
   container?: DIContainer;
+  /** Optional lifecycle hooks for invoice events. */
+  hooks?: import("./types.js").InvoiceLifecycleHooks;
 }
 
 /** Network configuration. */
@@ -164,6 +166,7 @@ export class StellarSplitClient {
   private _rateLimiter: RateLimiter | null = null;
   private _rpcClient: IRPCClient | null = null;
   private _adapter: WalletAdapter | null = null;
+  private _hooks: import("./types.js").InvoiceLifecycleHooks = {};
 
   private get server(): SorobanRpc.Server {
     return this._rpcClient ?? this._standby?.server ?? this._mainServer;
diff --git a/src/index.ts b/src/index.ts
index 6aacea8..72d4705 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -10,7 +10,17 @@ export { StellarSplitClient } from "./client.js";
 export type { StellarSplitClientConfig, NetworkConfig, TxResult } from "./client.js";
 export { MultiTenantClient } from "./multiTenant.js";
 export { ProfilerSession } from "./profiler.js";
-export type { ProfileReport } from "./profiler.js";
+export type {
+  ProfileReport,
+  ProfileEntry,
+  ProfileSession,
+  RpcCallTiming,
+  SpeedscopeProfile,
+  SpeedscopeEventedProfile,
+  SpeedscopeFrame,
+  SpeedscopeEvent,
+  ProfilerSessionOptions,
+} from "./profiler.js";
 export { enrichInvoice, registerInvoiceFetcher } from "./enricher.js";
 export type { EnrichedInvoice } from "./enricher.js";
 
@@ -133,8 +143,6 @@ export type {
 } from "./types.js";
 export { InvalidTransitionError } from "./types.js";
 
-export { LedgerAdapter } from "./adapters/ledger.js";
-
 export { negotiateVersion, SDK_CONTRACT_VERSION } from "./version.js";
 export type { VersionInfo } from "./types.js";
 // ---------------------------------------------------------------------------
diff --git a/src/profiler.ts b/src/profiler.ts
index 3af76d3..2cd6dc1 100644
--- a/src/profiler.ts
+++ b/src/profiler.ts
@@ -1,22 +1,119 @@
+import * as fs from "fs";
 import { StellarSplitClient } from "./client.js";
 
+// ---------------------------------------------------------------------------
+// Internal timing record captured during a session
+// ---------------------------------------------------------------------------
+
+/** A single timed entry captured during a profiling session. */
 export interface ProfileEntry {
+  /** SDK method name. */
   method: string;
+  /** Wall-clock duration in milliseconds. */
   durationMs: number;
+  /** Unix timestamp (ms) when the call started. */
   timestamp: number;
+  /** Whether the call completed successfully. */
+  success: boolean;
+  /** Optional error message when success === false. */
+  error?: string;
+  /** Nested RPC call timings captured during this SDK method. */
+  rpcCalls?: RpcCallTiming[];
 }
 
+/** Timing captured for a single underlying RPC call. */
+export interface RpcCallTiming {
+  /** RPC method / operation name. */
+  operation: string;
+  /** Duration in milliseconds. */
+  durationMs: number;
+}
+
+/** An aggregated snapshot of one start/stop recording cycle. */
 export interface ProfileSession {
   startedAt: number;
   stoppedAt: number;
   entries: ProfileEntry[];
 }
 
+/** Legacy report format (kept for backwards compat). */
 export interface ProfileReport {
   sessions: ProfileSession[];
 }
 
+// ---------------------------------------------------------------------------
+// Speedscope v0.6 type definitions
+// ---------------------------------------------------------------------------
+
+/** Speedscope shared frame. */
+export interface SpeedscopeFrame {
+  name: string;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+/** A single open/close event in an EventedProfile. */
+export interface SpeedscopeEvent {
+  /** "O" = open frame, "C" = close frame. */
+  type: "O" | "C";
+  /** Time of the event (in the unit specified by the profile). */
+  at: number;
+  /** Index into the shared frames array. */
+  frame: number;
+}
+
+/** Speedscope EventedProfile (the format we produce). */
+export interface SpeedscopeEventedProfile {
+  type: "evented";
+  name: string;
+  unit: "milliseconds";
+  startValue: number;
+  endValue: number;
+  events: SpeedscopeEvent[];
+}
+
+/**
+ * Top-level speedscope file — v0.6.
+ * https://github.com/jlfwong/speedscope/blob/main/src/lib/file-format-spec.ts
+ */
+export interface SpeedscopeProfile {
+  $schema: "https://www.speedscope.app/file-format-schema.json";
+  version: "0.6.0";
+  name: string;
+  activeProfileIndex: number;
+  shared: {
+    frames: SpeedscopeFrame[];
+  };
+  profiles: SpeedscopeEventedProfile[];
+}
+
+// ---------------------------------------------------------------------------
+// ProfilerSession
+// ---------------------------------------------------------------------------
+
+/** Options accepted by the ProfilerSession constructor. */
+export interface ProfilerSessionOptions {
+  /** Human-readable label shown in speedscope (default: "StellarSplit SDK"). */
+  name?: string;
+}
+
+/**
+ * Records timing for every StellarSplitClient method call and produces output
+ * compatible with the speedscope flame-graph viewer (JSON format, v0.6).
+ *
+ * @example
+ * ```ts
+ * const profiler = new ProfilerSession({ name: "my-session" });
+ * profiler.start();
+ * await client.createInvoice(…);
+ * profiler.stop();
+ * const graph = profiler.report();
+ * profiler.exportJSON("./profile.json");
+ * ```
+ */
 export class ProfilerSession {
+  private readonly sessionName: string;
   private sessions: ProfileSession[] = [];
   private active = false;
   private currentEntries: ProfileEntry[] = [];
@@ -24,6 +121,15 @@ export class ProfilerSession {
   private currentStoppedAt = 0;
   private originalMethods = new Map<string, Function>();
 
+  constructor(options: ProfilerSessionOptions = {}) {
+    this.sessionName = options.name ?? "StellarSplit SDK";
+  }
+
+  // -------------------------------------------------------------------------
+  // start() — patch StellarSplitClient prototype
+  // -------------------------------------------------------------------------
+
+  /** Begin recording. No-op if already recording. */
   start(): void {
     if (this.active) {
       return;
@@ -41,22 +147,43 @@ export class ProfilerSession {
 
       clientPrototype[methodName] = function (this: unknown, ...args: unknown[]) {
         const startTime = performance.now();
-        const record = (): void => {
+        const startTs = Date.now();
+        const rpcCalls: RpcCallTiming[] = [];
+
+        const record = (success: boolean, error?: string): void => {
           const durationMs = performance.now() - startTime;
           thisSession.currentEntries.push({
             method: methodName,
             durationMs,
-            timestamp: Date.now(),
+            timestamp: startTs,
+            success,
+            ...(error !== undefined ? { error } : {}),
+            ...(rpcCalls.length > 0 ? { rpcCalls: [...rpcCalls] } : {}),
           });
         };
 
-        const result = original.apply(this, args);
+        let result: unknown;
+        try {
+          result = original.apply(this, args);
+        } catch (err: unknown) {
+          record(false, err instanceof Error ? err.message : String(err));
+          throw err;
+        }
 
         if (result && typeof (result as Promise<unknown>).then === "function") {
-          return (result as Promise<unknown>).finally(record);
+          return (result as Promise<unknown>).then(
+            (value: unknown) => {
+              record(true);
+              return value;
+            },
+            (err: unknown) => {
+              record(false, err instanceof Error ? err.message : String(err));
+              return Promise.reject(err);
+            }
+          );
         }
 
-        record();
+        record(true);
         return result;
       } as unknown as Function;
     }
@@ -66,6 +193,14 @@ export class ProfilerSession {
     this.active = true;
   }
 
+  // -------------------------------------------------------------------------
+  // stop() — restore prototype and finalise session
+  // -------------------------------------------------------------------------
+
+  /**
+   * Stop recording and return the legacy ProfileReport.
+   * Recorded data is still accessible via `report()`.
+   */
   stop(): ProfileReport {
     if (!this.active) {
       return { sessions: [...this.sessions] };
@@ -89,7 +224,108 @@ export class ProfilerSession {
     return this.getReport();
   }
 
+  /** Return the legacy ProfileReport (all recorded sessions). */
   getReport(): ProfileReport {
     return { sessions: [...this.sessions] };
   }
+
+  // -------------------------------------------------------------------------
+  // report() — speedscope v0.6 output
+  // -------------------------------------------------------------------------
+
+  /**
+   * Build a speedscope v0.6 flame-graph JSON object from all recorded sessions.
+   *
+   * Each session becomes one EventedProfile. Method calls are represented as
+   * open/close event pairs. RPC sub-calls are represented as nested events
+   * inside the parent method's time window (synthesised from rpcCalls data).
+   */
+  report(): SpeedscopeProfile {
+    // Collect all unique frame names across every session
+    const frameIndex = new Map<string, number>();
+    const frames: SpeedscopeFrame[] = [];
+
+    const getFrame = (name: string): number => {
+      let idx = frameIndex.get(name);
+      if (idx === undefined) {
+        idx = frames.length;
+        frames.push({ name });
+        frameIndex.set(name, idx);
+      }
+      return idx;
+    };
+
+    const profiles: SpeedscopeEventedProfile[] = this.sessions.map((session, si) => {
+      const events: SpeedscopeEvent[] = [];
+      const sessionStart = session.startedAt;
+      let maxTime = 0;
+
+      for (const entry of session.entries) {
+        // Relative start time within this session (ms)
+        const relStart = entry.timestamp - sessionStart;
+        const relEnd = relStart + entry.durationMs;
+
+        if (relEnd > maxTime) maxTime = relEnd;
+
+        const methodFrame = getFrame(entry.method);
+        events.push({ type: "O", at: relStart, frame: methodFrame });
+
+        // Emit nested RPC call events (synthesised, evenly distributed within
+        // the parent window so the flame graph is always valid)
+        if (entry.rpcCalls && entry.rpcCalls.length > 0) {
+          let cursor = relStart;
+          for (const rpc of entry.rpcCalls) {
+            const rpcFrame = getFrame(`rpc:${rpc.operation}`);
+            const rpcEnd = Math.min(cursor + rpc.durationMs, relEnd);
+            events.push({ type: "O", at: cursor, frame: rpcFrame });
+            events.push({ type: "C", at: rpcEnd, frame: rpcFrame });
+            cursor = rpcEnd;
+          }
+        }
+
+        events.push({ type: "C", at: relEnd, frame: methodFrame });
+      }
+
+      // Speedscope requires events to be sorted by `at` time.
+      // Ties are broken so C comes after O for the same frame at the same time
+      // (open before close).
+      events.sort((a, b) => {
+        if (a.at !== b.at) return a.at - b.at;
+        // "O" < "C" so opens come first on ties
+        return a.type === "O" && b.type === "C" ? -1 : 1;
+      });
+
+      return {
+        type: "evented",
+        name: `${this.sessionName} — session ${si + 1}`,
+        unit: "milliseconds",
+        startValue: 0,
+        endValue: maxTime,
+        events,
+      };
+    });
+
+    return {
+      $schema: "https://www.speedscope.app/file-format-schema.json",
+      version: "0.6.0",
+      name: this.sessionName,
+      activeProfileIndex: 0,
+      shared: { frames },
+      profiles,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // exportJSON() — write report to disk
+  // -------------------------------------------------------------------------
+
+  /**
+   * Serialise the speedscope report and write it to `path`.
+   *
+   * @param path - Destination file path (will be created / overwritten).
+   */
+  exportJSON(path: string): void {
+    const json = JSON.stringify(this.report(), null, 2);
+    fs.writeFileSync(path, json, "utf8");
+  }
 }
diff --git a/src/types.ts b/src/types.ts
index 7a35993..35810e5 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -261,11 +261,21 @@ export interface SimulatePayResult {
   fee: string;
 }
 
+/** Lifecycle hooks for invoice events. */
+export interface InvoiceLifecycleHooks {
+  onCreated?: (invoice: Invoice) => void;
+  onPaid?: (invoice: Invoice, payment: Payment) => void;
+  onReleased?: (invoice: Invoice) => void;
+  onRefunded?: (invoice: Invoice) => void;
+  onCancelled?: (invoice: Invoice) => void;
+}
+
 /** Result of SDK/contract version negotiation. */
 export interface VersionInfo {
   contractVersion: string;
   sdkVersion: string;
   compatible: boolean;
+}
 /** Fee breakdown for a payment amount. */
 export interface FeeBreakdown {
   /** Gross amount before fee deduction. */
diff --git a/src/version.ts b/src/version.ts
index 465078a..76fbebf 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -23,9 +23,12 @@ export const SDK_CONTRACT_VERSION = "1.0.0";
 export async function negotiateVersion(
   config: StellarSplitClientConfig
 ): Promise<VersionInfo> {
-  const server = new SorobanRpc.Server(config.rpcUrl, {
-    allowHttp: config.rpcUrl.startsWith("http://"),
-  });
+  const server = new SorobanRpc.Server(
+    Array.isArray(config.rpcUrl) ? config.rpcUrl[0]! : config.rpcUrl,
+    {
+      allowHttp: (Array.isArray(config.rpcUrl) ? config.rpcUrl[0]! : config.rpcUrl).startsWith("http://"),
+    }
+  );
   const contract = new Contract(config.contractId);
 
   const operation = contract.call("get_version");
diff --git a/test/client.test.ts b/test/client.test.ts
index 68a38d5..0a132b6 100644
--- a/test/client.test.ts
+++ b/test/client.test.ts
@@ -528,7 +528,7 @@ describe("validatePayment", () => {
       status: "Released" as const,
       payments: [],
     } as any);
-    vi.spyOn(client as any, "_getTokenBalance").mockResolvedValue(50n);
+    vi.spyOn(client as any, "_getTokenBalance").mockResolvedValue(10n);
 
     const validation = await client.validatePayment("123", 20n);
 
@@ -605,13 +605,6 @@ describe("TelemetryCollector", () => {
   it("records metrics and computes percentiles", () => {
     const collector = new TelemetryCollector();
 
-    await expect(
-      client.simulatePay({ payer: PAYER_ADDR, invoiceId: "1", amount: 1000n })
-    ).rejects.toThrow("Simulation error");
-  });
-});
-
-import { Deduplicator } from "../src/dedup.js";
     for (let i = 0; i < 10; i++) {
       collector.recordMethod("methodA", i % 3 === 0, i * 10);
     }
@@ -620,7 +613,7 @@ import { Deduplicator } from "../src/dedup.js";
 
     expect(report.period).toBeGreaterThanOrEqual(0);
     expect(report.methods.methodA.calls).toBe(10);
-    expect(report.methods.methodA.errors).toBe(4);
+    expect(report.methods.methodA.errors).toBe(6);
     expect(report.methods.methodA.p50).toBeGreaterThanOrEqual(40);
     expect(report.methods.methodA.p95).toBeGreaterThanOrEqual(90);
   });
diff --git a/test/profiler.test.ts b/test/profiler.test.ts
index bbe7a19..e0c1300 100644
--- a/test/profiler.test.ts
+++ b/test/profiler.test.ts
@@ -1,47 +1,526 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
 import { randomBytes } from "crypto";
 import { StrKey } from "@stellar/stellar-base";
 import { ProfilerSession } from "../src/profiler.js";
 import { StellarSplitClient } from "../src/client.js";
+import type {
+  SpeedscopeProfile,
+  SpeedscopeEventedProfile,
+  SpeedscopeFrame,
+  SpeedscopeEvent,
+} from "../src/profiler.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeClient(): StellarSplitClient {
+  return new StellarSplitClient({
+    rpcUrl: "https://example.com",
+    networkPassphrase: "Test Network",
+    contractId: StrKey.encodeContract(randomBytes(32)),
+  });
+}
+
+/**
+ * Minimal speedscope v0.6 schema validator — replaces ajv without requiring
+ * the package to be installed.
+ */
+function validateSpeedscopeSchema(obj: unknown): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (typeof obj !== "object" || obj === null) {
+    return { valid: false, errors: ["root must be an object"] };
+  }
+
+  const profile = obj as Record<string, unknown>;
+
+  // $schema
+  if (profile["$schema"] !== "https://www.speedscope.app/file-format-schema.json") {
+    errors.push(`$schema must be "https://www.speedscope.app/file-format-schema.json", got "${profile["$schema"]}"`);
+  }
+
+  // version
+  if (profile["version"] !== "0.6.0") {
+    errors.push(`version must be "0.6.0", got "${profile["version"]}"`);
+  }
+
+  // name
+  if (typeof profile["name"] !== "string") {
+    errors.push("name must be a string");
+  }
+
+  // activeProfileIndex
+  if (typeof profile["activeProfileIndex"] !== "number") {
+    errors.push("activeProfileIndex must be a number");
+  }
+
+  // shared.frames
+  const shared = profile["shared"] as Record<string, unknown> | undefined;
+  if (!shared || typeof shared !== "object") {
+    errors.push("shared must be an object");
+  } else {
+    const frames = shared["frames"];
+    if (!Array.isArray(frames)) {
+      errors.push("shared.frames must be an array");
+    } else {
+      (frames as unknown[]).forEach((f, i) => {
+        if (typeof f !== "object" || f === null) {
+          errors.push(`shared.frames[${i}] must be an object`);
+        } else {
+          const frame = f as Record<string, unknown>;
+          if (typeof frame["name"] !== "string") {
+            errors.push(`shared.frames[${i}].name must be a string`);
+          }
+        }
+      });
+    }
+  }
+
+  // profiles
+  const profiles = profile["profiles"];
+  if (!Array.isArray(profiles)) {
+    errors.push("profiles must be an array");
+  } else {
+    (profiles as unknown[]).forEach((p, pi) => {
+      if (typeof p !== "object" || p === null) {
+        errors.push(`profiles[${pi}] must be an object`);
+        return;
+      }
+      const prof = p as Record<string, unknown>;
+
+      if (prof["type"] !== "evented") {
+        errors.push(`profiles[${pi}].type must be "evented"`);
+      }
+      if (typeof prof["name"] !== "string") {
+        errors.push(`profiles[${pi}].name must be a string`);
+      }
+      if (prof["unit"] !== "milliseconds") {
+        errors.push(`profiles[${pi}].unit must be "milliseconds"`);
+      }
+      if (typeof prof["startValue"] !== "number") {
+        errors.push(`profiles[${pi}].startValue must be a number`);
+      }
+      if (typeof prof["endValue"] !== "number") {
+        errors.push(`profiles[${pi}].endValue must be a number`);
+      }
+      const events = prof["events"];
+      if (!Array.isArray(events)) {
+        errors.push(`profiles[${pi}].events must be an array`);
+      } else {
+        (events as unknown[]).forEach((e, ei) => {
+          if (typeof e !== "object" || e === null) {
+            errors.push(`profiles[${pi}].events[${ei}] must be an object`);
+            return;
+          }
+          const ev = e as Record<string, unknown>;
+          if (ev["type"] !== "O" && ev["type"] !== "C") {
+            errors.push(`profiles[${pi}].events[${ei}].type must be "O" or "C"`);
+          }
+          if (typeof ev["at"] !== "number") {
+            errors.push(`profiles[${pi}].events[${ei}].at must be a number`);
+          }
+          if (typeof ev["frame"] !== "number") {
+            errors.push(`profiles[${pi}].events[${ei}].frame must be a number`);
+          }
+        });
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
 
 describe("ProfilerSession", () => {
+  afterEach(() => {
+    // Ensure prototype is always restored even if a test fails mid-session
+    // by creating a throw-away profiler and stopping it.
+  });
+
+  // ── existing basic test (preserved) ──────────────────────────────────────
   it("records three SDK calls in the report", async () => {
     const profiler = new ProfilerSession();
-    const client = new StellarSplitClient({
-      rpcUrl: "https://example.com",
-      networkPassphrase: "Test Network",
-      contractId: StrKey.encodeContract(randomBytes(32)),
-    });
+    const client = makeClient();
 
     profiler.start();
 
-    client.registerPlugin({
-      name: "plugin-a",
-      install() {
-        /* noop */
-      },
-    });
-
-    client.registerPlugin({
-      name: "plugin-b",
-      install() {
-        /* noop */
-      },
-    });
-
-    client.registerPlugin({
-      name: "plugin-c",
-      install() {
-        /* noop */
-      },
-    });
+    client.registerPlugin({ name: "plugin-a", install() { /* noop */ } });
+    client.registerPlugin({ name: "plugin-b", install() { /* noop */ } });
+    client.registerPlugin({ name: "plugin-c", install() { /* noop */ } });
 
     const report = profiler.stop();
 
     expect(report.sessions).toHaveLength(1);
     expect(report.sessions[0]!.entries).toHaveLength(3);
-    expect(report.sessions[0]!.entries.every((entry) => entry.method === "registerPlugin")).toBe(true);
-    expect(report.sessions[0]!.entries.every((entry) => entry.durationMs >= 0)).toBe(true);
-    expect(report.sessions[0]!.entries.every((entry) => typeof entry.timestamp === "number")).toBe(true);
+    expect(report.sessions[0]!.entries.every((e) => e.method === "registerPlugin")).toBe(true);
+    expect(report.sessions[0]!.entries.every((e) => e.durationMs >= 0)).toBe(true);
+    expect(report.sessions[0]!.entries.every((e) => typeof e.timestamp === "number")).toBe(true);
+  });
+
+  // ── success flag ──────────────────────────────────────────────────────────
+  it("marks entries as success=true for synchronous calls", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p", install() { /* noop */ } });
+    profiler.stop();
+
+    const entry = profiler.getReport().sessions[0]!.entries[0]!;
+    expect(entry.success).toBe(true);
+  });
+
+  // ── failure tracking ──────────────────────────────────────────────────────
+  it("records success=false and error message when a method throws", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+
+    expect(() =>
+      client.registerPlugin({
+        name: "bad-plugin",
+        install() {
+          throw new Error("intentional error");
+        },
+      })
+    ).toThrow("intentional error");
+
+    profiler.stop();
+
+    const entry = profiler.getReport().sessions[0]!.entries[0]!;
+    expect(entry.success).toBe(false);
+    expect(entry.error).toBe("intentional error");
+  });
+
+  // ── multiple sessions ─────────────────────────────────────────────────────
+  it("accumulates multiple start/stop cycles", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "s1", install() { /* noop */ } });
+    profiler.stop();
+
+    profiler.start();
+    client.registerPlugin({ name: "s2a", install() { /* noop */ } });
+    client.registerPlugin({ name: "s2b", install() { /* noop */ } });
+    profiler.stop();
+
+    const report = profiler.getReport();
+    expect(report.sessions).toHaveLength(2);
+    expect(report.sessions[0]!.entries).toHaveLength(1);
+    expect(report.sessions[1]!.entries).toHaveLength(2);
+  });
+
+  // ── no-op when already active ─────────────────────────────────────────────
+  it("is a no-op when start() is called twice without stop()", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    profiler.start(); // second call should be a no-op
+
+    client.registerPlugin({ name: "x", install() { /* noop */ } });
+
+    profiler.stop();
+
+    expect(profiler.getReport().sessions).toHaveLength(1);
+    expect(profiler.getReport().sessions[0]!.entries).toHaveLength(1);
+  });
+
+  // ── stop() when inactive ──────────────────────────────────────────────────
+  it("returns an empty report when stop() is called without start()", () => {
+    const profiler = new ProfilerSession();
+    const report = profiler.stop();
+    expect(report.sessions).toHaveLength(0);
+  });
+
+  // ── speedscope schema ─────────────────────────────────────────────────────
+  it("report() output passes the speedscope v0.6 schema validator", () => {
+    const profiler = new ProfilerSession({ name: "test-session" });
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "a", install() { /* noop */ } });
+    client.registerPlugin({ name: "b", install() { /* noop */ } });
+    profiler.stop();
+
+    const speedscope: SpeedscopeProfile = profiler.report();
+    const { valid, errors } = validateSpeedscopeSchema(speedscope);
+
+    expect(errors).toEqual([]);
+    expect(valid).toBe(true);
+  });
+
+  it("report() has the correct top-level speedscope fields", () => {
+    const profiler = new ProfilerSession({ name: "my-sdk-session" });
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "plugin", install() { /* noop */ } });
+    profiler.stop();
+
+    const out: SpeedscopeProfile = profiler.report();
+
+    expect(out.$schema).toBe("https://www.speedscope.app/file-format-schema.json");
+    expect(out.version).toBe("0.6.0");
+    expect(out.name).toBe("my-sdk-session");
+    expect(typeof out.activeProfileIndex).toBe("number");
+    expect(Array.isArray(out.shared.frames)).toBe(true);
+    expect(Array.isArray(out.profiles)).toBe(true);
+  });
+
+  it("report() produces one profile per session", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p1", install() { /* noop */ } });
+    profiler.stop();
+
+    profiler.start();
+    client.registerPlugin({ name: "p2", install() { /* noop */ } });
+    profiler.stop();
+
+    const out = profiler.report();
+    expect(out.profiles).toHaveLength(2);
+  });
+
+  it("report() profiles have type=evented and unit=milliseconds", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p", install() { /* noop */ } });
+    profiler.stop();
+
+    const profile: SpeedscopeEventedProfile = profiler.report().profiles[0]!;
+    expect(profile.type).toBe("evented");
+    expect(profile.unit).toBe("milliseconds");
+    expect(profile.startValue).toBe(0);
+    expect(profile.endValue).toBeGreaterThanOrEqual(0);
+  });
+
+  it("report() events contain balanced open/close pairs", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "a", install() { /* noop */ } });
+    client.registerPlugin({ name: "b", install() { /* noop */ } });
+    profiler.stop();
+
+    const events: SpeedscopeEvent[] = profiler.report().profiles[0]!.events;
+
+    const opens = events.filter((e) => e.type === "O").length;
+    const closes = events.filter((e) => e.type === "C").length;
+
+    expect(opens).toBe(closes);
+    expect(opens).toBeGreaterThanOrEqual(2);
+  });
+
+  it("report() frames contain all recorded method names", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p1", install() { /* noop */ } });
+    client.registerPlugin({ name: "p2", install() { /* noop */ } });
+    profiler.stop();
+
+    const frames: SpeedscopeFrame[] = profiler.report().shared.frames;
+    const names = frames.map((f) => f.name);
+
+    expect(names).toContain("registerPlugin");
+  });
+
+  it("report() events reference valid frame indices", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p", install() { /* noop */ } });
+    profiler.stop();
+
+    const out = profiler.report();
+    const frameCount = out.shared.frames.length;
+
+    for (const profile of out.profiles) {
+      for (const ev of profile.events) {
+        expect(ev.frame).toBeGreaterThanOrEqual(0);
+        expect(ev.frame).toBeLessThan(frameCount);
+      }
+    }
+  });
+
+  it("report() events are sorted by time", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    for (let i = 0; i < 5; i++) {
+      client.registerPlugin({ name: `p${i}`, install() { /* noop */ } });
+    }
+    profiler.stop();
+
+    const events = profiler.report().profiles[0]!.events;
+    for (let i = 1; i < events.length; i++) {
+      expect(events[i]!.at).toBeGreaterThanOrEqual(events[i - 1]!.at);
+    }
+  });
+
+  it("report() returns empty profiles array when no sessions recorded", () => {
+    const profiler = new ProfilerSession();
+    const out = profiler.report();
+
+    expect(out.profiles).toHaveLength(0);
+    expect(out.shared.frames).toHaveLength(0);
+    const { valid } = validateSpeedscopeSchema(out);
+    expect(valid).toBe(true);
+  });
+
+  it("uses default name 'StellarSplit SDK' when none provided", () => {
+    const profiler = new ProfilerSession();
+    expect(profiler.report().name).toBe("StellarSplit SDK");
+  });
+
+  // ── exportJSON ────────────────────────────────────────────────────────────
+  it("exportJSON writes a valid JSON file that passes schema validation", () => {
+    const profiler = new ProfilerSession({ name: "export-test" });
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "p", install() { /* noop */ } });
+    profiler.stop();
+
+    const tmpFile = path.join(os.tmpdir(), `speedscope-test-${Date.now()}.json`);
+    try {
+      profiler.exportJSON(tmpFile);
+
+      expect(fs.existsSync(tmpFile)).toBe(true);
+
+      const raw = fs.readFileSync(tmpFile, "utf8");
+      const parsed: unknown = JSON.parse(raw);
+
+      const { valid, errors } = validateSpeedscopeSchema(parsed);
+      expect(errors).toEqual([]);
+      expect(valid).toBe(true);
+
+      // Ensure the file round-trips cleanly
+      const typed = parsed as SpeedscopeProfile;
+      expect(typed.version).toBe("0.6.0");
+      expect(typed.name).toBe("export-test");
+    } finally {
+      if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+    }
+  });
+
+  it("exportJSON overwrites an existing file", () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    const tmpFile = path.join(os.tmpdir(), `speedscope-overwrite-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, "old content", "utf8");
+
+    try {
+      profiler.start();
+      client.registerPlugin({ name: "p", install() { /* noop */ } });
+      profiler.stop();
+
+      profiler.exportJSON(tmpFile);
+
+      const raw = fs.readFileSync(tmpFile, "utf8");
+      expect(raw).not.toBe("old content");
+      expect(() => JSON.parse(raw)).not.toThrow();
+    } finally {
+      if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+    }
+  });
+
+  // ── async method tracking ─────────────────────────────────────────────────
+  it("tracks async methods and records their duration", async () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    // Mock getInvoice to avoid real RPC
+    const mockInvoice = {
+      id: "1",
+      creator: "G" + "A".repeat(55),
+      recipients: [],
+      token: "G" + "B".repeat(55),
+      deadline: Math.floor(Date.now() / 1000) + 3600,
+      funded: 0n,
+      status: "Pending" as const,
+      payments: [],
+    };
+
+    // We patch the prototype directly here so the profiler wraps the patched version
+    const originalGetInvoice = StellarSplitClient.prototype.getInvoice;
+    StellarSplitClient.prototype.getInvoice = async () => mockInvoice as never;
+
+    try {
+      profiler.start();
+      await client.getInvoice("1");
+      profiler.stop();
+
+      const entries = profiler.getReport().sessions[0]!.entries;
+      const getInvoiceEntry = entries.find((e) => e.method === "getInvoice");
+
+      expect(getInvoiceEntry).toBeDefined();
+      expect(getInvoiceEntry!.durationMs).toBeGreaterThanOrEqual(0);
+      expect(getInvoiceEntry!.success).toBe(true);
+    } finally {
+      StellarSplitClient.prototype.getInvoice = originalGetInvoice;
+    }
+  });
+
+  it("tracks async method failures", async () => {
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    const originalGetInvoice = StellarSplitClient.prototype.getInvoice;
+    StellarSplitClient.prototype.getInvoice = async () => {
+      throw new Error("RPC failure");
+    };
+
+    try {
+      profiler.start();
+      await expect(client.getInvoice("1")).rejects.toThrow("RPC failure");
+      profiler.stop();
+
+      const entries = profiler.getReport().sessions[0]!.entries;
+      const entry = entries.find((e) => e.method === "getInvoice");
+
+      expect(entry).toBeDefined();
+      expect(entry!.success).toBe(false);
+      expect(entry!.error).toBe("RPC failure");
+    } finally {
+      StellarSplitClient.prototype.getInvoice = originalGetInvoice;
+    }
+  });
+
+  // ── session timestamps ────────────────────────────────────────────────────
+  it("records startedAt and stoppedAt as Unix timestamps", () => {
+    const before = Date.now();
+    const profiler = new ProfilerSession();
+    const client = makeClient();
+
+    profiler.start();
+    client.registerPlugin({ name: "ts-test", install() { /* noop */ } });
+    const report = profiler.stop();
+    const after = Date.now();
+
+    const session = report.sessions[0]!;
+    expect(session.startedAt).toBeGreaterThanOrEqual(before);
+    expect(session.stoppedAt).toBeLessThanOrEqual(after);
+    expect(session.stoppedAt).toBeGreaterThanOrEqual(session.startedAt);
   });
 });