@thesight/sdk 0.1.1 → 0.3.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`.