@secondlayer/sdk 6.22.0 → 6.23.1

package/README.md

@@ -1,6 +1,6 @@
 # @secondlayer/sdk
 
-TypeScript SDK for the Second Layer API.
+TypeScript SDK for the Secondlayer API.
 
 ## Install
 
@@ -36,12 +36,19 @@ plan's tier.
 
 ## Mental model
 
-- `sl.streams` reads raw ordered chain events from Stacks Streams.
-- `sl.index` reads the decoded layer from Stacks Index — FT/NFT transfers, all event types (`events`), and `contractCalls`.
-- `sl.contracts` finds deployed contracts by trait (SIP-009/010/013).
-- `sl.subgraphs` reads app-specific tables from Stacks Subgraphs.
+Everything is indexing — the question is how much of the indexer you run:
 
-## Stacks Streams
+- `sl.index` — decoded rows we keep indexed: query FT/NFT transfers, all event
+  types (`events`), and `contractCalls` — or build your own app index on them
+  with the checkpointed `consume()` loop (automatic reorg rewind), `walk()`
+  sweeps, and resumable cursors on every page.
+- `sl.subgraphs` — deploy your own indexer (one `defineSubgraph()` file via the
+  CLI), then read your hosted tables here. We run the loop.
+- `sl.streams` — the raw ordered event firehose Index itself is built on, with
+  a checkpointed `consume()` and dumps `replay()` for building from zero.
+- `sl.contracts` — find deployed contracts by trait (SIP-009/010/013).
+
+## Streams
 
 Typed HTTP client for the raw event firehose. Reads require a bearer token (`apiKey`).
 
@@ -217,7 +224,7 @@ the decoder. Decoders throw when the event type or payload is malformed. Add new
 helpers beside `src/streams/ft-transfer.ts` and export them through
 `src/streams/index.ts`.
 
-## Stacks Index
+## Index
 
 Decoded transfer events.
 
@@ -245,9 +252,33 @@ for await (const transfer of sl.index.ftTransfers.walk({
 }
 ```
 
+Checkpointed consumer — build your app index.
+
+`index.events.consume` / `index.contractCalls.consume` is the same contract as
+the Streams consumer: write your rows inside `onBatch`, return the cursor you
+committed, and reorgs rewind automatically to the fork point. `finalizedOnly`
+holds delivery to rows at or below `tip.finalized_height` (Index rows carry no
+per-event flag). Full runnable example: `examples/sales-index/`.
+
+```typescript
+await sl.index.contractCalls.consume({
+  contractId: "SP...marketplace-v4",
+  functionName: "purchase-asset",
+  fromCursor: await loadCheckpoint(), // null on first run
+  fromHeight: 0,                      // first run: backfill from genesis
+  onBatch: async (calls, envelope, ctx) => {
+    await commitRowsAndCheckpoint(calls, ctx.cursor);
+    return ctx.cursor;
+  },
+  onReorg: async (reorg) => {
+    await rollbackAboveHeight(reorg.fork_point_height);
+  },
+});
+```
+
 ## Transaction-inclusion proofs
 
-Verify — **without trusting Second Layer** — that a transaction is included in a
+Verify — **without trusting Secondlayer** — that a transaction is included in a
 Stacks (Nakamoto) block, and that ≥70% of the reward cycle's signer weight
 attested to that block. `verifyTransactionProof` recomputes everything
 client-side and trusts nothing the API returned.
@@ -314,7 +345,7 @@ fetchRewardSet(opts: {
 
 Exported types: `TransactionProof`, `TransactionProofVerifyResult`, `RewardSet`.
 
-## Stacks Subgraphs
+## Subgraphs
 
 Deploy and query app-specific tables.