@secondlayer/sdk 6.37.1 → 6.39.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +214 -20
- package/dist/index.js +267 -79
- package/dist/index.js.map +11 -9
- package/dist/sinks/kysely.d.ts +108 -0
- package/dist/sinks/kysely.js +236 -0
- package/dist/sinks/kysely.js.map +11 -0
- package/dist/streams/index.d.ts +188 -6
- package/dist/streams/index.js +199 -71
- package/dist/streams/index.js.map +8 -7
- package/dist/subgraphs/index.d.ts +155 -17
- package/dist/subgraphs/index.js +224 -17
- package/dist/subgraphs/index.js.map +9 -7
- package/package.json +18 -3
package/dist/index.d.ts
CHANGED
|
@@ -367,6 +367,57 @@ declare function fetchRewardSet(opts: {
|
|
|
367
367
|
declare function verifyTransactionProof(proof: TransactionProof, opts?: {
|
|
368
368
|
rewardSet?: RewardSet
|
|
369
369
|
}): TransactionProofVerifyResult;
|
|
370
|
+
/**
|
|
371
|
+
* A consumer sink: the destination adapter a consume loop writes through.
|
|
372
|
+
*
|
|
373
|
+
* Without a sink, the user owns the three hard parts of a durable indexer —
|
|
374
|
+
* checkpoint persistence, rows+cursor atomicity, and reorg rollback — and
|
|
375
|
+
* the reasoning that makes them safe lives in doc comments. A sink owns all
|
|
376
|
+
* three: the loop loads its committed cursor, hands the handler a
|
|
377
|
+
* transaction, commits rows AND cursor atomically, and rolls back reorgs
|
|
378
|
+
* without any user code. Crucially, a sink also closes the silent-skip
|
|
379
|
+
* hazard where omitting `onReorg` meant reorgs were ignored forever: with a
|
|
380
|
+
* sink attached, rollback is unconditional.
|
|
381
|
+
*
|
|
382
|
+
* The interface is dependency-free on purpose: implementations with real
|
|
383
|
+
* database drivers live behind subpath exports (`@secondlayer/sdk/sinks/*`)
|
|
384
|
+
* so the root entry ships no DB dependency.
|
|
385
|
+
*/
|
|
386
|
+
interface ConsumerSink<Tx = unknown> {
|
|
387
|
+
/** Phantom marker carrying `Tx` in a directly-inferable position, so the
|
|
388
|
+
* consume loops' `TTx` type parameter resolves from the `sink` option
|
|
389
|
+
* (never set at runtime). */
|
|
390
|
+
readonly _tx?: Tx;
|
|
391
|
+
/** The committed checkpoint, or `null` on first run. Called once, before
|
|
392
|
+
* the first page. Implementations may create their checkpoint storage
|
|
393
|
+
* here and SHOULD validate their rollback preconditions (e.g. that every
|
|
394
|
+
* declared table carries the height column). */
|
|
395
|
+
loadCursor(): Promise<string | null>;
|
|
396
|
+
/**
|
|
397
|
+
* Apply one batch atomically: open a transaction, run `write(tx)` (the
|
|
398
|
+
* user's inserts), and commit the rows AND `cursor` together. A throw
|
|
399
|
+
* from `write` must abort the whole transaction — leaving neither rows
|
|
400
|
+
* nor cursor, so a crashed batch is simply re-read on restart.
|
|
401
|
+
*/
|
|
402
|
+
commitBatch(cursor: string, write: (tx: Tx) => Promise<void> | void): Promise<void>;
|
|
403
|
+
/**
|
|
404
|
+
* Roll the projection back to the fork: delete everything AT OR ABOVE
|
|
405
|
+
* `forkPointHeight` (inclusive `>=` — the new chain re-supplies the fork
|
|
406
|
+
* block) and commit `rewindCursor` in the SAME transaction. Deleting
|
|
407
|
+
* without the rewound cursor is the classic silent-gap bug: a crash
|
|
408
|
+
* between the two writes resumes above the fork and the deleted range is
|
|
409
|
+
* never re-read.
|
|
410
|
+
*/
|
|
411
|
+
rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
|
|
412
|
+
}
|
|
413
|
+
/** The transaction type a sink hands to `onBatch` (`ctx.tx`). */
|
|
414
|
+
type SinkTx<S> = S extends ConsumerSink<infer Tx> ? Tx : never;
|
|
415
|
+
/** `ctx` gains `tx` exactly when a sink is attached; without one the shape
|
|
416
|
+
* is unchanged (an intersection with `unknown` is an identity, so
|
|
417
|
+
* contextual typing of `onBatch` callbacks never degrades to a union). */
|
|
418
|
+
type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
|
|
419
|
+
tx: TTx
|
|
420
|
+
};
|
|
370
421
|
import { StreamsEventType } from "@secondlayer/shared";
|
|
371
422
|
/** A Clarity value as Streams serves it: the canonical hex string, a typed
|
|
372
423
|
* object carrying that hex (`{ hex }`), or a decoded Clarity-JSON object.
|
|
@@ -612,8 +663,28 @@ type StreamsBatchContext = ConsumerBatchContext;
|
|
|
612
663
|
type StreamsReorgContext = {
|
|
613
664
|
cursor: string
|
|
614
665
|
};
|
|
615
|
-
type StreamsEventsConsumeParams
|
|
666
|
+
type StreamsEventsConsumeParams<
|
|
667
|
+
TTx = never,
|
|
668
|
+
D extends boolean = false
|
|
669
|
+
> = {
|
|
616
670
|
fromCursor?: string | null
|
|
671
|
+
/**
|
|
672
|
+
* Deliver events pre-decoded as the flat, `event_type`-discriminated rows
|
|
673
|
+
* Index serves (`IndexEvent`), so Streams consumption reads identically
|
|
674
|
+
* to Index consumption — no guard+decode pairs in your handler.
|
|
675
|
+
*/
|
|
676
|
+
decoded?: D
|
|
677
|
+
/**
|
|
678
|
+
* Destination adapter that owns the checkpoint + rollback transaction
|
|
679
|
+
* (e.g. `kyselySink` from `@secondlayer/sdk/sinks/kysely`). With a sink:
|
|
680
|
+
* the loop resumes from the sink's committed cursor, `onBatch` receives
|
|
681
|
+
* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
|
|
682
|
+
* transaction), reorg rollback is automatic, and `onBatch`'s return value
|
|
683
|
+
* is ignored.
|
|
684
|
+
*/
|
|
685
|
+
sink?: ConsumerSink<TTx>
|
|
686
|
+
/** Fires once per page, before `onBatch` and before any early return. */
|
|
687
|
+
onProgress?: (ctx: ConsumerBatchContext) => void
|
|
617
688
|
mode?: "tail" | "bounded"
|
|
618
689
|
/**
|
|
619
690
|
* Emit only finalized (immutable) events and never surface reorgs. The SDK
|
|
@@ -634,7 +705,7 @@ type StreamsEventsConsumeParams = {
|
|
|
634
705
|
* transaction as your writes. Returning a cursor overrides `ctx.cursor` as
|
|
635
706
|
* the resume point (advanced manual control); returning nothing uses it.
|
|
636
707
|
*/
|
|
637
|
-
onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
|
|
708
|
+
onBatch: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
|
|
638
709
|
/**
|
|
639
710
|
* Roll your projection back to `reorg.fork_point_height`, persisting
|
|
640
711
|
* `ctx.cursor` in the same transaction. Called once per *new* reorg
|
|
@@ -792,7 +863,12 @@ type StreamsClient = {
|
|
|
792
863
|
* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
|
|
793
864
|
* stops it.
|
|
794
865
|
*/
|
|
795
|
-
consume
|
|
866
|
+
consume<
|
|
867
|
+
TTx = never,
|
|
868
|
+
D extends boolean = false
|
|
869
|
+
>(params: StreamsEventsConsumeParams<TTx, D> & {
|
|
870
|
+
sink?: ConsumerSink<TTx>
|
|
871
|
+
}): Promise<StreamsEventsConsumeResult>
|
|
796
872
|
/**
|
|
797
873
|
* Backfill from bulk dumps, then continue live from the dump→live seam in
|
|
798
874
|
* one call. Iterates finalized dump files (via `onDumpFile`) in block
|
|
@@ -881,16 +957,18 @@ type IndexFeedFetcher<TEnvelope extends IndexFeedEnvelope> = (params: {
|
|
|
881
957
|
}) => Promise<TEnvelope>;
|
|
882
958
|
/** Consumer options shared by `index.events.consume` and
|
|
883
959
|
* `index.contractCalls.consume`. Same contract as the Streams consumer:
|
|
884
|
-
* commit your writes inside `onBatch`, return the cursor you committed
|
|
960
|
+
* commit your writes inside `onBatch`, return the cursor you committed —
|
|
961
|
+
* or attach a `sink` and let it own checkpointing and rollback entirely. */
|
|
885
962
|
type IndexConsumeOptions<
|
|
886
963
|
TItem extends IndexFeedItem,
|
|
887
|
-
TEnvelope extends IndexFeedEnvelope
|
|
964
|
+
TEnvelope extends IndexFeedEnvelope,
|
|
965
|
+
TTx = never
|
|
888
966
|
> = {
|
|
889
967
|
/** Resume from a committed checkpoint. Without it (and without
|
|
890
968
|
* `fromHeight`) the API serves only the recent default window. */
|
|
891
969
|
fromCursor?: string | null
|
|
892
970
|
/** Start a fresh sweep at this height (e.g. `0` for genesis backfill).
|
|
893
|
-
* Ignored once a cursor exists. */
|
|
971
|
+
* Ignored once a cursor exists (including a sink's committed cursor). */
|
|
894
972
|
fromHeight?: number
|
|
895
973
|
/** `tail` (default) keeps polling at the tip; `bounded` returns on the
|
|
896
974
|
* first empty page. */
|
|
@@ -900,7 +978,20 @@ type IndexConsumeOptions<
|
|
|
900
978
|
* never reorgs, so `onReorg` is skipped entirely. */
|
|
901
979
|
finalizedOnly?: boolean
|
|
902
980
|
batchSize?: number
|
|
903
|
-
|
|
981
|
+
/**
|
|
982
|
+
* Destination adapter that owns the checkpoint + rollback transaction
|
|
983
|
+
* (e.g. `kyselySink` from `@secondlayer/sdk/sinks/kysely`). With a sink:
|
|
984
|
+
* the loop resumes from the sink's committed cursor, `onBatch` receives
|
|
985
|
+
* `ctx.tx` and must write ONLY through it (rows and cursor commit in one
|
|
986
|
+
* transaction — a throw aborts both), reorg rollback is automatic (no
|
|
987
|
+
* `onReorg` needed), and `onBatch`'s return value is ignored.
|
|
988
|
+
*/
|
|
989
|
+
sink?: ConsumerSink<TTx>
|
|
990
|
+
/** Fires once per page, before `onBatch` and before any early return —
|
|
991
|
+
* an empty page still proves the loop is alive. Feed it to
|
|
992
|
+
* `consumerHealth().record`. */
|
|
993
|
+
onProgress?: (ctx: ConsumerBatchContext) => void
|
|
994
|
+
onBatch: (items: TItem[], envelope: TEnvelope, ctx: ConsumerBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
|
|
904
995
|
onReorg?: (reorg: IndexReorg, ctx: {
|
|
905
996
|
cursor: string
|
|
906
997
|
}) => Promise<void> | void
|
|
@@ -931,8 +1022,9 @@ type IndexConsumeOptions<
|
|
|
931
1022
|
*/
|
|
932
1023
|
declare function consumeIndexFeed<
|
|
933
1024
|
TItem extends IndexFeedItem,
|
|
934
|
-
TEnvelope extends IndexFeedEnvelope
|
|
935
|
-
|
|
1025
|
+
TEnvelope extends IndexFeedEnvelope,
|
|
1026
|
+
TTx = never
|
|
1027
|
+
>(opts: IndexConsumeOptions<TItem, TEnvelope, TTx> & {
|
|
936
1028
|
fetchPage: IndexFeedFetcher<TEnvelope>
|
|
937
1029
|
itemsOf: (envelope: TEnvelope) => TItem[]
|
|
938
1030
|
}): Promise<{
|
|
@@ -1149,8 +1241,19 @@ type IndexPrint = IndexEventBase & {
|
|
|
1149
1241
|
/** Decoded chain event, discriminated by `event_type`. */
|
|
1150
1242
|
type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint;
|
|
1151
1243
|
type IndexEventType = IndexEvent["event_type"];
|
|
1152
|
-
|
|
1153
|
-
|
|
1244
|
+
/** Fields every read returns regardless of `fields` — the consume contract
|
|
1245
|
+
* (`cursor`, `block_height`) plus the union discriminant. */
|
|
1246
|
+
type IndexAlwaysFields = "cursor" | "block_height" | "event_type";
|
|
1247
|
+
/** An event row narrowed to a `fields` selection (plus what always ships). */
|
|
1248
|
+
type IndexEventFields<
|
|
1249
|
+
T extends IndexEventType,
|
|
1250
|
+
F extends keyof IndexEventOf<T> & string
|
|
1251
|
+
> = Pick<IndexEventOf<T>, (F | IndexAlwaysFields) & keyof IndexEventOf<T>>;
|
|
1252
|
+
type EventsEnvelope<
|
|
1253
|
+
T extends IndexEventType = IndexEventType,
|
|
1254
|
+
TRow = IndexEventOf<T>
|
|
1255
|
+
> = {
|
|
1256
|
+
events: TRow[]
|
|
1154
1257
|
next_cursor: string | null
|
|
1155
1258
|
tip: IndexTip
|
|
1156
1259
|
reorgs: IndexReorg[]
|
|
@@ -1183,12 +1286,30 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
|
|
|
1183
1286
|
* Avoids a `/v1/index/transactions` call per event; for `print` events it's
|
|
1184
1287
|
* the only source of the submitting sender. */
|
|
1185
1288
|
txContext?: boolean
|
|
1289
|
+
/**
|
|
1290
|
+
* Return only these columns. The server projects the SELECT, so an
|
|
1291
|
+
* unrequested field is physically absent — and the returned row type
|
|
1292
|
+
* narrows to match, making a read of one a compile error rather than
|
|
1293
|
+
* `undefined`.
|
|
1294
|
+
*
|
|
1295
|
+
* `cursor`, `block_height`, and `event_type` come back regardless: the
|
|
1296
|
+
* first two are the consume contract, the third carries the discriminant.
|
|
1297
|
+
* Don't list them.
|
|
1298
|
+
*
|
|
1299
|
+
* Cost note: this does NOT change your bill — Index meters per row read,
|
|
1300
|
+
* not per field. What it buys is wire bytes, plus skipping the `blocks`
|
|
1301
|
+
* join when `block_time` is omitted.
|
|
1302
|
+
*/
|
|
1303
|
+
fields?: readonly (keyof IndexEventOf<T> & string)[]
|
|
1186
1304
|
};
|
|
1187
1305
|
type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & {
|
|
1188
1306
|
batchSize?: number
|
|
1189
1307
|
signal?: AbortSignal
|
|
1190
1308
|
};
|
|
1191
|
-
type EventsConsumeParams<
|
|
1309
|
+
type EventsConsumeParams<
|
|
1310
|
+
T extends IndexEventType = IndexEventType,
|
|
1311
|
+
TTx = never
|
|
1312
|
+
> = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
|
|
1192
1313
|
type IndexContractCall = {
|
|
1193
1314
|
cursor: string
|
|
1194
1315
|
block_height: number
|
|
@@ -1228,7 +1349,7 @@ type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & {
|
|
|
1228
1349
|
batchSize?: number
|
|
1229
1350
|
signal?: AbortSignal
|
|
1230
1351
|
};
|
|
1231
|
-
type ContractCallsConsumeParams = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope>;
|
|
1352
|
+
type ContractCallsConsumeParams<TTx = never> = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope, TTx>;
|
|
1232
1353
|
/** One canonical block in the sync map. Lean by design — block + parent hash
|
|
1233
1354
|
* for chain linkage, burn anchor for Bitcoin confirmations. Use `blocks` for
|
|
1234
1355
|
* the full block resource. */
|
|
@@ -1699,8 +1820,8 @@ type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & {
|
|
|
1699
1820
|
batchSize?: number
|
|
1700
1821
|
signal?: AbortSignal
|
|
1701
1822
|
};
|
|
1702
|
-
type SbtcEventsConsumeParams = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope>;
|
|
1703
|
-
type SbtcDepositsConsumeParams = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope>;
|
|
1823
|
+
type SbtcEventsConsumeParams<TTx = never> = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope, TTx>;
|
|
1824
|
+
type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope, TTx>;
|
|
1704
1825
|
/** `index.sbtc` — the decoded sBTC peg surface (deposits, withdrawals, raw
|
|
1705
1826
|
* events, scoreboard). The only productized decoded sBTC peg feed on Stacks. */
|
|
1706
1827
|
interface SbtcResource {
|
|
@@ -1709,7 +1830,9 @@ interface SbtcResource {
|
|
|
1709
1830
|
walk(params?: SbtcDepositsWalkParams): AsyncIterable<IndexSbtcDeposit>
|
|
1710
1831
|
/** Checkpointed sweep of completed deposits — append-only, so safe to
|
|
1711
1832
|
* mirror. See {@link IndexConsumeOptions}. */
|
|
1712
|
-
consume(params: SbtcDepositsConsumeParams
|
|
1833
|
+
consume<TTx = never>(params: SbtcDepositsConsumeParams<TTx> & {
|
|
1834
|
+
sink?: ConsumerSink<TTx>
|
|
1835
|
+
}): Promise<{
|
|
1713
1836
|
cursor: string | null
|
|
1714
1837
|
pages: number
|
|
1715
1838
|
emptyPolls: number
|
|
@@ -1728,7 +1851,9 @@ interface SbtcResource {
|
|
|
1728
1851
|
walk(params?: SbtcEventsWalkParams): AsyncIterable<IndexSbtcEvent>
|
|
1729
1852
|
/** Checkpointed sweep of the raw peg event log — append-only across all
|
|
1730
1853
|
* six topics. See {@link IndexConsumeOptions}. */
|
|
1731
|
-
consume(params: SbtcEventsConsumeParams
|
|
1854
|
+
consume<TTx = never>(params: SbtcEventsConsumeParams<TTx> & {
|
|
1855
|
+
sink?: ConsumerSink<TTx>
|
|
1856
|
+
}): Promise<{
|
|
1732
1857
|
cursor: string | null
|
|
1733
1858
|
pages: number
|
|
1734
1859
|
emptyPolls: number
|
|
@@ -1876,9 +2001,23 @@ interface NftTransfersResource {
|
|
|
1876
2001
|
/** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
|
|
1877
2002
|
interface IndexEventsResource {
|
|
1878
2003
|
<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
|
|
2004
|
+
/** Narrowing overload: `fields` shrinks the returned row type to exactly
|
|
2005
|
+
* the requested columns plus {@link IndexAlwaysFields}. `const F` means no
|
|
2006
|
+
* `as const` at the call site. */
|
|
2007
|
+
list<
|
|
2008
|
+
T extends IndexEventType,
|
|
2009
|
+
const F extends keyof IndexEventOf<T> & string
|
|
2010
|
+
>(params: EventsListParams<T> & {
|
|
2011
|
+
fields: readonly F[]
|
|
2012
|
+
}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
|
|
1879
2013
|
list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
|
|
1880
2014
|
walk<T extends IndexEventType>(params: EventsWalkParams<T>): AsyncIterable<IndexEventOf<T>>;
|
|
1881
|
-
consume<
|
|
2015
|
+
consume<
|
|
2016
|
+
T extends IndexEventType,
|
|
2017
|
+
TTx = never
|
|
2018
|
+
>(params: EventsConsumeParams<T, TTx> & {
|
|
2019
|
+
sink?: ConsumerSink<TTx>
|
|
2020
|
+
}): Promise<{
|
|
1882
2021
|
cursor: string | null
|
|
1883
2022
|
pages: number
|
|
1884
2023
|
emptyPolls: number
|
|
@@ -1924,7 +2063,9 @@ declare class Index extends BaseClient {
|
|
|
1924
2063
|
readonly contractCalls: {
|
|
1925
2064
|
list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>
|
|
1926
2065
|
walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>
|
|
1927
|
-
consume: (params: ContractCallsConsumeParams
|
|
2066
|
+
consume: <TTx = never>(params: ContractCallsConsumeParams<TTx> & {
|
|
2067
|
+
sink?: ConsumerSink<TTx>
|
|
2068
|
+
}) => Promise<{
|
|
1928
2069
|
cursor: string | null
|
|
1929
2070
|
pages: number
|
|
1930
2071
|
emptyPolls: number
|
|
@@ -2256,6 +2397,22 @@ type CreateStreamsClientOptions = {
|
|
|
2256
2397
|
verifyDumpsManifest?: boolean
|
|
2257
2398
|
};
|
|
2258
2399
|
declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
|
|
2400
|
+
/**
|
|
2401
|
+
* Decode a raw Streams event into the SAME flat, `event_type`-discriminated
|
|
2402
|
+
* row shape Index serves — so Streams consumption reads identically to Index
|
|
2403
|
+
* consumption, with one call instead of eleven guard+decode pairs.
|
|
2404
|
+
*
|
|
2405
|
+
* ```ts
|
|
2406
|
+
* for (const event of envelope.events) {
|
|
2407
|
+
* const row = decode(event);
|
|
2408
|
+
* if (row.event_type === "ft_transfer") row.amount; // string, narrowed
|
|
2409
|
+
* }
|
|
2410
|
+
* ```
|
|
2411
|
+
*
|
|
2412
|
+
* Prefer `decoded: true` on `streams.events.consume` — then decoding never
|
|
2413
|
+
* appears in your code at all.
|
|
2414
|
+
*/
|
|
2415
|
+
declare function decode(event: StreamsEvent): IndexEvent;
|
|
2259
2416
|
import { ByoBreakingChangeDetails } from "@secondlayer/shared/errors";
|
|
2260
2417
|
/** Options accepted by every error in the family. */
|
|
2261
2418
|
interface SecondLayerErrorOptions {
|
|
@@ -2830,6 +2987,43 @@ type PayAndRetryOptions = Omit<WithX402Options, never> & {
|
|
|
2830
2987
|
*/
|
|
2831
2988
|
declare function payAndRetry(doFetch: X402FetchFn, opts: PayAndRetryOptions): Promise<Response>;
|
|
2832
2989
|
import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
|
|
2990
|
+
/**
|
|
2991
|
+
* The two pieces every "deploy a consumer" guide leaves out, packaged:
|
|
2992
|
+
* a liveness endpoint and a graceful-shutdown signal. Both are
|
|
2993
|
+
* runtime-agnostic — the SDK never binds a port or assumes Bun/Node.
|
|
2994
|
+
*/
|
|
2995
|
+
interface ConsumerHealth {
|
|
2996
|
+
/** Feed this to the consume loop's `onProgress` — it stamps arrival time
|
|
2997
|
+
* and keeps the latest progress ctx for the health body. */
|
|
2998
|
+
record: (ctx: ConsumerBatchContext) => void;
|
|
2999
|
+
/** Fetch-style handler for `GET /health`. Mount it on whatever serves
|
|
3000
|
+
* HTTP in your runtime:
|
|
3001
|
+
* `Bun.serve({ port, fetch: health.handler })` ·
|
|
3002
|
+
* `http.createServer(...)` via an adapter · a Workers route. */
|
|
3003
|
+
handler: (req: Request) => Response;
|
|
3004
|
+
}
|
|
3005
|
+
/**
|
|
3006
|
+
* Liveness for a consume loop. The gate is "did a page land recently", NOT
|
|
3007
|
+
* "are we near the tip": during a genesis backfill the loop is millions of
|
|
3008
|
+
* blocks behind and perfectly healthy, so lag can't be the signal. A wedged
|
|
3009
|
+
* loop stops reporting pages and flips to 503 — that's what platforms
|
|
3010
|
+
* should restart on. `blocks_behind` still ships in the body for dashboards.
|
|
3011
|
+
*/
|
|
3012
|
+
declare function consumerHealth(options?: {
|
|
3013
|
+
staleAfterMs?: number
|
|
3014
|
+
}): ConsumerHealth;
|
|
3015
|
+
/**
|
|
3016
|
+
* An `AbortSignal` wired to SIGTERM/SIGINT (redeploys arrive as SIGTERM).
|
|
3017
|
+
* Pass it as the consume loop's `signal`: aborting is checked at the top of
|
|
3018
|
+
* the loop, never mid-batch, so the in-flight transaction — rows AND
|
|
3019
|
+
* checkpoint — always commits before the process exits. Nothing is
|
|
3020
|
+
* half-written; the next run resumes from exactly that cursor.
|
|
3021
|
+
*
|
|
3022
|
+
* No-op (never fires) on runtimes without `process` signal handling.
|
|
3023
|
+
*/
|
|
3024
|
+
declare function shutdownSignal(options?: {
|
|
3025
|
+
signals?: readonly ("SIGTERM" | "SIGINT")[]
|
|
3026
|
+
}): AbortSignal;
|
|
2833
3027
|
import { ChainWebhookDelivery } from "@secondlayer/shared";
|
|
2834
3028
|
import { StandardWebhooksHeaders } from "@secondlayer/shared/crypto/standard-webhooks";
|
|
2835
3029
|
import { StandardWebhooksHeaders as StandardWebhooksHeaders2, verify } from "@secondlayer/shared/crypto/standard-webhooks";
|
|
@@ -2993,4 +3187,4 @@ declare function toJsonSafe(value: unknown): unknown;
|
|
|
2993
3187
|
/** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
|
|
2994
3188
|
* buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
|
|
2995
3189
|
declare function decodeClarityValue(hex: string): unknown;
|
|
2996
|
-
export { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, createX402Client, createStreamsClient, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SelectOfferOptions, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };
|
|
3190
|
+
export { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, decode, createX402Client, createStreamsClient, consumerHealth, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WithSinkTx, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SinkTx, SelectOfferOptions, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerSink, ConsumerHealth, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };
|