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

fix(docs): Historical reference library updates #7166

Merged
merged 1 commit into from
Jun 28, 2024
Merged

fix(docs): Historical reference library updates #7166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
164 changes: 89 additions & 75 deletions docs/docs/reference/smart_contract_reference/history_lib_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,100 +7,85 @@ sidebar_position: 3

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

### prove_note_inclusion

`prove_note_inclusion_at` takes 3 parameters:
`prove_note_inclusion` takes 1 parameter:

| 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 | Note | The note you are proving inclusion for |

## prove_note_commitment_inclusion
#### Example

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](../../aztec/concepts/storage/trees/index.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 |
#include_code prove_note_inclusion noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

## Note validity

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.
This proves that a note exists and has not been nullified in a specific block header.

### prove_note_validity

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

`prove_note_validity` takes 2 parameters:

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

#### Example

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

## Nullifier inclusion

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.
This proves that a nullifier exists in a given block header (can be used to prove that a note had been nullified).

### prove_nullifier_inclusion

`prove_nullifier_inclusion_at` takes 3 parameters:
`prove_nullifier_inclusion` takes 1 parameter:

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

`prove_nullifier_inclusion` takes 2 parameters:
#### Example

| Name | Type | Description |
| --------- | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |
#include_code prove_nullifier_inclusion noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

### prove_note_is_nullified_at / prove_note_is_nullified
### prove_note_is_nullified

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

#### Implementation

#include_code prove_note_is_nullified noir-projects/aztec-nr/aztec/src/history/nullifier_inclusion.nr rust

## 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).
This proves that a nullifier was not included in a certain block, given the block header (can be used to prove that a note had not yet been nullified in a given block).

### prove_nullifier_not_included
### prove_nullifier_non_inclusion

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

`prove_nullifier_not_included` takes 2 parameters:
#### Example

| Name | Type | Description |
| --------- | -------------- | ------------------------------------------- |
| nullifier | Field | The nullifier you are proving inclusion for |
| context | PrivateContext | Private context |
#include_code prove_nullifier_non_inclusion noir-projects/aztec-nr/aztec/src/history/contract_inclusion.nr rust

### prove_note_not_nullified_at / prove_note_not_nullified
### prove_note_not_nullified

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

#### Implementation

#include_code prove_note_not_nullified noir-projects/aztec-nr/aztec/src/history/nullifier_non_inclusion.nr rust

## Public storage historical reads

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`).
Expand All @@ -109,36 +94,65 @@ Note that it is never possible to read the _current_ value in a public storage s

### public_storage_historical_read

`public_storage_historical_read_at` takes 4 parameters:
`public_storage_historical_read` takes 2 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 |
| ---------------- | ------------ | --------------------------------------- |
| storage_slot | Field | Storage slot |
| contract_address | AztecAddress | The contract that owns the storage slot |

`public_storage_historical_read` takes 3 parameters. `block_number` is implicitly the historical block number from the context:
#### Example

| Name | Type | Description |
| ---------------- | -------------- | --------------------------------------- |
| context | PrivateContext | Private context |
| storage_slot | Field | Storage slot |
| contract_address | AztecAddress | The contract that owns the storage slot |
#include_code public_storage_historical_read noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

## Contract inclusion

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

### prove_contract_inclusion
### prove_contract_deployment

`prove_contract_deployment` takes 1 parameter:

| Name | Type | Description |
| ---------------- | ------------ | ------------------------------------------- |
| contract_address | AztecAddress | The contract address to prove deployment of |

#### Example

#include_code prove_contract_deployment noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

### prove_contract_non_deployment

`prove_contract_non_deployment` takes 1 parameter:

| Name | Type | Description |
| ---------------- | ------------ | ----------------------------------------------- |
| contract_address | AztecAddress | The contract address to prove non-deployment of |

#### Example

#include_code prove_contract_non_deployment noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

### prove_contract_initialization

`prove_contract_initialization` takes 1 parameter:

| Name | Type | Description |
| ---------------- | ------------ | ----------------------------------------------- |
| contract_address | AztecAddress | The contract address to prove initialization of |

#### Example

#include_code prove_contract_initialization noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust

### prove_contract_non_initialization

`prove_contract_non_initialization` takes 1 parameter:

| Name | Type | Description |
| ---------------- | ------------ | --------------------------------------------------- |
| contract_address | AztecAddress | The contract address to prove non-initialization of |

`prove_contract_inclusion_at` takes 7 parameters:
#### Example

| 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 |
| block_number | u32 | Block number for proof verification |
| context | PrivateContext | Private context |
#include_code prove_contract_non_initialization noir-projects/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust
2 changes: 2 additions & 0 deletions noir-projects/aztec-nr/aztec/src/history/contract_inclusion.nr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,9 @@ impl ProveContractNonDeployment for Header {
contract_address.to_field()
);

// docs:start:prove_nullifier_non_inclusion
self.prove_nullifier_non_inclusion(nullifier);
// docs:end:prove_nullifier_non_inclusion
}
}

Expand Down
2 changes: 2 additions & 0 deletions noir-projects/aztec-nr/aztec/src/history/nullifier_inclusion.nr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,11 @@ trait ProveNoteIsNullified {
}

impl ProveNoteIsNullified for Header {
// docs:start:prove_note_is_nullified
fn prove_note_is_nullified<Note, N, M>(self, note: Note, context: &mut PrivateContext) where Note: NoteInterface<N, M> {
let nullifier = compute_siloed_nullifier(note, context);

self.prove_nullifier_inclusion(nullifier);
}
// docs:end:prove_note_is_nullified
}
2 changes: 2 additions & 0 deletions noir-projects/aztec-nr/aztec/src/history/nullifier_non_inclusion.nr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,11 @@ trait ProveNoteNotNullified {
}

impl ProveNoteNotNullified for Header {
// docs:start:prove_note_not_nullified
fn prove_note_not_nullified<Note, N, M>(self, note: Note, context: &mut PrivateContext) where Note: NoteInterface<N, M> {
let nullifier = compute_siloed_nullifier(note, context);

self.prove_nullifier_non_inclusion(nullifier);
}
// docs:end:prove_note_not_nullified
}
10 changes: 10 additions & 0 deletions noir-projects/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 @@ -194,9 +194,11 @@ contract InclusionProofs {
let header = context.get_header_at(block_number);

assert_eq(
// docs:start:public_storage_historical_read
header.public_storage_historical_read(
storage.public_unused_value.storage_slot,
context.this_address()
// docs:end:public_storage_historical_read
), 0
);
}
Expand Down Expand Up @@ -229,10 +231,14 @@ contract InclusionProofs {
let header = context.get_header_at(block_number);

if test_deployment {
// docs:start:prove_contract_deployment
header.prove_contract_deployment(contract_address);
// docs:end:prove_contract_deployment
}
if test_initialization {
// docs:start:prove_contract_initialization
header.prove_contract_initialization(contract_address);
// docs:end:prove_contract_initialization
}
}

Expand All @@ -247,10 +253,14 @@ contract InclusionProofs {
let header = context.get_header_at(block_number);

if test_deployment {
// docs:start:prove_contract_non_deployment
header.prove_contract_non_deployment(contract_address);
// docs:end:prove_contract_non_deployment
}
if test_initialization {
// docs:start:prove_contract_non_initialization
header.prove_contract_non_initialization(contract_address);
// docs:end:prove_contract_non_initialization
}
}
}
Loading