chore(docs): Update PXE concepts

docs/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

docs/docs/aztec/concepts/pxe/index.md

@@ -8,44 +8,99 @@ importance: 1
 
 import Image from "@theme/IdealImage";
 
-The Private Execution Environment (or PXE, pronounced 'pixie') is a client-side library for the execution of private operations. It is a TypeScript library and can be run within Node, such as when you run the sandbox. In the future it could be run inside wallet software or a browser.
+This page describes the Private Execution Environment (PXE, pronounced "pixie"), a client-side library for the execution of private operations. It is a TypeScript library that can be run within Node.js, inside wallet software or a browser.
+
+The PXE generates proofs of private function execution, and sends these proofs along with public function execution requests to the sequencer. Private inputs never leave the client-side PXE.
+
+The PXE is responsible for:
+
+- storing secrets (e.g. encryption keys, notes, tagging secrets for note discovery) and exposing an interface for safely accessing them
+- orchestrating private function (circuit) execution and proof generation, including implementing [oracles](../../smart_contracts/oracles/index.md) needed for transaction execution
+- syncing users' relevant network state, obtained from an Aztec node
+- safely handling multiple accounts with siloed data and permissions
+
+One PXE can handle data and secrets for multiple accounts, while also providing isolation between them as required.
+
+## System architecture
+
+```mermaid
+flowchart TB
+    User --Interacts with--> Wallet
+    Wallet --Prompts--> User
+    subgraph Browser
+    Dapp
+    end
+    Dapp --Calls (requires auth)--> Wallet
+    subgraph Client-side
+        Wallet --Scoped--> PXE
+        PXE --Execute/Prove--> Circuits
+        Circuits --Oracle--> PXE
+    end
+    PXE --Queries world-state (causes privacy leaks)--> Node
+    Wallet --Track tx state (may be handled via PXE)--> Node
+```
 
-The PXE generates proofs of private function execution, and sends these proofs along with public function requests to the sequencer. Private inputs never leave the client-side PXE.
+## Components
 
-<Image img={require("/img/pxe.png")} />
+### Transaction Simulator
 
-## PXE Service
+An application will prompt the users PXE to execute a transaction (e.g. execute X function, with Y arguments, from Z account). The application or the wallet may handle gas estimation.
 
-The PXE is a client-side interface of the PXE Service, which is a set of server-side APIs for interacting with the network. It provides functions for account management, contract and transaction interactions, note management, and more.
+The ACIR (Abstract Circuit Intermediate Representation) simulator handles the execution of smart contract functions by simulating transactions. It generates the required data and inputs for these functions. You can find more details about how it works [here](./acir_simulator.md).
 
