@thesight/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rick Dsida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @thesight/sdk
+
+**See the truth of your Solana program.**
+
+[Sight](https://thesight.dev) is the first OpenTelemetry-native
+observability SDK for Solana. One package install, one `initSight()`
+call, and every transaction becomes a span with per-CPI compute-unit
+attribution, decoded Anchor errors, and full wallet↔RPC↔program
+correlation — consumable by the Sight dashboard or any APM backend
+(Datadog, Grafana, Honeycomb, Tempo).
+
+## Install
+
+```bash
+pnpm add @thesight/sdk
+```
+
+All OpenTelemetry dependencies are bundled transitively — you do **not**
+need to `pnpm add @opentelemetry/*` separately.
+
+## Quickstart
+
+```ts
+import { initSight, InstrumentedConnection } from '@thesight/sdk';
+import { clusterApiUrl } from '@solana/web3.js';
+
+// Call once near the top of your process entry point
+initSight({
+  apiKey:      process.env.SIGHT_API_KEY!,
+  serviceName: 'my-service',
+});
+
+// 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);
+```
+
+`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.
+
+## Anchor IDL registration
+
+Sight never guesses program names from chain. Tell it what you know:
+
+```ts
+import { Program } from '@coral-xyz/anchor';
+
+const program = new Program(idl, programId, provider);
+connection.registerIdl(program.programId.toBase58(), program.idl);
+```
+
+Or pass a map at init:
+
+```ts
+const connection = new InstrumentedConnection(rpcUrl, {
+  idls: {
+    [swapProgramId]: swapIdl,
+    [lendingProgramId]: lendingIdl,
+  },
+});
+```
+
+Unknown programs surface as short-ids in the dashboard rather than
+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:
+
+```ts
+initSight({
+  apiKey:      'sk_live_...',
+  serviceName: 'my-service',
+  ingestUrl:   'http://localhost:3001/ingest', // local compose stack
+});
+```
+
+## What's on the span
+
+Every `sendAndConfirmInstrumented` call 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.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)
+- `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
+
+## Shutdown
+
+Call `shutdown()` on the handle returned by `initSight` at graceful
+shutdown time so pending spans flush before the process exits:
+
+```ts
+const sight = initSight({ apiKey, serviceName });
+
+process.on('SIGTERM', async () => {
+  await sight.shutdown();
+  process.exit(0);
+});
+```
+
+## License
+
+MIT — see `LICENSE`.

package/dist/exporter.d.ts

@@ -0,0 +1,43 @@
+import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { type ExportResult } from '@opentelemetry/core';
+export interface SightExporterConfig {
+    /** Project API key (`sk_live_...`). Sent as Bearer auth on every POST. */
+    apiKey: string;
+    /**
+     * Full ingest URL including the path (e.g. `https://ingest.thesight.dev/ingest`
+     * or `http://localhost:3001/ingest` for local dev).
+     */
+    ingestUrl: string;
+    /** Inject a fake fetch in tests. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Max spans per POST. Ingest enforces an upper bound of 100. */
+    maxBatchSize?: number;
+}
+/**
+ * An OTel `SpanExporter` that translates OTel spans to Sight's custom
+ * ingest payload shape and POSTs them to `/ingest`.
+ *
+ * Each span becomes one object in the `spans` array. Solana-specific
+ * attributes flow through as-is (the set that `InstrumentedConnection`
+ * already populates — `solana.tx.signature`, `solana.tx.cu_used`,
+ * `solana.tx.program`, etc). The exporter intentionally does not attempt
+ * to translate span events or links — the ingest schema doesn't have
+ * slots for those, and we prefer dropping silently over guessing.
+ *
+ * The BatchSpanProcessor upstream handles retries, timeouts, and batching;
+ * this exporter stays a thin wire-format translator.
+ */
+export declare class SightSpanExporter implements SpanExporter {
+    private readonly apiKey;
+    private readonly ingestUrl;
+    private readonly fetchImpl;
+    private readonly maxBatchSize;
+    private shuttingDown;
+    constructor(config: SightExporterConfig);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): Promise<void>;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private sendChunk;
+    private convertSpan;
+}
+//# sourceMappingURL=exporter.d.ts.map

