@secondlayer/sdk 6.37.1 → 6.39.0

package/dist/subgraphs/index.d.ts

@@ -316,6 +316,55 @@ interface TransactionProof {
 		reward_set: RewardSet
 	};
 }
+/**
+* A consumer sink: the destination adapter a consume loop writes through.
+*
+* Without a sink, the user owns the three hard parts of a durable indexer —
+* checkpoint persistence, rows+cursor atomicity, and reorg rollback — and
+* the reasoning that makes them safe lives in doc comments. A sink owns all
+* three: the loop loads its committed cursor, hands the handler a
+* transaction, commits rows AND cursor atomically, and rolls back reorgs
+* without any user code. Crucially, a sink also closes the silent-skip
+* hazard where omitting `onReorg` meant reorgs were ignored forever: with a
+* sink attached, rollback is unconditional.
+*
+* The interface is dependency-free on purpose: implementations with real
+* database drivers live behind subpath exports (`@secondlayer/sdk/sinks/*`)
+* so the root entry ships no DB dependency.
+*/
+interface ConsumerSink<Tx = unknown> {
+	/** Phantom marker carrying `Tx` in a directly-inferable position, so the
+	*  consume loops' `TTx` type parameter resolves from the `sink` option
+	*  (never set at runtime). */
+	readonly _tx?: Tx;
+	/** The committed checkpoint, or `null` on first run. Called once, before
+	*  the first page. Implementations may create their checkpoint storage
+	*  here and SHOULD validate their rollback preconditions (e.g. that every
+	*  declared table carries the height column). */
+	loadCursor(): Promise<string | null>;
+	/**
+	* Apply one batch atomically: open a transaction, run `write(tx)` (the
+	* user's inserts), and commit the rows AND `cursor` together. A throw
+	* from `write` must abort the whole transaction — leaving neither rows
+	* nor cursor, so a crashed batch is simply re-read on restart.
+	*/
+	commitBatch(cursor: string, write: (tx: Tx) => Promise<void> | void): Promise<void>;
+	/**
+	* Roll the projection back to the fork: delete everything AT OR ABOVE
+	* `forkPointHeight` (inclusive `>=` — the new chain re-supplies the fork
+	* block) and commit `rewindCursor` in the SAME transaction. Deleting
+	* without the rewound cursor is the classic silent-gap bug: a crash
+	* between the two writes resumes above the fork and the deleted range is
+	* never re-read.
+	*/
+	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+}
+/** `ctx` gains `tx` exactly when a sink is attached; without one the shape
+*  is unchanged (an intersection with `unknown` is an identity, so
+*  contextual typing of `onBatch` callbacks never degrades to a union). */
+type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
+	tx: TTx
+};
 import { StreamsEventType } from "@secondlayer/shared";
 /** A Clarity value as Streams serves it: the canonical hex string, a typed
 *  object carrying that hex (`{ hex }`), or a decoded Clarity-JSON object.
@@ -558,8 +607,28 @@ type StreamsBatchContext = ConsumerBatchContext;
 type StreamsReorgContext = {
 	cursor: string
 };
-type StreamsEventsConsumeParams = {
+type StreamsEventsConsumeParams<
+	TTx = never,
+	D extends boolean = false
+> = {
 	fromCursor?: string | null
+	/**
+	* Deliver events pre-decoded as the flat, `event_type`-discriminated rows
+	* Index serves (`IndexEvent`), so Streams consumption reads identically
+	* to Index consumption — no guard+decode pairs in your handler.
+	*/
+	decoded?: D
+	/**
+	* Destination adapter that owns the checkpoint + rollback transaction
+	* (e.g. `kyselySink` from `@secondlayer/sdk/sinks/kysely`). With a sink:
+	* the loop resumes from the sink's committed cursor, `onBatch` receives
+	* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
+	* transaction), reorg rollback is automatic, and `onBatch`'s return value
+	* is ignored.
+	*/
+	sink?: ConsumerSink<TTx>
+	/** Fires once per page, before `onBatch` and before any early return. */
+	onProgress?: (ctx: ConsumerBatchContext) => void
 	mode?: "tail" | "bounded"
 	/**
 	* Emit only finalized (immutable) events and never surface reorgs. The SDK
@@ -580,7 +649,7 @@ type StreamsEventsConsumeParams = {
 	* transaction as your writes. Returning a cursor overrides `ctx.cursor` as
 	* the resume point (advanced manual control); returning nothing uses it.
 	*/
