docs: audit and fix outdated READMEs across all packages

Remove dead contracts API examples from root, sdk, api, shared READMEs.
Fix infra docs: backfill hiro-pg source, raw_tx burnchain ops, sync
estimates, zstd archive commands, $COMPOSE consistency.
Fix stacks module docs: transport signatures, pox params, action imports,
new enum values. Remove dead contracts export from shared package.json.

Author: ryanwaits

README.md

@@ -169,9 +169,6 @@ bun add -g @secondlayer/cli
 sl auth login                    # authenticate via magic link
 sl streams list                  # manage event streams
 sl subgraphs list                # manage subgraphs
-sl contracts search "token"      # search indexed contracts by name
-sl contracts info SP2J6..token   # contract details (deployer, call count, etc.)
-sl contracts abi SP2J6..token    # fetch + display contract ABI
 ```
 
 All commands support `--json` for machine-readable output.
@@ -187,32 +184,32 @@ import { SecondLayer } from "@secondlayer/sdk";
 
 const sl = new SecondLayer({ apiKey: "sk-sl_..." });
 
-// Search contracts
-const { contracts, total } = await sl.contracts.search("bns", { limit: 10 });
+// List streams
+const { streams, total } = await sl.streams.list({ status: "active" });
 
-// Get contract detail
-const contract = await sl.contracts.get("SP000000000000000000002Q6VF78.bns");
+// Create a stream
+const { stream, signingSecret } = await sl.streams.create({
+  name: "my-stream",
+  endpointUrl: "https://example.com/receive",
+  filters: { type: "contract_call", contract_id: "SP...token" },
+});
 
-// Fetch ABI (lazy-cached from Stacks node)
-const abi = await sl.contracts.getAbi("SP000000000000000000002Q6VF78.bns");
+// List subgraphs
+const { data } = await sl.subgraphs.list();
 ```
 
 ### REST API
 
 Base URL: `https://api.secondlayer.tools`
 
 ```bash
-# Search contracts
+# List streams
 curl -H "Authorization: Bearer $TOKEN" \
-  "https://api.secondlayer.tools/api/contracts?q=bns&limit=20"
+  "https://api.secondlayer.tools/api/streams"
 
-# Contract detail
+# List subgraphs
 curl -H "Authorization: Bearer $TOKEN" \
-  "https://api.secondlayer.tools/api/contracts/SP000000000000000000002Q6VF78.bns"
-
-# Contract ABI (cached, ?refresh=true to force re-fetch)
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://api.secondlayer.tools/api/contracts/SP000000000000000000002Q6VF78.bns/abi"
+  "https://api.secondlayer.tools/api/subgraphs"
 ```
 
 See [packages/api/README.md](packages/api/README.md) and [packages/sdk/README.md](packages/sdk/README.md) for full docs.

docker/docs/README.md

@@ -81,7 +81,7 @@ chown -R 1000:1000 $BITCOIN_DATA_DIR
 
 ## Genesis Sync
 
-Full chain sync from block 0. Takes ~4-10 days total. **All steps are manual** — stacks-node does not auto-start.
+Full chain sync from block 0. Takes ~10-14 days total. **All steps are manual** — stacks-node does not auto-start.
 
 ### Steps
 
@@ -109,7 +109,7 @@ cd /opt/secondlayer/docker
 # Truncate DB for clean genesis sync
 docker exec secondlayer-postgres-1 psql -U secondlayer -d secondlayer \
   -c "TRUNCATE blocks, transactions, events, jobs, deliveries, index_progress CASCADE;"
-TIP_FOLLOWER_ENABLED=false docker compose -f docker-compose.yml -f docker-compose.hetzner.yml up -d
+TIP_FOLLOWER_ENABLED=false $COMPOSE up -d
 ```
 
 **3. Start stacks-node** — only after bitcoind blocks > 666050
@@ -133,7 +133,7 @@ ssh node-server "cd /opt/secondlayer/docker/node-server && docker compose logs -
 
 # App server
 ssh app-server "cd /opt/secondlayer/docker && \
-  docker compose -f docker-compose.yml -f docker-compose.hetzner.yml logs -f indexer"
+  $COMPOSE logs -f indexer"
 ```
 
 **4. After sync completes**
@@ -142,14 +142,13 @@ ssh app-server "cd /opt/secondlayer/docker && \
 ssh app-server
 cd /opt/secondlayer/docker
 
