@secondlayer/sdk 6.1.0 → 6.2.0

package/dist/subgraphs/index.d.ts

@@ -105,6 +105,170 @@ declare class Subgraphs extends BaseClient {
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
+/**
+* Typed client for the contract-discovery API (`GET /v1/contracts`).
+*
+* "Find all contracts conforming to a trait" — backed by the contract registry:
+* `declared` traits parsed from Clarity source, `inferred` standards from static
+* ABI shape-matching. Anonymous public read. `trait` is required; the ABI blob is
+* omitted unless `include: "abi"` is passed.
+*/
+/** Whether a trait match must be declared in source, inferred from ABI, or either. */
+type ContractConformance = "declared" | "inferred" | "any";
+interface ContractsListParams {
+	/** Required. Trait identifier to match (e.g. "sip-010", or a fully-qualified trait). */
+	trait: string;
+	/** Match source. Defaults to "any" server-side. */
+	conformance?: ContractConformance;
+	/** Set to "abi" to include the full ABI blob in each row. */
+	include?: "abi";
+	/** Page size, 1–500 (default 100 server-side). */
+	limit?: number;
+	/** Opaque cursor from a prior response's `next_cursor`. */
+	cursor?: string;
+}
+interface ContractSummary {
+	contract_id: string;
+	deployer: string;
+	block_height: number;
+	declared_traits: string[] | null;
+	inferred_standards: string[] | null;
+	abi_status: string;
+	/** Present only when `include: "abi"` was requested. */
+	abi?: unknown;
+}
+interface ContractsEnvelope {
+	contracts: ContractSummary[];
+	next_cursor: string | null;
+}
+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>;
+}
+/**
+* Typed client for the Foundation Datasets REST API (`/v1/datasets/*`).
+*
+* Most datasets are cursor-paginated event lists with a uniform `list`/`walk`
+* surface; a few (bns names/namespaces/resolve, network-health) are
+* offset/single-object/summary and get bespoke methods. Query params are typed
+* per dataset; rows are `DatasetRow` (JSON) in v1 — per-dataset row interfaces
+* are a fast-follow.
+*/
+/** A dataset row — flat JSON object. Per-dataset interfaces are a follow-up. */
+type DatasetRow = Record<string, unknown>;
+/** Filters shared by every cursor-paginated dataset. */
+interface CursorListParams {
+	cursor?: string;
+	limit?: number;
+	fromBlock?: number;
+	toBlock?: number;
+}
+interface CursorEnvelope {
+	rows: DatasetRow[];
+	next_cursor: string | null;
+	tip?: {
+		block_height: number
+	};
+}
+type RangeFilters = CursorListParams;
+type StxTransfersParams = RangeFilters & {
+	sender?: string
+	recipient?: string
+};
+type SbtcEventsParams = RangeFilters & {
+	topic?: string
+	address?: string
+};
+type SbtcTokenEventsParams = RangeFilters & {
+	eventType?: string
+	sender?: string
+	recipient?: string
+};
+type Pox4CallsParams = RangeFilters & {
+	functionName?: string
+	stacker?: string
+	delegateTo?: string
+	signerKey?: string
+	rewardCycle?: number
+	/** Any-role: matches caller OR stacker OR delegate_to. */
+	address?: string
+};
+type BurnchainRewardsParams = RangeFilters & {
+	/** Filter to one Bitcoin reward address. */
+	recipient?: string
+};
+type BurnchainRewardSlotsParams = RangeFilters & {
+	/** Filter to one reward-set Bitcoin address. */
+	holder?: string
+};
+type BnsEventsParams = RangeFilters & {
+	topic?: string
+	namespace?: string
+	name?: string
+	owner?: string
+};
+type BnsNamespaceEventsParams = RangeFilters & {
+	status?: string
+	namespace?: string
+};
+type BnsMarketplaceEventsParams = RangeFilters & {
+	action?: string
+	bnsId?: string
+};
+type CursorDataset<P> = {
+	list: (params?: P) => Promise<CursorEnvelope>
+	walk: (params?: P & {
+		batchSize?: number
+		signal?: AbortSignal
+	}) => AsyncIterable<DatasetRow>
+};
+declare class Datasets extends BaseClient {
+	constructor(options?: Partial<SecondLayerOptions>);
+	/** Dataset catalog + freshness (the discovery endpoint). */
+	listDatasets(): Promise<unknown>;
+	/**
+	* Generic cursor query by slug — used by the CLI. Params are passed through as
+	* REST query keys (snake_case), so callers can use the documented filter names
+	* directly. Throws for non-cursor (bespoke) datasets.
+	*/
+	query(slug: string, params?: Record<string, unknown>): Promise<CursorEnvelope>;
+	readonly stxTransfers: CursorDataset<StxTransfersParams>;
+	readonly sbtcEvents: CursorDataset<SbtcEventsParams>;
+	readonly sbtcTokenEvents: CursorDataset<SbtcTokenEventsParams>;
+	readonly pox4Calls: CursorDataset<Pox4CallsParams>;
+	readonly burnchainRewards: CursorDataset<BurnchainRewardsParams>;
+	readonly burnchainRewardSlots: CursorDataset<BurnchainRewardSlotsParams>;
+	readonly bnsEvents: CursorDataset<BnsEventsParams>;
+	readonly bnsNamespaceEvents: CursorDataset<BnsNamespaceEventsParams>;
+	readonly bnsMarketplaceEvents: CursorDataset<BnsMarketplaceEventsParams>;
+	/** BNS names — offset-paginated. */
+	bnsNames(params?: {
+		namespace?: string
+		owner?: string
+		limit?: number
+		offset?: number
+	}): Promise<{
+		names: DatasetRow[]
+	}>;
+	/** All BNS namespaces (no pagination). */
+	bnsNamespaces(): Promise<{
+		namespaces: DatasetRow[]
+	}>;
+	/** Resolve a fully-qualified BNS name → single record. */
+	bnsResolve(fqn: string): Promise<{
+		name: DatasetRow | null
+	}>;
+	/** Network health summary. */
+	networkHealth(): Promise<{
+		summary: DatasetRow
+	}>;
+	private get;
+	/** Map camelCase filter fields to snake_case query keys (dropping pagination
+	*  controls) and build the canonical query suffix. */
+	private paramsToQuery;
+	private cursorDataset;
+}
 type IndexTip = {
 	block_height: number
 	lag_seconds: number
@@ -701,6 +865,8 @@ declare class Subscriptions extends BaseClient {
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
 	readonly index: Index;
+	readonly datasets: Datasets;
+	readonly contracts: Contracts;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);

package/dist/subgraphs/index.js

@@ -324,6 +324,142 @@ class Subgraphs extends BaseClient {
     };
   }
 }
