@thesight/sdk 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Connection, ConnectionConfig, Commitment, Transaction, VersionedTransaction, SendOptions } from '@solana/web3.js';
+import { TransactionSignature, Connection, Finality, ConnectionConfig, Commitment, SendOptions } from '@solana/web3.js';
 import { Tracer } from '@opentelemetry/api';
-import { AnchorIdl, CpiTree, DecodedError } from '@thesight/core';
+import { IdlResolver, AnchorIdl } from '@thesight/core';
 export { AnchorIdl, CpiTree, CuAttribution, DecodedError, FlamegraphItem, IdlResolver } from '@thesight/core';
 import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
@@ -108,14 +108,92 @@ declare class SightSpanExporter implements SpanExporter {
     private convertSpan;
 }
 
+interface TrackTransactionOptions {
+    /** The signature returned from a prior `sendRawTransaction` / `sendTransaction` call. */
+    signature: TransactionSignature;
+    /**
+     * Any `@solana/web3.js` Connection — plain or instrumented. Used to fetch
+     * the on-chain transaction via `getTransaction` for enrichment. Does
+     * **not** need to be an `InstrumentedConnection`; this helper intentionally
+     * never touches the transaction-send path.
+     */
+    connection: Connection;
+    /**
+     * Service name used for the span. Falls back to the service name
+     * configured by `initSight`. Useful when you want a different service
+     * name for a specific subsystem's spans.
+     */
+    serviceName?: string;
+    /** OTel tracer override. Defaults to `trace.getTracer('@thesight/sdk')`. */
+    tracer?: Tracer;
+    /** Optional IDL resolver for program/error decoding. A fresh one is built if omitted. */
+    idlResolver?: IdlResolver;
+    /**
+     * Pre-registered IDLs to hand to a freshly-built resolver. Ignored when
+     * `idlResolver` is provided.
+     */
+    idls?: Record<string, AnchorIdl>;
+    /** Finality commitment used for the enrichment fetch. Default 'confirmed'. */
+    commitment?: Finality;
+    /** Max wall-time before the span is ended with status=timeout. Default 30000ms. */
+    timeoutMs?: number;
+    /** Base poll interval for retrying getTransaction. Default 500ms. */
+    pollIntervalMs?: number;
+}
+/**
+ * **Non-wrapping observation helper.** Given a transaction signature that
+ * was already sent through any `Connection`, fetch the on-chain record,
+ * parse the logs, and emit a single OpenTelemetry span describing the
+ * transaction.
+ *
+ * Unlike `InstrumentedConnection`, this helper **never touches the send
+ * path** — it only observes after the fact via `getTransaction(signature)`.
+ * Use this when:
+ *
+ * - You want observability for wallet-adapter flows where the send path
+ *   goes through the wallet and you can't easily override the Connection
+ * - You're security-conscious and don't want any SDK code on the critical
+ *   transaction path
+ * - You want to instrument a handful of high-value transactions rather
+ *   than every call a Connection makes
+ *
+ * Usage:
+ *
+ *     import { trackSolanaTransaction } from '@thesight/sdk';
+ *     import { Connection } from '@solana/web3.js';
+ *
+ *     const connection = new Connection(rpcUrl);
+ *     const signature  = await wallet.sendTransaction(tx, connection);
+ *
+ *     // Fire-and-forget. Span flushes on its own.
+ *     void trackSolanaTransaction({
+ *       signature,
+ *       connection,
+ *       serviceName: 'checkout',
+ *       idls: { [programId]: idl },
+ *     });
+ *
+ * Returns a `Promise<void>` — typically not awaited, but callers who want
+ * to wait for the span to export (e.g. short-lived scripts) can await it.
+ */
+declare function trackSolanaTransaction(opts: TrackTransactionOptions): Promise<void>;
+
 interface SightConfig {
-    /** OTel tracer. Get via trace.getTracer('your-service') */
+    /** OTel tracer. Defaults to `trace.getTracer('@thesight/sdk')`. */
     tracer?: Tracer;
     /** Override RPC endpoint for IDL fetching (defaults to same as connection) */
     idlRpcEndpoint?: string;
-    /** Commitment to use when fetching confirmed tx details */
+    /**
+     * Commitment used when fetching confirmed tx details for enrichment.
+     * Defaults to 'confirmed'.
+     */
     commitment?: Commitment;
-    /** Skip IDL resolution (faster, no program names or error decoding) */
+    /**
+     * Skip IDL resolution entirely. Spans will still emit with signature and
+     * timing attributes, but program names, instruction names, CPI trees, and
+     * decoded errors will all be omitted. Useful when you want minimal
+     * overhead and don't care about the richer observability.
+     */
     skipIdlResolution?: boolean;
     /**
      * Pre-register IDLs at construction time. Keys are program IDs, values are
@@ -126,18 +204,35 @@ interface SightConfig {
     /**
      * Opt into reading Anchor IDL accounts from the on-chain PDA as a fallback
      * when a program is not explicitly registered. Defaults to **false** —
-     * Sight's model is that IDLs are explicitly provided by the application
-     * (via this option or `registerIdl`), not silently guessed from chain.
+     * Sight's model is that IDLs are explicitly provided by the application,
+     * not silently guessed from chain.
      */
     allowOnChainIdlFetch?: boolean;
+    /**
+     * Max wall-time the background enrichment task will wait for a
+     * transaction to show up in `getTransaction`. After this expires the
+     * span is ended with `solana.tx.status = 'timeout'`. Default 30000 (30s).
+     */
+    enrichmentTimeoutMs?: number;
+    /**
+     * How often the enrichment task polls `getTransaction`. Each retry backs
+     * off by 1.5x up to a cap. Default 500ms base.
+     */
+    enrichmentPollIntervalMs?: number;
+    /**
+     * Disable automatic span creation in the overridden `sendRawTransaction`.
+     * When true, InstrumentedConnection behaves like a plain Connection. You
+     * probably don't want this — it's here as an escape hatch for tests and
+     * rare cases where you need the class hierarchy but not the tracing.
+     */
+    disableAutoSpan?: boolean;
 }
 interface SightSpanAttributes {
     'solana.tx.signature': string;
-    'solana.tx.status': 'confirmed' | 'failed' | 'timeout';
+    'solana.tx.status': 'submitted' | 'confirmed' | 'failed' | 'timeout';
     'solana.tx.slot'?: number;
     'solana.tx.fee_lamports'?: number;
     'solana.tx.submit_ms': number;
-    'solana.tx.confirmation_ms'?: number;
     'solana.tx.enrichment_ms'?: number;
     'solana.tx.cu_used'?: number;
     'solana.tx.cu_budget'?: number;
@@ -150,17 +245,41 @@ interface SightSpanAttributes {
     'solana.tx.error_msg'?: string;
 }
 /**
- * Drop-in replacement for @solana/web3.js Connection that instruments
- * every transaction with OpenTelemetry spans.
+ * Drop-in replacement for `@solana/web3.js`'s `Connection` that emits an
+ * OpenTelemetry span for **every** call to `sendRawTransaction` —
+ * regardless of whether the caller is your own code, an Anchor provider's
+ * `sendAndConfirm`, `@solana/web3.js`'s top-level `sendAndConfirmTransaction`,
+ * a wallet adapter, or anything else.
+ *
+ * Internally it overrides the parent class's `sendRawTransaction`, so the
+ * span covers the same surface web3.js already mediates. No mutation of
+ * the transaction bytes — we call `super.sendRawTransaction(rawTx, opts)`
+ * verbatim and observe the signature it returns.
+ *
+ * After the signature is returned (synchronously from the caller's point
+ * of view), a background task polls `getTransaction` until the on-chain
+ * record is available, parses the program logs via `@thesight/core`, and
+ * enriches the span with CU attribution, per-CPI events, program + instruction
+ * names, and decoded error details. The background task never blocks the
+ * caller — if it fails or times out, the span ends with status=timeout and
+ * whatever partial data was collected.
  *
  * Usage:
- *   const connection = new InstrumentedConnection(rpcUrl, {
- *     tracer: trace.getTracer('my-service'),
- *   });
  *
- * The Solana transaction becomes a child span of whatever OTel context
- * is active when sendAndConfirmTransaction is called — so it automatically
- * nests inside your HTTP handler or background job span.
+ *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
+ *
+ *     initSight({ apiKey, serviceName: 'swap-bot' });
+ *
+ *     // Anywhere you currently construct a Connection, construct this instead:
+ *     const connection = new InstrumentedConnection(rpcUrl, {
+ *       commitment: 'confirmed',
+ *     });
+ *
+ *     // All of the following now emit spans automatically:
+ *     await connection.sendRawTransaction(tx.serialize());
+ *     await sendAndConfirmTransaction(connection, tx, signers); // web3.js
+ *     await program.methods.foo().rpc();                        // Anchor
+ *     await wallet.sendTransaction(tx, connection);             // wallet adapter
  */
 declare class InstrumentedConnection extends Connection {
     private sightConfig;
@@ -179,16 +298,41 @@ declare class InstrumentedConnection extends Connection {
     /** Bulk-register multiple IDLs. */
     registerIdls(idls: Record<string, AnchorIdl>): void;
     /**
-     * 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.
+     */
+    sendRawTransaction(rawTransaction: Buffer | Uint8Array | Array<number>, options?: SendOptions): Promise<TransactionSignature>;
+    /**
+     * 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.
+     */
+    private enrichSpanInBackground;
+    /**
+     * 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.
+     */
+    private pollForTransaction;
+    /** Attach the flat fields (slot, fee, CU, status) from a tx response to a span. */
+    private attachTxDetailsToSpan;
+    /**
+     * 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.
      */
-    sendAndConfirmInstrumented(transaction: Transaction | VersionedTransaction, options?: SendOptions & {
-        commitment?: Commitment;
-    }): Promise<{
-        signature: string;
-        cpiTree?: CpiTree;
-        error?: DecodedError;
-    }>;
+    private attachParsedLogsToSpan;
 }
 
-export { type InitSightConfig, InstrumentedConnection, type SightConfig, type SightExporterConfig, type SightSpanAttributes, SightSpanExporter, type SightTracerHandle, initSight };
+export { type InitSightConfig, InstrumentedConnection, type SightConfig, type SightExporterConfig, type SightSpanAttributes, SightSpanExporter, type SightTracerHandle, type TrackTransactionOptions, initSight, trackSolanaTransaction };

package/dist/index.js

@@ -2,9 +2,13 @@
 import {
   Connection
 } from "@solana/web3.js";
-import { trace, context, SpanStatusCode } from "@opentelemetry/api";
-import { parseLogs, IdlResolver, enrichTree, flatAttributions } from "@thesight/core";
-import { IdlResolver as IdlResolver2 } from "@thesight/core";
+import {
+  trace as trace2,
+  context as context2,
+  SpanStatusCode as SpanStatusCode2
+} from "@opentelemetry/api";
+import { parseLogs as parseLogs2, IdlResolver as IdlResolver2, enrichTree as enrichTree2, flatAttributions as flatAttributions2 } from "@thesight/core";
+import { IdlResolver as IdlResolver3 } from "@thesight/core";
 
 // src/init.ts
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
@@ -175,6 +179,98 @@ function initSight(config) {
   };
 }
 
+// src/track.ts
+import { trace, context, SpanStatusCode } from "@opentelemetry/api";
+import { parseLogs, IdlResolver, enrichTree, flatAttributions } from "@thesight/core";
+async function trackSolanaTransaction(opts) {
+  const tracerName = opts.serviceName ?? "@thesight/sdk";
+  const tracer = opts.tracer ?? trace.getTracer(tracerName);
+  const span = tracer.startSpan("solana.trackTransaction", {}, 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 } = parseLogs({ logs });
+      await enrichTree(cpiTree, resolver);
+      for (const attr of 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: SpanStatusCode.ERROR });
+    } else {
+      span.setStatus({ code: SpanStatusCode.OK });
+    }
+  } catch (err) {
+    span.recordException(err instanceof Error ? err : new Error(String(err)));
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: err instanceof Error ? err.message : String(err)
+    });
+  } finally {
+    span.end();
+  }
+}
+function buildResolverFromIdls(idls) {
+  const resolver = new 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 Connection {
   sightConfig;
@@ -187,16 +283,29 @@ var InstrumentedConnection = class extends Connection {
       skipIdlResolution,
       idls,
       allowOnChainIdlFetch,
+      enrichmentTimeoutMs,
+      enrichmentPollIntervalMs,
+      disableAutoSpan,
+      commitment,
       ...connectionConfig
     } = config ?? {};
     super(endpoint, connectionConfig);
-    this.sightConfig = { tracer, idlRpcEndpoint, skipIdlResolution, allowOnChainIdlFetch };
-    this.idlResolver = new IdlResolver({
+    this.sightConfig = {
+      tracer,
+      idlRpcEndpoint,
+      skipIdlResolution,
+      allowOnChainIdlFetch,
+      enrichmentTimeoutMs: enrichmentTimeoutMs ?? 3e4,
+      enrichmentPollIntervalMs: enrichmentPollIntervalMs ?? 500,
+      disableAutoSpan,
+      commitment
+    };
+    this.idlResolver = new IdlResolver2({
       rpcEndpoint: idlRpcEndpoint ?? endpoint,
       allowOnChainFetch: allowOnChainIdlFetch ?? false
     });
     if (idls) this.idlResolver.registerMany(idls);
-    this.tracer = tracer ?? trace.getTracer("@thesight/sdk");
+    this.tracer = tracer ?? trace2.getTracer("@thesight/sdk");
   }
   /**
    * Register an IDL for a single program. Convenience forwarder for the
@@ -213,131 +322,164 @@ var InstrumentedConnection = class extends 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", {}, context.active());
+  async sendRawTransaction(rawTransaction, options) {
+    if (this.sightConfig.disableAutoSpan) {
+      return super.sendRawTransaction(rawTransaction, options);
+    }
+    const span = this.tracer.startSpan("solana.sendRawTransaction", {}, context2.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: 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: SpanStatusCode2.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 } = parseLogs({ logs });
-          if (!this.sightConfig.skipIdlResolution) {
-            await enrichTree(cpiTree, this.idlResolver);
-          }
-          const attributions = 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: SpanStatusCode.OK });
-          span.end();
-          return { signature, cpiTree };
+        const logs = txDetails.meta?.logMessages ?? [];
+        if (logs.length > 0) {
+          await this.attachParsedLogsToSpan(span, logs);
         }
       }
-      span.setStatus({ code: SpanStatusCode.OK });
-      span.end();
-      return { signature };
+      span.setAttribute("solana.tx.enrichment_ms", Date.now() - submitStart);
+      if (txDetails.meta?.err) {
+        span.setStatus({ code: SpanStatusCode2.ERROR });
+      } else {
+        span.setStatus({ code: SpanStatusCode2.OK });
+      }
     } catch (err) {
-      span.setAttribute("solana.tx.status", "failed");
-      span.setAttribute("solana.tx.submit_ms", Date.now() - submitStart);
-      span.setStatus({
-        code: 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 } = parseLogs2({ logs });
+    await enrichTree2(cpiTree, this.idlResolver);
+    const attributions = flatAttributions2(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));
+}
 export {
-  IdlResolver2 as IdlResolver,
+  IdlResolver3 as IdlResolver,
   InstrumentedConnection,
   SightSpanExporter,
-  initSight
+  initSight,
+  trackSolanaTransaction
 };
 //# sourceMappingURL=index.js.map