Skip to content

Commit

Permalink
chore: update docs for historical state (#4461)
Browse files Browse the repository at this point in the history 
Co-authored-by: Rahul Kothari <[email protected]>
  • Loading branch information
@sklppy88 @rahul-kothari
sklppy88 and rahul-kothari authored Feb 6, 2024
1 parent f99392d commit 16a2eca
Show file tree
Hide file tree
Showing 4 changed files with 94 additions and 70 deletions.
73 changes: 49 additions & 24 deletions docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md
View file
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
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
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
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

0 comments on commit 16a2eca

Please sign in to comment.