-	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	onBatch: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
 	/**
 	* Roll your projection back to `reorg.fork_point_height`, persisting
 	* `ctx.cursor` in the same transaction. Called once per *new* reorg
@@ -737,7 +806,12 @@ type StreamsClient = {
 		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
 		* stops it.
 		*/
-		consume(params: StreamsEventsConsumeParams): Promise<StreamsEventsConsumeResult>
+		consume<
+			TTx = never,
+			D extends boolean = false
+		>(params: StreamsEventsConsumeParams<TTx, D> & {
+			sink?: ConsumerSink<TTx>
+		}): Promise<StreamsEventsConsumeResult>
 		/**
 		* Backfill from bulk dumps, then continue live from the dump→live seam in
 		* one call. Iterates finalized dump files (via `onDumpFile`) in block
@@ -818,16 +892,18 @@ type IndexFeedEnvelope = {
 };
 /** Consumer options shared by `index.events.consume` and
 *  `index.contractCalls.consume`. Same contract as the Streams consumer:
-*  commit your writes inside `onBatch`, return the cursor you committed. */
+*  commit your writes inside `onBatch`, return the cursor you committed —
+*  or attach a `sink` and let it own checkpointing and rollback entirely. */
 type IndexConsumeOptions<
 	TItem extends IndexFeedItem,
