chore: Accumulated backports to v4-next (#22924)

BEGIN_COMMIT_OVERRIDE
docs: add map and state variable docs  (#22824)
fix: e2e compat should not fail for contracts added after legacy stables
(#22900)
chore: fix kv-store browser tests hangs (#22721)
feat: kv-store sqlite backend with page level encryption (#22759)
fix: install node 22 for aztec-cli acceptance test (#22917)
feat: backport kv-store sqlite encryption (#22759) to v4-next (#22927)
fix(docs): correct llms.txt links for versioned developer docs (#22819)
feat(docs): improve discoverability of Aztec.nr API reference docs
(#22861)
feat(docs): backport improve discoverability of Aztec.nr API reference
docs (#22861) to v4-next (#22931)
feat(aztec-nr): add call_self stubs for utility functions (#22885)
docs: add map and state variable docs (backport #22824) (#22880)
refactor: `getPackageVersion` fn cleanup (#22941)
fix(ci): skip acceptance test for canary -commit. tags (#22951)
fix: closing db, correct stub side effects (#22939)
END_COMMIT_OVERRIDE

Author: AztecBot

.github/workflows/aztec-cli-acceptance-test.yml

@@ -21,7 +21,9 @@ jobs:
     runs-on: ubuntu-latest
     if: >-
       github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
+      (github.event_name == 'workflow_run'
+       && github.event.workflow_run.conclusion == 'success'
+       && !contains(github.event.workflow_run.head_branch, '-commit.'))
     timeout-minutes: 30
     env:
       VERSION: ${{ github.event.inputs.version || github.event.workflow_run.head_branch }}
@@ -31,6 +33,13 @@ jobs:
         with:
           ref: ${{ github.event.workflow_run.head_sha || github.sha }}
 
+      # Node is only used to run the .ts harness in run-test.sh, which needs >=22.18 for TS
+      # type-stripping. The aztec CLI installer manages its own node version independently.
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
       - name: Run Aztec CLI acceptance test
         run: ./aztec-up/test/aztec-cli-acceptance-test/run-test.sh
 

.test_patterns.yml

@@ -167,14 +167,19 @@ tests:
       - *palla
 
   # yarn-project tests
+  # Attempt to catch all kv-store browser test failures (consider them quarantined for now)
+  - regex: "yarn-project/kv-store"
+    error_regex: "vitest"
+    owners:
+      - *martin
   - regex: "yarn-project/kv-store"
     error_regex: "Could not import your test module"
     owners:
       - *grego
   - regex: "yarn-project/kv-store"
     error_regex: "timeout: sending signal TERM to command"
     owners:
-      - *alex
+      - *martin
   - regex: "yarn-project/kv-store"
     error_regex: "Failed to fetch dynamically imported module"
     owners:

docs/docusaurus.config.js

@@ -260,12 +260,16 @@ const config = {
       {
         generateLLMsTxt: true,
         generateLLMsFullTxt: true,
-        docsDir: `developer_versioned_docs/version-${mainnetDeveloperVersion || developerTestnetVersion}/`,
+        docsDir: `developer_versioned_docs/version-${mainnetDeveloperVersion || developerTestnetVersion}`,
         title: "Aztec Protocol Documentation",
         excludeImports: true,
         version: mainnetDeveloperVersion || developerTestnetVersion,
+        addMdExtension: false,
         pathTransformation: {
-          ignorePaths: ["docs"],
+          ignorePaths: [
+            `developer_versioned_docs/version-${mainnetDeveloperVersion || developerTestnetVersion}`,
+          ],
+          addPaths: ["developers"],
         },
       },
     ],

docs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "build": "yarn clean && yarn preprocess && yarn spellcheck && yarn preprocess:move && yarn validate:redirects && yarn validate:api-ref-links && docusaurus build && node scripts/append_api_docs_to_llms.js",
+    "build": "yarn clean && yarn preprocess && yarn spellcheck && yarn preprocess:move && yarn validate:redirects && yarn validate:api-ref-links && docusaurus build && node scripts/augment_sitemap.js && node scripts/append_api_docs_to_llms.js",
     "validate:redirects": "./scripts/validate_redirect_targets.sh",
     "validate:api-ref-links": "./scripts/validate_api_ref_links.sh",
     "clean": "./scripts/clean.sh",
@@ -41,7 +41,7 @@
     "@docusaurus/tsconfig": "3.9.1",
     "@tsconfig/docusaurus": "^1.0.7",
     "cspell": "^8.19.4",
-    "docusaurus-plugin-llms": "^0.2.0",
+    "docusaurus-plugin-llms": "^0.4.0",
     "dotenv": "^16.6.1",
     "netlify-cli": "^24.0.1"
   },

docs/scripts/append_api_docs_to_llms.js

@@ -15,20 +15,42 @@ const path = require("path");
 const BUILD_DIR = path.join(__dirname, "..", "build");
 const STATIC_DIR = path.join(__dirname, "..", "static");
 
-// Load version from developer_versions.json (same as docusaurus.config.js)
+// Load version config (source of truth for type→version mapping)
+let developerVersionConfig;
+try {
+  developerVersionConfig = require("../developer_version_config.json");
+} catch {
+  // Fallback to legacy array-based detection
+  developerVersionConfig = null;
+}
 const developerVersions = require("../developer_versions.json");
 
-// Find testnet version dynamically (same logic as docusaurus.config.js)
-const testnetVersion = developerVersions.find((v) => v.includes("rc") || v.includes("testnet"));
-
-// The API docs directories use stable folder names
-const API_DIRS = [
-  ...(testnetVersion ? [{
-    name: "Aztec.nr API Reference (Testnet)",
-    dir: "aztec-nr-api/testnet",
-    description: `Auto-generated API documentation for Aztec.nr (${testnetVersion})`,
-  }] : []),
-];
+// Determine the default (highest-priority) API docs version to append.
+// Only include one set to avoid bloating llms.txt. Priority: mainnet > testnet.
+const defaultType = developerVersionConfig?.mainnet ? "mainnet"
+  : developerVersionConfig?.testnet ? "testnet"
+  : null;
+const defaultVersion = defaultType ? developerVersionConfig[defaultType] : (developerVersions[0] || null);
+
+const API_DIRS = [];
+if (defaultType && fs.existsSync(path.join(STATIC_DIR, `aztec-nr-api/${defaultType}`))) {
+  API_DIRS.push({
+    name: "Aztec.nr API Reference",
+    dir: `aztec-nr-api/${defaultType}`,
+    description: `Auto-generated API documentation for Aztec.nr (${defaultVersion})`,
+    format: "html",
+  });
+} else if (!defaultType) {
+  console.warn("Warning: No default version found for API docs");
+}
+if (defaultType && fs.existsSync(path.join(STATIC_DIR, `typescript-api/${defaultType}`))) {
+  API_DIRS.push({
+    name: "TypeScript API Reference",
+    dir: `typescript-api/${defaultType}`,
+    description: `Auto-generated TypeScript API documentation for Aztec packages (${defaultVersion})`,
+    format: "markdown",
+  });
+}
 
 /**
  * Extract text content from HTML, stripping tags and normalizing whitespace.
@@ -81,9 +103,9 @@ function htmlToText(html) {
 }
 
 /**
- * Recursively find all HTML files in a directory.
+ * Recursively find all files with a given extension in a directory.
  */
-function findHtmlFiles(dir, files = []) {
+function findFiles(dir, ext, files = []) {
   if (!fs.existsSync(dir)) {
     return files;
   }
@@ -93,15 +115,30 @@ function findHtmlFiles(dir, files = []) {
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      findHtmlFiles(fullPath, files);
-    } else if (entry.name.endsWith(".html")) {
+      findFiles(fullPath, ext, files);
+    } else if (entry.name.endsWith(ext)) {
       files.push(fullPath);
     }
   }
 
   return files;
 }
 
+/**
+ * Recursively find all HTML files in a directory.
+ */
+function findHtmlFiles(dir) {
+  return findFiles(dir, ".html");
+}
+
+/**
+ * Recursively find all markdown files in a directory.
+ * Note: `llm-summary.txt` is naturally excluded since it does not end in `.md`.
+ */
+function findMarkdownFiles(dir) {
+  return findFiles(dir, ".md");
+}
+
 /**
  * Get the relative URL path for a file.
  */
@@ -158,6 +195,7 @@ function main() {
     : "";
 
   let totalFiles = 0;
+  let sectionsAdded = 0;
   let linksSection = "\n\n# API Reference Documentation\n\n";
   let fullContentSection = "\n\n---\n\n# API Reference Documentation\n\n";
 
@@ -169,43 +207,66 @@ function main() {
       continue;
     }
 
-    const htmlFiles = sortByImportance(findHtmlFiles(dirPath));
-    console.log(`Found ${htmlFiles.length} HTML files in ${apiDir.dir}`);
+    const isMarkdown = apiDir.format === "markdown";
+    const files = isMarkdown
+      ? findMarkdownFiles(dirPath).sort()
+      : sortByImportance(findHtmlFiles(dirPath));
+    const ext = isMarkdown ? ".md" : ".html";
+    console.log(`Found ${files.length} ${isMarkdown ? "markdown" : "HTML"} files in ${apiDir.dir}`);
 
-    if (htmlFiles.length === 0) {
+    if (files.length === 0) {
       continue;
     }
 
+    sectionsAdded++;
+
     // Add section header
     linksSection += `## ${apiDir.name}\n\n`;
     linksSection += `${apiDir.description}\n\n`;
     fullContentSection += `## ${apiDir.name}\n\n`;
     fullContentSection += `${apiDir.description}\n\n`;
 
-    // Process only index files for links to avoid overwhelming the llms.txt
-    const indexFiles = htmlFiles.filter(
-      (f) => f.endsWith("index.html") || f.includes("/fn.") || f.includes("/struct.") || f.includes("/trait.")
-    );
-
-    // Add links for key files
-    for (const file of indexFiles.slice(0, 100)) {
-      // Limit to 100 links per section
-      const urlPath = getUrlPath(file, STATIC_DIR);
-      const fileName = path.basename(file, ".html");
-      linksSection += `- [${fileName}](${urlPath})\n`;
-    }
+    if (isMarkdown) {
+      // For markdown API docs, add a link per file and include llm-summary.txt if present
+      const summaryPath = path.join(dirPath, "llm-summary.txt");
+      if (fs.existsSync(summaryPath)) {
+        linksSection += fs.readFileSync(summaryPath, "utf-8") + "\n\n";
+      }
+      // Cap link list at 100 entries to bound llms.txt size as the API surface grows.
+      for (const file of files.slice(0, 100)) {
+        const urlPath = getUrlPath(file, STATIC_DIR);
+        const fileName = path.basename(file, ext);
+        linksSection += `- [${fileName}](${urlPath})\n`;
+      }
+      if (files.length > 100) {
+        linksSection += `- ... and ${files.length - 100} more files\n`;
+      }
+    } else {
+      // For HTML API docs, process only index files for links
+      const indexFiles = files.filter(
+        (f) => f.endsWith("index.html") || f.includes("/fn.") || f.includes("/struct.") || f.includes("/trait.")
+      );
+
+      // Add links for key files
+      for (const file of indexFiles.slice(0, 100)) {
+        // Limit to 100 links per section
+        const urlPath = getUrlPath(file, STATIC_DIR);
+        const fileName = path.basename(file, ext);
+        linksSection += `- [${fileName}](${urlPath})\n`;
+      }
 
-    if (indexFiles.length > 100) {
-      linksSection += `- ... and ${indexFiles.length - 100} more files\n`;
+      if (indexFiles.length > 100) {
+        linksSection += `- ... and ${indexFiles.length - 100} more files\n`;
+      }
     }
 
     linksSection += "\n";
 
     // Add full content for all files
-    for (const file of htmlFiles) {
+    for (const file of files) {
       try {
-        const html = fs.readFileSync(file, "utf-8");
-        const text = htmlToText(html);
+        const raw = fs.readFileSync(file, "utf-8");
+        const text = isMarkdown ? raw.trim() : htmlToText(raw);
 
         if (text.length > 100) {
           // Only include if there's meaningful content
@@ -220,6 +281,11 @@ function main() {
     }
   }
 
+  if (sectionsAdded === 0) {
+    console.log("No API docs found on disk — leaving llms.txt and llms-full.txt unchanged");
+    return;
+  }
+
   // Append to llms.txt
   fs.writeFileSync(llmsTxtPath, llmsTxtContent + linksSection);
   console.log(`Updated llms.txt with API reference links`);

docs/scripts/augment_sitemap.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Post-build script to add static API documentation URLs to the sitemap.
+ *
+ * Docusaurus only includes its managed routes in sitemap.xml. This script
+ * appends entries for the auto-generated API docs in static/ that are
+ * copied to build/ but not indexed by the sitemap plugin.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const BUILD_DIR = path.join(__dirname, "..", "build");
+// Override with SITE_URL env var if the canonical URL ever changes.
+// Kept in sync with `url` in docusaurus.config.js.
+// Trailing slash is stripped because <loc> entries below prepend "/".
+const SITE_URL = (process.env.SITE_URL || "https://docs.aztec.network").replace(/\/+$/, "");
+
+// Load version config to determine which version subdirectory to index.
+let developerVersionConfig;
+try {
+  developerVersionConfig = require("../developer_version_config.json");
+} catch {
+  developerVersionConfig = null;
+}
+
+const defaultType = developerVersionConfig?.mainnet
+  ? "mainnet"
+  : developerVersionConfig?.testnet
+    ? "testnet"
+    : null;
+
+if (!defaultType) {
+  console.warn("Warning: No default version found — skipping sitemap augmentation");
+  process.exit(0);
+}
+
+/**
+ * Recursively find all files with a given extension.
+ */
+function findFiles(dir, ext) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(fullPath, ext));
+    } else if (entry.name.endsWith(ext)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function main() {
+  const sitemapPath = path.join(BUILD_DIR, "sitemap.xml");
+
+  if (!fs.existsSync(sitemapPath)) {
+    console.error("Error: build/sitemap.xml not found. Run the build first.");
+    process.exit(1);
+  }
+
+  let sitemap = fs.readFileSync(sitemapPath, "utf-8");
+
+  // Aztec.nr API HTML files (skip raw markdown — those aren't browsable pages)
+  const nrApiDir = path.join(BUILD_DIR, `aztec-nr-api/${defaultType}`);
+  // Exclude Noir stdlib (duplicated at noir-lang.org), the all.html mega-index,
+  // and per-constant global.*.html pages. Keeps the sitemap aligned with the
+  // Typesense stop_urls list so both discovery paths surface the same content.
+  const EXCLUDE_RE = new RegExp(
+    `aztec-nr-api/${defaultType}/(std/|all\\.html$|.*/global\\.[^/]+\\.html$)`
+  );
+  const htmlFiles = findFiles(nrApiDir, ".html").filter(
+    (f) => !EXCLUDE_RE.test(f.replace(/\\/g, "/"))
+  );
+
+  if (htmlFiles.length === 0) {
+    console.log("No static API docs found to add to sitemap");
+    return;
+  }
+
+  // Build XML entries
+  const entries = htmlFiles
+    .map((file) => {
+      const relativePath = path.relative(BUILD_DIR, file).replace(/\\/g, "/");
+      return `<url><loc>${SITE_URL}/${relativePath}</loc><changefreq>monthly</changefreq><priority>0.3</priority></url>`;
+    })
+    .join("");
+
+  // Insert before closing </urlset>
+  if (!sitemap.includes("</urlset>")) {
+    console.error("Error: build/sitemap.xml missing </urlset> closing tag — aborting.");
+    process.exit(1);
+  }
+  sitemap = sitemap.replace("</urlset>", entries + "</urlset>");
+
+  fs.writeFileSync(sitemapPath, sitemap);
+  console.log(`Added ${htmlFiles.length} Aztec.nr API doc URLs to sitemap.xml`);
+}
+
+main();