package/dist/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAI7B,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,mBAAmB;IAiBjC,MAAM,CACV,KAAK,EAAW,YAAY,EAAE,EAC9B,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAC7C,OAAO,CAAC,IAAI,CAAC;IA2BV,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAOnB,SAAS;IAsBvB,OAAO,CAAC,WAAW;CAuCpB"}

package/dist/exporter.js

@@ -0,0 +1,151 @@
+import { hrTimeToMilliseconds, ExportResultCode, } from '@opentelemetry/core';
+// ─── Exporter ────────────────────────────────────────────────────────────────
+/**
+ * An OTel `SpanExporter` that translates OTel spans to Sight's custom
+ * ingest payload shape and POSTs them to `/ingest`.
+ *
+ * Each span becomes one object in the `spans` array. Solana-specific
+ * attributes flow through as-is (the set that `InstrumentedConnection`
+ * already populates — `solana.tx.signature`, `solana.tx.cu_used`,
+ * `solana.tx.program`, etc). The exporter intentionally does not attempt
+ * to translate span events or links — the ingest schema doesn't have
+ * slots for those, and we prefer dropping silently over guessing.
+ *
+ * The BatchSpanProcessor upstream handles retries, timeouts, and batching;
+ * this exporter stays a thin wire-format translator.
+ */
+export class SightSpanExporter {
+    apiKey;
+    ingestUrl;
+    fetchImpl;
+    maxBatchSize;
+    shuttingDown = false;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.ingestUrl = config.ingestUrl;
+        this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
+        // Ingest's IngestPayload schema caps at 100 spans per POST. Allow
+        // operators to lower the batch size for tighter latency, but never
+        // raise it above the server's limit.
+        this.maxBatchSize = Math.min(100, config.maxBatchSize ?? 100);
+        if (!this.fetchImpl) {
+            throw new Error('SightSpanExporter: globalThis.fetch is not available. Node >= 18 ships ' +
+                'with fetch built in, or pass `fetchImpl` explicitly.');
+        }
+    }
+    async export(spans, resultCallback) {
+        if (this.shuttingDown) {
+            resultCallback({ code: ExportResultCode.FAILED, error: new Error('Exporter is shut down') });
+            return;
+        }
+        // Split into chunks if the upstream processor handed us a larger
+        // batch than ingest will accept. Uncommon with a well-configured
+        // BatchSpanProcessor but cheap to handle defensively.
+        const chunks = [];
+        for (let i = 0; i < spans.length; i += this.maxBatchSize) {
+            chunks.push(spans.slice(i, i + this.maxBatchSize));
+        }
+        try {
+            for (const chunk of chunks) {
+                await this.sendChunk(chunk);
+            }
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        }
+        catch (err) {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    }
+    async shutdown() {
+        this.shuttingDown = true;
+    }
+    async forceFlush() {
+        // The exporter is stateless — BatchSpanProcessor's own forceFlush
+        // drains the queue before calling export(). Nothing to do here.
+    }
+    // ─── Internal ──────────────────────────────────────────────────────────────
+    async sendChunk(spans) {
+        const payload = {
+            spans: spans.map((span) => this.convertSpan(span)),
+        };
+        const response = await this.fetchImpl(this.ingestUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const body = await safeReadText(response);
+            throw new Error(`Sight ingest returned ${response.status} ${response.statusText}: ${body}`);
+        }
+    }
+    convertSpan(span) {
+        const attr = span.attributes;
+        const resource = span.resource.attributes;
+        const serviceName = typeof resource['service.name'] === 'string'
+            ? resource['service.name']
+            : undefined;
+        const startTimeMs = hrTimeToMilliseconds(span.startTime);
+        const endTimeMs = hrTimeToMilliseconds(span.endTime);
+        const durationMs = Math.max(0, endTimeMs - startTimeMs);
+        const out = {
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            spanName: span.name,
+            startTimeMs,
+            durationMs,
+        };
+        const parentSpanId = span.parentSpanId;
+        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']);
+        copyIfNumber(attr, 'solana.tx.slot', out);
+        copyIfNumber(attr, 'solana.tx.cu_used', out);
+        copyIfNumber(attr, 'solana.tx.cu_budget', out);
+        copyIfNumber(attr, 'solana.tx.cu_utilization', out);
+        copyIfString(attr, 'solana.tx.program', out);
+        copyIfString(attr, 'solana.tx.instruction', out);
+        copyIfString(attr, 'solana.tx.error', out);
+        copyIfNumber(attr, 'solana.tx.error_code', out);
+        copyIfString(attr, 'solana.tx.error_program', out);
+        copyIfNumber(attr, 'solana.tx.submit_ms', out);
+        copyIfNumber(attr, 'solana.tx.confirmation_ms', out);
+        copyIfNumber(attr, 'solana.tx.fee_lamports', out);
+        return out;
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function copyIfString(attr, key, out) {
+    const v = attr[key];
+    if (typeof v === 'string') {
+        out[key] = v;
+    }
+}
+function copyIfNumber(attr, key, out) {
+    const v = attr[key];
+    if (typeof v === 'number' && Number.isFinite(v)) {
+        out[key] = v;
+    }
+}
+function copyIfEnum(attr, key, out, allowed) {
+    const v = attr[key];
+    if (typeof v === 'string' && allowed.includes(v)) {
+        out[key] = v;
+    }
+}
+async function safeReadText(res) {
+    try {
+        return (await res.text()).slice(0, 500);
+    }
+    catch {
+        return '<no body>';
+    }
+}
+//# sourceMappingURL=exporter.js.map

package/dist/exporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.js","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { Connection, type ConnectionConfig, type Transaction, type VersionedTransaction, type SendOptions, type Commitment } from '@solana/web3.js';
+import { type Tracer } from '@opentelemetry/api';
+import type { AnchorIdl, DecodedError, CpiTree } from '@thesight/core';
+export interface SightConfig {
+    /** OTel tracer. Get via trace.getTracer('your-service') */
+    tracer?: Tracer;
+    /** Override RPC endpoint for IDL fetching (defaults to same as connection) */
+    idlRpcEndpoint?: string;
+    /** Commitment to use when fetching confirmed tx details */
+    commitment?: Commitment;
+    /** Skip IDL resolution (faster, no program names or error decoding) */
+    skipIdlResolution?: boolean;
+    /**
+     * Pre-register IDLs at construction time. Keys are program IDs, values are
+     * full Anchor IDL objects. Anchor users can pass `program.idl` directly off
+     * their `Program` instance — zero setup friction.
+     */
+    idls?: Record<string, AnchorIdl>;
+    /**
+     * 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.
+     */
+    allowOnChainIdlFetch?: boolean;
+}
+export interface SightSpanAttributes {
+    'solana.tx.signature': string;
+    'solana.tx.status': '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;
+    'solana.tx.cu_utilization'?: number;
+    'solana.tx.program'?: string;
+    'solana.tx.instruction'?: string;
+    'solana.tx.error'?: string;
+    'solana.tx.error_code'?: number;
+    'solana.tx.error_program'?: string;
+    'solana.tx.error_msg'?: string;
+}
+/**
+ * Drop-in replacement for @solana/web3.js Connection that instruments
+ * every transaction with OpenTelemetry spans.
+ *
+ * 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.
+ */
+export declare class InstrumentedConnection extends Connection {
+    private sightConfig;
+    private idlResolver;
+    private tracer;
+    constructor(endpoint: string, config?: ConnectionConfig & SightConfig);
+    /**
+     * Register an IDL for a single program. Convenience forwarder for the
+     * underlying resolver. Anchor users typically call this right after
+     * constructing a `Program`:
+     *
+     *     const program = new Program(idl, programId, provider);
+     *     connection.registerIdl(program.programId.toBase58(), program.idl);
+     */
+    registerIdl(programId: string, idl: AnchorIdl): void;
+    /** 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.
+     */
+    sendAndConfirmInstrumented(transaction: Transaction | VersionedTransaction, options?: SendOptions & {
+        commitment?: Commitment;
+    }): Promise<{
+        signature: string;
+        cpiTree?: CpiTree;
+        error?: DecodedError;
+    }>;
+}
+export { IdlResolver } from '@thesight/core';
+export type { CpiTree, CuAttribution, FlamegraphItem, DecodedError, AnchorIdl } from '@thesight/core';
+export { initSight } from './init.js';
+export type { InitSightConfig, SightTracerHandle } from './init.js';
+export { SightSpanExporter } from './exporter.js';
+export type { SightExporterConfig } from './exporter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,175 @@
+import { Connection, } from '@solana/web3.js';
+import { trace, context, SpanStatusCode } from '@opentelemetry/api';
+import { parseLogs, IdlResolver, enrichTree, flatAttributions } from '@thesight/core';
+/**
+ * Drop-in replacement for @solana/web3.js Connection that instruments
+ * every transaction with OpenTelemetry spans.
+ *
+ * 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.
+ */
+export class InstrumentedConnection extends Connection {
+    sightConfig;
+    idlResolver;
+    tracer;
+    constructor(endpoint, config) {
+        const { tracer, idlRpcEndpoint, skipIdlResolution, idls, allowOnChainIdlFetch, ...connectionConfig } = config ?? {};
+        super(endpoint, connectionConfig);
+        this.sightConfig = { tracer, idlRpcEndpoint, skipIdlResolution, allowOnChainIdlFetch };
+        this.idlResolver = new IdlResolver({
+            rpcEndpoint: idlRpcEndpoint ?? endpoint,
+            allowOnChainFetch: allowOnChainIdlFetch ?? false,
+        });
+        if (idls)
+            this.idlResolver.registerMany(idls);
+        this.tracer = tracer ?? trace.getTracer('@thesight/sdk');
+    }
+    /**
+     * Register an IDL for a single program. Convenience forwarder for the
+     * underlying resolver. Anchor users typically call this right after
+     * constructing a `Program`:
+     *
+     *     const program = new Program(idl, programId, provider);
+     *     connection.registerIdl(program.programId.toBase58(), program.idl);
+     */
+    registerIdl(programId, idl) {
+        this.idlResolver.register(programId, idl);
+    }
+    /** Bulk-register multiple IDLs. */
+    registerIdls(idls) {
+        this.idlResolver.registerMany(idls);
+    }
+    /**
+     * Sends and confirms a transaction, wrapped in an OTel span.
+     * The span is a child of the current active context.
+     */
+    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());
+        const submitStart = Date.now();
+        try {
+            // Submit the transaction
+            const signature = await this.sendRawTransaction('serialize' in transaction
+                ? transaction.serialize()
+                : transaction.serialize(), { skipPreflight: false, ...options });
+            span.setAttribute('solana.tx.signature', signature);
+            const submitMs = Date.now() - submitStart;
+            span.setAttribute('solana.tx.submit_ms', submitMs);
+            // Await confirmation
+            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) {
+                    // Enrich error with IDL decoding
+                    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 !== undefined) {
+                        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.end();
+                return { signature };
+            }
+            span.setAttribute('solana.tx.status', 'confirmed');
+            // Enrich with on-chain details
+            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 !== undefined)
+                        span.setAttribute('solana.tx.fee_lamports', fee);
+                    if (cuUsed !== undefined) {
+                        span.setAttribute('solana.tx.cu_used', cuUsed);
+                        span.setAttribute('solana.tx.cu_budget', 200_000);
+                        span.setAttribute('solana.tx.cu_utilization', parseFloat((cuUsed / 200_000 * 100).toFixed(1)));
+                    }
+                    // Parse logs into CPI tree
+                    const { cpiTree } = parseLogs({ logs });
+                    if (!this.sightConfig.skipIdlResolution) {
+                        await enrichTree(cpiTree, this.idlResolver);
+                    }
+                    // Emit one span event per CPI invocation
+                    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)),
+                        });
+                    }
+                    // Top-level instruction info
+                    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 };
+                }
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            return { signature };
+        }
+        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.end();
+            throw err;
+        }
+    }
+}
+export { IdlResolver } from '@thesight/core';
+// ─── Tracing initialization ──────────────────────────────────────────────────
+// One-call setup that wires a NodeTracerProvider + SightSpanExporter as the
+// global OTel tracer. After calling initSight, every InstrumentedConnection
+// span routes to Sight ingest automatically — no separate OTel setup needed.
+export { initSight } from './init.js';
+export { SightSpanExporter } from './exporter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/init.d.ts

@@ -0,0 +1,62 @@
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+export interface InitSightConfig {
+    /** Project API key (`sk_live_...`) from the Sight dashboard. */
+    apiKey: string;
+    /**
+     * Human-readable service name that shows up on every span. Pick something
+     * that identifies this process — `'swap-bot'`, `'market-maker'`,
+     * `'trade-settler'`, etc.
+     */
+    serviceName: string;
+    /** Optional version string for the service. Useful for correlating spans with a deploy. */
+    serviceVersion?: string;
+    /**
+     * Full ingest URL. Defaults to the hosted Sight ingest. Override for
+     * local development (e.g. `http://localhost:3001/ingest`) or self-hosted
+     * deployments.
+     */
+    ingestUrl?: string;
+    /** BatchSpanProcessor flush interval, in ms. Defaults to 5s. */
+    batchDelayMs?: number;
+    /** Max spans per HTTP POST. Clamped to 100 by the exporter. */
+    maxBatchSize?: number;
+    /** Inject a fetch implementation for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface SightTracerHandle {
+    provider: NodeTracerProvider;
+    /** Flush any pending spans and release the batch processor. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize Sight tracing. Call this **once** near the top of your
+ * process entry point — typically in the same file that boots your
+ * HTTP server or worker.
+ *
+ *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
+ *
+ *     initSight({
+ *       apiKey:      process.env.SIGHT_API_KEY!,
+ *       serviceName: 'swap-bot',
+ *       ingestUrl:   process.env.SIGHT_INGEST_URL, // optional, defaults to prod
+ *     });
+ *
+ *     const connection = new InstrumentedConnection(process.env.RPC_URL!);
+ *     const { signature } = await connection.sendAndConfirmInstrumented(tx);
+ *
+ * Registers a NodeTracerProvider as the global OTel tracer, so any call to
+ * `trace.getTracer(...)` (including the ones inside `InstrumentedConnection`)
+ * routes spans through the Sight exporter. Context propagation uses the
+ * Node async hooks manager so spans nest correctly across await boundaries.
+ *
+ * Returns a handle with a `shutdown()` method. Call it at graceful shutdown
+ * time so pending spans are flushed before the process exits:
+ *
+ *     const sight = initSight({ ... });
+ *     process.on('SIGTERM', async () => {
+ *       await sight.shutdown();
+ *       process.exit(0);
+ *     });
+ */
+export declare function initSight(config: InitSightConfig): SightTracerHandle;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAQnE,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CA8CpE"}

package/dist/init.js

@@ -0,0 +1,78 @@
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { Resource } from '@opentelemetry/resources';
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { SightSpanExporter } from './exporter.js';
+// ─── Entry point ────────────────────────────────────────────────────────────
+const DEFAULT_INGEST_URL = 'https://ingest.thesight.dev/ingest';
+/**
+ * Initialize Sight tracing. Call this **once** near the top of your
+ * process entry point — typically in the same file that boots your
+ * HTTP server or worker.
+ *
+ *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
+ *
+ *     initSight({
+ *       apiKey:      process.env.SIGHT_API_KEY!,
+ *       serviceName: 'swap-bot',
+ *       ingestUrl:   process.env.SIGHT_INGEST_URL, // optional, defaults to prod
+ *     });
+ *
+ *     const connection = new InstrumentedConnection(process.env.RPC_URL!);
+ *     const { signature } = await connection.sendAndConfirmInstrumented(tx);
+ *
+ * Registers a NodeTracerProvider as the global OTel tracer, so any call to
+ * `trace.getTracer(...)` (including the ones inside `InstrumentedConnection`)
+ * routes spans through the Sight exporter. Context propagation uses the
+ * Node async hooks manager so spans nest correctly across await boundaries.
+ *
+ * Returns a handle with a `shutdown()` method. Call it at graceful shutdown
+ * time so pending spans are flushed before the process exits:
+ *
+ *     const sight = initSight({ ... });
+ *     process.on('SIGTERM', async () => {
+ *       await sight.shutdown();
+ *       process.exit(0);
+ *     });
+ */
+export function initSight(config) {
+    if (!config.apiKey) {
+        throw new Error('initSight: `apiKey` is required');
+    }
+    if (!config.serviceName) {
+        throw new Error('initSight: `serviceName` is required');
+    }
+    const resource = new Resource({
+        [SEMRESATTRS_SERVICE_NAME]: config.serviceName,
+        ...(config.serviceVersion
+            ? { [SEMRESATTRS_SERVICE_VERSION]: config.serviceVersion }
+            : {}),
+    });
+    const provider = new NodeTracerProvider({ resource });
+    const exporter = new SightSpanExporter({
+        apiKey: config.apiKey,
+        ingestUrl: config.ingestUrl ?? DEFAULT_INGEST_URL,
+        fetchImpl: config.fetchImpl,
+        maxBatchSize: config.maxBatchSize,
+    });
+    // BatchSpanProcessor buffers spans and flushes on an interval. This is the
+    // right default for production — simple span processor is one HTTP round
+    // trip per span, which is fine for tests and dev but nasty at scale.
+    const processor = new BatchSpanProcessor(exporter, {
+        scheduledDelayMillis: config.batchDelayMs ?? 5_000,
+        maxExportBatchSize: config.maxBatchSize ?? 100,
+        maxQueueSize: 2048,
+    });
+    provider.addSpanProcessor(processor);
+    // Register as the global OTel tracer provider. After this call,
+    // `trace.getTracer('anything')` returns a tracer from our provider,
+    // which routes spans to SightSpanExporter.
+    provider.register();
+    return {
+        provider,
+        shutdown: async () => {
+            await provider.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAC5G,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAyClD,+EAA+E;AAE/E,MAAM,kBAAkB,GAAG,oCAAoC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC;QAC5B,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC,WAAW;QAC9C,GAAG,CAAC,MAAM,CAAC,cAAc;YACvB,CAAC,CAAC,EAAE,CAAC,2BAA2B,CAAC,EAAE,MAAM,CAAC,cAAc,EAAE;YAC1D,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC;QACrC,MAAM,EAAQ,MAAM,CAAC,MAAM;QAC3B,SAAS,EAAK,MAAM,CAAC,SAAS,IAAI,kBAAkB;QACpD,SAAS,EAAK,MAAM,CAAC,SAAS;QAC9B,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,SAAS,GAAG,IAAI,kBAAkB,CAAC,QAAQ,EAAE;QACjD,oBAAoB,EAAE,MAAM,CAAC,YAAY,IAAI,KAAK;QAClD,kBAAkB,EAAI,MAAM,CAAC,YAAY,IAAI,GAAG;QAChD,YAAY,EAAU,IAAI;KAC3B,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAErC,gEAAgE;IAChE,oEAAoE;IACpE,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAEpB,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@thesight/sdk",
+  "version": "0.1.0",
+  "description": "Sight SDK — OpenTelemetry-native observability for Solana. One call (initSight) wires a NodeTracerProvider + Sight exporter, then InstrumentedConnection turns every transaction into a span with per-CPI compute-unit attribution, decoded Anchor errors, and wallet-to-program correlation.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Rick Dsida <rick@dsida.us>",
+  "license": "MIT",
+  "homepage": "https://thesight.dev",
+  "keywords": [
+    "solana",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "distributed-tracing",
+    "compute-units",
+    "cpi",
+    "anchor",
+    "apm",
+    "sight",
+    "thesight"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@thesight/core": "^0.1.0",
+    "@solana/web3.js": "^1.95.0",
+    "@opentelemetry/api": "^1.8.0",
+    "@opentelemetry/core": "^1.24.0",
+    "@opentelemetry/resources": "^1.24.0",
+    "@opentelemetry/sdk-trace-base": "^1.24.0",
+    "@opentelemetry/sdk-trace-node": "^1.24.0",
+    "@opentelemetry/semantic-conventions": "^1.24.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}