@secondlayer/sdk 6.11.0 → 6.13.0

package/README.md

@@ -215,6 +215,75 @@ for await (const transfer of sl.index.ftTransfers.walk({
 }
 ```
 
+## Transaction-inclusion proofs
+
+Verify — **without trusting Second Layer** — 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.
+
+> Verification uses Node's crypto via `@secondlayer/shared` — Node/server-side use.
+
+```typescript
+import { verifyTransactionProof, fetchRewardSet } from "@secondlayer/sdk";
+
+const proof = await fetch(
+  `https://api.secondlayer.tools/v1/index/transactions/${txid}/proof`,
+).then((r) => r.json());
+
+const result = verifyTransactionProof(proof); // anchored + consensus (embedded set)
+// result.ok, result.level === "consensus", result.signerWeightBps
+
+// Fully trustless — resolve the reward set from your own node:
+const rewardSet = await fetchRewardSet({
+  nodeUrl: "https://your-stacks-node:20443",
+  cycle: proof.consensus.reward_cycle,
+});
+const trustless = verifyTransactionProof(proof, { rewardSet }); // rewardSetSource: "provided"
+```
+
+Two trust levels:
+
+- **Anchored** — recompute the txid from `raw_tx`, fold `tx_merkle_path` up to the
+  header's `tx_merkle_root`, and recompute `block_hash` + `index_block_hash` from
+  `raw_header`. The tx is in a header any node can corroborate.
+- **Consensus** — additionally recover the header's signer signatures and confirm
+  ≥70% of the reward cycle's signer weight signed the block. Fully trustless when
+  you pass a `rewardSet` resolved yourself via `fetchRewardSet`
+  (`rewardSetSource: "provided"`); otherwise it uses the proof's embedded set
+  (`rewardSetSource: "embedded"`).
+
+```typescript
+verifyTransactionProof(
+  proof: TransactionProof,
+  opts?: { rewardSet?: RewardSet },
+): TransactionProofVerifyResult;
+
+fetchRewardSet(opts: {
+  nodeUrl: string;            // your own stacks-node
+  cycle: number;             // reward cycle — proof.consensus.reward_cycle
+  fetchImpl?: typeof fetch;
+}): Promise<RewardSet | null>; // reads /v3/stacker_set/{cycle}
+```
+
+`verifyTransactionProof` returns a `TransactionProofVerifyResult`:
+
+```typescript
+{
+  level: "anchored" | "consensus";
+  txidMatches: boolean;
+  includedInHeader: boolean;
+  headerSelfConsistent: boolean;
+  signerWeightBps?: number;   // consensus only
+  thresholdMet?: boolean;     // consensus only — ≥70% (7000 bps)
+  rewardSetSource?: "provided" | "embedded";
+  ok: boolean;
+  errors: string[];
+}
+```
+
+Exported types: `TransactionProof`, `TransactionProofVerifyResult`, `RewardSet`.
+
 ## Stacks Subgraphs
 
 Deploy and query app-specific L3 tables.

package/dist/index.d.ts

@@ -337,6 +337,27 @@ type IndexTip = {
 	block_height: number
 	lag_seconds: number
 };
+/**
+* A chain reorg overlapping a returned page's height range. Height-keyed feeds
+* (`/transactions`, `/contract-calls`, `/stacking`) populate this so a consumer
+* can reconcile: roll back the rows whose `block_height:tx_index` cursor falls in
+* `orphaned_range`, then re-fetch from `new_canonical_tip`. Empty when the page
+* spans no reorg.
+*/
+type IndexReorg = {
+	id: string
+	detected_at: string
+	fork_point_height: number
+	old_index_block_hash: string | null
+	new_index_block_hash: string | null
+	/** Orphaned cursor span `<block_height>:<tx_index>`, inclusive. */
+	orphaned_range: {
+		from: string
+		to: string
+	}
+	/** New canonical tip cursor to resume from. */
+	new_canonical_tip: string
+};
 type IndexUsage = {
 	product: "index"
 	tier: string
@@ -365,7 +386,7 @@ type FtTransfersEnvelope = {
 	events: FtTransfer[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 };
 type FtTransfersListParams = {
 	cursor?: string | null
@@ -398,7 +419,7 @@ type NftTransfersEnvelope = {
 	events: NftTransfer[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 };
 type NftTransfersListParams = {
 	cursor?: string | null
@@ -502,7 +523,7 @@ type EventsEnvelope = {
 	events: IndexEvent[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 };
 type EventsListParams = {
 	/** Required. One of the decoded event types. */
@@ -539,7 +560,7 @@ type ContractCallsEnvelope = {
 	contract_calls: IndexContractCall[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 };
 type ContractCallsListParams = {
 	cursor?: string | null
@@ -682,7 +703,7 @@ type TransactionsEnvelope = {
 	transactions: IndexTransaction[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 };
 type TransactionEnvelope = {
 	transaction: IndexTransaction
@@ -731,7 +752,7 @@ type StackingEnvelope = {
 	stacking: IndexStackingAction[]
 	next_cursor: string | null
 	tip: IndexTip
-	reorgs: never[]
+	reorgs: IndexReorg[]
 	/** Present only when the PoX-4 decoder is disabled, explaining an empty feed. */
 	notes?: string
 };
@@ -1807,10 +1828,90 @@ declare function verifyWebhookSignature(rawBody: string, headers: WebhookHeaderI
 * ```
 */
 declare function verifySecondlayerSignature(rawBody: string, headers: WebhookHeaderInput, publicKeyPem: string): boolean;
+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
+	};
+}
+interface TransactionProofVerifyResult {
+	/** Highest level actually verified. "consensus" requires the proof's
+	*  `consensus` field and a met signer-weight threshold. */
+	level: "anchored" | "consensus";
+	/** Recomputed txid === proof.txid. */
+	txidMatches: boolean;
+	/** Merkle path folds the txid to the header's tx_merkle_root. */
+	includedInHeader: boolean;
+	/** Recomputed block_hash + index_block_hash match the header / proof. */
+	headerSelfConsistent: boolean;
+	/** Basis points (0–10000) of reward-set signer weight that signed the block.
+	*  Only set when the proof carries a `consensus` field. */
+	signerWeightBps?: number;
+	/** ≥70% of signer weight signed. Only set with a `consensus` field. */
+	thresholdMet?: boolean;
+	/** Which reward set the signer check used: "provided" (caller-resolved →
+	*  fully trustless) or "embedded" (the one Secondlayer put in the proof). */
+	rewardSetSource?: "provided" | "embedded";
+	/** All applicable checks passed (incl. the threshold when consensus is present). */
+	ok: boolean;
+	errors: string[];
+}
+/**
+* Resolve a reward set directly from a stacks-node (`/v3/stacker_set/{cycle}`),
+* so a caller can verify the consensus layer against a node IT trusts rather than
+* the reward set Secondlayer embedded in the proof. Pass the result as
+* `verifyTransactionProof(proof, { rewardSet })`.
+*/
+declare function fetchRewardSet(opts: {
+	nodeUrl: string
+	cycle: number
+	fetchImpl?: typeof fetch
+}): Promise<RewardSet | null>;
+/**
+* Verify a transaction-inclusion proof. Every check is recomputed client-side,
+* so a `true` result does not rely on trusting Secondlayer. Pass
+* `{ rewardSet }` (resolved via {@link fetchRewardSet} from your own node) to
+* verify the consensus layer against a reward set you trust rather than the one
+* embedded in the proof.
+*/
+declare function verifyTransactionProof(proof: TransactionProof, opts?: {
+	rewardSet?: RewardSet
+}): TransactionProofVerifyResult;
+import { RewardSet as RewardSet2 } from "@secondlayer/shared/node/consensus";
 /** Make a cvToValue result JSON-serializable: Clarity (u)ints decode to bigint,
 *  which JSON.stringify can't handle — convert recursively to strings. */
 declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { verifyWebhookSignature, verifySecondlayerSignature, trigger, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, 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, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StackingWalkParams, StackingListParams, StackingEnvelope, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexPostCondition, IndexMempoolTransaction, IndexEventType, IndexEvent, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, 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, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CURSOR_SLUGS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiError, ActiveSubgraphOperation };