-## Components
+Until there are simulated simulations ([#9133](https://github.com/AztecProtocol/aztec-packages/issues/9133)), authwits are required for simulation, before attempting to prove.
+
+### Proof Generation
 
-### ACIR simulator
+After simulation, the wallet calls `proveTx` on the PXE with all of the data generated during simulation and any [authentication witnesses](../accounts/authwit.md) (for allowing contracts to act on behalf of the users' account contract).
 
-The ACIR (Abstract Circuit Intermediate Representation) simulator handles the accurate execution of smart contract functions by simulating transactions. It generates the required data and inputs for these functions. You can find more details about how it works [here](./acir_simulator.md).
+Once proven, the wallet sends the transaction to the network and sends the transaction hash back to the application.
 
 ### Database
 
-The database stores transactional data and notes within the user's PXE. In the Aztec protocol, the database is implemented as a key-value database backed by LMDB. There is an interface ([GitHub](https://github.com/AztecProtocol/aztec-packages/blob/ca8b5d9dbff8d8062dbf1cb1bd39d93a4a636e86/yarn-project/pxe/src/database/pxe_database.ts)) for this PXE database that can be implemented in other ways, such as an in-memory database that can be used for testing.
+The database stores transactional data and notes within the user's PXE.
 
 The database stores various types of data, including:
 
-- **Notes**: Encrypted representations of assets.
-- **Deferred Notes**: Notes that are intended for a user but cannot yet be decoded due to the associated contract not being present in the database. When new contracts are deployed, there may be some time before it is accessible from the PXE database. When the PXE database is updated, deferred note are decoded.
-- **Authentication Witnesses**: Data used to approve others from executing transactions on your behalf.
+- **Notes**: Data representing users' private state. These are often stored on-chain, encrypted to a user. A contract will parse on-chain data to find notes relevant for users' accounts and they are stored in the PXE.
+- **Authentication Witnesses**: Data used to approve others for executing transactions on your behalf. The PXE provides this data to transactions on-demand during transaction simulation via oracles.
 - **Capsules**: External data or data injected into the system via [oracles](#oracles).
+- **Address Book**: A list of expected addresses that a PXE may encrypt notes for, or received encrypted notes from. This list helps the PXE reduce the amount of work required to find notes relevant to it's registered accounts.
 
 ### Note discovery
 
-There is an open RFP for how note discovery will work on Aztec. You can find more information in the [forum](https://forum.aztec.network/t/request-for-proposals-note-discovery-protocol/2584).
+Note discovery helps solve the problem of a user parsing the chain for their encrypted notes.
+
+There is a note tagging scheme that allows users to register an expected note sender in their PXE, which tells the PXE to expect notes coming from that expected sender. This helps the PXE more efficiently discover the encrypted notes being created for its registered accounts.
+
+### Authorization
+
+The PXE handles access rights by:
+
+1. action
+2. domain
+3. contract
+4. account
+
+For example, uniswap.com (**domain**) can query (**action**, involves execution that has access to an accounts' private state) on these five token **contracts** for these two **accounts** of mine, that are registered in the PXE.
+
+Available actions include:
+
+- Seeing that the accounts exist in the PXE
+- Running queries, simulations, accessing logs, registering contracts, etc at a given a contract address
+- Manually adding notes
+
+Providing an application with an empty scopes array (e.g. `scopes: []`) to the PXE means that no information can be accessed, but no scopes (e.g. `scopes: undefined`) defaults to _all_ scopes being available.
+
+### Contract management
 
-Currently in the Aztec sandbox, users download every note, compute a secret, and generate the symmetric decryption key from that secret. If the note belongs to them, then the user will have derived the same secret and ultimately the required decryption key.
+Applications can add contract code required for a user to interact with the application to the users PXE. The PXE will check whether the required contracts have already been registered in users PXE. There are no getters to check whether the contract has been registered, as this could leak privacy (e.g. a dapp could check whether specific contracts have been registered in a users PXE and infer information about their interaction history).
 
 ### Keystore
 
 The keystore is a secure storage for private and public keys.
 
-## Oracles
+### Oracles
 
 Oracles are pieces of data that are injected into a smart contract function from the client side. You can read more about why and how they work in the [smart contracts section](../../smart_contracts/oracles/index.md).
 

docs/docs/reference/developer_references/smart_contract_reference/storage/shared_state.md

@@ -86,7 +86,9 @@ Returns the current value in a public, private or unconstrained execution contex
 
 #include_code shared_mutable_get_current_public /noir-projects/noir-contracts/contracts/auth_contract/src/main.nr rust
 
-Calling this function in a private execution context will set the `max_block_number` property of the transaction request, introducing a new validity condition to the entire transaction: it cannot be included in any block with a block number larger than `max_block_number`. This could [potentially leak some privacy](#privacy-considerations).
+Calling this function in a private execution context will have a 1 block delay, as compared to calling in the public context. This is because calling `get_current_value` in private constructs a historical state proof, using the latest proven block, for the public value, so the "current value" in private execution will be delayed by 1 block when compared to what the public value is.
+
+Also, calling in private will set the `max_block_number` property of the transaction request, introducing a new validity condition to the entire transaction: it cannot be included in any block with a block number larger than `max_block_number`. This could [potentially leak some privacy](#privacy-considerations).
 
 #include_code shared_mutable_get_current_private /noir-projects/noir-contracts/contracts/auth_contract/src/main.nr rust
 

docs/package.json

@@ -27,10 +27,10 @@
     "@mdx-js/react": "^3.0.1",
     "@slorber/react-ideal-image": "^0.0.12",
     "axios": "^1.4.0",
-    "clsx": "^1.1.1",
+    "clsx": "^2.0.0",
     "docusaurus-theme-search-typesense": "0.23.0-0",
     "hast-util-is-element": "1.1.0",
-    "prism-react-renderer": "^2.1.0",
+    "prism-react-renderer": "^2.3.0",
     "prop-types": "^15.8.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -45,14 +45,17 @@
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.6.0",
+    "@docusaurus/tsconfig": "3.6.0",
     "@docusaurus/types": "3.6.0",
     "@tsconfig/docusaurus": "^1.0.5",
     "@types/prop-types": "^15",
+    "@types/react": "^18.0.0",
     "concurrently": "^8.0.1",
     "docusaurus-plugin-typedoc": "^0.20.2",
     "dotenv": "^16.3.1",
     "netlify-cli": "^17.23.0",
     "nodemon": "^3.0.1",
+    "react-waypoint": "^10.3.0",
     "typedoc": "^0.25.1",
     "typedoc-plugin-markdown": "^3.16.0",
     "typescript": "^5.0.4"
@@ -68,5 +71,6 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
-  }
+  },
+  "packageManager": "[email protected]"
 }

docs/yarn.lock

@@ -2507,6 +2507,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@docusaurus/tsconfig@npm:3.6.0":
+  version: 3.6.0
+  resolution: "@docusaurus/tsconfig@npm:3.6.0"
+  checksum: 10c0/5ff75afa1c9a8bff6a1c4722517a05827bb87a689ad99e5d9ccc5c7eeef0c1fff7d8d71fea1d0b4c3eb6e7b1aeea618c109512dc5443736e8ba4dcdd5456e3c4
+  languageName: node
+  linkType: hard
+
 "@docusaurus/types@npm:3.6.0":
   version: 3.6.0
   resolution: "@docusaurus/types@npm:3.6.0"
@@ -6972,6 +6979,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react@npm:^18.0.0":
+  version: 18.3.18
+  resolution: "@types/react@npm:18.3.18"
+  dependencies:
+    "@types/prop-types": "npm:*"
+    csstype: "npm:^3.0.2"
+  checksum: 10c0/8fb2b00672072135d0858dc9db07873ea107cc238b6228aaa2a9afd1ef7a64a7074078250db38afbeb19064be8ea6af5eac32d404efdd5f45e093cc4829d87f8
+  languageName: node
+  linkType: hard
+
 "@types/retry@npm:0.12.0":
   version: 0.12.0
   resolution: "@types/retry@npm:0.12.0"
@@ -8194,26 +8211,29 @@ __metadata:
     "@docusaurus/plugin-ideal-image": "npm:3.6.0"
     "@docusaurus/preset-classic": "npm:3.6.0"
     "@docusaurus/theme-mermaid": "npm:3.6.0"
+    "@docusaurus/tsconfig": "npm:3.6.0"
     "@docusaurus/types": "npm:3.6.0"
     "@mdx-js/react": "npm:^3.0.1"
     "@slorber/react-ideal-image": "npm:^0.0.12"
     "@tsconfig/docusaurus": "npm:^1.0.5"
     "@types/prop-types": "npm:^15"
+    "@types/react": "npm:^18.0.0"
     axios: "npm:^1.4.0"
-    clsx: "npm:^1.1.1"
+    clsx: "npm:^2.0.0"
     concurrently: "npm:^8.0.1"
     docusaurus-plugin-typedoc: "npm:^0.20.2"
     docusaurus-theme-search-typesense: "npm:0.23.0-0"
     dotenv: "npm:^16.3.1"
     hast-util-is-element: "npm:1.1.0"
     netlify-cli: "npm:^17.23.0"
     nodemon: "npm:^3.0.1"
-    prism-react-renderer: "npm:^2.1.0"
+    prism-react-renderer: "npm:^2.3.0"
     prop-types: "npm:^15.8.1"
     react: "npm:^18.2.0"
     react-dom: "npm:^18.2.0"
     react-markdown: "npm:6.0.0"
     react-player: "npm:^2.12.0"
+    react-waypoint: "npm:^10.3.0"
     rehype-katex: "npm:7"
     remark-math: "npm:6"
     remark-mdx: "npm:^3.0.1"
@@ -9270,13 +9290,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"clsx@npm:^1.1.1":
-  version: 1.2.1
-  resolution: "clsx@npm:1.2.1"
-  checksum: 10c0/34dead8bee24f5e96f6e7937d711978380647e936a22e76380290e35486afd8634966ce300fc4b74a32f3762c7d4c0303f442c3e259f4ce02374eb0c82834f27
-  languageName: node
-  linkType: hard
-
 "clsx@npm:^2.0.0, clsx@npm:^2.1.0":
   version: 2.1.1
   resolution: "clsx@npm:2.1.1"
@@ -19397,7 +19410,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"prism-react-renderer@npm:^2.1.0, prism-react-renderer@npm:^2.3.0":
+"prism-react-renderer@npm:^2.3.0":
   version: 2.3.1
   resolution: "prism-react-renderer@npm:2.3.1"
   dependencies: