@thesight/sdk 0.1.1 → 0.2.0

package/README.md

@@ -13,12 +13,24 @@ correlation — consumable by the Sight dashboard or any APM backend
 
 ```bash
 pnpm add @thesight/sdk
+# or npm install @thesight/sdk
+# or yarn add @thesight/sdk
 ```
 
 All OpenTelemetry dependencies are bundled transitively — you do **not**
 need to `pnpm add @opentelemetry/*` separately.
 
-## Quickstart
+Ships both ESM and CJS builds. Works from modern TypeScript projects,
+Node ESM, legacy CJS via `require()`, bundlers, and serverless runtimes.
+
+## Quickstart — `InstrumentedConnection` (automatic spans)
+
+The simplest pattern: swap your `Connection` for `InstrumentedConnection`
+and every transaction you send through it gets a span automatically —
+no matter whether you're calling it directly, going through an Anchor
+`provider.sendAndConfirm`, using web3.js's top-level
+`sendAndConfirmTransaction`, or letting a wallet adapter drive the
+flow.
 
 ```ts
 import { initSight, InstrumentedConnection } from '@thesight/sdk';
@@ -33,17 +45,73 @@ initSight({
 // Drop-in replacement for @solana/web3.js Connection
 const connection = new InstrumentedConnection(clusterApiUrl('mainnet'));
 
-// Every confirmed transaction becomes an OTel span routed to Sight ingest
-const { signature, cpiTree } = await connection.sendAndConfirmInstrumented(tx);
+// Anywhere a Solana tx goes out, a span goes with it:
+await connection.sendRawTransaction(tx.serialize());
+// or...
+await sendAndConfirmTransaction(connection, tx, signers);
+// or...
+const program = new Program(idl, programId, new AnchorProvider(connection, wallet, {}));
+await program.methods.foo().rpc();
+// or...
+await wallet.sendTransaction(tx, connection);
+```
+
+Under the hood, `InstrumentedConnection` overrides the single method
+every Solana send-path eventually calls — `sendRawTransaction` — so you
+get spans regardless of which layer is driving the transaction.
+
+### What the span does, step by step
+
+1. On the synchronous submit path, a span named `solana.sendRawTransaction`
+   starts as a child of whatever OTel context is active.
+2. `super.sendRawTransaction(rawTx, options)` is called verbatim — **no
+   byte mutation, no interception of signing, no private key access**.
+3. The returned signature is attached to the span and the caller gets
+   it back immediately.
+4. In the background (never blocking the caller), a task polls
+   `getTransaction(signature)` with exponential backoff until the
+   on-chain record is available, parses the program logs into a CPI
+   tree via `@thesight/core`, enriches with registered Anchor IDLs,
+   and adds `cpi.invoke` events, per-program CU attribution, and
+   decoded error details to the span.
+5. The span ends and flushes via the Sight exporter configured by
+   `initSight`.
+
+## Alternative — `trackSolanaTransaction` (non-wrapping)
+
+If you don't want to wrap your `Connection` at all, `trackSolanaTransaction`
+observes by signature alone after you've already sent the transaction
+through *any* connection:
+
+```ts
+import { Connection } from '@solana/web3.js';
+import { initSight, trackSolanaTransaction } from '@thesight/sdk';
+
+initSight({ apiKey, serviceName: 'checkout' });
+
+// Use your normal Connection, unchanged.
+const connection = new Connection(rpcUrl);
+const signature  = await wallet.sendTransaction(tx, connection);
+
+// Fire-and-forget — span flushes on its own in the background.
+void trackSolanaTransaction({
+  signature,
+  connection,
+  serviceName: 'checkout',
+  idls: { [swapProgramId]: swapIdl },
+});
 ```
 
-`initSight` registers a `NodeTracerProvider` as the global OpenTelemetry
-tracer, installs a batch span processor, and wires a Sight-specific
-exporter that POSTs to ingest in the expected format. Any tracer
-obtained via `trace.getTracer(...)` (including the one
-`InstrumentedConnection` uses internally) routes through the same
-exporter — so if you add OTel instrumentation elsewhere in your app,
-those spans get Sight-correlated for free.
+This helper **never touches the send path**. It only observes the
+transaction after the fact by calling `getTransaction(signature)`.
+Recommended when:
+
+- You're security-conscious and don't want any SDK code on the
+  critical transaction path
+- Your send path goes through a wallet adapter or a wrapper SDK you
+  don't control
+- You want to instrument a specific high-value transaction rather
+  than everything a connection sends
 
 ## Anchor IDL registration
 
@@ -73,7 +141,8 @@ being fabricated.
 ## Self-host the ingest
 
 By default spans export to `https://ingest.thesight.dev/ingest`.
-Override via `ingestUrl` to point at a self-hosted Sight ingest:
+Override via `ingestUrl` to point at a self-hosted Sight ingest (or a
+local Docker stack for development):
 
 ```ts
 initSight({
@@ -85,24 +154,45 @@ initSight({
 
 ## What's on the span
 
-Every `sendAndConfirmInstrumented` call produces an OTel span with the
+Every instrumented transaction produces an OTel span with the
 following attributes when they're available:
 
 - `solana.tx.signature` — base58 signature
-- `solana.tx.status` — `confirmed` / `failed` / `timeout`
+- `solana.tx.status` — `submitted` → `confirmed` / `failed` / `timeout`
 - `solana.tx.slot`
 - `solana.tx.cu_used` / `solana.tx.cu_budget` / `solana.tx.cu_utilization`
 - `solana.tx.program` — root program name (from registered IDL or
-  curated known-programs list)
+  the curated known-programs list)
 - `solana.tx.instruction` — extracted from `Program log: Instruction: …`
 - `solana.tx.error` / `solana.tx.error_code` / `solana.tx.error_program`
   — decoded from on-chain return data via the registered IDL's error
   table or the hardcoded native-error tables
 - `solana.tx.fee_lamports`
-- `solana.tx.submit_ms` / `solana.tx.confirmation_ms` /
-  `solana.tx.enrichment_ms` — client-observed latencies
-- Per-CPI `cpi.invoke` events on the span: program, instruction, depth,
-  CU consumed, CU self, percentage
+- `solana.tx.submit_ms` / `solana.tx.enrichment_ms` — client-observed
+  latencies
+- Per-CPI `cpi.invoke` events on the span: program, instruction,
+  depth, CU consumed, CU self, percentage
+
+## Configuration
+
+`InstrumentedConnection` accepts these extra options alongside the
+standard web3.js `ConnectionConfig`:
+
+```ts
+new InstrumentedConnection(rpcUrl, {
+  // Standard ConnectionConfig fields work as before
+  commitment: 'confirmed',
+
+  // Sight-specific
+  tracer:                    customTracer,
+  skipIdlResolution:         false,  // skip log parsing + IDL decoding
+  idls:                      { [programId]: idl },
+  allowOnChainIdlFetch:      false,  // off by default — never guess
+  enrichmentTimeoutMs:       30_000, // background enrichment wall time
+  enrichmentPollIntervalMs:  500,    // base poll interval with 1.5x backoff
+  disableAutoSpan:           false,  // escape hatch for tests
+});
+```
 
 ## Shutdown
 
@@ -118,6 +208,33 @@ process.on('SIGTERM', async () => {
 });
 ```
 
+## Migration from 0.1.x
+
+Version 0.2.0 removes the `sendAndConfirmInstrumented()` method that
+earlier versions required you to call explicitly. Spans now fire
+automatically from every call to `sendRawTransaction()` — including
+those made by Anchor's provider, web3.js's top-level helpers, and
+wallet adapters — so explicit wrapping is no longer necessary.
+
+**If your 0.1.x code looked like this:**
+
+```ts
+const { signature, cpiTree } = await connection.sendAndConfirmInstrumented(tx);
+```
+
+**Replace it with either:**
+
+```ts
+// 1. Standard web3.js — span fires automatically
+const signature = await sendAndConfirmTransaction(connection, tx, signers);
+
+// 2. Or inspect the span attributes via your OTel processor
+```
+
+The `cpiTree` is no longer returned from a direct call. It lives on the
+span as `cpi.invoke` events, accessible via any OTel processor hooked
+into the same tracer provider, or visible in the Sight dashboard.
+
 ## License
 
 MIT — see `LICENSE`.

package/dist/index.cjs

@@ -20,16 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  IdlResolver: () => import_core3.IdlResolver,
+  IdlResolver: () => import_core4.IdlResolver,
   InstrumentedConnection: () => InstrumentedConnection,
   SightSpanExporter: () => SightSpanExporter,
-  initSight: () => initSight
+  initSight: () => initSight,
+  trackSolanaTransaction: () => trackSolanaTransaction
 });
 module.exports = __toCommonJS(index_exports);
 var import_web3 = require("@solana/web3.js");
-var import_api = require("@opentelemetry/api");
-var import_core2 = require("@thesight/core");
+var import_api2 = require("@opentelemetry/api");
 var import_core3 = require("@thesight/core");
+var import_core4 = require("@thesight/core");
 
 // src/init.ts
 var import_sdk_trace_node = require("@opentelemetry/sdk-trace-node");
@@ -197,6 +198,98 @@ function initSight(config) {
   };
 }
 