-	TEnvelope extends IndexFeedEnvelope
+	TEnvelope extends IndexFeedEnvelope,
+	TTx = never
 > = {
 	/** Resume from a committed checkpoint. Without it (and without
 	*  `fromHeight`) the API serves only the recent default window. */
 	fromCursor?: string | null
 	/** Start a fresh sweep at this height (e.g. `0` for genesis backfill).
-	*  Ignored once a cursor exists. */
+	*  Ignored once a cursor exists (including a sink's committed cursor). */
 	fromHeight?: number
 	/** `tail` (default) keeps polling at the tip; `bounded` returns on the
 	*  first empty page. */
@@ -837,7 +913,20 @@ type IndexConsumeOptions<
 	*  never reorgs, so `onReorg` is skipped entirely. */
 	finalizedOnly?: boolean
 	batchSize?: number
-	onBatch: (items: TItem[], envelope: TEnvelope, ctx: ConsumerBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	/**
+	* Destination adapter that owns the checkpoint + rollback transaction
+	* (e.g. `kyselySink` from `@secondlayer/sdk/sinks/kysely`). With a sink:
+	* the loop resumes from the sink's committed cursor, `onBatch` receives
+	* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
+	* transaction — a throw aborts both), reorg rollback is automatic (no
+	* `onReorg` needed), and `onBatch`'s return value is ignored.
+	*/
+	sink?: ConsumerSink<TTx>
+	/** Fires once per page, before `onBatch` and before any early return —
+	*  an empty page still proves the loop is alive. Feed it to
+	*  `consumerHealth().record`. */
+	onProgress?: (ctx: ConsumerBatchContext) => void
+	onBatch: (items: TItem[], envelope: TEnvelope, ctx: ConsumerBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
 	onReorg?: (reorg: IndexReorg, ctx: {
 		cursor: string
 	}) => Promise<void> | void
@@ -1064,8 +1153,19 @@ type IndexPrint = IndexEventBase & {
 /** Decoded chain event, discriminated by `event_type`. */
 type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint;
 type IndexEventType = IndexEvent["event_type"];
-type EventsEnvelope<T extends IndexEventType = IndexEventType> = {
-	events: IndexEventOf<T>[]
+/** Fields every read returns regardless of `fields` — the consume contract
+*  (`cursor`, `block_height`) plus the union discriminant. */
+type IndexAlwaysFields = "cursor" | "block_height" | "event_type";
+/** An event row narrowed to a `fields` selection (plus what always ships). */
+type IndexEventFields<
+	T extends IndexEventType,
+	F extends keyof IndexEventOf<T> & string
+> = Pick<IndexEventOf<T>, (F | IndexAlwaysFields) & keyof IndexEventOf<T>>;
+type EventsEnvelope<
+	T extends IndexEventType = IndexEventType,
+	TRow = IndexEventOf<T>
+> = {
+	events: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
@@ -1098,12 +1198,30 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*  Avoids a `/v1/index/transactions` call per event; for `print` events it's
 	*  the only source of the submitting sender. */
 	txContext?: boolean
+	/**
+	* Return only these columns. The server projects the SELECT, so an
+	* unrequested field is physically absent — and the returned row type
+	* narrows to match, making a read of one a compile error rather than
+	* `undefined`.
+	*
+	* `cursor`, `block_height`, and `event_type` come back regardless: the
+	* first two are the consume contract, the third carries the discriminant.
+	* Don't list them.
+	*
+	* Cost note: this does NOT change your bill — Index meters per row read,
+	* not per field. What it buys is wire bytes, plus skipping the `blocks`
+	* join when `block_time` is omitted.
+	*/
+	fields?: readonly (keyof IndexEventOf<T> & string)[]
 };
 type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
-type EventsConsumeParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>>;
+type EventsConsumeParams<
+	T extends IndexEventType = IndexEventType,
+	TTx = never
+> = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
 type IndexContractCall = {
 	cursor: string
 	block_height: number
@@ -1143,7 +1261,7 @@ type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
-type ContractCallsConsumeParams = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope>;
+type ContractCallsConsumeParams<TTx = never> = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope, TTx>;
 /** One canonical block in the sync map. Lean by design — block + parent hash
 *  for chain linkage, burn anchor for Bitcoin confirmations. Use `blocks` for
 *  the full block resource. */
@@ -1614,8 +1732,8 @@ type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
-type SbtcEventsConsumeParams = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope>;
-type SbtcDepositsConsumeParams = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope>;
+type SbtcEventsConsumeParams<TTx = never> = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope, TTx>;
+type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope, TTx>;
 /** `index.sbtc` — the decoded sBTC peg surface (deposits, withdrawals, raw
 *  events, scoreboard). The only productized decoded sBTC peg feed on Stacks. */
 interface SbtcResource {
@@ -1624,7 +1742,9 @@ interface SbtcResource {
 		walk(params?: SbtcDepositsWalkParams): AsyncIterable<IndexSbtcDeposit>
 		/** Checkpointed sweep of completed deposits — append-only, so safe to
 		*  mirror. See {@link IndexConsumeOptions}. */
-		consume(params: SbtcDepositsConsumeParams): Promise<{
+		consume<TTx = never>(params: SbtcDepositsConsumeParams<TTx> & {
+			sink?: ConsumerSink<TTx>
+		}): Promise<{
 			cursor: string | null
 			pages: number
 			emptyPolls: number
@@ -1643,7 +1763,9 @@ interface SbtcResource {
 		walk(params?: SbtcEventsWalkParams): AsyncIterable<IndexSbtcEvent>
 		/** Checkpointed sweep of the raw peg event log — append-only across all
 		*  six topics. See {@link IndexConsumeOptions}. */
-		consume(params: SbtcEventsConsumeParams): Promise<{
+		consume<TTx = never>(params: SbtcEventsConsumeParams<TTx> & {
+			sink?: ConsumerSink<TTx>
+		}): Promise<{
 			cursor: string | null
 			pages: number
 			emptyPolls: number
@@ -1791,9 +1913,23 @@ interface NftTransfersResource {
 /** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
 interface IndexEventsResource {
 	<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
+	/** Narrowing overload: `fields` shrinks the returned row type to exactly
+	*  the requested columns plus {@link IndexAlwaysFields}. `const F` means no
+	*  `as const` at the call site. */
+	list<
+		T extends IndexEventType,
+		const F extends keyof IndexEventOf<T> & string
+	>(params: EventsListParams<T> & {
+		fields: readonly F[]
+	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
 	walk<T extends IndexEventType>(params: EventsWalkParams<T>): AsyncIterable<IndexEventOf<T>>;
-	consume<T extends IndexEventType>(params: EventsConsumeParams<T>): Promise<{
+	consume<
+		T extends IndexEventType,
+		TTx = never
+	>(params: EventsConsumeParams<T, TTx> & {
+		sink?: ConsumerSink<TTx>
+	}): Promise<{
 		cursor: string | null
 		pages: number
 		emptyPolls: number
@@ -1839,7 +1975,9 @@ declare class Index extends BaseClient {
 	readonly contractCalls: {
 		list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>
 		walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>
-		consume: (params: ContractCallsConsumeParams) => Promise<{
+		consume: <TTx = never>(params: ContractCallsConsumeParams<TTx> & {
+			sink?: ConsumerSink<TTx>
+		}) => Promise<{
 			cursor: string | null
 			pages: number
 			emptyPolls: number

package/dist/subgraphs/index.js

@@ -655,7 +655,7 @@ async function consumeStreamsEvents(opts) {
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
   const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
   const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
-  let cursor = opts.fromCursor ?? null;
+  let cursor = opts.fromCursor ?? await opts.sink?.loadCursor() ?? null;
   const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
@@ -678,13 +678,14 @@ async function consumeStreamsEvents(opts) {
       signal: opts.signal
     });
     pages++;
-    if (!finalizedOnly && opts.onReorg) {
+    if (!finalizedOnly && (opts.onReorg || opts.sink)) {
       const fresh = envelope.reorgs.filter((reorg) => !handledReorgs.has(reorgKey(reorg))).sort((a, b) => a.fork_point_height - b.fork_point_height);
       if (fresh.length > 0) {
         const forkPoint = Math.min(...fresh.map((reorg) => reorg.fork_point_height));
         const rewind = Cursor.atHeight(forkPoint);
         for (const reorg of fresh) {
-          await opts.onReorg(reorg, { cursor: rewind });
+          await opts.sink?.rollback(reorg.fork_point_height, rewind);
+          await opts.onReorg?.(reorg, { cursor: rewind });
           handledReorgs.add(reorgKey(reorg));
         }
         cursor = rewind;
@@ -696,10 +697,26 @@ async function consumeStreamsEvents(opts) {
     const emitted = finalizedOnly ? envelope.events.filter((event) => event.finalized) : envelope.events;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const returnedCursor = await opts.onBatch(emitted, envelope, batchContext(checkpoint, height, envelope.tip.block_height));
-    if (finalizedOnly)
-      assertFinalizedCheckpoint(returnedCursor, checkpoint);
-    const nextCursor = returnedCursor ?? checkpoint;
+    const ctx = batchContext(checkpoint, height, envelope.tip.block_height);
+    opts.onProgress?.(ctx);
+    let nextCursor;
+    if (opts.sink) {
+      const sink = opts.sink;
+      if (checkpoint !== null && (checkpoint !== cursor || emitted.length > 0)) {
+        await sink.commitBatch(checkpoint, async (tx) => {
+          await opts.onBatch(emitted, envelope, {
+            ...ctx,
+            tx
+          });
+        });
+      }
+      nextCursor = checkpoint;
+    } else {
+      const returnedCursor = await opts.onBatch(emitted, envelope, ctx);
+      if (finalizedOnly)
+        assertFinalizedCheckpoint(returnedCursor, checkpoint);
+      nextCursor = returnedCursor ?? checkpoint;
+    }
     if (nextCursor && nextCursor !== cursor) {
       cursor = nextCursor;
       emptyPolls = 0;
@@ -800,7 +817,7 @@ async function consumeIndexFeed(opts) {
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
   const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
   const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
-  let cursor = opts.fromCursor ?? null;
+  let cursor = opts.fromCursor ?? await opts.sink?.loadCursor() ?? null;
   const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
@@ -818,13 +835,14 @@ async function consumeIndexFeed(opts) {
       signal: opts.signal
     });
     pages++;
-    if (!finalizedOnly && opts.onReorg) {
+    if (!finalizedOnly && (opts.onReorg || opts.sink)) {
       const fresh = envelope.reorgs.filter((reorg) => !handledReorgs.has(reorg.id)).sort((a, b) => a.fork_point_height - b.fork_point_height);
       if (fresh.length > 0) {
         const forkPoint = Math.min(...fresh.map((reorg) => reorg.fork_point_height));
         const rewind = Cursor.atHeight(forkPoint);
         for (const reorg of fresh) {
-          await opts.onReorg(reorg, { cursor: rewind });
+          await opts.sink?.rollback(reorg.fork_point_height, rewind);
+          await opts.onReorg?.(reorg, { cursor: rewind });
           handledReorgs.add(reorg.id);
         }
         cursor = rewind;
@@ -837,10 +855,26 @@ async function consumeIndexFeed(opts) {
     const emitted = finalizedOnly ? items.filter((item) => item.block_height <= envelope.tip.finalized_height) : items;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const returnedCursor = await opts.onBatch(emitted, envelope, batchContext(checkpoint, height, envelope.tip.block_height));
-    if (finalizedOnly)
-      assertFinalizedCheckpoint(returnedCursor, checkpoint);
-    const nextCursor = returnedCursor ?? checkpoint;
+    const ctx = batchContext(checkpoint, height, envelope.tip.block_height);
+    opts.onProgress?.(ctx);
+    let nextCursor;
+    if (opts.sink) {
+      const sink = opts.sink;
+      if (checkpoint !== null && (checkpoint !== cursor || emitted.length > 0)) {
+        await sink.commitBatch(checkpoint, async (tx) => {
+          await opts.onBatch(emitted, envelope, {
+            ...ctx,
+            tx
+          });
+        });
+      }
+      nextCursor = checkpoint;
+    } else {
+      const returnedCursor = await opts.onBatch(emitted, envelope, ctx);
+      if (finalizedOnly)
+        assertFinalizedCheckpoint(returnedCursor, checkpoint);
+      nextCursor = returnedCursor ?? checkpoint;
+    }
     if (nextCursor && nextCursor !== cursor) {
       cursor = nextCursor;
       emptyPolls = 0;
@@ -1079,7 +1113,8 @@ class Index extends BaseClient {
       from_height: params.fromHeight,
       to_height: params.toHeight,
       trait: params.trait,
-      tx_context: params.txContext ? "true" : undefined
+      tx_context: params.txContext ? "true" : undefined,
+      fields: params.fields?.join(",")
     })}`);
   }
   walkEvents(params) {
@@ -1313,6 +1348,175 @@ class Projects extends BaseClient {
 // src/streams/client.ts
 import { ed25519 as ed255192 } from "@secondlayer/shared";
 
+// src/streams/_payload.ts
+function requireString(payload, field, eventType) {
+  const value = payload[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${eventType} payload missing ${field}`);
+  }
+  return value;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function requireAmountField(payload, field, eventType) {
+  const amount = requireString(payload, field, eventType);
+  if (!/^(0|[1-9]\d*)$/.test(amount)) {
+    throw new Error(`${eventType} payload has malformed ${field}`);
+  }
+  return amount;
+}
+function requireAmount(payload, eventType) {
+  return requireAmountField(payload, "amount", eventType);
+}
+function parseAssetIdentifier(assetIdentifier, eventType) {
+  const [contractId, tokenName] = assetIdentifier.split("::");
+  if (!contractId) {
+    throw new Error(`${eventType} payload has malformed asset_identifier`);
+  }
+  return {
+    contract_id: contractId,
+    token_name: tokenName && tokenName.length > 0 ? tokenName : null
+  };
+}
+function requireHexValue(payload, eventType) {
+  const rawValue = payload.raw_value;
+  if (typeof rawValue === "string") {
+    if (!/^0x[0-9a-fA-F]*$/.test(rawValue)) {
+      throw new Error(`${eventType} payload has malformed value`);
+    }
+    return rawValue;
+  }
+  const value = payload.value;
+  const hex = typeof value === "string" ? value : value && typeof value === "object" && typeof value.hex === "string" ? value.hex : null;
+  if (!hex) {
+    throw new Error(`${eventType} payload missing value`);
+  }
+  if (!/^0x[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error(`${eventType} payload has malformed value`);
+  }
+  return hex;
+}
+function decodedRow(event, eventType, decoded_payload) {
+  return {
+    cursor: event.cursor,
+    block_height: event.block_height,
+    tx_id: event.tx_id,
+    tx_index: event.tx_index,
+    event_index: event.event_index,
+    event_type: eventType,
+    decoded_payload,
+    source_cursor: event.cursor
+  };
+}
+
+// src/streams/decode.ts
+function decode(event) {
+  const base = {
+    cursor: event.cursor,
+    block_height: event.block_height,
+    block_time: event.ts,
+    tx_id: event.tx_id,
+    tx_index: event.tx_index,
+    event_index: event.event_index,
+    contract_id: event.contract_id
+  };
+  const p = event.payload;
+  switch (event.event_type) {
+    case "stx_transfer":
+      return {
+        ...base,
+        event_type: "stx_transfer",
+        sender: requireString(p, "sender", event.event_type),
+        recipient: requireString(p, "recipient", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type),
+        memo: optionalString(p.memo)
+      };
+    case "stx_mint":
+      return {
+        ...base,
+        event_type: "stx_mint",
+        recipient: requireString(p, "recipient", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type)
+      };
+    case "stx_burn":
+      return {
+        ...base,
+        event_type: "stx_burn",
+        sender: requireString(p, "sender", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type)
+      };
+    case "stx_lock":
+      return {
+        ...base,
+        event_type: "stx_lock",
+        sender: requireString(p, "locked_address", event.event_type),
+        amount: requireAmountField(p, "locked_amount", event.event_type),
+        payload: { unlock_height: optionalString(p.unlock_height) }
+      };
+    case "ft_transfer":
+      return {
+        ...base,
+        event_type: "ft_transfer",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        sender: requireString(p, "sender", event.event_type),
+        recipient: requireString(p, "recipient", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type)
+      };
+    case "ft_mint":
+      return {
+        ...base,
+        event_type: "ft_mint",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        recipient: requireString(p, "recipient", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type)
+      };
+    case "ft_burn":
+      return {
+        ...base,
+        event_type: "ft_burn",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        sender: requireString(p, "sender", event.event_type),
+        amount: requireAmountField(p, "amount", event.event_type)
+      };
+    case "nft_transfer":
+      return {
+        ...base,
+        event_type: "nft_transfer",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        sender: requireString(p, "sender", event.event_type),
+        recipient: requireString(p, "recipient", event.event_type),
+        value: requireHexValue(p, event.event_type)
+      };
+    case "nft_mint":
+      return {
+        ...base,
+        event_type: "nft_mint",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        recipient: requireString(p, "recipient", event.event_type),
+        value: requireHexValue(p, event.event_type)
+      };
+    case "nft_burn":
+      return {
+        ...base,
+        event_type: "nft_burn",
+        asset_identifier: requireString(p, "asset_identifier", event.event_type),
+        sender: requireString(p, "sender", event.event_type),
+        value: requireHexValue(p, event.event_type)
+      };
+    case "print":
+      return {
+        ...base,
+        event_type: "print",
+        payload: {
+          topic: optionalString(p.topic),
+          value: p.value,
+          raw_value: optionalString(p.raw_value)
+        }
+      };
+  }
+}
+
 // src/streams/dumps.ts
 import { createHash } from "node:crypto";
 import { verifyStreamsBulkManifestSignature } from "@secondlayer/shared/streams-bulk-manifest";
@@ -1687,8 +1891,11 @@ function createStreamsClient(options) {
         return request(`/v1/streams/events/${encodeURIComponent(txId)}`);
       },
       consume(params) {
+        const onBatch = params.decoded ? (events, envelope, ctx) => params.onBatch(events.map(decode), envelope, ctx) : params.onBatch;
         return consumeStreamsEvents({
           fromCursor: params.fromCursor,
+          sink: params.sink,
+          onProgress: params.onProgress,
           mode: params.mode,
           finalizedOnly: params.finalizedOnly,
           types: params.types,
@@ -1699,7 +1906,7 @@ function createStreamsClient(options) {
           assetIdentifier: params.assetIdentifier,
           batchSize: params.batchSize ?? 100,
           fetchEvents,
-          onBatch: params.onBatch,
+          onBatch,
           onReorg: params.onReorg,
           emptyBackoffMs: params.emptyBackoffMs,
           maxPages: params.maxPages,
@@ -1942,5 +2149,5 @@ export {
   Subgraphs
 };
 
-//# debugId=A36A74FD0514129964756E2164756E21
+//# debugId=F62665719058CC2664756E2164756E21
 //# sourceMappingURL=index.js.map