Skip to content

Commit

Permalink
feat!: rename storage inclusion proof to historical storage read (#5379)
Browse files Browse the repository at this point in the history 
`prove_public_value_inclusion` forces the caller to produce and pass a
historical public storage value. This is subpar because it introduces an
oracle requirement for no good reason - there is only one correct value
that can be passed.

This PR renames `public_value_inclusion` to `history::storage`, and
`prove_public_value_inclusion` to `storage_historical_read`. The
function now _returns_ the historical storage value, so no oracles are
needed. If comparison with some value is required, the caller can still
manually do this against the return value (though this seems an unlikely
use case).

I also updated slightly some of the docs, added some notes, and
liberally touched the tests a little bit. This is another example of how
annoying it is to not be able to return anything from a private call
(forcing us to to perform the assertion inside noir, which makes the
test obscure).

---------

Co-authored-by: Jan Beneš <[email protected]>
  • Loading branch information
@nventuro @benesjan
nventuro and benesjan authored Mar 22, 2024
1 parent 6573173 commit b6e7216
Show file tree
Hide file tree
Showing 8 changed files with 218 additions and 198 deletions.
126 changes: 64 additions & 62 deletions docs/docs/developers/contracts/references/history_lib_reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,30 @@ title: History Reference

<!-- Note: This will soon be moved into an Aztec.nr reference category under Aztec.nr smart contracts -->

## Note inclusion
## Note inclusion

Note inclusion proves that a note existed (its hash was included in a note hash tree) at a specific block number. There exists a version that tests for note inclusion at current block number. It is recommended to use this version whenever possible to reduce cost.

### prove_note_inclusion

`prove_note_inclusion_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_with_header| Note | The note you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ---------------- | -------------- | ----------------------------------------- |
| note_with_header | Note | The note you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |

## prove_note_commitment_inclusion

A **commitment**, also referred to as a **note hash** is a public acknowledgment of the existence of a note without revealing the content of the note. You can learn more about how to compress a note to a note hash [here](../../../learn/concepts/storage/trees/main.md#example-note).

`prove_note_commitment_inclusion` takes 2 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_with_header| Note | The note you are proving inclusion for |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ---------------- | -------------- | -------------------------------------- |
| note_with_header | Note | The note you are proving inclusion for |
| context | PrivateContext | Private context |

## Note validity

Expand All @@ -37,18 +37,18 @@ This proves that a note exists and has not been nullified at a specified block.

`prove_note_validity_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_with_header| Note | The note you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ---------------- | -------------- | ----------------------------------------- |
| note_with_header | Note | The note you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |

`prove_note_validity` takes 2 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_with_header| Note | The note you are proving inclusion for |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ---------------- | -------------- | -------------------------------------- |
| note_with_header | Note | The note you are proving inclusion for |
| context | PrivateContext | Private context |

## Nullifier inclusion

Expand All @@ -58,18 +58,18 @@ This proves that a nullifier was included in a certain block (can be used to pro

`prove_nullifier_inclusion_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| nullifier | Field | The nullifier you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ------------ | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |

`prove_nullifier_inclusion` takes 2 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |
| Name | Type | Description |
| --------- | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |

### prove_note_is_nullified_at / prove_note_is_nullified

Expand All @@ -83,45 +83,47 @@ This proves that a nullifier was not included in a certain block (can be used to

`prove_nullifier_not_included_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| nullifier | Field | The nullifier you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ------------ | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| block_number | u32 | Block number for proving note's existence |
| context | PrivateContext | Private context |

`prove_nullifier_not_included` takes 2 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |
| Name | Type | Description |
| --------- | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |

### prove_note_not_nullified_at / prove_note_not_nullified

Instead of passing the nullifier, you can check that a note has not been nullified by passing the note.

## Public value inclusion
## Public storage historical reads

This proves that a public value exists at a certain block.
These return the value stored in a public storage slot of a given contract at the end of the execution of a certain block (the latest one if using `public_storage_historical_read`).

### prove_public_value_inclusion
Note that it is never possible to read the _current_ value in a public storage slot in private since private execution is local and by definition always works on _historical_ state.

`prove_public_value_inclusion_at` takes 4 parameters:
### public_storage_historical_read

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| value | Field | The public value you are proving inclusion for |
| storage_slot | Field | Storage slot the value exists in |
| block_number | u32 | Block number for proving value's existence |
| context | PrivateContext | Private context |
`public_storage_historical_read_at` takes 4 parameters:

`prove_public_value_inclusion` takes 3 parameters:
| Name | Type | Description |
| ---------------- | -------------- | ---------------------------------------- |
| context | PrivateContext | Private context |
| storage_slot | Field | Storage slot |
| contract_address | AztecAddress | The contract that owns the storage slot |
| block_number | u32 | Historical block number in which to read |

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| value | Field | The public value you are proving inclusion for |
| storage_slot | Field | Storage slot the value exists in |
| context | PrivateContext | Private context |
`public_storage_historical_read` takes 3 parameters. `block_number` is implicitly the historical block number from the context:

| Name | Type | Description |
| ---------------- | -------------- | --------------------------------------- |
| context | PrivateContext | Private context |
| storage_slot | Field | Storage slot |
| contract_address | AztecAddress | The contract that owns the storage slot |

## Contract inclusion

Expand All @@ -131,15 +133,15 @@ This proves that a contract exists in, ie had been deployed before or in, a cert

`prove_contract_inclusion_at` takes 7 parameters:

| Name | Type | Description |
|---------------------------|-----------------|-------------------------------------------------------|
| deployer_public_key | GrumpkinPoint | Public key of the contract deployer |
| contract_address_salt | Field | Unique identifier for the contract's address |
| function_tree_root | Field | Root of the contract's function tree |
| constructor_hash | Field | Hash of the contract's constructor |
| portal_contract_address | EthAddress | Ethereum address of the associated portal contract |
| block_number | u32 | Block number for proof verification |
| context | PrivateContext | Private context |
| Name | Type | Description |
| ----------------------- | -------------- | -------------------------------------------------- |
| deployer_public_key | GrumpkinPoint | Public key of the contract deployer |
| contract_address_salt | Field | Unique identifier for the contract's address |
| function_tree_root | Field | Root of the contract's function tree |
| constructor_hash | Field | Hash of the contract's constructor |
| portal_contract_address | EthAddress | Ethereum address of the associated portal contract |
| block_number | u32 | Block number for proof verification |
| context | PrivateContext | Private context |

If there is no associated portal contract, you can use a zero Ethereum address:

Expand Down
44 changes: 39 additions & 5 deletions docs/docs/misc/migration_notes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,31 @@ keywords: [sandbox, cli, aztec, notes, migration, updating, upgrading]

Aztec is in full-speed development. Literally every version breaks compatibility with the previous ones. This page attempts to target errors and difficulties you might encounter when upgrading, and how to resolve them.

## TBD

This comment has been minimized.

Sign in to view

Copy link
@rahul-kothari

rahul-kothari Mar 25, 2024

Contributor

@nventuro you can see the next release version if you search for "release" in the open pull requests. But typically due to breaking changes, it is fine to assume that the next version will be an incremental.
So 0.30.0 -> 0.31.0

### [Aztec.nr] Public storage historical read API improvement

`history::public_value_inclusion::prove_public_value_inclusion` has been renamed to `history::public_storage::public_storage_historical_read`, and its API changed slightly. Instead of receiving a `value` parameter it now returns the historical value stored at that slot.

If you were using an oracle to get the value to pass to `prove_public_value_inclusion`, drop the oracle and use the return value from `public_storage_historical_read` instead:

```diff
- let value = read_storage();
- prove_public_value_inclusion(value, storage_slot, contract_address, context);
+ let value = public_storage_historical_read(storage_slot, contract_address, context);
```

If you were proving historical existence of a value you got via some other constrained means, perform an assertion against the return value of `public_storage_historical_read` instead:

```diff
- prove_public_value_inclusion(value, storage_slot, contract_address, context);
+ assert(public_storage_historical_read(storage_slot, contract_address, context) == value);
```

## 0.30.0

### [AztecJS] Simplify authwit syntax

```diff
- const messageHash = computeAuthWitMessageHash(accounts[1].address, action.request());
- await wallets[0].setPublicAuth(messageHash, true).send().wait();
Expand All @@ -30,7 +53,7 @@ Also note some of the naming changes:

### [Aztec.nr] Automatic NoteInterface implementation and selector changes

Implementing a note required a fair amount of boilerplate code, which has been substituted by the `#[aztec(note)]` attribute.
Implementing a note required a fair amount of boilerplate code, which has been substituted by the `#[aztec(note)]` attribute.

```diff
+ #[aztec(note)]
Expand Down Expand Up @@ -107,7 +130,7 @@ impl NoteInterface<ADDRESS_NOTE_LEN> for AddressNote {

Automatic note (de)serialization implementation also means it is now easier to filter notes using `NoteGetterOptions.select` via the `::properties()` helper:

Before:
Before:

```rust
let options = NoteGetterOptions::new().select(0, amount, Option::none()).select(1, owner.to_field(), Option::none()).set_limit(1);
Expand Down Expand Up @@ -139,7 +162,7 @@ Before this version, every contract was required to have exactly one `constructo

To signal that a function can be used to **initialize** a contract, you must now decorate it with the `#[aztec(initializer)]` attribute. Initializers are regular functions that set an "initialized" flag (a nullifier) for the contract. A contract can only be initialized once, and contract functions can only be called after the contract has been initialized, much like a constructor. However, if a contract defines no initializers, it can be called at any time. Additionally, you can define as many initializer functions in a contract as you want, both private and public.

To migrate from current code, simply add an initializer attribute to your constructor functions.
To migrate from current code, simply add an initializer attribute to your constructor functions.

```diff
+ #[aztec(initializer)]
Expand All @@ -165,14 +188,17 @@ context.static_call_public_function(targetContractAddress, targetSelector, args)

A new `prelude` module to include common Aztec modules and types.
This simplifies dependency syntax. For example:

```rust
use dep::aztec::protocol_types::address::AztecAddress;
use dep::aztec::{
context::{PrivateContext, Context}, note::{note_header::NoteHeader, utils as note_utils},
state_vars::Map
};
```

Becomes:

```rust
use dep::aztec::prelude::{AztecAddress, NoteHeader, PrivateContext, Map};
use dep::aztec::context::Context;
Expand All @@ -190,6 +216,7 @@ The prelude consists of
The `internal` keyword is now removed from Noir, and is replaced by an `aztec(internal)` attribute in the function. The resulting behavior is exactly the same: these functions will only be callable from within the same contract.

Before:

```rust
#[aztec(private)]
internal fn double(input: Field) -> Field {
Expand All @@ -198,6 +225,7 @@ internal fn double(input: Field) -> Field {
```

After:

```rust
#[aztec(private)]
#[aztec(internal)]
Expand All @@ -207,26 +235,30 @@ fn double(input: Field) -> Field {
```

### [Aztec.nr] No SafeU120 anymore!

Noir now have overflow checks by default. So we don't need SafeU120 like libraries anymore.

You can replace it with `U128` instead

Before:
Before:

```
SafeU120::new(0)
```

Now:

```
U128::from_integer(0)
```

### [Aztec.nr] `compute_note_hash_and_nullifier` is now autogenerated

Historically developers have been required to include a `compute_note_hash_and_nullifier` function in each of their contracts. This function is now automatically generated, and all instances of it in contract code can be safely removed.

It is possible to provide a user-defined implementation, in which case auto-generation will be skipped (though there are no known use cases for this).

### [Aztec.nr] Updated naming of state variable wrappers
### [Aztec.nr] Updated naming of state variable wrappers

We have decided to change the naming of our state variable wrappers because the naming was not clear.
The changes are as follows:
Expand Down Expand Up @@ -254,6 +286,7 @@ Furthermore, the `caller` parameter of the "authwits" have been moved "further o
For most contracts, this won't be changing much, but for the account contract, it will require a few changes.

Before:

```rust
#[aztec(public)]
fn is_valid_public(message_hash: Field) -> Field {
Expand All @@ -269,6 +302,7 @@ fn is_valid(message_hash: Field) -> Field {
```

After:

```rust
#[aztec(private)]
fn spend_private_authwit(inner_hash: Field) -> Field {
Expand Down
2 changes: 1 addition & 1 deletion noir-projects/aztec-nr/aztec/src/history.nr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ mod note_inclusion;
mod note_validity;
mod nullifier_inclusion;
mod nullifier_non_inclusion;
mod public_value_inclusion;
mod public_storage;
Loading

0 comments on commit b6e7216

Please sign in to comment.