+// src/track.ts
+var import_api = require("@opentelemetry/api");
+var import_core2 = require("@thesight/core");
+async function trackSolanaTransaction(opts) {
+  const tracerName = opts.serviceName ?? "@thesight/sdk";
+  const tracer = opts.tracer ?? import_api.trace.getTracer(tracerName);
+  const span = tracer.startSpan("solana.trackTransaction", {}, import_api.context.active());
+  span.setAttribute("solana.tx.signature", opts.signature);
+  const start = Date.now();
+  const deadline = start + (opts.timeoutMs ?? 3e4);
+  const commitment = opts.commitment ?? "confirmed";
+  const basePoll = opts.pollIntervalMs ?? 500;
+  const resolver = opts.idlResolver ?? buildResolverFromIdls(opts.idls);
+  try {
+    const txDetails = await pollGetTransaction(opts.connection, opts.signature, commitment, deadline, basePoll);
+    if (!txDetails) {
+      span.setAttribute("solana.tx.status", "timeout");
+      span.setAttribute("solana.tx.enrichment_ms", Date.now() - start);
+      return;
+    }
+    span.setAttribute("solana.tx.status", txDetails.meta?.err ? "failed" : "confirmed");
+    span.setAttribute("solana.tx.slot", txDetails.slot);
+    const fee = txDetails.meta?.fee;
+    if (fee !== void 0) span.setAttribute("solana.tx.fee_lamports", fee);
+    const cuUsed = txDetails.meta?.computeUnitsConsumed;
+    if (cuUsed !== void 0 && cuUsed !== null) {
+      span.setAttribute("solana.tx.cu_used", Number(cuUsed));
+      span.setAttribute("solana.tx.cu_budget", 2e5);
+      span.setAttribute(
+        "solana.tx.cu_utilization",
+        parseFloat((Number(cuUsed) / 2e5 * 100).toFixed(1))
+      );
+    }
+    const logs = txDetails.meta?.logMessages ?? [];
+    if (logs.length > 0) {
+      const { cpiTree } = (0, import_core2.parseLogs)({ logs });
+      await (0, import_core2.enrichTree)(cpiTree, resolver);
+      for (const attr of (0, import_core2.flatAttributions)(cpiTree)) {
+        span.addEvent("cpi.invoke", {
+          "cpi.program": attr.programName ?? attr.programId,
+          "cpi.instruction": attr.instructionName ?? "unknown",
+          "cpi.depth": attr.depth,
+          "cpi.cu_consumed": attr.cuConsumed,
+          "cpi.cu_self": attr.cuSelf,
+          "cpi.percentage": parseFloat(attr.percentage.toFixed(2))
+        });
+      }
+      const root = cpiTree.roots[0];
+      if (root) {
+        if (root.programName) span.setAttribute("solana.tx.program", root.programName);
+        if (root.instructionName) span.setAttribute("solana.tx.instruction", root.instructionName);
+      }
+    }
+    span.setAttribute("solana.tx.enrichment_ms", Date.now() - start);
+    if (txDetails.meta?.err) {
+      span.setStatus({ code: import_api.SpanStatusCode.ERROR });
+    } else {
+      span.setStatus({ code: import_api.SpanStatusCode.OK });
+    }
+  } catch (err) {
+    span.recordException(err instanceof Error ? err : new Error(String(err)));
+    span.setStatus({
+      code: import_api.SpanStatusCode.ERROR,
+      message: err instanceof Error ? err.message : String(err)
+    });
+  } finally {
+    span.end();
+  }
+}
+function buildResolverFromIdls(idls) {
+  const resolver = new import_core2.IdlResolver();
+  if (idls) resolver.registerMany(idls);
+  return resolver;
+}
+async function pollGetTransaction(connection, signature, commitment, deadline, basePollMs) {
+  let attempt = 0;
+  while (Date.now() < deadline) {
+    try {
+      const tx = await connection.getTransaction(signature, {
+        commitment,
+        maxSupportedTransactionVersion: 0
+      });
+      if (tx) return tx;
+    } catch {
+    }
+    attempt++;
+    const waitMs = Math.min(basePollMs * Math.pow(1.5, attempt - 1), 2e3);
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+  }
+  return null;
+}
+
 // src/index.ts
 var InstrumentedConnection = class extends import_web3.Connection {
   sightConfig;
@@ -209,16 +302,29 @@ var InstrumentedConnection = class extends import_web3.Connection {
       skipIdlResolution,
       idls,
       allowOnChainIdlFetch,
+      enrichmentTimeoutMs,
+      enrichmentPollIntervalMs,
+      disableAutoSpan,
+      commitment,
       ...connectionConfig
     } = config ?? {};
     super(endpoint, connectionConfig);
-    this.sightConfig = { tracer, idlRpcEndpoint, skipIdlResolution, allowOnChainIdlFetch };
-    this.idlResolver = new import_core2.IdlResolver({
+    this.sightConfig = {
+      tracer,
+      idlRpcEndpoint,
+      skipIdlResolution,
+      allowOnChainIdlFetch,
+      enrichmentTimeoutMs: enrichmentTimeoutMs ?? 3e4,
+      enrichmentPollIntervalMs: enrichmentPollIntervalMs ?? 500,
+      disableAutoSpan,
+      commitment
+    };
+    this.idlResolver = new import_core3.IdlResolver({
       rpcEndpoint: idlRpcEndpoint ?? endpoint,
       allowOnChainFetch: allowOnChainIdlFetch ?? false
     });
     if (idls) this.idlResolver.registerMany(idls);
-    this.tracer = tracer ?? import_api.trace.getTracer("@thesight/sdk");
+    this.tracer = tracer ?? import_api2.trace.getTracer("@thesight/sdk");
   }
   /**
    * Register an IDL for a single program. Convenience forwarder for the
@@ -235,132 +341,165 @@ var InstrumentedConnection = class extends import_web3.Connection {
   registerIdls(idls) {
     this.idlResolver.registerMany(idls);
   }
+  // ─── Overridden method ────────────────────────────────────────────────────
   /**
-   * Sends and confirms a transaction, wrapped in an OTel span.
-   * The span is a child of the current active context.
+   * Overrides the parent `Connection.sendRawTransaction` so every submit —
+   * including those made by Anchor's `provider.sendAndConfirm`, web3.js's
+   * top-level `sendAndConfirmTransaction`, and wallet adapter flows — is
+   * observed by an OTel span automatically.
+   *
+   * The span is a child of whatever OTel context is active when the call
+   * fires, so app-level parent spans (HTTP handlers, job runs, wallet flow
+   * spans from another SDK) nest the Sight span correctly.
    */
-  async sendAndConfirmInstrumented(transaction, options) {
-    const commitment = options?.commitment ?? this.sightConfig.commitment ?? "confirmed";
-    const finality = commitment === "processed" ? "confirmed" : commitment;
-    const span = this.tracer.startSpan("solana.sendAndConfirmTransaction", {}, import_api.context.active());
+  async sendRawTransaction(rawTransaction, options) {
+    if (this.sightConfig.disableAutoSpan) {
+      return super.sendRawTransaction(rawTransaction, options);
+    }
+    const span = this.tracer.startSpan("solana.sendRawTransaction", {}, import_api2.context.active());
     const submitStart = Date.now();
+    let signature;
     try {
-      const signature = await this.sendRawTransaction(
-        "serialize" in transaction ? transaction.serialize() : transaction.serialize(),
-        { skipPreflight: false, ...options }
-      );
-      span.setAttribute("solana.tx.signature", signature);
+      signature = await super.sendRawTransaction(rawTransaction, options);
+    } catch (err) {
       const submitMs = Date.now() - submitStart;
       span.setAttribute("solana.tx.submit_ms", submitMs);
-      const confirmStart = Date.now();
-      const { value: result } = await this.confirmTransaction(
-        { signature, ...await this.getLatestBlockhash(commitment) },
-        commitment
-      );
-      const confirmMs = Date.now() - confirmStart;
-      span.setAttribute("solana.tx.confirmation_ms", confirmMs);
-      if (result.err) {
-        span.setAttribute("solana.tx.status", "failed");
-        span.setStatus({ code: import_api.SpanStatusCode.ERROR });
-        if (!this.sightConfig.skipIdlResolution) {
-          const txDetails = await this.getParsedTransaction(signature, {
-            commitment: finality,
-            maxSupportedTransactionVersion: 0
-          });
-          const accountKeys = txDetails?.transaction.message.accountKeys.map(
-            (k) => k.pubkey ? k.pubkey.toBase58() : k.toBase58()
-          ) ?? [];
-          const programIds = txDetails?.transaction.message.instructions.map(
-            (ix) => ix.programId ? ix.programId.toBase58() : accountKeys[ix.programIdIndex] ?? ""
-          ) ?? [];
-          const decoded = await this.idlResolver.decodeError(
-            result.err,
-            accountKeys,
-            programIds
-          );
-          if (decoded.errorName) {
-            span.setAttribute("solana.tx.error", decoded.errorName);
-          }
-          if (decoded.errorCode !== void 0) {
-            span.setAttribute("solana.tx.error_code", decoded.errorCode);
-          }
-          if (decoded.programName) {
-            span.setAttribute("solana.tx.error_program", decoded.programName);
-          }
-          if (decoded.errorMsg) {
-            span.setAttribute("solana.tx.error_msg", decoded.errorMsg);
-          }
-          span.end();
-          return { signature, error: decoded };
-        }
+      span.setAttribute("solana.tx.status", "failed");
+      span.recordException(err instanceof Error ? err : new Error(String(err)));
+      span.setStatus({
+        code: import_api2.SpanStatusCode.ERROR,
+        message: err instanceof Error ? err.message : String(err)
+      });
+      span.end();
+      throw err;
+    }
+    span.setAttribute("solana.tx.signature", signature);
+    span.setAttribute("solana.tx.submit_ms", Date.now() - submitStart);
+    span.setAttribute("solana.tx.status", "submitted");
+    void this.enrichSpanInBackground(span, signature, submitStart);
+    return signature;
+  }
+  // ─── Background enrichment ───────────────────────────────────────────────
+  /**
+   * Poll `getTransaction` until the on-chain record is available, then
+   * enrich the span with CU attribution, program names, decoded errors,
+   * and per-CPI events.
+   *
+   * This runs async and is never awaited by callers of `sendRawTransaction`.
+   * Failures inside this method attach to the span via recordException
+   * rather than throwing.
+   */
+  async enrichSpanInBackground(span, signature, submitStart) {
+    const enrichStart = Date.now();
+    const deadline = enrichStart + (this.sightConfig.enrichmentTimeoutMs ?? 3e4);
+    const commitment = this.sightConfig.commitment ?? "confirmed";
+    const basePollMs = this.sightConfig.enrichmentPollIntervalMs ?? 500;
+    try {
+      const txDetails = await this.pollForTransaction(signature, commitment, deadline, basePollMs);
+      if (!txDetails) {
+        span.setAttribute("solana.tx.status", "timeout");
+        span.setAttribute("solana.tx.enrichment_ms", Date.now() - submitStart);
         span.end();
-        return { signature };
+        return;
       }
-      span.setAttribute("solana.tx.status", "confirmed");
+      this.attachTxDetailsToSpan(span, txDetails);
       if (!this.sightConfig.skipIdlResolution) {
-        const enrichStart = Date.now();
-        const txDetails = await this.getTransaction(signature, {
-          commitment: finality,
-          maxSupportedTransactionVersion: 0
-        });
-        if (txDetails) {
-          const slot = txDetails.slot;
-          const fee = txDetails.meta?.fee;
-          const logs = txDetails.meta?.logMessages ?? [];
-          const cuUsed = txDetails.meta?.computeUnitsConsumed;
-          span.setAttribute("solana.tx.slot", slot);
-          if (fee !== void 0) span.setAttribute("solana.tx.fee_lamports", fee);
-          if (cuUsed !== void 0) {
-            span.setAttribute("solana.tx.cu_used", cuUsed);
-            span.setAttribute("solana.tx.cu_budget", 2e5);
-            span.setAttribute("solana.tx.cu_utilization", parseFloat((cuUsed / 2e5 * 100).toFixed(1)));
-          }
-          const { cpiTree } = (0, import_core2.parseLogs)({ logs });
-          if (!this.sightConfig.skipIdlResolution) {
-            await (0, import_core2.enrichTree)(cpiTree, this.idlResolver);
-          }
-          const attributions = (0, import_core2.flatAttributions)(cpiTree);
-          for (const attr of attributions) {
-            span.addEvent("cpi.invoke", {
-              "cpi.program": attr.programName ?? attr.programId,
-              "cpi.instruction": attr.instructionName ?? "unknown",
-              "cpi.depth": attr.depth,
-              "cpi.cu_consumed": attr.cuConsumed,
-              "cpi.cu_self": attr.cuSelf,
-              "cpi.percentage": parseFloat(attr.percentage.toFixed(2))
-            });
-          }
-          const root = cpiTree.roots[0];
-          if (root) {
-            if (root.programName) span.setAttribute("solana.tx.program", root.programName);
-            if (root.instructionName) span.setAttribute("solana.tx.instruction", root.instructionName);
-          }
-          span.setAttribute("solana.tx.enrichment_ms", Date.now() - enrichStart);
-          span.setStatus({ code: import_api.SpanStatusCode.OK });
-          span.end();
-          return { signature, cpiTree };
+        const logs = txDetails.meta?.logMessages ?? [];
+        if (logs.length > 0) {
+          await this.attachParsedLogsToSpan(span, logs);
         }
       }
-      span.setStatus({ code: import_api.SpanStatusCode.OK });
-      span.end();
-      return { signature };
+      span.setAttribute("solana.tx.enrichment_ms", Date.now() - submitStart);
+      if (txDetails.meta?.err) {
+        span.setStatus({ code: import_api2.SpanStatusCode.ERROR });
+      } else {
+        span.setStatus({ code: import_api2.SpanStatusCode.OK });
+      }
     } catch (err) {
-      span.setAttribute("solana.tx.status", "failed");
-      span.setAttribute("solana.tx.submit_ms", Date.now() - submitStart);
-      span.setStatus({
-        code: import_api.SpanStatusCode.ERROR,
-        message: err instanceof Error ? err.message : String(err)
-      });
+      span.recordException(err instanceof Error ? err : new Error(String(err)));
+      span.setAttribute(
+        "solana.tx.enrichment_error",
+        err instanceof Error ? err.message : String(err)
+      );
+    } finally {
       span.end();
-      throw err;
     }
   }
+  /**
+   * Poll `getTransaction(signature)` until either the on-chain record is
+   * returned or the deadline passes. Exponential backoff (1.5x) capped at
+   * 2 seconds to balance responsiveness against RPC load.
+   */
+  async pollForTransaction(signature, commitment, deadline, basePollMs) {
+    let attempt = 0;
+    while (Date.now() < deadline) {
+      try {
+        const tx = await super.getTransaction(signature, {
+          commitment,
+          maxSupportedTransactionVersion: 0
+        });
+        if (tx) return tx;
+      } catch {
+      }
+      attempt++;
+      const waitMs = Math.min(basePollMs * Math.pow(1.5, attempt - 1), 2e3);
+      await sleep(waitMs);
+    }
+    return null;
+  }
+  /** Attach the flat fields (slot, fee, CU, status) from a tx response to a span. */
+  attachTxDetailsToSpan(span, txDetails) {
+    span.setAttribute("solana.tx.status", txDetails.meta?.err ? "failed" : "confirmed");
+    span.setAttribute("solana.tx.slot", txDetails.slot);
+    const fee = txDetails.meta?.fee;
+    if (fee !== void 0) span.setAttribute("solana.tx.fee_lamports", fee);
+    const cuUsed = txDetails.meta?.computeUnitsConsumed;
+    if (cuUsed !== void 0 && cuUsed !== null) {
+      span.setAttribute("solana.tx.cu_used", Number(cuUsed));
+      span.setAttribute("solana.tx.cu_budget", 2e5);
+      span.setAttribute(
+        "solana.tx.cu_utilization",
+        parseFloat((Number(cuUsed) / 2e5 * 100).toFixed(1))
+      );
+    }
+  }
+  /**
+   * Parse program logs into a CPI tree, enrich with registered IDLs, and
+   * emit one `cpi.invoke` event per invocation onto the span. Root
+   * program/instruction names are copied onto span attributes so dashboards
+   * can filter by them without walking events.
+   */
+  async attachParsedLogsToSpan(span, logs) {
+    const { cpiTree } = (0, import_core3.parseLogs)({ logs });
+    await (0, import_core3.enrichTree)(cpiTree, this.idlResolver);
+    const attributions = (0, import_core3.flatAttributions)(cpiTree);
+    for (const attr of attributions) {
+      span.addEvent("cpi.invoke", {
+        "cpi.program": attr.programName ?? attr.programId,
+        "cpi.instruction": attr.instructionName ?? "unknown",
+        "cpi.depth": attr.depth,
+        "cpi.cu_consumed": attr.cuConsumed,
+        "cpi.cu_self": attr.cuSelf,
+        "cpi.percentage": parseFloat(attr.percentage.toFixed(2))
+      });
+    }
+    const root = cpiTree.roots[0];
+    if (root) {
+      if (root.programName) span.setAttribute("solana.tx.program", root.programName);
+      if (root.instructionName) span.setAttribute("solana.tx.instruction", root.instructionName);
+    }
+    return cpiTree;
+  }
 };
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   IdlResolver,
   InstrumentedConnection,
   SightSpanExporter,
-  initSight
+  initSight,
+  trackSolanaTransaction
 });
 //# sourceMappingURL=index.cjs.map