Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: more RPC Server --> PXE naming fixes #2574

Merged
merged 4 commits into from
Sep 28, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/docs/concepts/foundation/accounts/keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,8 @@ An application in Aztec.nr can access the encryption public key for a given addr
#include_code encrypted /yarn-project/aztec-nr/value-note/src/utils.nr rust

:::info
In order to be able to provide the public encryption key for a given address, that public key needs to have been registered in advance. At the moment, there is no broadcasting mechanism for public keys, which means that you will need to manually register all addresses you intend to send encrypted notes to. You can do this via the `registerRecipient` method of the Private Execution Environment (PXE), callable either via aztec.js or the CLI. Note that any accounts you own that have been added to the RPC server are automatically registered.
In order to be able to provide the public encryption key for a given address, that public key needs to have been registered in advance. At the moment, there is no broadcasting mechanism for public keys, which means that you will need to manually register all addresses you intend to send encrypted notes to. You can do this via the `registerRecipient` method of the Private Execution Environment (PXE), callable either via aztec.js or the CLI.
Note that any accounts you own that have been added to the PXE are automatically registered.
:::

### Nullifier secrets
Expand Down
4 changes: 3 additions & 1 deletion docs/docs/concepts/foundation/accounts/main.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,9 @@ However, this is not required when sitting on the receiving end. A user can dete

Account contracts are also expected, though not required by the protocol, to implement a set of methods for authorizing actions on behalf of the user. During a transaction, a contract may call into the account contract and request the user authorization for a given action, identified by a hash. This pattern is used, for instance, for transferring tokens from an account that is not the caller.

When executing a private function, this authorization is checked by requesting an _auth witness_ from the execution oracle, which is usually a signed message. The RPC Server is responsible for storing these auth witnesses and returning them to the requesting account contract. Auth witnesses can belong to the current user executing the local transaction, or to another user who shared it out-of-band.
When executing a private function, this authorization is checked by requesting an _auth witness_ from the execution oracle, which is usually a signed message.
The PXE is responsible for storing these auth witnesses and returning them to the requesting account contract.
Auth witnesses can belong to the current user executing the local transaction, or to another user who shared it out-of-band.

