Private Kernel Circuit - Initial

Requirements

In the initial kernel iteration, the process involves taking a transaction_request and private call data , performing checks on this data (see below), and preparing the necessary data for subsequent circuits to operate. This "initial" circuit is an optimization over the inner private kernel circuit, as there is no "previous kernel" to verify at the beginning of a transaction. Additionally, this circuit executes tasks that need only occur once per transaction.

Key Checks within this Circuit

This first function call of the transaction must match the caller's intent

The following data in the private_inputs.private_call must match the corresponding fields of the user's private_inputs.transaction_request:

• contract_address
• function_data
• args_hash: Hash of the function arguments.

Notice: a transaction_request doesn't explicitly contain a signature. Aztec implements account abstraction, so the process for authorizing a transaction (if at all) is dictated by the logic of the functions of that transaction. In particular, an account contract can be called as an 'entrypoint' to a transaction, and there, custom authorization logic can be executed.

It must be a standard synchronous function call

For the private_inputs.private_call.call_stack_item.public_inputs.call_context: CallContext, the circuit checks that:

• It must not be a delegate call:
  • call_context.is_delegate_call == false
• It must not be a static call:
  • call_context.is_static_call == false

The transaction_request must be unique

It must emit the hash of the private_inputs.transaction_request as the first nullifier.

The hash is computed as:

let { origin, function_data, args_hash, tx_context } =
  private_inputs.transaction_request;
let tx_hash = hash(origin, function_data.hash(), args_hash, tx_context.hash());

Where function_data.hash() and tx_context.hash() are the hashes of the serialized field elements.

This nullifier serves multiple purposes:

• Identifying a transaction.
• Non-malleability. Preventing the signature of a transaction request from being reused in another transaction.
• Generating values that should be maintained within the transaction's scope. For example, it is utilized to compute the note nonces for all the note hashes in a transaction.

Note that the final transaction data is not deterministic for a given transaction request. The production of new notes, the destruction of notes, and various other values are likely to change based on the time and conditions when a transaction is being composed. However, the intricacies of implementation should not be a concern for the entity initiating the transaction.

Processing a Private Function Call

The function being called must exist within the contract class of the called contract_address

With the following data provided from private_inputs.private_call:

• contract_address in private_call.call_stack_item.
• contract_instance
• contract_class
• function_data in private_call.call_stack_item.

This circuit validates the existence of the function in the contract through the following checks:

1. Verify that the contract_address can be derived from the contract_instance:

   Refer to the details here for the process of computing the address for a contract instance.

2. Verify that the contract_instance.contract_class_id can be derived from the given contract_class:

   Refer to the details here for the process of computing the contract_class_id.

3. Verify that contract_class_data.private_functions includes the function being called:

   1. Compute the hash of the verification key:
      • vk_hash = hash(private_call.vk)
   2. Compute the function leaf:
      • hash(function_data.selector, vk_hash, private_call.bytecode_hash)
   3. Perform a membership check; that the function leaf exists within the function tree, where:
      • The index and sibling path are provided through private_call.function_leaf_membership_witness.
      • The root is contract_class.private_functions.

The private function proof must verify

It verifies that the private function was executed successfully with the provided proof data, verification key, and the public inputs of the private function circuit. I.e. private_inputs.private_call.vk, private_inputs.private_call.proof, and private_inputs.private_call.call_stack_item.public_inputs.

Validate the counters.

In ensuring the integrity of emitted data, counters play a crucial role in establishing the chronological order of elements generated during a transaction. This validation process not only guards against misinterpretations but also reinforces trust in the sequence of transactions.

Counters are employed to validate the following aspects:

1. Read Requests: Verify that a read request is reading a value created before the request is submitted.
   • Refer to Read Request Reset Private Kernel Circuit for verification details.
2. Ordered Emission: Ensure that side effects (note hashes, nullifiers, logs) are emitted in the same order as they were created.
   • Refer to Tail Private Kernel Circuit for order enforcement.

For these operations to be effective, specific requirements for the counters must be met:

• Each counter for values of the same type must be unique, avoiding confusion about the order.
• Values emitted within a function call must not be mistaken for values emitted from another function call.

The circuit undergoes the following validations for data within private_inputs.private_call.public_inputs:

1. Validate the counter range of call_stack_item.

   • The counter_start must be 0.
     • This check can be skipped for inner private kernel circuit.
   • The counter_end must be strictly greater than the counter_start.

   The counter range (counter_start to counter_end) is later used to restrict counters emitted within the call.