+export { verifyWebhookSignature, verifyTransactionProof, verifySecondlayerSignature, trigger, toJsonSafe, 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, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, 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, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StackingWalkParams, StackingListParams, StackingEnvelope, SecondLayerOptions, SecondLayer, ScopedKeyProduct, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStackingAction, IndexReorg, IndexPostCondition, IndexMempoolTransaction, IndexEventType, IndexEvent, IndexContractCall, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, 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, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContextSnapshot, ContextAccount, ChainTriggerType, ChainTrigger, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CURSOR_SLUGS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiError, ActiveSubgraphOperation };

package/dist/index.js

@@ -1965,8 +1965,84 @@ function verifySecondlayerSignature(rawBody, headers, publicKeyPem) {
   const signature = pickHeader(headers, "x-secondlayer-signature");
   return verifySecondlayerSignatureValues(rawBody, id, signature, publicKeyPem);
 }
+// src/proofs.ts
+import {
+  verifySignerSignatures
+} from "@secondlayer/shared/node/consensus";
+import {
+  nakamotoBlockHash,
+  nakamotoBlockId,
+  parseNakamotoBlockHeader,
+  stacksTxid,
+  verifyTxMerkleProof
+} from "@secondlayer/shared/node/nakamoto";
+var strip = (h) => h.startsWith("0x") ? h.slice(2) : h;
+var bytes = (h) => Uint8Array.from(Buffer.from(strip(h), "hex"));
+async function fetchRewardSet(opts) {
+  const f = opts.fetchImpl ?? fetch;
+  const res = await f(`${opts.nodeUrl.replace(/\/+$/, "")}/v3/stacker_set/${opts.cycle}`);
+  if (res.status === 404)
+    return null;
+  if (!res.ok) {
+    throw new Error(`/v3/stacker_set/${opts.cycle} returned ${res.status}`);
+  }
+  const body = await res.json();
+  const signers = body.stacker_set.signers.map((s) => ({
+    signing_key: strip(s.signing_key),
+    weight: s.weight
+  }));
+  return {
+    signers,
+    total_weight: signers.reduce((sum, s) => sum + s.weight, 0)
+  };
+}
+function verifyTransactionProof(proof, opts) {
+  const errors = [];
+  const computedTxid = stacksTxid(bytes(proof.raw_tx));
+  const txidMatches = computedTxid === strip(proof.txid);
+  if (!txidMatches)
+    errors.push("txid does not match raw_tx");
+  const header = parseNakamotoBlockHeader(bytes(proof.raw_header));
+  const includedInHeader = verifyTxMerkleProof(computedTxid, proof.tx_merkle_path, header.txMerkleRoot);
+  if (!includedInHeader)
+    errors.push("merkle path does not reach tx_merkle_root");
+  const blockHash = nakamotoBlockHash(header);
+  const indexBlockHash = nakamotoBlockId(blockHash, header.consensusHash);
+  const headerSelfConsistent = indexBlockHash === strip(proof.index_block_hash);
+  if (!headerSelfConsistent) {
+    errors.push("recomputed index_block_hash does not match proof");
+  }
+  const anchoredOk = txidMatches && includedInHeader && headerSelfConsistent;
+  const rewardSet = opts?.rewardSet ?? proof.consensus?.reward_set;
+  let level = "anchored";
+  let signerWeightBps;
+  let thresholdMet;
+  let rewardSetSource;
+  if (rewardSet) {
+    const v = verifySignerSignatures(blockHash, header.signerSignatures, rewardSet);
+    signerWeightBps = v.totalWeight > 0 ? Math.round(v.signedWeight / v.totalWeight * 1e4) : 0;
+    thresholdMet = v.thresholdMet;
+    rewardSetSource = opts?.rewardSet ? "provided" : "embedded";
+    if (!thresholdMet)
+      errors.push("signer weight below the 70% threshold");
+    if (anchoredOk && thresholdMet)
+      level = "consensus";
+  }
+  return {
+    level,
+    txidMatches,
+    includedInHeader,
+    headerSelfConsistent,
+    signerWeightBps,
+    thresholdMet,
+    rewardSetSource,
+    ok: anchoredOk && (rewardSet ? thresholdMet === true : true),
+    errors
+  };
+}
 export {
   verifyWebhookSignature,
+  verifyTransactionProof,
   verifySecondlayerSignature,
   trigger,
   toJsonSafe,
@@ -1982,6 +2058,7 @@ export {
   isFtMint,
   isFtBurn,
   getSubgraph,
+  fetchRewardSet,
   decodeStxTransfer,
   decodeStxMint,
   decodeStxLock,
@@ -2013,5 +2090,5 @@ export {
   ApiError
 };
 
-//# debugId=7E891A303DCCD65B64756E2164756E21
+//# debugId=5E490BEDE2791EFC64756E2164756E21
 //# sourceMappingURL=index.js.map