However, during a public function execution, it is not possible to retrieve a value from the local oracle. To support authorizations in public functions, account contracts should save in contract storage what actions have been pre-authorized by their owner.

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/dev_docs/tutorials/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ Private state in the Aztec Network is represented via sets of [private notes](..

#include_code value-note-def yarn-project/aztec-nr/value-note/src/value_note.nr rust

We can query the RPC server for all notes encrypted for a given user in a contract slot. For this example, we'll get all notes encrypted for the `owner` user that are stored on the token contract address and on the slot we calculated earlier. To calculate the actual balance, we extract the `value` of each note, which is the first element, and sum them up.
We can query the Private eXecution Environment (PXE) for all notes encrypted for a given user in a contract slot. For this example, we'll get all notes encrypted for the `owner` user that are stored on the token contract address and on the slot we calculated earlier. To calculate the actual balance, we extract the `value` of each note, which is the first element, and sum them up.

#include_code private-storage /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript

Expand All @@ -157,7 +157,7 @@ At the time of this writing, only unencrypted events can be queried directly. En

#### Querying unencrypted logs

We can query the RPC server for the unencrypted logs emitted in the block where our transaction is mined. Note that logs need to be unrolled and formatted as strings for consumption.
We can query the PXE for the unencrypted logs emitted in the block where our transaction is mined. Note that logs need to be unrolled and formatted as strings for consumption.

#include_code unencrypted-logs /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ This should have created an artifact `contracts/token/target/Token.json` with th

## Deploy your contracts

Let's now write a script for deploying your contracts to the Sandbox. We'll create an RPC client, and then use the `ContractDeployer` class to deploy our contracts, and store the deployment address to a local JSON file.
Let's now write a script for deploying your contracts to the Sandbox. We'll create a Private eXecution Environment (PXE) client, and then use the `ContractDeployer` class to deploy our contracts, and store the deployment address to a local JSON file.

Create a new file `src/deploy.mjs`:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Let's start by showing our user's private balance for the token across their acc
#include_code balance_of_private yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust

:::info
Note that this function will only return a valid response for accounts registered in the RPC Server, since it requires access to the [user's private state](../../wallets/main.md#private-state). In other words, you cannot query the private balance of another user for the token contract.
Note that this function will only return a valid response for accounts registered in the Private eXecution Environment (PXE), since it requires access to the [user's private state](../../wallets/main.md#private-state). In other words, you cannot query the private balance of another user for the token contract.
:::

To do this, let's first initialize a new `Contract` instance using `aztec.js` that represents our deployed token contracts. Create a new `src/contracts.mjs` file with the imports for our artifacts and other dependencies:
Expand Down Expand Up @@ -43,7 +43,7 @@ Balance of 0x0e1f60e8566e2c6d32378bdcadb7c63696e853281be798c107266b8c3a88ea9b: 0

## Transferring private tokens

Now that we can see the balance for each user, let's transfer tokens from one account to another. To do this, we will first need access to a `Wallet` object. This wraps access to an RPC Server and also provides an interface to craft and sign transactions on behalf of one of the user accounts.
Now that we can see the balance for each user, let's transfer tokens from one account to another. To do this, we will first need access to a `Wallet` object. This wraps access to an PXE and also provides an interface to craft and sign transactions on behalf of one of the user accounts.

We can initialize a wallet using one of the `getAccount` methods from `aztec.js`, along with the corresponding signing and encryption keys:

Expand Down Expand Up @@ -98,7 +98,7 @@ While they are [fundamentally differently](../../../concepts/foundation/state_mo
#include_code showPublicBalances yarn-project/end-to-end/src/sample-dapp/index.mjs javascript

:::info
Since this is a public token contract we are working with, we can now query the balance for any address, not just those registered in our local RPC Server. We can also send funds to addresses for which we don't know their [public encryption key](../../../concepts/foundation/accounts/keys.md#encryption-keys).
Since this is a public token contract we are working with, we can now query the balance for any address, not just those registered in our local PXE. We can also send funds to addresses for which we don't know their [public encryption key](../../../concepts/foundation/accounts/keys.md#encryption-keys).
:::

Here, since the public token contract does not mint any initial funds upon deployment, the balances for all of our user's accounts will be zero. But we can send a transaction to mint tokens to change this, using very similar code to the one for sending private funds:
Expand All @@ -121,7 +121,7 @@ Balance of 0x226f8087792beff8d5009eb94e65d2a4a505b70baf4a9f28d33c8d620b0ba972: 0
Balance of 0x0e1f60e8566e2c6d32378bdcadb7c63696e853281be798c107266b8c3a88ea9b: 0
```

Public functions can emit [unencrypted public logs](../../contracts/syntax/events.md#unencrypted-events), which we can query via the RPC Server interface. In particular, the public token contract emits a generic `Coins minted` whenever the `mint` method is called:
Public functions can emit [unencrypted public logs](../../contracts/syntax/events.md#unencrypted-events), which we can query via the PXE interface. In particular, the public token contract emits a generic `Coins minted` whenever the `mint` method is called:

#include_code unencrypted_log yarn-project/noir-contracts/src/contracts/public_token_contract/src/main.nr rust

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/dev_docs/tutorials/writing_dapp/project_setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@ yarn add @aztec/aztec.js

## Next steps

With your project already set up, let's [connect to the Sandbox RPC Server and grab an account to interact with it](./pxe_service.md).
With your project already set up, let's [connect to the Private eXecution Environment (PXE) running inside Sandbox and grab an account to interact with it](./pxe_service.md).
21 changes: 14 additions & 7 deletions docs/docs/dev_docs/tutorials/writing_dapp/pxe_service.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
# Connecting to the RPC Server
# Connecting to the Private eXecution Environment (PXE)

As an app developer, the [Private Execution Environment (PXE)](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/pxe) interface provides you with access to the user's accounts and their private state, as well as a connection to the network for accessing public global state.
PXE is a component of the Aztec Protocol that provides a private execution environment for your application.

During the Sandbox phase, this role is fulfilled by the [Aztec Sandbox](../../getting_started/sandbox.md), which runs a local RPC Server and an Aztec Node, both connected to a local Ethereum development node like Anvil. The Sandbox also includes a set of pre-initialized accounts that you can use from your app.
As an app developer, the [PXE](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/pxe) interface provides you with access to the user's accounts and their private state, as well as a connection to the network for accessing public global state.

During the Sandbox phase, this role is fulfilled by the [Aztec Sandbox](../../getting_started/sandbox.md), which runs a local PXE and an Aztec Node, both connected to a local Ethereum development node like Anvil.
The Sandbox also includes a set of pre-initialized accounts that you can use from your app.

In this section, we'll connect to the Sandbox from our project.

## Create RPC client
## Create PXE client

We'll use the `createPXEClient` function from `aztec.js` to connect to the Sandbox, which by default runs on `localhost:8080`. To test the connection works, we'll request and print the node's chain id.
We'll use the `createPXEClient` function from `aztec.js` to connect to the Sandbox.
Sandbox exposes a HTTP JSON-RPC interface of PXE.
By default it runs on `localhost:8080`.
To test the connection works, we'll request and print the node's chain id.

Let's create our first file `src/index.mjs` with the following contents:

Expand All @@ -26,7 +32,8 @@ Should the above fail due to a connection error, make sure the Sandbox is runnin

## Load user accounts

With our connection to the RPC server, let's try loading the accounts that are pre-initialized in the Sandbox:
In sandbox PXE comes with a set of pre-initialized accounts that you can use from your app.
Let's try loading the accounts:

#include_code showAccounts yarn-project/end-to-end/src/sample-dapp/index.mjs javascript

Expand All @@ -41,4 +48,4 @@ User accounts:

## Next steps

With a working connection to the RPC Server, let's now setup our application by [compiling and deploying our contracts](./contract_deployment.md).
With a working connection to PXE, let's now setup our application by [compiling and deploying our contracts](./contract_deployment.md).
4 changes: 3 additions & 1 deletion docs/docs/dev_docs/wallets/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ Wallets expose to dapps an interface that allows them to act on behalf of the us

## Overview

Architecture-wise, a wallet is an instance of an **Private Execution Environment (PXE)** which manages user keys and private state. The RPC server also communicates with an **Aztec Node** for retrieving public information or broadcasting transactions. Note that the RPC server requires a local database for keeping private state, and is also expected to be continuously syncing new blocks for trial-decryption of user notes.
Architecture-wise, a wallet is an instance of an **Private Execution Environment (PXE)** which manages user keys and private state.
The PXE also communicates with an **Aztec Node** for retrieving public information or broadcasting transactions.
Note that the PXE requires a local database for keeping private state, and is also expected to be continuously syncing new blocks for trial-decryption of user notes.

Additionally, a wallet must be able to handle one or more [account contract implementations](../../concepts/foundation/accounts/main.md#account-contracts-and-wallets). When a user creates a new account, the account is represented on-chain by an account contract. The wallet is responsible for deploying and interacting with this contract. A wallet may support multiple flavours of accounts, such as an account that uses ECDSA signatures, or one that relies on WebAuthn, or one that requires multi-factor authentication. For a user, the choice of what account implementation to use is then determined by the wallet they interact with.

Expand Down
7 changes: 5 additions & 2 deletions docs/docs/dev_docs/wallets/creating_schnorr_accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This section shows how to create schnorr account wallets on the Aztec Sandbox.
An in-depth explaining about accounts on aztec can be found [here](../../concepts/foundation/accounts/main.md). But creating an account on the Sandbox does 2 things:

1. Deploys an account contract -- representing you -- allowing you to perform actions on the network (deploy contracts, call functions etc).
2. Adds your encryption keys to the RPC Server allowing it to decrypt and manage your private state.
2. Adds your encryption keys to the Private eXecution Environment (PXE) allowing it to decrypt and manage your private state.

## Pre-requisites

Expand Down Expand Up @@ -53,7 +53,10 @@ That might seem like a lot to digest but it can be broken down into the followin
Note, we use the `getRegisteredAccounts` API to verify that the addresses computed as part of the
account contract deployment have been successfully added to the Sandbox.

If you were looking at your terminal that is running the Sandbox you should have seen a lot of activity. This is because the Sandbox will have simulated the deployment of both contracts, executed the private kernel circuit for each before submitted 2 transactions to the pool. The sequencer will have picked them up and inserted them into a rollup and executed the recursive rollup circuits before publishing the rollup to Anvil. Once this has completed, the rollup is retrieved and pulled down to the internal RPC Server so that any new account state can be decrypted.
If you were looking at your terminal that is running the Sandbox you should have seen a lot of activity.
This is because the Sandbox will have simulated the deployment of both contracts, executed the private kernel circuit for each account deployement and later on submitted the 2 transactions to the pool.
The sequencer will have picked them up and inserted them into an L2 block and executed the recursive rollup circuits before publishing the L2 block on L1 (in our case Anvil).
Once this has completed, the L2 block is retrieved and pulled down to the PXE so that any new account state can be decrypted.

## Next Steps

Expand Down
2 changes: 1 addition & 1 deletion yarn-project/aztec-node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The Aztec Node implements a sequencer node in the network, and is currently meant to be used for local development and testing. The Node is the entrypoint for creating and starting a new Sequencer client with default components (a local P2P client, an in-memory merkle tree database, etc).

The Node also exposes methods that are consumed by the client (see `pxe`), such as querying network info or submitting a transaction. As Aztec evolves beyond local development, these methods will be accessible via a JSON-RPC API or similar. Refer to the `end-to-end` tests for examples on how to initialize an Aztec Node and use it along with an RPC client.
The Node also exposes methods that are consumed by the client (see `pxe`), such as querying network info or submitting a transaction. As Aztec evolves beyond local development, these methods will be accessible via a JSON-RPC API or similar. Refer to the `end-to-end` tests for examples on how to initialize an Aztec Node and use it along with a Private eXecution Environment (PXE).

## Development

Expand Down
2 changes: 1 addition & 1 deletion yarn-project/end-to-end/src/fixtures/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ export async function setupPXEService(
* @param account - The account for use in create viem wallets.
* @param config - The aztec Node Configuration
* @param logger - The logger to be used
* @returns RPC Client, viwm wallets, contract addreses etc.
* @returns Private eXecution Environment (PXE) client, viem wallets, contract addreses etc.
*/
async function setupWithSandbox(account: Account, config: AztecNodeConfig, logger: DebugLogger) {
// we are setting up against the sandbox, l1 contracts are already deployed
Expand Down
2 changes: 1 addition & 1 deletion yarn-project/pxe/src/simulator_oracle/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ export class SimulatorOracle implements DBOracle {
preimage: notePreimage.items,
innerNoteHash,
siloedNullifier,
// RPC Client can use this index to get full MembershipWitness
// PXE can use this index to get full MembershipWitness
index,
}),
);
Expand Down