Skip to content

docs(yellow-paper): update circuit sections for nullifier keys and static calls #4155

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
LeilaWang merged 2 commits into from
Jan 19, 2024
Merged

docs(yellow-paper): update circuit sections for nullifier keys and static calls #4155

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
98c3136
Update circuit sections in yp.
LeilaWang Jan 18, 2024
1edfd56
Checks for static calls.
LeilaWang Jan 19, 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
42 changes: 25 additions & 17 deletions yellow-paper/docs/circuits/private-function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,23 +16,24 @@ The public inputs of a private function circuit will be incorporated into the pr

The following format defines the ABI that is used by the private kernel circuit when processing private function public inputs:

| Field | Type | Description |
| -------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| _call_context_ | _[CallContext](#callcontext)_ | Context of the call corresponding to this function execution. |
| _args_hash_ | _field_ | Hash of the function arguments. |
| _return_values_ | [_field_; _C_] | Return values of this function call. |
| _read_requests_ | [_[ReadRequest](#readrequest)_; _C_] | Requests to read notes in the note hash tree. |
| _note_hashes_ | [_[NoteHash](#notehash)_; _C_] | New note hashes created in this function call. |
| _nullifiers_ | [_[Nullifier](#nullifier)_; _C_] | New nullifiers created in this function call. |
| _l2_to_l1_messages_ | [_field_; _C_] | New L2 to L1 messages created in this function call. |
| _unencrypted_log_hashes_ | [_[UnencryptedLogHash](#unencryptedloghash)_; _C_] | Hashes of the unencrypted logs emitted in this function call. |
| _encrypted_log_hashes_ | [_[EncryptedLogHash](#encryptedloghash)_; _C_] | Hashes of the encrypted logs emitted in this function call. |
| _encrypted_note_preimage_hashes_ | [_[EncryptedNotePreimageHash](#encryptednotepreimagehash)_; _C_] | Hashes of the encrypted note preimages emitted in this function call. |
| _private_call_stack_item_hashes_ | [_field_; _C_] | Hashes of the private function calls initiated by this function. |
| _public_call_stack_item_hashes_ | [_field_; _C_] | Hashes of the public function calls initiated by this function. |
| _block_header_ | _[BlockHeader](#blockheader)_ | Information about the trees used for the transaction. |
| _chain_id_ | _field_ | Chain ID of the transaction. |
| _version_ | _field_ | Version of the transaction. |
| Field | Type | Description |
| ----------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| _call_context_ | _[CallContext](#callcontext)_ | Context of the call corresponding to this function execution. |
| _args_hash_ | _field_ | Hash of the function arguments. |
| _return_values_ | [_field_; _C_] | Return values of this function call. |
| _read_requests_ | [_[ReadRequest](#readrequest)_; _C_] | Requests to read notes in the note hash tree. |
| _nullifier_key_validation_requests_ | [_[NullifierKeyValidationRequest](#nullifierkeyvalidationrequest)_; _C_] | Requests to validate nullifier keys used in this function call. |
| _note_hashes_ | [_[NoteHash](#notehash)_; _C_] | New note hashes created in this function call. |
| _nullifiers_ | [_[Nullifier](#nullifier)_; _C_] | New nullifiers created in this function call. |
| _l2_to_l1_messages_ | [_field_; _C_] | New L2 to L1 messages created in this function call. |
| _unencrypted_log_hashes_ | [_[UnencryptedLogHash](#unencryptedloghash)_; _C_] | Hashes of the unencrypted logs emitted in this function call. |
| _encrypted_log_hashes_ | [_[EncryptedLogHash](#encryptedloghash)_; _C_] | Hashes of the encrypted logs emitted in this function call. |
| _encrypted_note_preimage_hashes_ | [_[EncryptedNotePreimageHash](#encryptednotepreimagehash)_; _C_] | Hashes of the encrypted note preimages emitted in this function call. |
| _private_call_stack_item_hashes_ | [_field_; _C_] | Hashes of the private function calls initiated by this function. |
| _public_call_stack_item_hashes_ | [_field_; _C_] | Hashes of the public function calls initiated by this function. |
| _block_header_ | _[BlockHeader](#blockheader)_ | Information about the trees used for the transaction. |
| _chain_id_ | _field_ | Chain ID of the transaction. |
| _version_ | _field_ | Version of the transaction. |

> The above **C**s represent constants defined by the protocol. Each **C** might have a different value from the others.

Expand All @@ -55,6 +56,13 @@ The following format defines the ABI that is used by the private kernel circuit
| _note_hash_ | _field_ | Hash of the note to be read. |
| _counter_ | _field_ | Counter at which the request was made. |

#### _NullifierKeyValidationRequest_

| Field | Type | Description |
| ------------ | ------- | -------------------------------------------------------------------- |
| _public_key_ | _field_ | Nullifier public key of an account. |
| _secret_key_ | _field_ | Nullifier secret key of an account siloed with the contract address. |

#### _NoteHash_

| Field | Type | Description |
Expand Down
47 changes: 31 additions & 16 deletions yellow-paper/docs/circuits/private-kernel-initial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,11 @@ This circuit verifies that the values in _[private_inputs](#private-inputs).[pri
3. For each non-empty call request in both _private_call_requests_ and _public_call_requests_:

- The _caller_contract_address_ equals the _contract_address_ in _[private_call](#privatecall).[call_stack_item](#privatecallstackitem)_.
- The _caller_context_ is either empty or aligns with the values in the _call_context_ within _private_function_public_inputs_.
- The following values in _caller_context_ are either empty or align with the values in the _call_context_ within _private_function_public_inputs_:
- _`(caller_context.msg_sender == 0) & (caller_context.storage_contract_address == 0)`_
- Or _`(caller_context.msg_sender == call_context.msg_sender) & (caller_context.storage_contract_address == call_context.storage_contract_address)`_
- The _is_static_call_ flag must be propagated:
- _`caller_context.is_static_call == call_context.is_static_call`_

> The caller context in a call request may be empty for standard calls. This precaution is crucial to prevent information leakage, particularly as revealing the _msg_sender_ of this private function when calling a public function could pose security risks.

Expand All @@ -183,6 +187,7 @@ This circuit verifies that the values in _[private_inputs](#private-inputs).[pri
- _nullifier_contexts_
- _l2_to_l1_message_contexts_
- _read_request_contexts_
- _nullifier_key_validation_request_contexts_
- _unencrypted_log_hash_contexts_
- _encrypted_log_hash_contexts_
- _encrypted_note_preimage_hash_contexts_
Expand Down Expand Up @@ -249,17 +254,18 @@ Data that remains the same throughout the entire transaction.

### _TransientAccumulatedData_

| Field | Type | Description |
| --------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| _note_hash_contexts_ | [_[NoteHashContext](#notehashcontext)_; _C_] | Note hashes with extra data aiding verification. |
| _nullifier_contexts_ | [_[NullifierContext](#nullifiercontext)_; _C_] | Nullifiers with extra data aiding verification. |
| _l2_to_l1_message_contexts_ | [_[L2toL1MessageContext](#l2tol1messagecontext)_; _C_] | L2-to-l1 messages with extra data aiding verification. |
| _read_request_contexts_ | [_[ReadRequestContext](#readrequestcontext)_; _C_] | Requests to read notes in the note hash tree. |
| _unencrypted_log_hash_contexts_ | [_[EncryptedLogHashContext](#encryptedloghashcontext)_; _C_] | Hashes of the unencrypted logs with extra data aiding verification. |
| _encrypted_log_hash_contexts_ | [_[UnencryptedLogHashContext](#unencryptedloghashcontext)_; _C_] | Hashes of the encrypted logs with extra data aiding verification. |
| _encrypted_note_preimage_hash_contexts_ | [_[EncryptedNotePreimageHashContext](#encryptednotepreimagehash)_; _C_] | Hashes of the encrypted note preimages with extra data aiding verification. |
| _private_call_requests_ | [_[CallRequest](#callrequest)_; _C_] | Requests to call private functions. |
| _public_call_requests_ | [_[CallRequest](#callrequest)_; _C_] | Requests to call publics functions. |
| Field | Type | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| _note_hash_contexts_ | [_[NoteHashContext](#notehashcontext)_; _C_] | Note hashes with extra data aiding verification. |
| _nullifier_contexts_ | [_[NullifierContext](#nullifiercontext)_; _C_] | Nullifiers with extra data aiding verification. |
| _l2_to_l1_message_contexts_ | [_[L2toL1MessageContext](#l2tol1messagecontext)_; _C_] | L2-to-l1 messages with extra data aiding verification. |
| _read_request_contexts_ | [_[ReadRequestContext](#readrequestcontext)_; _C_] | Requests to read notes in the note hash tree. |
| _nullifier_key_validation_request_contexts_ | [_[NullifierKeyValidationRequestContext](#nullifierkeyvalidationrequestcontext)_; _C_] | Requests to validate nullifier keys. |
| _unencrypted_log_hash_contexts_ | [_[EncryptedLogHashContext](#encryptedloghashcontext)_; _C_] | Hashes of the unencrypted logs with extra data aiding verification. |
| _encrypted_log_hash_contexts_ | [_[UnencryptedLogHashContext](#unencryptedloghashcontext)_; _C_] | Hashes of the encrypted logs with extra data aiding verification. |
| _encrypted_note_preimage_hash_contexts_ | [_[EncryptedNotePreimageHashContext](#encryptednotepreimagehash)_; _C_] | Hashes of the encrypted note preimages with extra data aiding verification. |
| _private_call_requests_ | [_[CallRequest](#callrequest)_; _C_] | Requests to call private functions. |
| _public_call_requests_ | [_[CallRequest](#callrequest)_; _C_] | Requests to call publics functions. |

> The above **C**s represent constants defined by the protocol. Each **C** might have a different value from the others.

Expand Down Expand Up @@ -314,10 +320,11 @@ Data that remains the same throughout the entire transaction.

#### _CallerContext_

| Field | Type | Description |
| ------------------ | -------------- | ------------------------------------------------ |
| _msg_sender_ | _AztecAddress_ | Address of the caller contract. |
| _storage_contract_ | _AztecAddress_ | Storage contract address of the caller contract. |
| Field | Type | Description |
| ------------------ | -------------- | ---------------------------------------------------- |
| _msg_sender_ | _AztecAddress_ | Address of the caller contract. |
| _storage_contract_ | _AztecAddress_ | Storage contract address of the caller contract. |
| _is_static_call_ | _bool_ | A flag indicating whether the call is a static call. |

#### _NoteHashContext_

Expand Down Expand Up @@ -353,6 +360,14 @@ Data that remains the same throughout the entire transaction.
| _counter_ | _field_ | Counter at which the request was made. |
| _contract_address_ | _AztecAddress_ | Address of the contract the request was made. |

#### _NullifierKeyValidationRequestContext_

| Field | Type | Description |
| ------------------ | -------------- | ---------------------------------------------------------- |
| _public_key_ | _field_ | Nullifier public key of an account. |
| _secret_key_ | _field_ | Secret key of an account siloed with the contract address. |
| _contract_address_ | _AztecAddress_ | Address of the contract the request was made. |

#### _UnencryptedLogHashContext_

| Field | Type | Description |
Expand Down
11 changes: 8 additions & 3 deletions yellow-paper/docs/circuits/private-kernel-inner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,14 @@ This circuit will:

For the _call_context_ in the [public_inputs](./private-function.md#public-inputs) of the _[private_call](#privatecall).[call_stack_item](./private-kernel-initial.md#privatecallstackitem)_ and the _call_request_ popped in the [previous step](#ensuring-the-current-call-matches-the-call-request), this circuit checks that:

1. If it is a standard call (`call_context.is_delegate_call == false`):
1. If it is a standard call: _`call_context.is_delegate_call == false`_

- The _msg_sender_ of the current iteration must be the same as the caller's _contract_address_:
- _`call_context.msg_sender == call_request.caller_contract_address`_
- The _storage_contract_address_ of the current iteration must be the same as its _contract_address_:
- _`call_context.storage_contract_address == call_stack_item.contract_address`_

2. If it is a delegate call (`call_context.is_delegate_call == true`):
2. If it is a delegate call: _`call_context.is_delegate_call == true`_

- The _caller_context_ in the _call_request_ must not be empty. Specifically, the following values of the caller must not be zeros:
- _msg_sender_
Expand All @@ -71,7 +71,12 @@ For the _call_context_ in the [public_inputs](./private-function.md#public-input
- The _storage_contract_address_ of the current iteration must not equal the _contract_address_:
- _`call_context.storage_contract_address != call_stack_item.contract_address`_

3. If it is an internal call (`call_stack_item.function_data.is_internal == true`):
3. If it is NOT a static call: _`call_context.is_static_call == false`_

- The previous iteration must not be a static call:
- _`caller_context.is_static_call == false`_

4. If it is an internal call: _`call_stack_item.function_data.is_internal == true`_

- The _msg_sender_ of the current iteration must equal the _storage_contract_address_:
- _`call_context.msg_sender == call_context.storage_contract_address`_
Expand Down
Loading