From 7bdbe9c11c57ff7ac9713dc63e9490f86427a241 Mon Sep 17 00:00:00 2001 From: Charlie <5764343+charlielye@users.noreply.github.com> Date: Fri, 3 Jul 2026 17:49:06 +0000 Subject: [PATCH 1/2] fix(docs): pull bb.js runtime deps via portal instead of hand-mirroring them The recursive_verification example links @aztec/bb.js via link:, which does not install the linked package's own dependencies, so the config hand-listed bb.js's runtime deps (pako, msgpackr, comlink, idb-keyval, commander, tslib). They were unversioned, so the bootstrap ran 'yarn add pako' = latest; when pako 3.0.0 (2026-06-26) dropped the ESM default export bb.js's 'import pako from pako' relies on, ci/docs/examples/bootstrap.sh execute broke on every fresh install. Add portal: support to the examples dependency parser and pull bb.js via portal:, which installs its dependencies at the versions bb.js pins (pako resolves to 2.2.0, not 3.0.0). Delete the hand-mirrored npm list: bb.js's own package.json is now the single source of truth, so this class of drift/float regression can't recur. link: (no dep install) remains for the noir packages. --- docs/examples/ts/bootstrap.sh | 7 +++++++ docs/examples/ts/lib.sh | 20 +++++++++++++++++-- .../ts/recursive_verification/config.yaml | 14 +++++-------- 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/examples/ts/bootstrap.sh b/docs/examples/ts/bootstrap.sh index 302614922013..c234f2d364ab 100755 --- a/docs/examples/ts/bootstrap.sh +++ b/docs/examples/ts/bootstrap.sh @@ -147,6 +147,7 @@ validate_project() { local aztec_deps=("${AZTEC_DEPS[@]}") local explicit_link_deps=("${EXPLICIT_LINK_DEPS[@]}") + local portal_deps=("${PORTAL_DEPS[@]}") local npm_deps=("${NPM_DEPS[@]}") if [ "$PARSED_DEPS_FOUND" = true ]; then @@ -162,6 +163,12 @@ validate_project() { yarn add "${explicit_link_deps[@]}" fi + # Install portal dependencies (like link:, but also installs the package's own deps) + if [ ${#portal_deps[@]} -gt 0 ]; then + echo_stderr "Adding portal deps: ${portal_deps[*]}" + yarn add "${portal_deps[@]}" + fi + # Install external npm dependencies if [ ${#npm_deps[@]} -gt 0 ]; then echo_stderr "Adding npm deps: ${npm_deps[*]}" diff --git a/docs/examples/ts/lib.sh b/docs/examples/ts/lib.sh index 03039d94befa..5608828d76d8 100644 --- a/docs/examples/ts/lib.sh +++ b/docs/examples/ts/lib.sh @@ -5,11 +5,19 @@ # parse_dependencies # # Reads a config.yaml via yq and classifies each dependency entry into one of -# three global arrays: +# these global arrays: # AZTEC_DEPS — @aztec/* packages resolved to pkg@link:/yarn-project/ # EXPLICIT_LINK_DEPS — link: packages resolved to pkg@link:/ +# PORTAL_DEPS — portal: packages resolved to pkg@portal:/ # NPM_DEPS — npm: packages (bare names, e.g. viem) # +# link: vs portal:: link: symlinks the package but does NOT install its own dependencies (the +# consumer must supply them), whereas portal: also installs the package's declared dependencies at +# the versions it pins. Use portal: for standalone packages whose runtime deps the example needs +# (e.g. @aztec/bb.js, which needs pako/msgpackr/...) so the package's own package.json is the single +# source of truth — rather than hand-mirroring its dependency list here (which drifts and, when left +# unversioned, floats to breaking majors). +# # Also sets PARSED_DEPS_FOUND to "true" if any dependency was found, "false" otherwise. parse_dependencies() { local config_file=$1 @@ -17,6 +25,7 @@ parse_dependencies() { AZTEC_DEPS=() EXPLICIT_LINK_DEPS=() + PORTAL_DEPS=() NPM_DEPS=() PARSED_DEPS_FOUND=false @@ -42,12 +51,19 @@ parse_dependencies() { local link_pkg_name="${link_spec%%:*}" local link_path="${link_spec#*:}" EXPLICIT_LINK_DEPS+=("${link_pkg_name}@link:${repo_root}/${link_path}") + elif [[ "$pkg" =~ ^portal: ]]; then + # Portal (installs the package's own deps): portal:@aztec/bb.js:barretenberg/ts/bb.js + # -> @aztec/bb.js@portal:$repo_root/barretenberg/ts/bb.js + local portal_spec="${pkg#portal:}" + local portal_pkg_name="${portal_spec%%:*}" + local portal_path="${portal_spec#*:}" + PORTAL_DEPS+=("${portal_pkg_name}@portal:${repo_root}/${portal_path}") elif [[ "$pkg" =~ ^@ ]]; then # @aztec/* package - auto-link from yarn-project/ local pkg_name="${pkg#@aztec/}" AZTEC_DEPS+=("${pkg}@link:${repo_root}/yarn-project/${pkg_name}") else - echo "Warning: Unknown dependency format '$pkg' (use '@aztec/pkg', 'link:pkg:path', or 'npm:pkg')" >&2 + echo "Warning: Unknown dependency format '$pkg' (use '@aztec/pkg', 'link:pkg:path', 'portal:pkg:path', or 'npm:pkg')" >&2 fi done < <(yq eval '.dependencies[]' "$config_file") } diff --git a/docs/examples/ts/recursive_verification/config.yaml b/docs/examples/ts/recursive_verification/config.yaml index 200fa1b77c4e..3837236d57a7 100644 --- a/docs/examples/ts/recursive_verification/config.yaml +++ b/docs/examples/ts/recursive_verification/config.yaml @@ -19,17 +19,13 @@ dependencies: - "@aztec/kv-store" - "@aztec/pxe" - "@aztec/noir-contracts.js" - # Packages outside yarn-project/ - use explicit link paths - - "link:@aztec/bb.js:barretenberg/ts/bb.js" + # Packages outside yarn-project/. bb.js is pulled via portal: (not link:) so its own runtime deps + # (pako, msgpackr, comlink, ...) are installed automatically at the versions bb.js pins — instead of + # hand-listing them here, which drifts from bb.js and, left unversioned, floated to a breaking major + # (pako 3.0.0 dropped the ESM default export bb.js relies on). + - "portal:@aztec/bb.js:barretenberg/ts/bb.js" - "link:@aztec/noir-noir_js:noir/packages/noir_js" # Transitive dependencies of @aztec/noir-noir_js - "link:@aztec/noir-acvm_js:noir/packages/acvm_js" - "link:@aztec/noir-noirc_abi:noir/packages/noirc_abi" - "link:@aztec/noir-types:noir/packages/types" - # Runtime deps of @aztec/bb.js (linked, so its own deps are not auto-installed) - - "npm:pako" - - "npm:msgpackr" - - "npm:comlink" - - "npm:idb-keyval" - - "npm:commander" - - "npm:tslib" From 8a89e488c850940dfe790ec17f313799b45c1532 Mon Sep 17 00:00:00 2001 From: Charlie <5764343+charlielye@users.noreply.github.com> Date: Fri, 3 Jul 2026 21:35:30 +0000 Subject: [PATCH 2/2] fix(docs): supply noir_js runtime pako dep in recursive_verification example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switching bb.js to portal: fixed bb.js's own pako import but surfaced a second pako consumer: @aztec/noir-noir_js (used in its debug.mjs) also declares pako ^2.1.0. It is link:'d (not portal:'d) because its @aztec/noir-* siblings are pinned to unpublished 1.0.0-beta.21 versions that portal cannot fetch, and link: does not install a package's own deps — so noir_js's pako must be supplied explicitly. Pinned to noir_js's own range (^2.1.0) so it can't float to the breaking pako 3.0.0 (dropped ESM default export). --- docs/examples/ts/recursive_verification/config.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/examples/ts/recursive_verification/config.yaml b/docs/examples/ts/recursive_verification/config.yaml index 3837236d57a7..df1cac96a735 100644 --- a/docs/examples/ts/recursive_verification/config.yaml +++ b/docs/examples/ts/recursive_verification/config.yaml @@ -29,3 +29,8 @@ dependencies: - "link:@aztec/noir-acvm_js:noir/packages/acvm_js" - "link:@aztec/noir-noirc_abi:noir/packages/noirc_abi" - "link:@aztec/noir-types:noir/packages/types" + # Runtime dep of @aztec/noir-noir_js (used by its debug.mjs). noir_js is link:'d (not portal:'d) + # because its @aztec/noir-* deps are pinned to unpublished versions, so portal can't fetch them — + # link: does not install a package's own deps, so pako must be supplied here. Pinned to noir_js's + # own range (^2.1.0) so it can't float to the breaking pako 3.0.0. + - "npm:pako@^2.1.0"