@thesight/sdk 0.1.1 → 0.3.0

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";
@@ -17,6 +21,38 @@ import {
   hrTimeToMilliseconds,
   ExportResultCode
 } from "@opentelemetry/core";
+
+// src/dsn.ts
+function parseDsn(dsn) {
+  let url;
+  try {
+    url = new URL(dsn);
+  } catch {
+    throw new Error(
+      `Invalid Sight DSN: "${dsn}". Expected format: https://<apiKey>@<host>/ingest \u2014 get your DSN from the Sight dashboard when you create a project.`
+    );
+  }
+  const apiKey = decodeURIComponent(url.username);
+  if (!apiKey) {
+    throw new Error(
+      `Invalid Sight DSN: no API key found in "${dsn}". The API key goes in the username position: https://sk_live_xxx@host/ingest`
+    );
+  }
+  url.username = "";
+  url.password = "";
+  const ingestUrl = url.toString().replace(/\/$/, "");
+  return { apiKey, ingestUrl };
+}
+function buildDsn(apiKey, ingestHost) {
+  const url = new URL(ingestHost);
+  url.username = apiKey;
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/ingest";
+  }
+  return url.toString();
+}
+
+// src/exporter.ts
 var SightSpanExporter = class {
   apiKey;
   ingestUrl;
@@ -24,8 +60,9 @@ var SightSpanExporter = class {
   maxBatchSize;
   shuttingDown = false;
   constructor(config) {
-    this.apiKey = config.apiKey;
-    this.ingestUrl = config.ingestUrl;
+    const parsed = parseDsn(config.dsn);
+    this.apiKey = parsed.apiKey;
+    this.ingestUrl = parsed.ingestUrl;
     this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
     this.maxBatchSize = Math.min(100, config.maxBatchSize ?? 100);
     if (!this.fetchImpl) {
@@ -98,7 +135,7 @@ var SightSpanExporter = class {
     if (parentSpanId) out.parentSpanId = parentSpanId;
     if (serviceName) out.serviceName = serviceName;
     copyIfString(attr, "solana.tx.signature", out);
-    copyIfEnum(attr, "solana.tx.status", out, ["confirmed", "failed", "timeout"]);
+    copyIfEnum(attr, "solana.tx.status", out, ["submitted", "confirmed", "failed", "timeout"]);
     copyIfNumber(attr, "solana.tx.slot", out);
     copyIfNumber(attr, "solana.tx.cu_used", out);
     copyIfNumber(attr, "solana.tx.cu_budget", out);
@@ -141,10 +178,11 @@ async function safeReadText(res) {
 }
 
 // src/init.ts
-var DEFAULT_INGEST_URL = "https://ingest.thesight.dev/ingest";
 function initSight(config) {
-  if (!config.apiKey) {
-    throw new Error("initSight: `apiKey` is required");
+  if (!config.dsn) {
+    throw new Error(
+      "initSight: `dsn` is required. Get your DSN from the Sight dashboard: https://thesight.dev"
+    );
   }
   if (!config.serviceName) {
     throw new Error("initSight: `serviceName` is required");
@@ -155,8 +193,7 @@ function initSight(config) {
   });
   const provider = new NodeTracerProvider({ resource });
   const exporter = new SightSpanExporter({
-    apiKey: config.apiKey,
-    ingestUrl: config.ingestUrl ?? DEFAULT_INGEST_URL,
+    dsn: config.dsn,
     fetchImpl: config.fetchImpl,
     maxBatchSize: config.maxBatchSize
   });
@@ -175,6 +212,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 +316,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 +355,166 @@ 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
+  buildDsn,
+  initSight,
+  parseDsn,
+  trackSolanaTransaction
 };
 //# sourceMappingURL=index.js.map