2. Validate the counter ranges of non-empty requests in private_call_requests.

   • The counter_end of each request must be strictly greater than its counter_start.
   • The counter_start of the first request must be strictly greater than the counter_start of the call_stack_item.
   • The counter_start of the second and each of the subsequent requests must be strictly greater than the counter_end of the previous request.
   • The counter_end of the last request must be strictly less than the counter_end of the call_stack_item.

   When a request is popped in a nested iteration, its counter range is checked against the call_stack_item, as described here. By enforcing that the counter ranges of all nested private_call_requests do not overlap with one another in this step, a function circuit will not be able to emit a value whose counter falls in the range of another call.

3. Validate the counters of the non-empty elements in the following arrays:

   • note_hashes

   • nullifiers

   • l2_to_l1_messages

   • unencrypted_log_hashes

   • encrypted_log_hashes

   • encrypted_note_preimage_hashes

   • note_hash_read_requests

   • nullifier_read_requests

   • public_call_requests

   1. For each of the above "ordered" array, the counters of the non-empty elements must be in a strictly-increasing order:

      • The counter of the first element must be strictly greater than the counter_start of the call_stack_item.
      • The counter of each subsequent element must be strictly greater than the counter of the previous item.
      • The counter of the last element must be strictly less than the counter_end of the call_stack_item.

   2. Additionally, the counters must not fall within the counter range of any nested private call.

      Get the value NE, which is the number of non-empty requests in private_call_requests. If NE is greater than 0, the circuit checks the following:

      For each note_hash at index i in note_hashes:

      • Find the request_index at hints.note_hash_range_hints[i], which is the index of the private_call_requests with the smallest counter_start that was emitted after the note_hash.
      • If request_index equals NE, indicating no request was emitted after the note_hash, its counter must be greater than the counter_end of the last request.
      • If request_index equals 0, indicating no request was emitted before the note_hash. Its counter must be less than the counter_start of the first request.
      • Otherwise, the request was emitted after the note_hash, and its immediate previous request was emitted before the note_hash. Its counter must fall between those two requests.

      The code simplifies as:

      let NE = count_non_empty_elements(private_call_requests);
      for i in 0..note_hashes.len() {
         let note_hash = note_hashes[i];
         if !note_hash.is_empty() {
           let request_index = note_hash_range_hints[i];
           if request_index != NE {
             note_hash.counter < private_call_requests[request_index].counter_start;
           }
           if request_index != 0 {
             note_hash.counter > private_call_requests[request_index - 1].counter_end;
           }
         }
      }

      Repeat the above process for emitted data, including:

      • nullifiers
      • unencrypted_log_hashes
      • encrypted_log_hashes
      • encrypted_note_preimage_hashes

Validating Public Inputs

Verifying the TransientAccumulatedData.

The various side effects of the private_inputs.private_call.call_stack_item.public_inputs: PrivateFunctionPublicInputs are formatted and pushed to the various arrays of the public_inputs.transient_accumulated_data: TransientAccumulatedData.

This circuit verifies that the values in private_inputs.private_call.call_stack_item.public_inputs: PrivateFunctionPublicInputs are aggregated into the various arrays of the public_inputs.transient_accumulated_data: TransientAccumulatedData correctly.

1. Ensure that the specified values in the following arrays match those in the corresponding arrays in the private_function_public_inputs:

• note_hash_contexts
  • value, counter
• nullifier_contexts
  • value, counter
• l2_to_l1_message_contexts
  • value, counter
• note_hash_read_requests
  • value, contract_address, counter
• nullifier_read_requests
  • value, contract_address, counter
• key_validation_request_contexts
  • parent_public_key, hardened_child_secret_key
• unencrypted_log_hash_contexts
  • hash, length, counter
• encrypted_log_hash_contexts
  • hash, length, randomness, counter
• encrypted_note_preimage_hash_contexts
  • hash, length, counter, note_hash_counter
• public_call_request_contexts
  • call_stack_item_hash, counter

1. Check that the values in private_call_request_stack align with the values in private_call_requests within private_function_public_inputs, but in reverse order.

   It's important that the private_call_requests are "pushed" to the private_call_request_stack in reverse order to ensure that they are executed in chronological order.