-# Verify no placeholder transactions
+# Check for placeholder transactions (excluding burnchain ops which legitimately have raw_tx = '0x00')
 docker exec secondlayer-postgres-1 psql -U secondlayer -d secondlayer \
-  -c "SELECT COUNT(*) FROM transactions WHERE raw_tx = '0x00';"
-# Should be 0
+  -c "SELECT COUNT(*) FROM transactions WHERE raw_tx = '0x00' AND type_id NOT IN (1,2,3,4,5);"
+# Should be 0. ~700 burnchain operations (PoX stacking, STX transfers via BTC) have raw_tx = '0x00' by design.
 
 # Re-enable tip follower
-TIP_FOLLOWER_ENABLED=true docker compose -f docker-compose.yml -f docker-compose.hetzner.yml \
-  up -d --force-recreate indexer
+TIP_FOLLOWER_ENABLED=true $COMPOSE up -d --force-recreate indexer
 ```
 
 ### Re-sync from genesis
@@ -392,13 +391,25 @@ docker run -d --name backfill \
   -e BACKFILL_BATCH_SIZE=100 \
   -e BACKFILL_FROM=2 \
   oven/bun:latest bun run packages/indexer/src/bulk-backfill.ts
+
+# Fastest option: backfill from local Hiro Postgres (~150 blocks/sec)
+docker run -d --name backfill \
+  --network secondlayer_default \
+  -v /opt/secondlayer:/app -w /app \
+  -e DATABASE_URL=postgres://secondlayer:secondlayer@postgres:5432/secondlayer \
+  -e HIRO_PG_URL=postgres://hiro_user:password@hiro-postgres:5432/stacks_blockchain_api \
+  -e BACKFILL_SOURCE=hiro-pg \
+  -e BACKFILL_CONCURRENCY=20 \
+  -e BACKFILL_BATCH_SIZE=100 \
+  -e BACKFILL_FROM=2 \
+  oven/bun:latest bun run packages/indexer/src/bulk-backfill.ts
 ```
 
 > Block 1 (genesis) has 330K events. Always set `BACKFILL_FROM=2`.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `BACKFILL_SOURCE` | `hiro` | `hiro` = Hiro API, `local` = own Postgres |
+| `BACKFILL_SOURCE` | `hiro` | `hiro` = Hiro API, `local` = own Postgres, `hiro-pg` = direct PG queries against local Hiro API database (fastest, ~150 blocks/sec) |
 | `BACKFILL_FROM` | `2` | Start height |
 | `BACKFILL_TO` | auto | End height (auto-detects chain tip) |
 | `BACKFILL_CONCURRENCY` | `20` | Parallel fetches |
@@ -419,16 +430,18 @@ Bootstrap stacks-node from Hiro's archive (~800-900 GB) instead of syncing from
 ```bash
 # Stream to disk (node server)
 ssh node-server
-wget -qO- https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz \
-  | tar xzf - -C /data/stacks
+wget -qO- https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.zst \
+  | tar --zstd -xf - -C /data/stacks
 
 # With resume support
-curl --continue-at - -L -o /tmp/snapshot.tar.gz \
-  https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz
-tar -xzf /tmp/snapshot.tar.gz -C /data/stacks
-rm /tmp/snapshot.tar.gz
+curl --continue-at - -L -o /tmp/snapshot.tar.zst \
+  https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.zst
+tar --zstd -xf /tmp/snapshot.tar.zst -C /data/stacks
+rm /tmp/snapshot.tar.zst
 ```
 
+> The archive may contain empty sqlite files. Stacks-node regenerates them on first boot — expect a longer initial startup.
+
 ---
 
 ## Troubleshooting

packages/api/README.md

@@ -1,6 +1,6 @@
 # @secondlayer/api
 
-REST API for Second Layer — streams, subgraphs, and contract discovery.
+REST API for Second Layer — streams and subgraphs.
 
 Base URL: `https://api.secondlayer.tools`
 
@@ -9,60 +9,11 @@ Base URL: `https://api.secondlayer.tools`
 All endpoints require a Bearer token (session token or API key):
 
 ```bash
-curl -H "Authorization: Bearer ss-sl_..." https://api.secondlayer.tools/api/contracts?q=bns
+curl -H "Authorization: Bearer ss-sl_..." https://api.secondlayer.tools/api/streams
 ```
 
 Get a session token via the CLI: `sl auth login`
 
