Skip to content

feat!: rename storage inclusion proof to historical storage read #5379

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.

Sign up for GitHub

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

Merged
nventuro merged 8 commits into from
Mar 22, 2024
Merged

feat!: rename storage inclusion proof to historical storage read #5379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
abec188
Adjust public value inclusion api
nventuro Mar 21, 2024
1495394
rename public_value_inclusion to storage
nventuro Mar 21, 2024
a19a44d
Update naming
nventuro Mar 21, 2024
df8c32c
Add migration notes
nventuro Mar 21, 2024
4b99272
Merge branch 'master' into nv/historical-api-return
nventuro Mar 21, 2024
33cd414
Apply suggestions from code review
nventuro Mar 22, 2024
5233db4
rename storage to public storage
nventuro Mar 22, 2024
bea5055
Fix import
nventuro Mar 22, 2024
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
126 changes: 64 additions & 62 deletions docs/docs/developers/contracts/references/history_lib_reference.md
View file
Open in desktop
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
Open in desktop
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

### [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
Open in desktop
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