Skip to content

Commit

Permalink
docs(yellow-paper): update circuit sections for nullifier keys and st…
Browse files Browse the repository at this point in the history 
…atic calls (#4155)

- Validate nullifier keys used in the private functions.
- Prevent static call calls non-static calls.
  • Loading branch information
@LeilaWang
LeilaWang authored Jan 19, 2024
1 parent 09dbfcd commit ed71a57
Show file tree
Hide file tree
Showing 5 changed files with 91 additions and 36 deletions.
42 changes: 25 additions & 17 deletions yellow-paper/docs/circuits/private-function.md
View file
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
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
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

0 comments on commit ed71a57

Please sign in to comment.