Skip to content

Commit

Permalink
fix(docs): Historical reference library updates (#7166)
Browse files Browse the repository at this point in the history 
This PR updates the references and adds links to examples and
implementations

closes: AztecProtocol/dev-rel#291
  • Loading branch information
@critesjosh
critesjosh authored Jun 28, 2024
1 parent 25507e6 commit b3409c4
Show file tree
Hide file tree
Showing 5 changed files with 105 additions and 75 deletions.
164 changes: 89 additions & 75 deletions docs/docs/reference/smart_contract_reference/history_lib_reference.md
View file
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
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
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
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
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
}
}
}

0 comments on commit b3409c4

Please sign in to comment.