docs: update instructions (#2297)

Fixes #1827

docs/docs/dev_docs/getting_started/updating.md

@@ -0,0 +1,91 @@
+---
+title: Updating
+---
+
+There are 4 components whose versions need to be kept compatible:
+1. Aztec Sandbox,
+2. Aztec CLI,
+3. Noir compiler `nargo`,
+4. Noir framework for Aztec contracts `aztec.nr`.
+
+Aztec Sandbox, Aztec CLI and `aztec.nr` are using the same versioning scheme and their versions must match.
+The Noir compiler `nargo` has its own versioning scheme and its version must match the compatible nargo version specified in Sandbox.
+
+## Updating Aztec Sandbox
+To update the sandbox to the latest version, simply run the curl command we used for installation again:
+```shell
+/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')"
+```
+
+It will download and start the latest version of sandbox.
+
+If you would like to use a fixed version of the sandbox, you can export the `SANDBOX_VERSION` environmental variable.
+If you are unsure what version to use go to [aztec-packages repository](https://github.com/AztecProtocol/aztec-packages/releases) and choose the `aztec-packages` release based on the changelog.
+
+Then set the `SANDBOX_VERSION` environmental variable to the version you want to use. E.g.:
+```shell
+export SANDBOX_VERSION=#include_aztec_short_version
+```
+
+Now when you run the curl command it will use the version you specified.
+To verify that it's the case check the console output of the curl command.
+You should see the following line:
+```
+Setting up Aztec Sandbox v#include_aztec_short_version (nargo #include_noir_version), please stand by...
+```
+
+Alternatively you can open a new terminal and use aztec-cli to get the version.
+
+#include_code node-info yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+The sandbox version should be the same as the one we chose by setting the `SANDBOX_VERSION` environmental variable.
+
+## Updating Aztec CLI
+If the latest version was used when updating the sandbox then we can simply run the following command to update the CLI:
+```shell
+npm install -g @aztec/cli
+```
+
+If a specific version was set for the sandbox then we need to install the CLI with the same version:
+```shell
+npm install -g @aztec/cli@$SANDBOX_VERSION
+```
+
+E.g.:
+```shell
+npm install -g @aztec/cli@#include_aztec_short_version
+```
+
+## Updating Noir compiler
+Now we need to update the Noir compiler `nargo` to the version compatible with the sandbox.
+Use `aztec-cli` to get it:
+#include_code node-info yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Then we install the `Compatible Nargo Version` with (replace `COMPATIBLE_NARGO_VERSION` with the version from the previous command):
+```shell
+noirup -v COMPATIBLE_NARGO_VERSION
+```
+
+## Updating Noir framework
+Finally we need to update the Noir framework for Aztec contracts.
+We need to install a version compatible with our `nargo` and Sandbox.
+
+To update the framework we will update a tag of the `aztec.nr` dependency in the `Nargo.toml` file to the `SANDBOX_VERSION` from above.
+Find all the dependencies pointing to the directory within `aztec.nr` framework and update the corresponding tag.
+E.g.:
+
+```diff
+[dependencies]
+-aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="aztec-packages-v0.7.5", directory="yarn-project/aztec-nr/aztec" }
++aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" }
+-value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="aztec-packages-v0.7.5", directory="yarn-project/aztec-nr/value-note" }
++value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note" }
+```
+
+Go to the project directory and try compiling it with `aztec-cli`` to verify that the update was successful:
+```shell
+cd /your/project/root
+aztec-cli compile ./
+```
+
+If the dependencies fail to resolve ensure that the tag matches a tag in the [aztec-packages repository](https://github.com/AztecProtocol/aztec-packages/tags).

docs/sidebars.js

@@ -196,6 +196,7 @@ const sidebars = {
       items: [
         "dev_docs/getting_started/quickstart",
         "dev_docs/getting_started/sandbox",
+        "dev_docs/getting_started/updating",
       ],
     },
 

docs/src/preprocess/include_version.js

@@ -1,7 +1,7 @@
 const path = require("path");
 const fs = require("fs");
 
-const VERSION_IDENTIFIERS = ["noir", "aztec"];
+const VERSION_IDENTIFIERS = ["noir", "aztec", "aztec_short"];
 
 let versions;
 async function getVersions() {
@@ -24,6 +24,7 @@ async function getVersions() {
       versions = {
         noir: noirVersion,
         aztec: `aztec-packages-v${aztecVersion}`,
+        aztec_short: aztecVersion,
       };
     } catch (err) {
       throw new Error(

yarn-project/aztec-sandbox/package.json

@@ -35,6 +35,7 @@
     "@aztec/ethereum": "workspace:^",
     "@aztec/foundation": "workspace:^",
     "@aztec/l1-artifacts": "workspace:^",
+    "@aztec/noir-compiler": "workspace:^",
     "@aztec/noir-contracts": "workspace:^",
     "@aztec/types": "workspace:^",
     "abitype": "^0.8.11",

yarn-project/aztec-sandbox/src/bin/index.ts

@@ -2,6 +2,7 @@
 import { deployInitialSandboxAccounts } from '@aztec/aztec.js';
 import { createDebugLogger } from '@aztec/foundation/log';
 import { fileURLToPath } from '@aztec/foundation/url';
+import NoirVersion from '@aztec/noir-compiler/noir-version';
 
 import { readFileSync } from 'fs';
 import { dirname, resolve } from 'path';
@@ -23,7 +24,7 @@ async function main() {
   const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json');
   const version = JSON.parse(readFileSync(packageJsonPath).toString()).version;
 
-  logger.info(`Setting up Aztec Sandbox v${version}, please stand by...`);
+  logger.info(`Setting up Aztec Sandbox v${version} (nargo ${NoirVersion.tag}), please stand by...`);
 
   const { l1Contracts, rpcServer, stop } = await createSandbox();
 
@@ -55,7 +56,9 @@ async function main() {
     }
   }
   logger.info(
-    `${splash}\n${github}\n\n`.concat(...accountStrings).concat(`Aztec Sandbox v${version} is now ready for use!`),
+    `${splash}\n${github}\n\n`
+      .concat(...accountStrings)
+      .concat(`Aztec Sandbox v${version} (nargo ${NoirVersion.tag}) is now ready for use!`),
   );
 }
 

yarn-project/aztec-sandbox/tsconfig.json

@@ -27,6 +27,9 @@
     {
       "path": "../l1-artifacts"
     },
+    {
+      "path": "../noir-compiler"
+    },
     {
       "path": "../noir-contracts"
     },

yarn-project/end-to-end/src/cli_docs_sandbox.test.ts

@@ -26,10 +26,24 @@ describe('CLI docs sandbox', () => {
   }, 60_000);
 
   const waitForSandboxWithCli = async () => {
+    const docs = `
+// docs:start:node-info
+% aztec-cli get-node-info
+Node Info:
+
+Sandbox Version: #include_aztec_short_version
+Compatible Nargo Version: #include_noir_version
+Chain Id: 31337
+Protocol Version: 1
+Rollup Address: 0x0dcd1bf9a1b36ce34237eeafef220932846bcd82
+// docs:end:node-info
+`;
+
+    const command = docs.split('\n')[2].split('aztec-cli ')[1];
     while (true) {
       resetCli();
       try {
-        await run('get-node-info');
+        await run(command);
         break;
       } catch (err) {
         await sleep(1000);

yarn-project/yarn.lock

@@ -183,6 +183,7 @@ __metadata:
     "@aztec/ethereum": "workspace:^"
     "@aztec/foundation": "workspace:^"
     "@aztec/l1-artifacts": "workspace:^"
+    "@aztec/noir-compiler": "workspace:^"
     "@aztec/noir-contracts": "workspace:^"
     "@aztec/types": "workspace:^"
     "@jest/globals": ^29.5.0