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.

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

chore: update docs for historical state #4461

Merged
merged 2 commits into from
Feb 6, 2024
Merged

chore: update docs for historical state #4461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
890152d
update docs
sklppy88 Feb 6, 2024
2ea37b8
Update docs/docs/developers/contracts/syntax/historical_access/how_to…
rahul-kothari Feb 6, 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
73 changes: 49 additions & 24 deletions docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,76 +6,93 @@ title: History Reference

## Note inclusion

Note inclusion proves that a note existed (its hash was included in a note hash tree) at a specific block number.
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

`prove_note_inclusion` takes 4 parameters:
`prove_note_inclusion_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_interface | NoteInterface<Note, N> | Interface for the note with necessary functionality|
| 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 3 parameters:
`prove_note_inclusion` takes 2 parameters:

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

## Note validity

This proves that a note exists and has not been nullified at a specified block.
This proves that a note exists and has not been nullified at a specified block. Again as above, there exists a version that tests for validity at current block. It is recommended to use this version whenever possible to reduce cost.

### prove_note_validity

`prove_note_validity` takes 4 parameters:
`prove_note_validity_at` takes 3 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
| note_interface | NoteInterface<Note, N> | Interface for the note with necessary functionality|
| 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 |

## Nullifier inclusion

This proves that a nullifier was included in a certain block (can be used to prove that a note had been nullified).
This proves that a nullifier was included in a certain block (can be used to prove that a note had been nullified). The same disclaimer above holds true for this, and subsequent functions that specify another version without a block_number argument.

### prove_nullifier_inclusion

`prove_nullifier_inclusion` takes 3 parameters:
`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 |

`prove_nullifier_inclusion` takes 2 parameters:

| 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

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

## Nullifier non inclusion

This proves that a nullifier was not included in a certain block (can be used to prove that a note had not yet been nullified in a given block).

### prove_nullifier_non_inclusion
### prove_nullifier_not_included