+// src/contracts/client.ts
+class Contracts extends BaseClient {
+  constructor(options = {}) {
+    super(options);
+  }
+  list(params) {
+    return this.request("GET", `/v1/contracts${buildQuery({
+      trait: params.trait,
+      conformance: params.conformance,
+      include: params.include,
+      limit: params.limit,
+      cursor: params.cursor
+    })}`);
+  }
+}
+
+// src/datasets/client.ts
+var PARAM_KEYS = {
+  fromBlock: "from_block",
+  toBlock: "to_block",
+  functionName: "function_name",
+  delegateTo: "delegate_to",
+  signerKey: "signer_key",
+  rewardCycle: "reward_cycle",
+  eventType: "event_type",
+  bnsId: "bns_id"
+};
+var CURSOR_SLUGS = {
+  "stx-transfers": { path: "stx-transfers", rowKey: "events" },
+  "sbtc-events": { path: "sbtc/events", rowKey: "events" },
+  "sbtc-token-events": { path: "sbtc/token-events", rowKey: "events" },
+  "pox-4-calls": { path: "pox-4/calls", rowKey: "calls" },
+  "burnchain-rewards": { path: "burnchain/rewards", rowKey: "rewards" },
+  "burnchain-reward-slots": {
+    path: "burnchain/reward-slots",
+    rowKey: "slots"
+  },
+  "bns-events": { path: "bns/events", rowKey: "events" },
+  "bns-namespace-events": { path: "bns/namespace-events", rowKey: "events" },
+  "bns-marketplace-events": {
+    path: "bns/marketplace-events",
+    rowKey: "events"
+  }
+};
+
+class Datasets extends BaseClient {
+  constructor(options = {}) {
+    super(options);
+  }
+  listDatasets() {
+    return this.request("GET", "/v1/datasets");
+  }
+  async query(slug, params = {}) {
+    const d = CURSOR_SLUGS[slug];
+    if (!d) {
+      throw new Error(`unknown cursor dataset "${slug}" (use one of: ${Object.keys(CURSOR_SLUGS).join(", ")})`);
+    }
+    const env = await this.get(d.path, this.paramsToQuery(params));
+    return {
+      rows: env[d.rowKey] ?? [],
+      next_cursor: env.next_cursor ?? null,
+      tip: env.tip
+    };
+  }
+  stxTransfers = this.cursorDataset("stx-transfers", "events");
+  sbtcEvents = this.cursorDataset("sbtc/events", "events");
+  sbtcTokenEvents = this.cursorDataset("sbtc/token-events", "events");
+  pox4Calls = this.cursorDataset("pox-4/calls", "calls");
+  burnchainRewards = this.cursorDataset("burnchain/rewards", "rewards");
+  burnchainRewardSlots = this.cursorDataset("burnchain/reward-slots", "slots");
+  bnsEvents = this.cursorDataset("bns/events", "events");
+  bnsNamespaceEvents = this.cursorDataset("bns/namespace-events", "events");
+  bnsMarketplaceEvents = this.cursorDataset("bns/marketplace-events", "events");
+  bnsNames(params = {}) {
+    return this.get("bns/names", buildQuery({
+      namespace: params.namespace,
+      owner: params.owner,
+      limit: params.limit,
+      offset: params.offset
+    }));
+  }
+  bnsNamespaces() {
+    return this.get("bns/namespaces", "");
+  }
+  bnsResolve(fqn) {
+    return this.get("bns/resolve", buildQuery({ fqn }));
+  }
+  networkHealth() {
+    return this.get("network-health/summary", "");
+  }
+  get(path, query) {
+    return this.request("GET", `/v1/datasets/${path}${query}`);
+  }
+  paramsToQuery(params) {
+    const mapped = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || k === "batchSize" || k === "signal")
+        continue;
+      mapped[PARAM_KEYS[k] ?? k] = v;
+    }
+    return buildQuery(mapped);
+  }
+  cursorDataset(path, rowKey) {
+    const list = async (params = {}) => {
+      const envelope = await this.get(path, this.paramsToQuery(params));
+      return {
+        rows: envelope[rowKey] ?? [],
+        next_cursor: envelope.next_cursor ?? null,
+        tip: envelope.tip
+      };
+    };
+    const walk = async function* (params = {}) {
+      const batchSize = params.batchSize ?? 200;
+      let cursor = params.cursor ?? null;
+      let first = true;
+      while (!params.signal?.aborted) {
+        const env = await list({
+          ...params,
+          limit: batchSize,
+          cursor: first ? params.cursor : cursor ?? undefined
+        });
+        for (const row of env.rows) {
+          if (params.signal?.aborted)
+            return;
+          yield row;
+        }
+        if (!env.next_cursor || env.next_cursor === cursor || env.rows.length < batchSize)
+          return;
+        cursor = env.next_cursor;
+        first = false;
+      }
+    }.bind(this);
+    return { list, walk };
+  }
+}
+
 // src/index-api/client.ts
 function firstWalkFromHeight(params) {
   if (params.fromHeight !== undefined)
@@ -1017,6 +1153,8 @@ class Subscriptions extends BaseClient {
 class SecondLayer extends BaseClient {
   streams;
   index;
+  datasets;
+  contracts;
   subgraphs;
   subscriptions;
   constructor(options = {}) {
@@ -1027,6 +1165,8 @@ class SecondLayer extends BaseClient {
       fetchImpl: options.fetchImpl
     });
     this.index = new Index(options);
+    this.datasets = new Datasets(options);
+    this.contracts = new Contracts(options);
     this.subgraphs = new Subgraphs(options);
     this.subscriptions = new Subscriptions(options);
   }
@@ -1047,5 +1187,5 @@ export {
   Subgraphs
 };
 
-//# debugId=CDC19E41AE11FF9164756E2164756E21
+//# debugId=9C60733D992A531964756E2164756E21
 //# sourceMappingURL=index.js.map