@secondlayer/cli 11.0.0 → 12.1.0

package/dist/cli.js

@@ -10414,9 +10414,9 @@ function lowercaseKeys(object) {
 
 // ../../node_modules/responselike/index.js
 import { Readable as ReadableStream2 } from "node:stream";
-var Response;
+var Response2;
 var init_responselike = __esm(() => {
-  Response = class Response extends ReadableStream2 {
+  Response2 = class Response2 extends ReadableStream2 {
     statusCode;
     headers;
     body;
@@ -10854,7 +10854,7 @@ class CacheableRequest {
                 response.once("end", resolve);
               });
               const headers = convertHeaders(revalidatedPolicy.policy.responseHeaders());
-              response = new Response({ statusCode: revalidate.statusCode, headers, body: revalidate.body, url: revalidate.url });
+              response = new Response2({ statusCode: revalidate.statusCode, headers, body: revalidate.body, url: revalidate.url });
               response.cachePolicy = revalidatedPolicy.policy;
               response.fromCache = true;
             }
@@ -10930,7 +10930,7 @@ class CacheableRequest {
           const policy = import_http_cache_semantics.default.fromObject(cacheEntry.cachePolicy);
           if (policy.satisfiesWithoutRevalidation(options_) && !options_.forceRefresh) {
             const headers = convertHeaders(policy.responseHeaders());
-            const response = new Response({ statusCode: cacheEntry.statusCode, headers, body: cacheEntry.body, url: cacheEntry.url });
+            const response = new Response2({ statusCode: cacheEntry.statusCode, headers, body: cacheEntry.body, url: cacheEntry.url });
             response.cachePolicy = policy;
             response.fromCache = true;
             ee.emit("response", response);
@@ -28878,23 +28878,8 @@ var init_require_auth = __esm(() => {
 });
 
 // src/templates/subgraph.ts
-function generateSubgraphTemplate(name, slug = "basic") {
-  const body = (() => {
-    switch (slug) {
-      case "sip-010-balances":
-        return sip010Balances(name);
-      case "sbtc-flows":
-        return sbtcFlows(name);
-      case "pox-stacking":
-        return poxStacking(name);
-      case "bns-names":
-        return bnsNames(name);
-      default:
-        return basic(name);
-    }
-  })();
-  return `${nextStepsHeader(name)}
-${body}`;
+function generateSubgraphStarter(name) {
+  return `${nextStepsHeader(name)}${starter(name)}`;
 }
 function nextStepsHeader(name) {
   return `// ───────────────────────────────────────────────────────────────────
@@ -28903,20 +28888,19 @@ function nextStepsHeader(name) {
 //   1. Edit the source filter + schema below to match what you want to track.
 //   2. Edit the handler at the bottom — it runs once per matching event.
 //   3. Deploy:   secondlayer subgraphs deploy ${name}.ts
-//      (You'll be prompted to log in if this is your first remote deploy.)
 //   4. Wait for sync:   secondlayer subgraphs status ${name}
-//      Mainnet backfill from genesis can take an hour or more depending on
-//      your filter scope. Use --start-block to skip ahead.
+//      Backfill from genesis can take an hour or more depending on your
+//      filter scope. Use --start-block to skip ahead.
 //   5. Query:    secondlayer subgraphs query ${name} <table-name>
-//      Or hit the auto-generated REST endpoint listed in the deploy output.
+//      Or hit the REST endpoint listed in the deploy output.
 //
-// Bind a typed Subscription to any table you write here — see
-// https://www.secondlayer.tools/docs/subscriptions
+// Prefer generating from a real contract:
+//   secondlayer subgraphs create ${name} --from-contract SP....my-contract
 // ───────────────────────────────────────────────────────────────────
 
 `;
 }
-function basic(name) {
+function starter(name) {
   return `import { defineSubgraph } from "@secondlayer/subgraphs";
 
 export default defineSubgraph({
@@ -28924,7 +28908,7 @@ export default defineSubgraph({
   version: "1.0.0",
   description: "TODO: describe what this subgraph tracks",
 
-  // Sources define what blockchain data this subgraph processes.
+  // Sources define what chain data this subgraph processes.
   // Each source is named — the name becomes the handler key.
   //
   // Filter types:
@@ -28969,345 +28953,6 @@ export default defineSubgraph({
 });
 `;
 }
-function sip010Balances(name) {
-  return `import { defineSchema, defineSubgraph, readContractAt, type TypedSubgraphContext } from "@secondlayer/subgraphs";
-
-/**
- * Track SIP-010 token balances per (asset_identifier, holder).
- * Mirrors the shape of the curated sBTC token-events view
- * surface — but works for ANY SIP-010 token. Constrain to a single
- * token by adding \`assetIdentifier: "SP...token::token-name"\` to each
- * source filter.
- *
- * Balances are moved with \`ctx.increment\`, which applies a DELTA in one
- * atomic statement. That matters: a read-modify-write (findOne → compute →
- * upsert) loses concurrent updates to the same row, and it is not replay-safe
- * under \`backfillMode: "concurrent"\`. Deltas commute, so order doesn't
- * matter and a reorg rewind reverses cleanly via the journal.
- *
- * Token metadata (decimals/symbol) comes from the token contract itself via
- * \`readContractAt\`, so \`amount\` stops being a bare integer nobody can
- * render. The read is pinned to the block being processed — a handler stays a
- * pure function of its block — and \`cache: "contract-constant"\` says these
- * two values can never change for a given token, so each is fetched ONCE
- * instead of once per block.
- *
- * Query examples once deployed:
- *   GET /v1/subgraphs/${name}/balances?_search=SP1...
- *   GET /v1/subgraphs/${name}/balances?holder=SP1...
- *   GET /v1/subgraphs/${name}/tokens
- */
-
-/** The two SIP-010 read-only functions this subgraph calls. */
-const SIP010_ABI = {
-  functions: [
-    { name: "get-decimals", access: "read-only", args: [], outputs: { response: { ok: "uint128", error: "uint128" } } },
-    { name: "get-symbol", access: "read-only", args: [], outputs: { response: { ok: { "string-ascii": { length: 32 } }, error: "uint128" } } },
-  ],
-} as const;
-
-/** Tokens already labelled in this process — metadata is immutable, so one
- *  resolution per token is enough even across a backfill. */
-const labelled = new Set<string>();
-
-// Hoisted so the helper below can be typed against it.
-const schema = defineSchema({
-  balances: {
-    columns: {
-      asset_identifier: { type: "text", indexed: true, search: true },
-      holder: { type: "principal", indexed: true, search: true },
-      amount: { type: "uint" },
-    },
-    // increment() upserts on this key.
-    uniqueKeys: [["asset_identifier", "holder"]],
-  },
-  tokens: {
-    columns: {
-      asset_identifier: { type: "text", indexed: true },
-      contract_id: { type: "text" },
-      symbol: { type: "text" },
-      decimals: { type: "uint" },
-    },
-    uniqueKeys: [["asset_identifier"]],
-  },
-});
-
-export default defineSubgraph({
-  name: "${name}",
-  version: "1.0.0",
-  description: "Per-token balance tracking for any SIP-010 asset",
-
-  sources: {
-    transfer: { type: "ft_transfer" },
-    mint: { type: "ft_mint" },
-    burn: { type: "ft_burn" },
-  },
-
-  schema,
-
-  handlers: {
-    transfer: async (event, ctx) => {
-      await labelToken(event.assetIdentifier, ctx);
-      const amount = BigInt(event.amount ?? 0);
-      if (event.sender) {
-        ctx.increment("balances", { asset_identifier: event.assetIdentifier, holder: event.sender }, { amount: -amount });
-      }
-      if (event.recipient) {
-        ctx.increment("balances", { asset_identifier: event.assetIdentifier, holder: event.recipient }, { amount });
-      }
-    },
-    mint: (event, ctx) => {
-      if (event.recipient) {
-        ctx.increment("balances", { asset_identifier: event.assetIdentifier, holder: event.recipient }, { amount: BigInt(event.amount ?? 0) });
-      }
-    },
-    burn: (event, ctx) => {
-      if (event.sender) {
-        ctx.increment("balances", { asset_identifier: event.assetIdentifier, holder: event.sender }, { amount: -BigInt(event.amount ?? 0) });
-      }
-    },
-  },
-});
-
-/** Resolve a token's symbol + decimals from its contract, once. */
-async function labelToken(
-  assetIdentifier: string | undefined,
-  ctx: TypedSubgraphContext<typeof schema>,
-) {
-  if (!assetIdentifier || labelled.has(assetIdentifier)) return;
-  labelled.add(assetIdentifier);
-  const contractId = assetIdentifier.split("::")[0];
-  const token = readContractAt(ctx, contractId, SIP010_ABI, { cache: "contract-constant" });
-  const [decimals, symbol] = await Promise.all([
-    token.read.getDecimals({}),
-    token.read.getSymbol({}),
-  ]);
-  ctx.upsert("tokens", { asset_identifier: assetIdentifier }, { asset_identifier: assetIdentifier, contract_id: contractId, symbol, decimals });
-}
-`;
-}
-function sbtcFlows(name) {
-  return `import { defineSubgraph } from "@secondlayer/subgraphs";
-
-/**
- * Track sBTC protocol flows: deposits, withdrawals, signer rotations,
- * governance updates — your own indexed view of the sbtc-registry contract.
- *
- * Source contract: sbtc-registry (mainnet).
- *
- * Query examples once deployed:
- *   GET /v1/subgraphs/${name}/flows?topic=completed-deposit
- *   GET /v1/subgraphs/${name}/flows?topic=withdrawal-create
- */
-export default defineSubgraph({
-  name: "${name}",
-  version: "1.0.0",
-  description: "sBTC deposits, withdrawals, signer rotations, governance",
-
-  // Skip pre-sBTC history. Raise this (e.g., to a recent block near tip) for
-  // a smaller backfill, or lower it if you need every sBTC event from genesis.
-  startBlock: 860000,
-
-  sources: {
-    registry: {
-      type: "print_event",
-      contractId: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry",
-    },
-  },
-
-  schema: {
-    flows: {
-      columns: {
-        topic: { type: "text", indexed: true, search: true },
-        request_id: { type: "uint", nullable: true, indexed: true },
-        amount: { type: "text", nullable: true },
-        sender: { type: "principal", nullable: true, indexed: true },
-        bitcoin_txid: { type: "text", nullable: true, search: true },
-        burn_height: { type: "uint", nullable: true },
-      },
-    },
-  },
-
-  handlers: {
-    registry: (event, ctx) => {
-      if (!event.topic) return;
-      // event.data is untyped across topics — cast to the fields you read, or
-      // declare \`prints\` per topic on the source for fully typed event.data.
-      const data = event.data as {
-        requestId?: bigint;
-        amount?: bigint | string;
-        sender?: string;
-        bitcoinTxid?: string;
-        burnHeight?: bigint;
-      };
-      ctx.insert("flows", {
-        topic: event.topic,
-        request_id: data.requestId ?? null,
-        amount: data.amount != null ? String(data.amount) : null,
-        sender: data.sender ?? null,
-        bitcoin_txid: data.bitcoinTxid ?? null,
-        burn_height: data.burnHeight ?? null,
-      });
-    },
-  },
-});
-`;
-}
-function poxStacking(name) {
-  return `import { defineSubgraph } from "@secondlayer/subgraphs";
-import { POX5_ABI } from "@secondlayer/stacks/pox5";
-
-/**
- * Track PoX-5 \`stake\` calls with their arguments already decoded.
- *
- * pox-5 replaced pox-4 when Epoch 4.0 activated (Bitcoin block 960,230,
- * 2026-07-30). SIP-045 reshaped the API: stacking became bonds + staking, so
- * the entry point is \`stake\`, not \`stack-stx\`.
- *
- * The source pairs \`abi\` with \`functionName\`, which is what makes
- * \`event.input\` a typed, named argument set instead of positional
- * \`args[0] as bigint\`. Add one source per function you want to track.
- *
- * Query examples once deployed:
- *   GET /v1/subgraphs/${name}/calls?caller=SP1...
- *   GET /v1/subgraphs/${name}/calls?caller=SP1...
- */
-export default defineSubgraph({
-  name: "${name}",
-  version: "1.0.0",
-  description: "PoX-5 stake calls with decoded arguments",
-
-  sources: {
-    pox: {
-      type: "contract_call",
-      // pox-5 is the live PoX contract since Epoch 4.0 activated at Bitcoin
-      // block 960,230 (2026-07-30). Stacking history before that is pox-4 —
-      // point a second source at \`.pox-4\` if you need it.
-      contractId: "SP000000000000000000002Q6VF78.pox-5",
-      // \`abi\` + \`functionName\` together are what type \`event.input\`: the
-      // arguments cannot be typed without knowing which function was called.
-      // POX5_ABI ships \`as const\` in @secondlayer/stacks, so there is no
-      // hand-copied ABI to drift. Add a source per function you care about.
-      functionName: "stake",
-      abi: POX5_ABI,
-    },
-  },
-
-  schema: {
-    calls: {
-      columns: {
-        function_name: { type: "text", indexed: true, search: true },
-        caller: { type: "principal", indexed: true, search: true },
-        amount_ustx: { type: "uint" },
-        num_cycles: { type: "uint" },
-        result_ok: { type: "boolean" },
-      },
-    },
-  },
-
-  handlers: {
-    pox: (event, ctx) => {
-      // \`event.input\` is the decoded, named, typed argument set — no
-      // \`args[0] as bigint\`. Hover \`amountUstx\` and it is a bigint.
-      const resultHex = event.resultHex ?? "";
-      ctx.insert("calls", {
-        function_name: event.functionName || ctx.tx.functionName || "",
-        caller: ctx.tx.sender,
-        amount_ustx: event.input.amountUstx,
-        num_cycles: event.input.numCycles,
-        result_ok: resultHex.startsWith("0x07"), // 0x07 = response-ok type tag
-      });
-    },
-  },
-});
-`;
-}
-function bnsNames(name) {
-  return `import { defineSubgraph } from "@secondlayer/subgraphs";
-
-/**
- * Track BNS-V2 name lifecycle events — registrations, transfers,
- * renewals, burns, airdrops.
- *
- * Source: BNS-V2 print events (topic-discriminated payloads).
- *
- * Query examples once deployed:
- *   GET /v1/subgraphs/${name}/names?owner=SP1...
- *   GET /v1/subgraphs/${name}/names?_search=alice
- */
-export default defineSubgraph({
-  name: "${name}",
-  version: "1.0.0",
-  description: "BNS-V2 name ownership and lifecycle",
-
-  sources: {
-    bns: {
-      type: "print_event",
-      contractId: "SP2QEZ06AGJ3RKJPBV14SY1V5BBFNAW33D96YPGZF.BNS-V2",
-    },
-  },
-
-  schema: {
-    names: {
-      columns: {
-        topic: { type: "text", indexed: true },
-        namespace: { type: "text", indexed: true, search: true },
-        name: { type: "text", indexed: true, search: true },
-        fqn: { type: "text", indexed: true, search: true },
-        owner: { type: "principal", nullable: true, indexed: true, search: true },
-      },
-    },
-  },
-
-  handlers: {
-    bns: (event, ctx) => {
-      if (!event.topic) return;
-      const data = event.data as { namespace?: unknown; name?: unknown; owner?: string };
-      const namespace = decodeBuffUtf8(data.namespace);
-      const nameLabel = decodeBuffUtf8(data.name);
-      if (!namespace || !nameLabel) return;
-      ctx.insert("names", {
-        topic: event.topic,
-        namespace,
-        name: nameLabel,
-        fqn: \`\${nameLabel}.\${namespace}\`,
-        owner: event.topic === "burn-name" ? null : (data.owner ?? null),
-      });
-    },
-  },
-});
-
-function decodeBuffUtf8(value: unknown): string | null {
-  if (typeof value !== "string") return null;
-  const hex = value.startsWith("0x") ? value.slice(2) : value;
-  if (hex.length === 0) return null;
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  let end = bytes.length;
-  while (end > 0 && bytes[end - 1] === 0) end -= 1;
-  return new TextDecoder("utf-8").decode(bytes.subarray(0, end));
-}
-`;
-}
-var SUBGRAPH_TEMPLATE_SLUGS, SUBGRAPH_TEMPLATE_DESCRIPTIONS;
-var init_subgraph = __esm(() => {
-  SUBGRAPH_TEMPLATE_SLUGS = [
-    "basic",
-    "sip-010-balances",
-    "sbtc-flows",
-    "pox-stacking",
-    "bns-names"
-  ];
-  SUBGRAPH_TEMPLATE_DESCRIPTIONS = {
-    basic: "Empty starter — pick any source filter type",
-    "sip-010-balances": "SIP-010 token balances (transfers + mints + burns)",
-    "sbtc-flows": "sBTC protocol flows (deposits, withdrawals, signer rotations)",
-    "pox-stacking": "PoX-4 stacking lifecycle calls",
-    "bns-names": "BNS-V2 name ownership and lifecycle"
-  };
-});
 
 // src/commands/subgraph-test.ts
 var exports_subgraph_test = {};
@@ -29969,27 +29614,15 @@ function formatSubgraphSync(sync) {
 }
 function registerSubgraphsCommand(program2) {
   const subgraphs = program2.command("subgraphs").description("Manage materialized subgraphs");
-  subgraphs.command("create <name>").description("Create a new subgraph definition file").option("--template <slug>", `Starter template (one of: ${SUBGRAPH_TEMPLATE_SLUGS.join(", ")})`).option("--from-contract <contractId>", "Generate sources/schema/handlers from the contract's observed print events (requires network)").option("--table-per-topic", "With --from-contract: one table per print topic instead of a single wide table").addHelpText("after", `
+  subgraphs.command("create <name>").description("Create a new subgraph definition file").option("--from-contract <contractId>", "Generate sources/schema/handlers from the contract's observed print events (requires network)").option("--table-per-topic", "With --from-contract: one table per print topic instead of a single wide table").addHelpText("after", `
 Examples:
   $ secondlayer subgraphs create my-graph
-  $ secondlayer subgraphs create token-balances --template sip-010-balances
   $ secondlayer subgraphs create sbtc-flows --from-contract SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry
   $ secondlayer subgraphs create sbtc-flows --from-contract SM3....sbtc-registry --table-per-topic`).action(async (name, opts) => {
-    if (opts.fromContract && opts.template) {
-      error("--from-contract and --template are mutually exclusive");
-      process.exit(1);
-    }
     if (opts.tablePerTopic && !opts.fromContract) {
       error("--table-per-topic requires --from-contract");
       process.exit(1);
     }
-    const slug = opts.template ?? "basic";
-    if (!opts.fromContract && !SUBGRAPH_TEMPLATE_SLUGS.includes(slug)) {
-      error(`Unknown template "${opts.template}". Available templates:
-${SUBGRAPH_TEMPLATE_SLUGS.map((s2) => `  ${s2.padEnd(20)} ${SUBGRAPH_TEMPLATE_DESCRIPTIONS[s2]}`).join(`
-`)}`);
-      process.exit(1);
-    }
     const dir = resolve3("subgraphs");
     const filePath = resolve3(dir, `${name}.ts`);
     if (existsSync3(filePath)) {
@@ -30018,7 +29651,7 @@ Check the contract id, and that the contract has emitted print events (schemas a
         sample: schema.sample
       }));
     } else {
-      content = generateSubgraphTemplate(name, slug);
+      content = generateSubgraphStarter(name);
     }
     if (!existsSync3(dir)) {
       mkdirSync2(dir, { recursive: true });
@@ -30027,8 +29660,6 @@ Check the contract id, and that the contract has emitted print events (schemas a
     success(`Created ${filePath}`);
     if (opts.fromContract) {
       info(`Schema inferred from ${opts.fromContract} print events (${opts.tablePerTopic ? "table per topic" : "single wide table"})`);
-    } else if (slug !== "basic") {
-      info(`Template: ${slug} — ${SUBGRAPH_TEMPLATE_DESCRIPTIONS[slug]}`);
     }
     info(`Next: secondlayer subgraphs deploy subgraphs/${name}.ts`);
   });
@@ -30788,7 +30419,6 @@ var init_subgraphs2 = __esm(() => {
   init_resolve_auth();
   init_resolve_auth();
   init_clarity();
-  init_subgraph();
   init_api();
   init_format();
   ORM_ONLY_CODEGEN_FLAGS = {
@@ -34690,14 +34320,14 @@ init_esm();
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "11.0.0",
+  version: "12.1.0",
+  description: "Run a Stacks index on your own hardware — set it up, restore verified history, and keep it current.",
   repository: {
     type: "git",
     url: "git+https://github.com/ryanwaits/secondlayer.git",
     directory: "packages/cli"
   },
   homepage: "https://github.com/ryanwaits/secondlayer/tree/main/packages/cli#readme",
-  description: "CLI for subgraphs and blockchain indexing on Stacks",
   type: "module",
   bin: {
     secondlayer: "./dist/cli.js",
@@ -34732,11 +34362,11 @@ var package_default = {
     "@dsnp/parquetjs": "^1.8.8",
     "@inquirer/prompts": "^8.2.0",
     "@secondlayer/bundler": "^0.5.1",
-    "@secondlayer/scaffold": "^1.5.3",
-    "@secondlayer/sdk": "^7.0.0",
-    "@secondlayer/shared": "^8.0.0",
-    "@secondlayer/stacks": "^3.3.1",
-    "@secondlayer/subgraphs": "^4.0.0",
+    "@secondlayer/scaffold": "^1.5.4",
+    "@secondlayer/sdk": "^8.0.1",
+    "@secondlayer/shared": "^10.0.0",
+    "@secondlayer/stacks": "^4.0.0",
+    "@secondlayer/subgraphs": "^4.0.2",
     esbuild: "^0.27.4",
     "smol-toml": "^1.6.1",
     zod: "^4.3.6"
@@ -39063,6 +38693,7 @@ Exit codes:
   });
 }
 // src/commands/bootstrap.ts
+import { createHash as createHash3 } from "node:crypto";
 import { unlink as unlink3, writeFile as writeFile6 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join16 } from "node:path";
@@ -39074,6 +38705,7 @@ import {
 } from "@secondlayer/shared/archive/copy-loader";
 import { computeRangeDigest as computeRangeDigest3 } from "@secondlayer/shared/archive/range-digest";
 import { getDb as getDb4, getRawClient, sql as sql3 } from "@secondlayer/shared/db";
+import { upsertSyncScope } from "@secondlayer/shared/db/queries/sync-scope";
 
 // src/lib/bootstrap-resume.ts
 function planTornImport(input4) {
@@ -39110,6 +38742,18 @@ var BOOTSTRAP_EXIT = {
 };
 var BLOCKS_PER_DAY_ESTIMATE = 5400;
 var RESTORE_ROWS_PER_SECOND = 30000;
+function archiveScopeBounds(partitions) {
+  if (partitions.length === 0)
+    return null;
+  return {
+    start_height: Math.min(...partitions.map((p2) => p2.from_block)),
+    tip_height: Math.max(...partitions.map((p2) => p2.to_block))
+  };
+}
+function manifestDigest(manifest) {
+  const { signature: _signature, key_id: _keyId, ...payload } = manifest;
+  return createHash3("sha256").update(JSON.stringify(payload)).digest("hex");
+}
 async function readNodeTip() {
   const url = process.env.STACKS_NODE_RPC_URL ?? "http://localhost:20443";
   try {
@@ -39164,10 +38808,11 @@ async function loadPartition(reference, partition, rawClient) {
   return written;
 }
 function attachBootstrapCommand(cmd) {
-  return cmd.requiredOption("--against <manifest>", "archive manifest: an https URL or a local file path").option("--to-block <n>", "stop at this height instead of the archive tip").option("--public-key <pem>", "pin the signing key instead of fetching it").option("-y, --yes", "skip the confirmation prompt").option("--json", "Output as JSON").addHelpText("after", `
+  return cmd.requiredOption("--against <manifest>", "archive manifest: an https URL or a local file path").option("--to-block <n>", "stop at this height instead of the archive tip").option("--from-block <n>", "forward-only: restore from this height instead of genesis; earlier history is declared out of scope").option("--public-key <pem>", "pin the signing key instead of fetching it").option("-y, --yes", "skip the confirmation prompt").option("--json", "Output as JSON").addHelpText("after", `
 Examples:
   $ secondlayer bootstrap --against https://archive.secondlayer.tools/.../snapshots/<digest>.json
   $ secondlayer bootstrap --against ./snapshot.json --to-block 4000000 --yes
+  $ secondlayer bootstrap --against ./snapshot.json --from-block 8000000 --yes
 
 Exit codes:
   0  restored and verified
@@ -39192,7 +38837,8 @@ Exit codes:
       const maxHeightRow = await db.selectFrom("blocks").select(({ fn }) => fn.max("height").as("max")).executeTakeFirst();
       const maxBlockHeight = maxHeightRow?.max === null || maxHeightRow?.max === undefined ? null : Number(maxHeightRow.max);
       const toBlock = opts.toBlock === undefined ? undefined : Number(opts.toBlock);
-      const declared = (reference.manifest.partitions ?? []).filter((p2) => toBlock === undefined || p2.to_block <= toBlock);
+      const fromBlock = opts.fromBlock === undefined ? undefined : Number(opts.fromBlock);
+      const declared = (reference.manifest.partitions ?? []).filter((p2) => (toBlock === undefined || p2.to_block <= toBlock) && (fromBlock === undefined || p2.from_block >= fromBlock));
       const resume = planTornImport({
         hasIndexProgress: !!progress,
         maxBlockHeight,
@@ -39219,6 +38865,8 @@ Exit codes:
         });
         process.exit(BOOTSTRAP_EXIT.REFUSED);
       }
+      const scopeBounds = archiveScopeBounds(declared);
+      const startHeight = scopeBounds?.start_height ?? 0;
       const totalRows = partitions.reduce((sum, p2) => sum + p2.row_count, 0);
       const totalBytes = partitions.reduce((sum, p2) => sum + p2.byte_size, 0);
       const tipHeight = Math.max(...partitions.map((p2) => p2.to_block));
@@ -39228,7 +38876,10 @@ Exit codes:
         console.error("");
         console.error(formatKeyValue([
           ["archive", reference.origin],
-          ["coverage", `genesis → ${tipHeight.toLocaleString()}`],
+          [
+            "coverage",
+            `${startHeight === 0 ? "genesis" : startHeight.toLocaleString()} → ${tipHeight.toLocaleString()}`
+          ],
           ["rows", totalRows.toLocaleString()],
           ["download", `${(totalBytes / 1e9).toFixed(1)} GB`],
           ["signature", "verified"]
@@ -39286,6 +38937,17 @@ Exit codes:
 						highest_seen_block = GREATEST(index_progress.highest_seen_block, EXCLUDED.highest_seen_block),
 						updated_at = NOW()
 				`.execute(db);
+      const genesisRow = startHeight === 0 ? await db.selectFrom("blocks").select("hash").where("canonical", "=", true).where("height", "=", 0).executeTakeFirst() : undefined;
+      await upsertSyncScope(db, {
+        network,
+        start_height: startHeight,
+        target_height: null,
+        bootstrap: {
+          source: "archive",
+          manifest_digest: manifestDigest(reference.manifest),
+          genesis_hash: genesisRow?.hash ?? null
+        }
+      });
       const seam = nodeTipAtStart !== null && nodeTipAtStart > tipHeight ? {
         nodeTip: nodeTipAtStart,
         gap: nodeTipAtStart - tipHeight
@@ -39294,6 +38956,7 @@ Exit codes:
       const report = {
         status: divergent === 0 ? "restored" : "divergent",
         archive: reference.origin,
+        start_height: startHeight,
         tip_height: tipHeight,
         rows: loaded,
         ranges_verified: referenceDigests.length,
@@ -39316,6 +38979,9 @@ Exit codes:
             }
             console.error("");
             console.error(dim(`Your instance holds history through ${tipHeight.toLocaleString()} and will resume at ${(tipHeight + 1).toLocaleString()}.`));
+            if (startHeight > 0) {
+              console.error(dim(`  Scope starts at ${startHeight.toLocaleString()} — earlier history is declared out of scope, not missing.`));
+            }
             if (seam) {
               console.error(dim(`The chain advanced to ${seam.nodeTip.toLocaleString()} while restoring — ${seam.gap.toLocaleString()} blocks to catch up.`));
               console.error(dim("  Start the indexer; it backfills that range before following the tip."));
@@ -39340,10 +39006,339 @@ Exit codes:
 function registerBootstrapCommand(program2) {
   attachBootstrapCommand(program2.command("bootstrap").description("Restore chain history from a verified archive instead of syncing from genesis"));
 }
+// src/commands/uninstall.ts
+init_output();
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync8, readFileSync as readFileSync7 } from "node:fs";
+import { join as join17, resolve as resolve13 } from "node:path";
+import { planUninstall, uninstallCommand } from "@secondlayer/shared/runtime";
+var UNINSTALL_EXIT = { OK: 0, FAILED: 1, REFUSED: 2 };
+var DEFAULT_COMPOSE = "docker/oss/docker-compose.yml";
+function bundleHasKeys(bundleDir) {
+  const manifest = join17(bundleDir, "manifest.json");
+  if (!existsSync8(manifest))
+    return false;
+  try {
+    const parsed = JSON.parse(readFileSync7(manifest, "utf8"));
+    return parsed.secrets != null;
+  } catch {
+    return false;
+  }
+}
+function registerUninstallCommand(program2) {
+  program2.command("uninstall").description("Stop the stack; the index, chainstate, and keys survive").option("--compose <file>", "compose file to tear down", DEFAULT_COMPOSE).option("--purge", "also destroy the volumes (wipes the index)").option("--yes", "confirm a purge").option("--backup <dir>", "a bundle proving the keys exist elsewhere (required to purge)").option("--apply", "actually run it (default is a dry run)").option("--json", "Output as JSON").action(async (opts) => {
+    const dataDir = process.env.DATA_DIR ?? "./data";
+    const secretsPresent = !!process.env.SECONDLAYER_SECRETS_KEY || existsSync8(resolve13(process.cwd(), ".env.local"));
+    const keysBackedUp = opts.backup ? bundleHasKeys(resolve13(opts.backup)) : false;
+    const decision = planUninstall({
+      purge: opts.purge === true,
+      confirmed: opts.yes === true,
+      keysBackedUp,
+      secretsPresent,
+      dataDir
+    });
+    if (!decision.ok) {
+      printError(decision.reason);
+      process.exit(UNINSTALL_EXIT.REFUSED);
+    }
+    const cmd = uninstallCommand(decision.plan, opts.compose);
+    if (!opts.apply) {
+      output({
+        json: opts.json,
+        data: { dryRun: true, plan: decision.plan, command: cmd },
+        human: () => {
+          note("dry run — nothing removed. Pass --apply to proceed.");
+          note(`would run: docker ${cmd.join(" ")}`);
+          for (const p2 of decision.plan.preserves) {
+            note(`preserved · ${p2.what}: ${p2.detail}`);
+          }
+          for (const d2 of decision.plan.destroys) {
+            warn(`DESTROYED · volume ${d2}`);
+          }
+        }
+      });
+      return;
+    }
+    const res = spawnSync3("docker", cmd, { stdio: "inherit" });
+    if ((res.status ?? 1) !== 0) {
+      printError(`docker ${cmd.join(" ")} exited ${res.status}`);
+      process.exit(UNINSTALL_EXIT.FAILED);
+    }
+    output({
+      json: opts.json,
+      data: { removed: true, plan: decision.plan },
+      human: () => {
+        success("stack removed");
+        for (const w2 of decision.warnings)
+          warn(w2);
+        for (const p2 of decision.plan.preserves) {
+          note(`preserved · ${p2.what}: ${p2.detail}`);
+        }
+      }
+    });
+  });
+}
+// src/commands/backup.ts
+init_output();
+import { createHash as createHash4 } from "node:crypto";
+import {
+  chmodSync,
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync8,
+  statSync as statSync3,
+  writeFileSync as writeFileSync7
+} from "node:fs";
+import { join as join18, resolve as resolve14 } from "node:path";
+import { closeDb, getDb as getDb5, sql as sql4 } from "@secondlayer/shared/db";
+import {
+  decryptBundle,
+  encryptBundle,
+  keyMatchesCanary,
+  planBackup,
+  precheckRestore,
+  sealKeyCanary
+} from "@secondlayer/shared/runtime";
+var BACKUP_EXIT = { OK: 0, FAILED: 1, REFUSED: 2 };
+var MANIFEST_FILE = "manifest.json";
+var DB_FILE = "db.dump";
+var SECRETS_FILE = "secrets.enc";
+var SECRET_ENV_KEYS = [
+  "INSTANCE_TOKEN",
+  "SECONDLAYER_SECRETS_KEY",
+  "STREAMS_SIGNING_PRIVATE_KEY",
+  "SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY",
+  "SL_API_KEY",
+  "ARCHIVE_SIGNING_PUBLIC_KEY"
+];
+function readSecretsKey() {
+  const key = process.env.SECONDLAYER_SECRETS_KEY?.trim();
+  return key ? key : undefined;
+}
+function sha256File(path11) {
+  return createHash4("sha256").update(readFileSync8(path11)).digest("hex");
+}
+async function readScope() {
+  const db = getDb5();
+  const bounds = await sql4`SELECT MIN(height)::text AS min, MAX(height)::text AS max FROM blocks WHERE canonical = true`.execute(db);
+  const row = bounds.rows[0];
+  const network = process.env.STACKS_NETWORK ?? "mainnet";
+  return {
+    network,
+    fromHeight: row?.min ? Number(row.min) : 0,
+    toHeight: row?.max ? Number(row.max) : null
+  };
+}
+function requireDatabaseUrl() {
+  const url = process.env.DATABASE_URL?.trim();
+  if (!url)
+    throw new Error("DATABASE_URL is required");
+  return url;
+}
+async function runProcess(cmd, label) {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const stderr = await new Response(proc.stderr).text();
+  const code = await proc.exited;
+  if (code !== 0) {
+    return { ok: false, stderr: `${label} exited ${code}: ${stderr.trim()}` };
+  }
+  return { ok: true, stderr };
+}
+function attachBackupCommand(cmd) {
+  return cmd.requiredOption("--out <dir>", "directory to write the bundle into").option("--passphrase <passphrase>", "encrypt bundled secrets (or set SECONDLAYER_BACKUP_PASSPHRASE)").option("--no-secrets", "omit keys; the bundle restores data only").option("--json", "Output as JSON").action(async (opts) => {
+    try {
+      await runBackup(opts);
+      await closeDb();
+    } catch (error2) {
+      printError(error2 instanceof Error ? error2.message : String(error2));
+      process.exit(BACKUP_EXIT.FAILED);
+    }
+  });
+}
+async function runBackup(opts) {
+  const databaseUrl = requireDatabaseUrl();
+  const includeSecrets = opts.secrets !== false;
+  const passphrase = opts.passphrase ?? process.env.SECONDLAYER_BACKUP_PASSPHRASE ?? "";
+  const secretsKey = readSecretsKey();
+  if (includeSecrets && !secretsKey) {
+    printError("SECONDLAYER_SECRETS_KEY is not set, so this backup cannot carry the keys that decrypt your data. Set it, or pass --no-secrets to take a data-only bundle.");
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  const scope = await readScope();
+  const plan = planBackup({
+    network: scope.network,
+    fromHeight: scope.fromHeight,
+    toHeight: scope.toHeight,
+    includeSecrets,
+    secretsEncrypted: includeSecrets && passphrase.length > 0,
+    canary: secretsKey ? sealKeyCanary(secretsKey) : undefined
+  });
+  if (!plan.ok) {
+    printError(plan.reason);
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  const outDir = resolve14(opts.out);
+  mkdirSync6(outDir, { recursive: true });
+  console.error("dumping database…");
+  const dumpPath = join18(outDir, DB_FILE);
+  const dump = await runProcess(["pg_dump", "-Fc", "--no-owner", "--no-acl", "-f", dumpPath, databaseUrl], "pg_dump");
+  if (!dump.ok) {
+    printError(dump.stderr);
+    process.exit(BACKUP_EXIT.FAILED);
+  }
+  const manifest = {
+    ...plan.manifest,
+    db: {
+      file: DB_FILE,
+      sha256: sha256File(dumpPath),
+      bytes: statSync3(dumpPath).size,
+      format: "pg_dump-custom"
+    }
+  };
+  if (includeSecrets && secretsKey) {
+    const lines2 = SECRET_ENV_KEYS.filter((k2) => process.env[k2]).map((k2) => `${k2}=${process.env[k2]}`);
+    const sealed = encryptBundle(lines2.join(`
+`), passphrase);
+    const secretsPath = join18(outDir, SECRETS_FILE);
+    writeFileSync7(secretsPath, sealed);
+    chmodSync(secretsPath, 384);
+    manifest.secrets = {
+      file: SECRETS_FILE,
+      encrypted: true,
+      canary: sealKeyCanary(secretsKey)
+    };
+  }
+  writeFileSync7(join18(outDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
+`);
+  output({
+    json: opts.json,
+    data: { out: outDir, manifest },
+    human: () => {
+      success(`backup written to ${outDir}`);
+      note(`blocks ${manifest.scope.from_height}–${manifest.scope.to_height ?? "?"} · ${(manifest.db?.bytes ?? 0) / 1024 ** 2 | 0} MB`);
+      if (!manifest.secrets) {
+        warn("no keys in this bundle — it can restore data, but not a working instance");
+      } else {
+        note("keys are encrypted; keep the passphrase somewhere else");
+      }
+    }
+  });
+}
+function attachRestoreCommand(cmd) {
+  return cmd.requiredOption("--from <dir>", "bundle directory to restore from").option("--passphrase <passphrase>", "decrypt bundled secrets (or set SECONDLAYER_BACKUP_PASSPHRASE)").option("--apply", "actually restore (default is a dry run)").option("--force", "restore over a database that already holds chain data").option("--json", "Output as JSON").action(async (opts) => {
+    try {
+      await runRestore(opts);
+      await closeDb();
+    } catch (error2) {
+      printError(error2 instanceof Error ? error2.message : String(error2));
+      process.exit(BACKUP_EXIT.FAILED);
+    }
+  });
+}
+async function runRestore(opts) {
+  const databaseUrl = requireDatabaseUrl();
+  const dir = resolve14(opts.from);
+  const manifestPath = join18(dir, MANIFEST_FILE);
+  if (!existsSync9(manifestPath)) {
+    printError(`no ${MANIFEST_FILE} in ${dir}`);
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  const manifest = JSON.parse(readFileSync8(manifestPath, "utf8"));
+  const dumpPath = join18(dir, manifest.db?.file ?? DB_FILE);
+  if (manifest.db && sha256File(dumpPath) !== manifest.db.sha256) {
+    printError("the database dump does not match the digest in the manifest; this bundle is corrupt or truncated");
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  const envKey = readSecretsKey();
+  let bundleKey;
+  if (manifest.secrets) {
+    const passphrase = opts.passphrase ?? process.env.SECONDLAYER_BACKUP_PASSPHRASE ?? "";
+    if (!passphrase) {
+      printError("this bundle carries encrypted keys; supply --passphrase to read them");
+      process.exit(BACKUP_EXIT.REFUSED);
+    }
+    try {
+      const env2 = decryptBundle(readFileSync8(join18(dir, manifest.secrets.file)), passphrase);
+      bundleKey = env2.split(`
+`).find((l2) => l2.startsWith("SECONDLAYER_SECRETS_KEY="))?.slice("SECONDLAYER_SECRETS_KEY=".length).trim();
+    } catch {
+      printError("could not decrypt the secrets bundle — wrong passphrase?");
+      process.exit(BACKUP_EXIT.REFUSED);
+    }
+  }
+  if (envKey && manifest.secrets && !keyMatchesCanary(manifest.secrets.canary, envKey)) {
+    printError("SECONDLAYER_SECRETS_KEY in this environment is NOT the key this backup was taken with. Restoring would leave every encrypted column unreadable. Unset it to install the bundle's key, or point this restore at the matching instance.");
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  const db = getDb5();
+  const present = await sql4`SELECT to_regclass('public.blocks') IS NOT NULL AS present`.execute(db);
+  let targetIsEmpty = true;
+  if (present.rows[0]?.present) {
+    const existing = await sql4`SELECT COUNT(*)::text AS count FROM blocks`.execute(db);
+    targetIsEmpty = (existing.rows[0]?.count ?? "0") === "0";
+  }
+  const check = precheckRestore({
+    manifest,
+    targetNetwork: process.env.STACKS_NETWORK ?? "mainnet",
+    targetIsEmpty,
+    force: opts.force === true,
+    secretsKeyHex: envKey ?? bundleKey
+  });
+  if (!check.ok) {
+    printError(check.reason);
+    process.exit(BACKUP_EXIT.REFUSED);
+  }
+  if (!opts.apply) {
+    output({
+      json: opts.json,
+      data: { dryRun: true, manifest, targetIsEmpty },
+      human: () => {
+        note("dry run — nothing written. Pass --apply to restore.");
+        note(`would restore ${manifest.network} blocks ${manifest.scope.from_height}–${manifest.scope.to_height ?? "?"}`);
+        if (bundleKey && !envKey) {
+          note("after restoring, install the bundle's keys before starting the runtime");
+        }
+      }
+    });
+    return;
+  }
+  console.error("restoring database…");
+  const restore = await runProcess([
+    "pg_restore",
+    "--no-owner",
+    "--no-acl",
+    "--clean",
+    "--if-exists",
+    "-d",
+    databaseUrl,
+    dumpPath
+  ], "pg_restore");
+  if (!restore.ok) {
+    printError(restore.stderr);
+    process.exit(BACKUP_EXIT.FAILED);
+  }
+  output({
+    json: opts.json,
+    data: { restored: true, manifest },
+    human: () => {
+      success("restore complete");
+      if (bundleKey && !envKey) {
+        warn("set SECONDLAYER_SECRETS_KEY from the bundle before starting the runtime, or it will generate a new one and the restored data will not decrypt");
+      }
+      note("verify with: secondlayer verify all --against <manifest>");
+    }
+  });
+}
+function registerBackupCommand(program2) {
+  attachBackupCommand(program2.command("backup").description("Write a restorable bundle: index, keys, and scope"));
+}
+function registerRestoreCommand(program2) {
+  attachRestoreCommand(program2.command("restore").description("Restore an instance from a backup bundle"));
+}
 // src/lib/instance-init.ts
 import { randomBytes as randomBytes3 } from "node:crypto";
-import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "node:fs";
-import { resolve as resolve13 } from "node:path";
+import { existsSync as existsSync10, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "node:fs";
+import { resolve as resolve15 } from "node:path";
 import { generateEd25519KeyPair } from "@secondlayer/shared/crypto/ed25519";
 import { INSTANCE_NETWORKS } from "@secondlayer/shared/db/queries/instance";
 var INSTANCE_ENV_FILE = ".env.local";
@@ -39377,9 +39372,9 @@ function unescapeEnvValue(raw) {
 `).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
 }
 function readEnvValue(envPath, key) {
-  if (!existsSync8(envPath))
+  if (!existsSync10(envPath))
     return null;
-  const match = readFileSync7(envPath, "utf8").match(new RegExp(`^${key}=(.*)$`, "m"));
+  const match = readFileSync9(envPath, "utf8").match(new RegExp(`^${key}=(.*)$`, "m"));
   return match ? unescapeEnvValue(match[1]) : null;
 }
 function buildInstanceEnv(input4) {
@@ -39422,12 +39417,12 @@ function renderInstanceEnv(env2) {
 `);
 }
 function writeInstanceEnv(cwd, env2, file = INSTANCE_ENV_FILE) {
-  const path11 = resolve13(cwd, file);
-  writeFileSync7(path11, renderInstanceEnv(env2), { mode: 384 });
+  const path11 = resolve15(cwd, file);
+  writeFileSync8(path11, renderInstanceEnv(env2), { mode: 384 });
   return path11;
 }
 function loadExistingInstanceEnv(cwd, file = INSTANCE_ENV_FILE) {
-  const path11 = resolve13(cwd, file);
+  const path11 = resolve15(cwd, file);
   return {
     INSTANCE_TOKEN: readEnvValue(path11, "INSTANCE_TOKEN"),
     SECONDLAYER_SECRETS_KEY: readEnvValue(path11, "SECONDLAYER_SECRETS_KEY"),
@@ -39581,7 +39576,7 @@ function registerStartCommand(program2) {
 }
 // src/cli.ts
 var { version } = package_default;
-program.name("secondlayer").alias("sl").description("Secondlayer CLI — self-hosted Stacks data runtime").version(version).option("--network <network>", "Override network (local, testnet, mainnet)").option("--api-key <key>", "API credential (overrides SL_API_KEY)").option("--api-url <url>", "API endpoint (overrides SL_API_URL)").showSuggestionAfterError(true).showHelpAfterError("(run `secondlayer --help` to see available commands)");
+program.name("secondlayer").alias("sl").description("Secondlayer CLI — run a Stacks index on your own hardware").version(version).option("--network <network>", "Override network (local, testnet, mainnet)").option("--api-key <key>", "API credential (overrides SL_API_KEY)").option("--api-url <url>", "API endpoint (overrides SL_API_URL)").showSuggestionAfterError(true).showHelpAfterError("(run `secondlayer --help` to see available commands)");
 program.hook("preAction", (thisCommand) => {
   const { network, apiKey, apiUrl } = thisCommand.opts();
   if (network)
@@ -39595,7 +39590,7 @@ program.addHelpText("after", `
 Quickstart:
   $ secondlayer init --network mainnet
   $ secondlayer bootstrap --against <manifest>
-  $ secondlayer subgraphs create my-watcher --template sip-010-balances
+  $ secondlayer subgraphs create my-watcher --from-contract SP....my-contract
   $ secondlayer subgraphs deploy subgraphs/my-watcher.ts
 `);
 program.commandsGroup("Getting started:");
@@ -39607,7 +39602,7 @@ registerConsoleCommand(program);
 registerLoginCommand(program);
 registerLogoutCommand(program);
 registerWhoamiCommand(program);
-program.commandsGroup("Data products:");
+program.commandsGroup("Your data:");
 registerSubgraphsCommand(program);
 registerSubscriptionsCommand(program);
 registerStreamsCommand(program);
@@ -39637,9 +39632,12 @@ registerConfigCommand(program);
 registerContextCommand(program);
 registerVerifyCommand(program);
 registerRepairCommand(program);
-program.commandsGroup("Account:");
+registerBackupCommand(program);
+registerRestoreCommand(program);
+registerUninstallCommand(program);
+program.commandsGroup("Archive:");
 registerCreditsCommand(program);
 program.parse();
 
-//# debugId=3107CF5F3E1F73F364756E2164756E21
+//# debugId=135579D3DFB23FDC64756E2164756E21
 //# sourceMappingURL=cli.js.map