-## Contracts
-
-### Search
-
-```
-GET /api/contracts?q=<query>&limit=20&offset=0
-```
-
-| Param | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `q` | yes | — | Search term (matches name and contract_id via ILIKE) |
-| `limit` | no | 20 | Max results (1-100) |
-| `offset` | no | 0 | Pagination offset |
-
-Response:
-```json
-{
-  "contracts": [
-    {
-      "contractId": "SP000000000000000000002Q6VF78.pox",
-      "name": "pox",
-      "deployer": "SP000000000000000000002Q6VF78",
-      "deployBlock": 0,
-      "callCount": 20,
-      "lastCalledAt": "2026-03-09T19:56:12.000Z",
-      "createdAt": "2026-03-09T18:00:00.000Z"
-    }
-  ],
-  "total": 1
-}
-```
-
-### Get Contract
-
-```
-GET /api/contracts/:contractId
-```
-
-Returns `ContractDetail` (summary + `deployTxId`, `abi`, `updatedAt`). 404 if not found.
-
-### Get ABI
-
-```
-GET /api/contracts/:contractId/abi
-GET /api/contracts/:contractId/abi?refresh=true
-```
-
-Returns the contract's Clarity ABI as JSON. On first request, fetches from the Stacks node and caches in the database. Subsequent requests serve from cache. Pass `?refresh=true` to force re-fetch (useful for upgraded contracts).
-
 ## Streams
 
 ```

packages/sdk/README.md

@@ -19,23 +19,6 @@ const sl = new SecondLayer({
 });
 ```
 
-## Contracts
-
-Search, inspect, and fetch ABIs for on-chain contracts.
-
-```typescript
-// Search by name
-const { contracts, total } = await sl.contracts.search("bns", { limit: 10, offset: 0 });
-
-// Get contract detail
-const contract = await sl.contracts.get("SP000000000000000000002Q6VF78.bns");
-// { contractId, name, deployer, deployBlock, deployTxId, callCount, lastCalledAt, abi, ... }
-
-// Fetch ABI (lazy-cached from Stacks node)
-const abi = await sl.contracts.getAbi("SP000000000000000000002Q6VF78.bns");
-// { functions: [...], maps: [...], variables: [...], ... }
-```
-
 ## Streams
 
 Manage real-time event streams with endpoint delivery.
