@secondlayer/sdk 6.18.0 → 6.20.0

package/dist/subgraphs/index.d.ts

@@ -52,6 +52,16 @@ interface SubgraphOperationStatus {
 	createdAt: string;
 	updatedAt: string;
 }
+/** /v1 cursor envelope for subgraph table reads. */
+interface SubgraphRowsEnvelope<T = unknown> {
+	rows: T[];
+	next_cursor: string | null;
+	tip: {
+		block_height: number
+		subgraph_height: number
+		blocks_behind: number
+	};
+}
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
@@ -94,6 +104,29 @@ declare class Subgraphs extends BaseClient {
 	}): Promise<{
 		message: string
 	}>;
+	/**
+	* Publish: claim the name in the global public namespace and open anon
+	* reads on /v1/subgraphs/:name. 409 PUBLIC_NAME_TAKEN if another account
+	* holds the public name.
+	*/
+	publish(name: string): Promise<{
+		name: string
+		visibility: "public"
+		url: string
+	}>;
+	/** Make reads private again (owning account's bearer key required). */
+	unpublish(name: string): Promise<{
+		name: string
+		visibility: "private"
+	}>;
+	/**
+	* Open /v1 read: cursor-paginated rows. Anon works for public subgraphs;
+	* pass an apiKey on the client for private ones. Resume with the returned
+	* `next_cursor`.
+	*/
+	rows<T = unknown>(name: string, table: string, params?: Omit<SubgraphQueryParams, "offset" | "sort"> & {
+		cursor?: string
+	}): Promise<SubgraphRowsEnvelope<T>>;
 	/** Recent reindex/backfill operations for a subgraph, newest first. */
 	operations(name: string): Promise<{
 		operations: SubgraphOperationStatus[]
@@ -232,6 +265,13 @@ declare class Contracts extends BaseClient {
 	constructor(options?: Partial<SecondLayerOptions>);
 	/** Find contracts conforming to `trait`. `trait` is required (server 400s without it). */
 	list(params: ContractsListParams): Promise<ContractsEnvelope>;
+	/**
+	* Fetch a single contract from the registry by id (the prod-safe ABI source).
+	* Pass `{ includeAbi: true }` for the full ABI blob. Resolves null on 404.
+	*/
+	get(contractId: string, opts?: {
+		includeAbi?: boolean
+	}): Promise<ContractSummary | null>;
 }
 /**
 * Typed client for the Foundation Datasets REST API (`/v1/datasets/*`).
@@ -377,6 +417,42 @@ declare class Datasets extends BaseClient {
 	private paramsToQuery;
 	private cursorDataset;
 }
+import { RewardSet } from "@secondlayer/shared/node/consensus";
+import { MerkleProofStep } from "@secondlayer/shared/node/nakamoto";
+/**
+* Trustless transaction-inclusion proof verification.
+*
+* Given a proof from `GET /v1/index/transactions/:txid/proof`, the consumer
+* re-derives everything itself — it does NOT trust any value Secondlayer
+* computed. Anchored level: (1) recompute the txid from the raw tx bytes, (2)
+* fold it up the merkle path to the header's `tx_merkle_root`, (3) recompute the
+* header's `block_hash` and `index_block_hash` from the raw header — "this tx is
+* included in a header any node can corroborate". Consensus level (when the proof
+* carries a `consensus` field, or a `rewardSet` is passed): additionally recover
+* the header's signer signatures and confirm ≥70% of reward-set signer weight
+* signed the block.
+*
+* Note: uses Node's crypto via `@secondlayer/shared` (same as the Streams
+* signature verify); intended for Node/server verification.
+*/
+interface TransactionProof {
+	txid: string;
+	index_block_hash: string;
+	block_height: number;
+	tx_index: number;
+	/** Raw consensus-serialized transaction bytes (hex). */
+	raw_tx: string;
+	/** Raw Nakamoto block-header bytes (hex) — parsed + re-hashed by the verifier. */
+	raw_header: string;
+	/** Authentication path from the tx leaf to `tx_merkle_root`. */
+	tx_merkle_path: MerkleProofStep[];
+	/** Present when consensus-level verification is available: the reward cycle and
+	*  its signer set, against which the header's signer signatures are checked. */
+	consensus?: {
+		reward_cycle: number
+		reward_set: RewardSet
+	};
+}
 type IndexTip = {
 	block_height: number
 	lag_seconds: number
@@ -877,6 +953,30 @@ type MempoolWalkParams = Omit<MempoolListParams, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
+/**
+* `index.ftTransfers` — callable shorthand for `.list()`, with `.list`/`.walk`
+* still available: `await sl.index.ftTransfers({ contractId })`.
+*
+* The API accepts `contract_id`/`sender`/`recipient` equality filters only —
+* no amount filtering and no asset-slug resolution on /v1/index/ft-transfers.
+*/
+interface FtTransfersResource {
+	(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	list(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	walk(params?: FtTransfersWalkParams): AsyncIterable<FtTransfer>;
+}
+/** `index.nftTransfers` — callable shorthand for `.list()` (see {@link FtTransfersResource}). */
+interface NftTransfersResource {
+	(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	list(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	walk(params?: NftTransfersWalkParams): AsyncIterable<NftTransfer>;
+}
+/** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
+interface IndexEventsResource {
+	(params: EventsListParams): Promise<EventsEnvelope>;
+	list(params: EventsListParams): Promise<EventsEnvelope>;
+	walk(params: EventsWalkParams): AsyncIterable<IndexEvent>;
+}
 /** Per-event-type filter vocabulary in the {@link IndexDiscovery} doc. */
 type IndexEventTypeFilters = {
 	columns?: string[]
@@ -901,19 +1001,13 @@ declare class Index extends BaseClient {
 	* learn what's queryable (and which types accept `trait`) instead of hardcoding.
 	*/
 	discover(): Promise<IndexDiscovery>;
-	readonly ftTransfers: {
-		list: (params?: FtTransfersListParams) => Promise<FtTransfersEnvelope>
-		walk: (params?: FtTransfersWalkParams) => AsyncIterable<FtTransfer>
-	};
-	readonly nftTransfers: {
-		list: (params?: NftTransfersListParams) => Promise<NftTransfersEnvelope>
-		walk: (params?: NftTransfersWalkParams) => AsyncIterable<NftTransfer>
-	};
-	/** Generic decoded events by `event_type` (the full /v1/index/events surface). */
-	readonly events: {
-		list: (params: EventsListParams) => Promise<EventsEnvelope>
-		walk: (params: EventsWalkParams) => AsyncIterable<IndexEvent>
-	};
+	/** Callable: `index.ftTransfers(params)` ≡ `index.ftTransfers.list(params)`. */
+	readonly ftTransfers: FtTransfersResource;
+	/** Callable: `index.nftTransfers(params)` ≡ `index.nftTransfers.list(params)`. */
+	readonly nftTransfers: NftTransfersResource;
+	/** Generic decoded events by `event_type` (the full /v1/index/events surface).
+	*  Callable: `index.events(params)` ≡ `index.events.list(params)`. */
+	readonly events: IndexEventsResource;
 	readonly contractCalls: {
 		list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>
 		walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>
@@ -936,6 +1030,7 @@ declare class Index extends BaseClient {
 		list: (params?: TransactionsListParams) => Promise<TransactionsEnvelope>
 		walk: (params?: TransactionsWalkParams) => AsyncIterable<IndexTransaction>
 		get: (txId: string) => Promise<TransactionEnvelope | null>
+		getProof: (txId: string) => Promise<TransactionProof | null>
 	};
 	/** Decoded PoX-4 stacking actions. Empty (with a `notes` hint) when the
 	*  platform's PoX-4 decoder is disabled. */
@@ -965,6 +1060,11 @@ declare class Index extends BaseClient {
 	private walkBlocks;
 	private listTransactions;
 	private getTransaction;
+	/** Fetch the inclusion proof for a tx (raw tx + Nakamoto header + merkle path)
+	*  to verify client-side with `verifyTransactionProof`. 404 → null. A 503
+	*  (`PROOF_TX_SET_INCOMPLETE` / `PROOF_NODE_UNAVAILABLE`) surfaces as an
+	*  ApiError — the proof can't be assembled on this deployment right now. */
+	private getTransactionProof;
 	private walkTransactions;
 	private listStacking;
 	private walkStacking;
@@ -1289,6 +1389,36 @@ type StreamsEventsConsumeParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+/**
+* One yielded page from {@link StreamsClient.consume} — the
+* `GET /v1/streams/events` envelope verbatim, with `next_cursor` renamed to
+* `cursor` (the checkpoint to persist and resume from).
+*/
+type StreamsBatch = {
+	/** Canonical events of this page, in cursor order. */
+	events: StreamsEvent[]
+	/** Checkpoint after this page — pass back as `consume({ cursor })` to resume. */
+	cursor: string | null
+	tip: StreamsTip
+	/** Chain reorgs reported alongside this page; empty when none. */
+	reorgs: StreamsReorg[]
+};
+type StreamsConsumeParams = {
+	/** Resume strictly after this cursor; omit to start from the oldest seekable page. */
+	cursor?: string | null
+	types?: readonly StreamsEventType[]
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
+	/** Events per page (the `limit` query param). Default 100. */
+	batchSize?: number
+	/** Poll interval while caught up at the tip, in ms. Default 2000. */
+	intervalMs?: number
+	/** Abort to end the iteration. */
+	signal?: AbortSignal
+};
 type StreamsEventsConsumeResult = {
 	cursor: string | null
 	pages: number
@@ -1356,6 +1486,21 @@ type StreamsDumps = {
 	download(file: StreamsDumpFile): Promise<Uint8Array>
 };
 type StreamsClient = {
+	/**
+	* Follow Streams as an async iterator of page batches.
+	*
+	* Yields one {@link StreamsBatch} per `GET /v1/streams/events` page — the
+	* existing envelope (`events`, `next_cursor` → `cursor`, `tip`, `reorgs`)
+	* with zero extra API calls. Batches are chosen over per-block groupings
+	* because the envelope is page-keyed, so every yield is exactly one fetch.
+	* Empty pages are skipped; at the tip the iterator re-polls every
+	* `intervalMs` (default 2000) until aborted via `signal`.
+	*
+	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
+	* rewound automatically — use `events.consume` with `onReorg` for managed
+	* rollback semantics.
+	*/
+	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>
 	events: {
 		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
 		byTxId(txId: string): Promise<StreamsEventsListEnvelope>

package/dist/subgraphs/index.js

@@ -281,6 +281,19 @@ class Subgraphs extends BaseClient {
     const qs = options?.force ? "?force=true" : "";
     return this.request("DELETE", `/api/subgraphs/${name}${qs}`);
   }
+  async publish(name) {
+    return this.request("POST", `/api/subgraphs/${name}/publish`);
+  }
+  async unpublish(name) {
+    return this.request("POST", `/api/subgraphs/${name}/unpublish`);
+  }
+  async rows(name, table, params = {}) {
+    const { cursor, ...rest } = params;
+    const qs = buildSubgraphQueryString(rest);
+    const sep = qs ? "&" : "?";
+    const cursorQs = cursor ? `${sep}cursor=${encodeURIComponent(cursor)}` : "";
+    return this.request("GET", `/v1/subgraphs/${name}/${table}${qs}${cursorQs}`);
+  }
   async operations(name) {
     return this.request("GET", `/api/subgraphs/${name}/operations`);
   }
@@ -417,6 +430,16 @@ class Contracts extends BaseClient {
       cursor: params.cursor
     })}`);
   }
+  async get(contractId, opts = {}) {
+    try {
+      const { contract } = await this.request("GET", `/v1/contracts/${encodeURIComponent(contractId)}${opts.includeAbi ? "?include=abi" : ""}`);
+      return contract;
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404)
+        return null;
+      throw err;
+    }
+  }
 }
 
 // src/datasets/client.ts
@@ -596,18 +619,18 @@ class Index extends BaseClient {
   discover() {
     return this.request("GET", "/v1/index");
   }
-  ftTransfers = {
+  ftTransfers = Object.assign((params = {}) => this.listFtTransfers(params), {
     list: (params = {}) => this.listFtTransfers(params),
     walk: (params = {}) => this.walkFtTransfers(params)
-  };
-  nftTransfers = {
+  });
+  nftTransfers = Object.assign((params = {}) => this.listNftTransfers(params), {
     list: (params = {}) => this.listNftTransfers(params),
     walk: (params = {}) => this.walkNftTransfers(params)
-  };
-  events = {
+  });
+  events = Object.assign((params) => this.listEvents(params), {
     list: (params) => this.listEvents(params),
     walk: (params) => this.walkEvents(params)
-  };
+  });
   contractCalls = {
     list: (params = {}) => this.listContractCalls(params),
     walk: (params = {}) => this.walkContractCalls(params)
@@ -624,7 +647,8 @@ class Index extends BaseClient {
   transactions = {
     list: (params = {}) => this.listTransactions(params),
     walk: (params = {}) => this.walkTransactions(params),
-    get: (txId) => this.getTransaction(txId)
+    get: (txId) => this.getTransaction(txId),
+    getProof: (txId) => this.getTransactionProof(txId)
   };
   stacking = {
     list: (params = {}) => this.listStacking(params),
@@ -886,6 +910,15 @@ class Index extends BaseClient {
       throw err;
     }
   }
+  async getTransactionProof(txId) {
+    try {
+      return await this.request("GET", `/v1/index/transactions/${encodeURIComponent(txId)}/proof`);
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404)
+        return null;
+      throw err;
+    }
+  }
   async* walkTransactions(params = {}) {
     const batchSize = params.batchSize ?? 200;
     let cursor = params.cursor ?? params.fromCursor ?? null;
@@ -1162,6 +1195,38 @@ async function consumeStreamsEvents(opts) {
   }
   return { cursor, pages, emptyPolls };
 }
+async function* iterateStreamsBatches(opts) {
+  const sleep = opts.sleep ?? defaultSleep;
+  let cursor = opts.fromCursor ?? null;
+  while (!opts.signal?.aborted) {
+    const envelope = await opts.fetchEvents({
+      cursor,
+      limit: opts.batchSize,
+      types: opts.types,
+      notTypes: opts.notTypes,
+      contractId: opts.contractId,
+      sender: opts.sender,
+      recipient: opts.recipient,
+      assetIdentifier: opts.assetIdentifier
+    });
+    const checkpoint = envelope.next_cursor ?? cursor;
+    if (envelope.events.length > 0 || envelope.reorgs.length > 0) {
+      yield {
+        events: envelope.events,
+        cursor: checkpoint,
+        tip: envelope.tip,
+        reorgs: envelope.reorgs
+      };
+    }
+    const advanced = checkpoint !== null && checkpoint !== cursor;
+    cursor = checkpoint;
+    if (!advanced && envelope.events.length === 0) {
+      if (opts.signal?.aborted)
+        return;
+      await sleep(opts.intervalMs, opts.signal);
+    }
+  }
+}
 async function* streamStreamsEvents(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
@@ -1539,6 +1604,21 @@ function createStreamsClient(options) {
     })}`);
   }
   return {
+    consume(params = {}) {
+      return iterateStreamsBatches({
+        fromCursor: params.cursor,
+        batchSize: params.batchSize ?? 100,
+        intervalMs: params.intervalMs ?? 2000,
+        types: params.types,
+        notTypes: params.notTypes,
+        contractId: params.contractId,
+        sender: params.sender,
+        recipient: params.recipient,
+        assetIdentifier: params.assetIdentifier,
+        signal: params.signal,
+        fetchEvents
+      });
+    },
     events: {
       list: listEvents,
       byTxId(txId) {
@@ -1795,5 +1875,5 @@ export {
   Subgraphs
 };
 
-//# debugId=A5185B837644857464756E2164756E21
+//# debugId=DD9EE9C3CECE53B564756E2164756E21
 //# sourceMappingURL=index.js.map