Private Function Circuit

Requirements

Private function circuits represent smart contract functions that can: privately read and modify leaves of the note hash tree and nullifier tree; perform computations on private data; and can be executed without revealing which function or contract has been executed.

The logic of each private function circuit is tailored to the needs of a particular application or scenario, but the public inputs of every private function circuit must adhere to a specific format. This specific format (often referred to as the "public inputs ABI for private functions") ensures that the private kernel circuits can correctly interpret the actions of every private function circuit.

Private Inputs

The private inputs of a private function circuit are customizable.

Public Inputs

The public inputs of every private function must adhere to the following ABI:

Field	Type	Description
call_context	CallContext	Context of the call corresponding to this function execution.
args_hash	field	Hash of the function arguments.
return_values	[field; RETURN_VALUES_LENGTH]	Return values of this function call.
note_hashes	[NoteHash; MAX_NEW_NOTE_HASHES_PER_CALL]	New note hashes created in this function call.
nullifiers	[Nullifier; MAX_NEW_NULLIFIERS_PER_CALL]	New nullifiers created in this function call.
l2_to_l1_messages	[L2toL1Message; MAX_NEW_L2_TO_L1_MSGS_PER_CALL]	New L2 to L1 messages created in this function call.
unencrypted_log_hashes	[UnencryptedLogHash; MAX_UNENCRYPTED_LOG_HASHES_PER_CALL]	Hashes of the unencrypted logs emitted in this function call.
encrypted_log_hashes	[EncryptedLogHash; MAX_ENCRYPTED_LOG_HASHES_PER_CALL]	Hashes of the encrypted logs emitted in this function call.
encrypted_note_preimage_hashes	[EncryptedNotePreimageHash; MAX_ENCRYPTED_NOTE_PREIMAGE_HASHES_PER_CALL]	Hashes of the encrypted note preimages emitted in this function call.
note_hash_read_requests	[ReadRequest; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL]	Requests to prove the note hashes being read exist.
nullifier_read_requests	[ReadRequest; MAX_NULLIFIER_READ_REQUESTS_PER_CALL]	Requests to prove the nullifiers being read exist.
nullifier_key_validation_requests	[ParentSecretKeyValidationRequest; MAX_NULLIFIER_KEY_VALIDATION_REQUESTS_PER_CALL]	Requests to validate nullifier keys used in this function call.
public_call_requests	[PublicCallRequest; MAX_PUBLIC_CALL_STACK_LENGTH_PER_CALL]	Requests to call public functions.
private_call_requests	[PrivateCallRequest; MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL]	Requests to call Private functions.
counter_start	u32	Counter at which the function call was initiated.
counter_end	u32	Counter at which the function call ended.
min_revertible_side_effect_counter	u32	Counter below which the side effects are non-revertible.
block_header	BlockHeader	Information about the trees used for the transaction.
chain_id	field	Chain ID of the transaction.
version	field	Version of the transaction.

After generating a proof for a private function circuit, that proof (and associated public inputs) will be passed-into a private kernel circuit as private inputs. Private kernel circuits use the private function's proof, public inputs, and verification key, to verify the correct execution of the private function. Private kernel circuits then perform a number of checks and computations on the private function's public inputs.

Types

CallContext

Field	Type	Description
msg_sender	AztecAddress	Address of the caller contract.
storage_contract_address	AztecAddress	Address of the contract against which all state changes will be stored. (It is not called contract_address, because in the context of delegate calls, that would be an ambiguous name.)
portal_contract_address	AztecAddress	Address of the portal contract to the storage contract.
is_delegate_call	bool	A flag indicating whether the call is a delegate call.
is_static_call	bool	A flag indicating whether the call is a static call.
gas_settings	GasSettings	Limits and max fees per each gas dimension.
transaction_fee	field	Accumulated transaction fee, only set during teardown phase.

GasSettings

Field	Type	Description
da.gas_limit	u32	Total limit for DA gas for the transaction.
da.teardown_gas_limit	u32	Limit for DA gas specific to the teardown phase.
da.max_fee_per_gas	field	Maximum amount that the sender is willing to pay per unit of DA gas.
l1.gas_limit	u32	Total limit for L1 gas for the transaction.
l1.teardown_gas_limit	u32	Limit for L1 gas specific to the teardown phase.
l1.max_fee_per_gas	field	Maximum amount that the sender is willing to pay per unit of L1 gas.
l2.gas_limit	u32	Total limit for L2 gas for the transaction.
l2.teardown_gas_limit	u32	Limit for L2 gas specific to the teardown phase.
l2.max_fee_per_gas	field	Maximum amount that the sender is willing to pay per unit of L2 gas.
inclusion_fee	field	Flat fee the user pays for inclusion.

NoteHash

Field	Type	Description
value	field	Hash of the note.
counter	u32	Counter at which the note hash was created.

Nullifier

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.

L2toL1Message

Field	Type	Description
value	field	L2-to-l2 message.
counter	u32	Counter at which the message was emitted.

UnencryptedLogHash

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.

EncryptedLogHash

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.
randomness	field	A random value to hide the contract address.

EncryptedNotePreimageHash

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.
note_hash_counter	u32	Counter of the corresponding note hash.

ReadRequest

Field	Type	Description
value	field	Value being read.
contract_address	AztecAddress	Address of the contract the value was created.
counter	u32	Counter at which the request was made.

ParentSecretKeyValidationRequest

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

PublicCallRequest

Field	Type	Description
call_stack_item_hash	field	Hash of the call stack item.
counter	u32	Counter at which the request was made.

PrivateCallRequest

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.

BlockHeader

Field	Type	Description
note_hash_tree_root	field	Root of the note hash tree.
nullifier_tree_root	field	Root of the nullifier tree.
l1_to_l2_messages_tree_root	field	Root of the l1-to-l2 messages tree.
public_data_tree_root	field	Root of the public data tree.
archive_tree_root	field	Root of the state roots tree archived at the block prior to when the transaction was assembled.
global_variables_hash	field	Hash of the previous global variables.