@@ -85,7 +68,7 @@ const result = await sl.subgraphs.deploy({ name, sources, schema, handlerCode })
 import { ApiError } from "@secondlayer/sdk";
 
 try {
-  await sl.contracts.get("nonexistent");
+  await sl.streams.get("nonexistent");
 } catch (err) {
   if (err instanceof ApiError) {
     console.log(err.status);  // 404

packages/shared/README.md

@@ -18,25 +18,25 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5432/streams_test bun test
 DATABASE_URL=... bun run migrate
 ```
 
-## Contracts
-
-Query helpers for the `contracts` table:
-
-```typescript
-import { searchContracts, getContract, cacheContractAbi } from "@secondlayer/shared/db/queries/contracts";
-
-// Search by name or contract_id (uses pg_trgm for fast ILIKE)
-const { contracts, total } = await searchContracts(db, "bns", 20, 0);
-
-// Get single contract by ID
-const contract = await getContract(db, "SP000000000000000000002Q6VF78.bns");
-
-// Cache ABI fetched from Stacks node
-await cacheContractAbi(db, "SP000000000000000000002Q6VF78.bns", abiJson);
-```
-
-Response schemas (`@secondlayer/shared/schemas`):
-
-- `ContractSummary` — contractId, name, deployer, deployBlock, callCount, lastCalledAt, createdAt
-- `ContractDetail` — extends summary with deployTxId, abi, updatedAt
-- `SearchContractsResponse` — { contracts: ContractSummary[], total: number }
+## Exports
+
+| Path | Description |
+|------|-------------|
+| `@secondlayer/shared` | Core utilities |
+| `@secondlayer/shared/db` | Kysely database layer |
+| `@secondlayer/shared/db/queries/*` | Query helpers (integrity, metrics, accounts, usage, subgraphs) |
+| `@secondlayer/shared/db/schema` | Database schema |
+| `@secondlayer/shared/db/jsonb` | JSONB helpers |
+| `@secondlayer/shared/schemas` | Zod schemas |
+| `@secondlayer/shared/schemas/filters` | Stream filter schemas |
+| `@secondlayer/shared/schemas/subgraphs` | Subgraph schemas |
+| `@secondlayer/shared/types` | Shared TypeScript types |
+| `@secondlayer/shared/queue` | Job queue |
+| `@secondlayer/shared/queue/listener` | Queue listener |
+| `@secondlayer/shared/queue/recovery` | Queue recovery |
+| `@secondlayer/shared/env` | Environment config |
+| `@secondlayer/shared/logger` | Logger |
+| `@secondlayer/shared/errors` | Error types |
+| `@secondlayer/shared/crypto` | HMAC signing |
+| `@secondlayer/shared/node` | Stacks node client |
+| `@secondlayer/shared/lib/plans` | Plan definitions |

packages/shared/package.json

@@ -33,10 +33,6 @@
       "types": "./dist/src/db/queries/subgraphs.d.ts",
       "import": "./dist/src/db/queries/subgraphs.js"
     },
-    "./db/queries/contracts": {
-      "types": "./dist/src/db/queries/contracts.d.ts",
-      "import": "./dist/src/db/queries/contracts.js"
-    },
     "./db/jsonb": {
       "types": "./dist/src/db/jsonb.d.ts",
       "import": "./dist/src/db/jsonb.js"

packages/stacks/src/actions/README.md

@@ -5,7 +5,7 @@ Standalone action functions for tree-shakeable imports. These are the same funct
 ## Public (Read-Only) Actions
 
 ```typescript
-import { getBalance, getNonce, readContract, getBlock } from "@secondlayer/stacks/actions";
+import { getBalance, getNonce, readContract, getBlock, getBlockHeight } from "@secondlayer/stacks/actions";
 
 const balance = await getBalance(client, { address: "SP2J6..." });
 const nonce = await getNonce(client, { address: "SP2J6..." });

packages/stacks/src/pox/README.md

@@ -50,6 +50,7 @@ await wallet.pox.stackStx({
   amount: 100_000_000_000n,       // 100k STX in microSTX
   btcAddress: "bc1q...",           // BTC reward address
   lockPeriod: 12,                  // 1-12 cycles
+  startBurnHeight: 850_000n,      // burn height at which stacking begins
   signerSig: signature,            // signer signature (buff 65)
   signerKey: publicKey,            // signer public key (buff 33)
   maxAmount: 100_000_000_000n,

packages/stacks/src/transactions/README.md

@@ -116,6 +116,30 @@ const originSigned = signTransaction(tx, originKey);
 const fullySigned = signSponsor(originSigned, sponsorKey);
 ```
 
+## Enums
+
+### ClarityVersion
+
+| Name | Value |
+|------|-------|
+| `Clarity1` | 1 |
+| `Clarity2` | 2 |
+| `Clarity3` | 3 |
+| `Clarity4` | 4 |
+| `Clarity5` | 5 |
+
+### TenureChangeCause
+
+| Name | Value |
+|------|-------|
+| `BlockFound` | 0x00 |
+| `Extended` | 0x01 |
+| `ExtendedRuntime` | 0x02 |
+| `ExtendedReadCount` | 0x03 |
+| `ExtendedReadLength` | 0x04 |
+| `ExtendedWriteCount` | 0x05 |
+| `ExtendedWriteLength` | 0x06 |
+
 ## Wire Format
 
 ```typescript

packages/stacks/src/transports/README.md

@@ -11,11 +11,10 @@ import { http } from "@secondlayer/stacks";
 const transport = http();
 
 // Custom URL
-const transport = http({ url: "https://my-node.example.com" });
+const transport = http("https://my-node.example.com");
 
 // With options
-const transport = http({
-  url: "https://my-node.example.com",
+const transport = http("https://my-node.example.com", {
   apiKey: "my-api-key",
   timeout: 30_000,
   retryCount: 3,
@@ -31,7 +30,7 @@ import { webSocket } from "@secondlayer/stacks";
 const transport = webSocket();
 
 // Custom URL
-const transport = webSocket({ url: "wss://my-node.example.com" });
+const transport = webSocket("wss://my-node.example.com");
 ```
 
 ## Fallback
@@ -42,8 +41,8 @@ Tries transports in order, falls back on failure.
 import { fallback, http } from "@secondlayer/stacks";
 
 const transport = fallback([
-  http({ url: "https://primary-node.com" }),
-  http({ url: "https://backup-node.com" }),
+  http("https://primary-node.com"),
+  http("https://backup-node.com"),
 ]);
 ```