`prove_nullifier_non_inclusion` takes 3 parameters:
`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 |


### note_not_nullified

`prove_nullifier_not_included` takes 2 parameters:

| 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.

Expand All @@ -85,7 +102,7 @@ This proves that a public value exists at a certain block.

### prove_public_value_inclusion

`prove_public_value_inclusion` takes 4 parameters:
`prove_public_value_inclusion_at` takes 4 parameters:

| Name | Type | Description |
|-----------------|------------------------|-----------------------------------------------------|
Expand All @@ -94,13 +111,21 @@ This proves that a public value exists at a certain block.
| block_number | u32 | Block number for proving value's existence |
| context | PrivateContext | Private context |

`prove_public_value_inclusion` takes 3 parameters:

| 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 |

## Contract inclusion

This proves that a contract exists in, ie had been deployed before or in, a certain block.

### prove_contract_inclusion

`prove_contract_inclusion` takes 7 parameters:
`prove_contract_inclusion_at` takes 7 parameters:

| Name | Type | Description |
|---------------------------|-----------------|-------------------------------------------------------|
Expand Down
25 changes: 9 additions & 16 deletions docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,22 +53,17 @@ In this example, the user's notes are stored in a map called `private_values`. W

## 4. Prove that a note was included in a specified block

To prove that a note existed in a specified block, call `prove_note_inclusion` as shown in this example:
To prove that a note existed in a specified block, call `prove_note_inclusion_at` as shown in this example:

#include_code prove_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

This function takes in 4 arguments:
This function takes in 3 arguments:

1. The note interface (`ValueNoteMethods`)
2. The note (`maybe_note.unwrap_unchecked()`). Here, `unwrap_unchecked()` returns the inner value without asserting `self.is_some()`
3. The block number
4. Private context

Note: for this to work, you will need to import `ValueNoteMethods` at the beginning of the contract:

#include_code value_note_imports yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust
1. The note (`maybe_note.unwrap_unchecked()`). Here, `unwrap_unchecked()` returns the inner value without asserting `self.is_some()`
2. The block number
3. Private context

This will only prove the note existed, not whether or not the note has been nullified. You can prove that a note existed and had not been nullified in a specified block by using `prove_note_validity` which takes the same arguments:
This will only prove the note existed at the specific block number, not whether or not the note has been nullified. You can prove that a note existed and had not been nullified in a specified block by using `prove_note_validity_at` which takes the same arguments:

#include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

Expand All @@ -84,7 +79,7 @@ You can then compute this nullifier with `note.compute_nullifier(&mut context)`.

## 6. Prove that a nullifier was included in a specified block

Call `prove_nullifier_inclusion` like so:
Call `prove_nullifier_inclusion_at` like so:

#include_code prove_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

Expand All @@ -93,10 +88,8 @@ This takes three arguments:
2. Block number
3. Private context

You can also prove that a nullifier was not included in a specified block by using `prove_nullifier_non_inclusion` which takes the same arguments:

#include_code prove_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust
You can also prove that a nullifier was not included in a specified block by using `prove_nullifier_not_included_at` which takes the same arguments.

## Prove contract inclusion, public value inclusion, and note commitment inclusion
## Prove contract inclusion, public value inclusion, and use current state in lookups

To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md).
52 changes: 26 additions & 26 deletions yarn-project/aztec-nr/aztec/src/history/public_value_inclusion.nr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,6 @@ use crate::{
},
};

pub fn prove_public_value_inclusion(
value: Field, // The value that we want to prove is in the public data tree
storage_slot: Field, // The storage slot in which the value is stored
contract_address: AztecAddress, // The contract we want to look into
context: PrivateContext
) {
_public_value_inclusion(
value,
storage_slot,
contract_address,
context.historical_header
);
}

pub fn prove_public_value_inclusion_at(
value: Field, // The value that we want to prove is in the public data tree
storage_slot: Field, // The storage slot in which the value is stored
contract_address: AztecAddress, // The contract we want to look into
block_number: u32, // The block at which we'll prove that the note exists
context: PrivateContext
) {
let header = context.get_header_at(block_number);

_public_value_inclusion(value, storage_slot, contract_address, header);
}

fn _public_value_inclusion(
value: Field,
storage_slot: Field,
Expand Down Expand Up @@ -88,3 +62,29 @@ fn _public_value_inclusion(
// --> Now we have traversed the trees all the way up to archive root and that way verified that a specific
// `value` was really set in a given contract storage slot at block `block_number` in public data tree.
}

pub fn prove_public_value_inclusion(
value: Field, // The value that we want to prove is in the public data tree
storage_slot: Field, // The storage slot in which the value is stored
contract_address: AztecAddress, // The contract we want to look into
context: PrivateContext
) {
_public_value_inclusion(
value,
storage_slot,
contract_address,
context.historical_header
);
}

pub fn prove_public_value_inclusion_at(
value: Field, // The value that we want to prove is in the public data tree
storage_slot: Field, // The storage slot in which the value is stored
contract_address: AztecAddress, // The contract we want to look into
block_number: u32, // The block at which we'll prove that the note exists
context: PrivateContext
) {
let header = context.get_header_at(block_number);

_public_value_inclusion(value, storage_slot, contract_address, header);
}
14 changes: 10 additions & 4 deletions yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,12 @@ contract InclusionProofs {
nullifier_inclusion::{
prove_nullifier_inclusion,
prove_nullifier_inclusion_at,
prove_note_is_nullified,
prove_note_is_nullified_at,
},
nullifier_non_inclusion::{
prove_nullifier_not_included,
prove_nullifier_not_included_at,
prove_note_not_nullified,
prove_note_not_nullified_at,
},
Expand Down Expand Up @@ -101,7 +105,9 @@ contract InclusionProofs {

// 2) Prove the note inclusion
if (use_block_number) {
// docs:start:prove_note_inclusion
prove_note_inclusion_at(maybe_note.unwrap_unchecked(), block_number, context);
// docs:end:prove_note_inclusion
} else {
prove_note_inclusion(maybe_note.unwrap_unchecked(), context);
}
Expand Down Expand Up @@ -169,13 +175,13 @@ contract InclusionProofs {
let note = notes[0].unwrap();

// 2) Prove the note validity
// docs:start:prove_note_validity
if (use_block_number) {
// docs:start:prove_note_validity
prove_note_validity_at(note, block_number, &mut context);
// docs:end:prove_note_validity
} else {
prove_note_validity(note, &mut context);
}
// docs:end:prove_note_validity
}

// docs:start:nullify_note
Expand All @@ -199,13 +205,13 @@ contract InclusionProofs {
use_block_number: bool,
block_number: u32 // The block at which we'll prove that the nullifier not exists in the tree
) {
// docs:start:prove_nullifier_inclusion
if (use_block_number) {
// docs:start:prove_nullifier_inclusion
prove_nullifier_inclusion_at(nullifier, block_number, context);
// docs:end:prove_nullifier_inclusion
} else {
prove_nullifier_inclusion(nullifier, context);
}
// docs:end:prove_nullifier_inclusion
}

#[aztec(private)]
Expand Down
Loading