2. For each non-empty call request in both private_call_request_stack and public_call_request_contexts within public_inputs.transient_accumulated_data:

   • The caller_contract_address equals the private_call.call_stack_item[.contract_address].
   • The following values in caller_context are either empty or align with the values in the private_inputs.private_call.call_stack_item.public_inputs.call_context:
     • (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.

3. For each non-empty item in the following arrays, its contract_address must equal the storage_contract_address in private_inputs.private_call.call_stack_item.public_inputs.call_context:

   • note_hash_contexts

   • nullifier_contexts

   • l2_to_l1_message_contexts

   • key_validation_request_contexts

   • unencrypted_log_hash_contexts

   • encrypted_log_hash_contexts

   • encrypted_note_preimage_hash_contexts

   Ensuring the alignment of the contract addresses is crucial, as it is later used to silo the values and to establish associations with values within the same contract.

4. For each non-empty item in l2_to_l1_message_contexts, its portal_contract_address must equal the portal_contract_address defined in private_function_public_inputs.call_context.

5. For each note_hash_context: NoteHashContext in the note_hash_contexts, validate its nullifier_counter. The value of the nullifier_counter can be:

   • Zero: if the note is not nullified in the same transaction.

   • Strictly greater than note_hash.counter: if the note is nullified in the same transaction.

   Nullifier counters are used in the reset private kernel circuit to ensure a read happens before a transient note is nullified.

   Zero can be used to indicate a non-existing transient nullifier, as this value can never serve as the counter of a nullifier. It corresponds to the counter_start of the first function call.

Note that the verification process outlined above is also applicable to the inner private kernel circuit. However, given that the transient_accumulated_data for the inner private kernel circuit comprises both values from previous iterations and the private_call, the above process specifically targets the values stemming from the private_call. The inner kernel circuit performs an extra check to ensure that the transient_accumulated_data also contains values from the previous iterations.

Verifying the constant data.

It verifies that:

• The tx_context in the constant_data matches the tx_context in the transaction_request.
• The block_header must align with the one used in the private function circuit, as verified earlier.

Verifying the min_revertible_side_effect_counter.

It verifies that the min_revertible_side_effect_counter equals the value in the public_inputs of the private function circuit.

Diagram

This diagram flows from the private inputs (which can be considered "inputs") to the public inputs (which can be considered "outputs").

---

Key:

---

The diagram:

PrivateInputs

Field	Type	Description
transaction_request	TransactionRequest
private_call	PrivateCall

TransactionRequest

Data that represents the caller's intent.

Field	Type	Description
origin	AztecAddress	Address of the entrypoint contract.
function_data	FunctionData	Data of the function being called.
args_hash	field	Hash of the function arguments.
tx_context	TransactionContext	Information about the transaction.
gas_settings	GasSettings	User-defined gas limits and max fees.

PrivateCall

Data that holds details about the current private function call.

Field	Type	Description
call_stack_item	PrivateCallStackItem	Information about the current private function call.
proof	Proof	Proof of the private function circuit.
vk	VerificationKey	Verification key of the private function circuit.
bytecode_hash	field	Hash of the function bytecode.
contract_instance	ContractInstance	Data of the contract instance being called.
contract_class	ContractClass	Data of the contract class.
function_leaf_membership_witness	MembershipWitness	Membership witness for the function being called.

Hints

Field	Type	Description
note_hash_range_hints	[field, MAX_NOTE_HASHES_PER_CALL]	Indices of the next emitted private call requests for note hashes.
nullifier_range_hints	[field, MAX_NULLIFIERS_PER_CALL]	Indices of the next emitted private call requests for nullifiers.
unencrypted_log_range_hints	[field, MAX_UNENCRYPTED_LOG_HASHES_PER_CALL]	Indices of the next emitted private call requests for unencrypted logs.
encrypted_log_range_hints	[field, MAX_ENCRYPTED_LOG_HASHES_PER_CALL]	Indices of the next emitted private call requests for encrypted logs.
encrypted_note_range_hints	[field, MAX_ENCRYPTED_NOTE_PREIMAGE_HASHES_PER_CALL]	Indices of the next emitted private call requests for encrypted notes.

PublicInputs

Field	Type	Description
constant_data	ConstantData
transient_accumulated_data	TransientAccumulatedData
min_revertible_side_effect_counter	u32

ConstantData

Data that remains the same throughout the entire transaction.

Field	Type	Description
header	Header	Header of a block which was used when assembling the tx.
tx_context	TransactionContext	Context of the transaction.

TransientAccumulatedData

Field	Type	Description
note_hash_contexts	[NoteHashContext; MAX_NOTE_HASHES_PER_TX]	Note hashes with extra data aiding verification.
nullifier_contexts	[NullifierContext; MAX_NULLIFIERS_PER_TX]	Nullifiers with extra data aiding verification.
l2_to_l1_message_contexts	[L2toL1MessageContext; MAX_L2_TO_L1_MSGS_PER_TX]	L2-to-l1 messages with extra data aiding verification.
unencrypted_log_hash_contexts	[UnencryptedLogHashContext; MAX_UNENCRYPTED_LOG_HASHES_PER_TX]	Hashes of the unencrypted logs with extra data aiding verification.
encrypted_log_hash_contexts	[EncryptedLogHashContext; MAX_ENCRYPTED_LOG_HASHES_PER_TX]	Hashes of the encrypted logs with extra data aiding verification.
encrypted_note_preimage_hash_contexts	[EncryptedNotePreimageHashContext; MAX_ENCRYPTED_NOTE_PREIMAGE_HASHES_PER_TX]	Hashes of the encrypted note preimages with extra data aiding verification.
note_hash_read_requests	[ReadRequest; MAX_NOTE_HASH_READ_REQUESTS_PER_TX]	Requests to prove the note hashes being read exist.
nullifier_read_requests	[ReadRequest; MAX_NULLIFIER_READ_REQUESTS_PER_TX]	Requests to prove the nullifiers being read exist.
key_validation_request_contexts	[ParentSecretKeyValidationRequestContext; MAX_KEY_VALIDATION_REQUESTS_PER_TX]	Requests to validate nullifier keys.
public_call_request_contexts	[PublicCallRequestContext; MAX_PUBLIC_CALL_STACK_LENGTH_PER_TX]	Requests to call publics functions.
private_call_request_stack	[PrivateCallRequestContext; MAX_PRIVATE_CALL_STACK_LENGTH_PER_TX]	Requests to call private functions. Pushed to the stack in reverse order so that they will be executed in chronological order.

Types

FunctionData

Field	Type	Description
function_selector	u32	Selector of the function being called.
function_type	private | public	Type of the function being called.

ContractClass

Field	Type	Description
version	u8	Version identifier.
registerer_address	AztecAddress	Address of the canonical contract used for registering this class.
artifact_hash	field	Hash of the contract artifact.
private_functions	field	Merkle root of the private function tree.
public_functions	field	Merkle root of the public function tree.
unconstrained_functions	field	Merkle root of the unconstrained function tree.

TransactionContext

Field	Type	Description
tx_type	standard | fee_paying | fee_rebate	Type of the transaction.
chain_id	field	Chain ID of the transaction.
version	field	Version of the transaction.

PrivateCallStackItem

Field	Type	Description
contract_address	AztecAddress	Address of the contract on which the function is invoked.
function_data	FunctionData	Data of the function being called.
public_inputs	PrivateFunctionPublicInputs	Public inputs of the private function circuit.

PrivateCallRequestContext

Field	Type	Description
call_stack_item_hash	field	Hash of the call stack item.
counter_start	u32	Counter at which the call was initiated.
counter_end	u32	Counter at which the call ended.
caller_contract_address	AztecAddress	Address of the contract calling the function.
caller_context	CallerContext	Context of the contract calling the function.

CallerContext

Field	Type	Description
msg_sender	AztecAddress	Address of the caller contract.
storage_contract_address	AztecAddress	Storage contract address of the caller contract.
is_static_call	bool	A flag indicating whether the call is a static call.

NoteHashContext

Field	Type	Description
value	field	Hash of the note.
counter	u32	Counter at which the note hash was created.
nullifier_counter	field	Counter at which the nullifier for the note was created.
contract_address	AztecAddress	Address of the contract the note was created.

NullifierContext

Field	Type	Description
value	field	Value of the nullifier.
counter	u32	Counter at which the nullifier was created.
note_hash_counter	u32	Counter of the transient note the nullifier is created for. 0 if the nullifier does not associate with a transient note.
contract_address	AztecAddress	Address of the contract the nullifier was created.

L2toL1MessageContext

Field	Type	Description
value	field	L2-to-l2 message.
counter	u32	Counter at which the message was emitted.
portal_contract_address	AztecAddress	Address of the portal contract to the contract.
contract_address	AztecAddress	Address of the contract the message was created.

ParentSecretKeyValidationRequestContext

Field	Type	Description
parent_public_key	GrumpkinPoint	Claimed parent public key of the secret key.
hardened_child_secret_key	fq	Secret key passed to the contract.
contract_address	AztecAddress	Address of the contract the request was made.

UnencryptedLogHashContext

Field	Type	Description
hash	field	Hash of the unencrypted log.
length	field	Number of fields of the log preimage.
counter	u32	Counter at which the hash was emitted.
contract_address	AztecAddress	Address of the contract the log was emitted.

EncryptedLogHashContext

Field	Type	Description
hash	field	Hash of the encrypted log.
length	field	Number of fields of the log preimage.
counter	u32	Counter at which the hash was emitted.
contract_address	AztecAddress	Address of the contract the log was emitted.
randomness	field	A random value to hide the contract address.

EncryptedNotePreimageHashContext

Field	Type	Description
hash	field	Hash of the encrypted note preimage.
length	field	Number of fields of the note preimage.
counter	u32	Counter at which the hash was emitted.
contract_address	AztecAddress	Address of the contract the log was emitted.
note_hash_counter	field	Counter of the corresponding note hash.

MembershipWitness

Field	Type	Description
leaf_index	field	Index of the leaf in the tree.
sibling_path	[field; H]	Sibling path to the leaf in the tree. H represents the height of the tree.