Skip to content

Commit

Permalink
docs: Add GlobalVariables to CombinedConstantData (#6071)
Browse files Browse the repository at this point in the history
Reflect the changes from #6031 in the protocol-specs.
  • Loading branch information
spalladino authored May 2, 2024
1 parent 979a22d commit cf026d2
Show file tree
Hide file tree
Showing 3 changed files with 15 additions and 10 deletions.
21 changes: 11 additions & 10 deletions docs/docs/protocol-specs/gas-and-fees/kernel-tracking.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ class PrivateCircuitPublicInputs {
+bool is_fee_payer
+u32 min_revertible_side_effect_counter
+Field public_teardown_function_hash
+Header historical_header
+Header historical_header
}
PrivateCircuitPublicInputs --> TxContext
PrivateCircuitPublicInputs --> Header
Expand Down Expand Up @@ -70,6 +70,7 @@ class PrivateAccumulatedData {
class CombinedConstantData {
+Header historical_header
+TxContext tx_context
+GlobalVariables global_variables
}
CombinedConstantData --> Header
CombinedConstantData --> TxContext
Expand Down Expand Up @@ -146,20 +147,19 @@ PrivateKernelTailToPublicCircuitPrivateInputs --> PrivateKernelData

## Private Context Initialization

Whenever a private function is run, it has a `PrivateContext` associated with it, which is initialized in part from a `PrivateContextInputs` object.
Whenever a private function is run, it has a `PrivateContext` associated with it, which is initialized in part from a `PrivateContextInputs` object.

The [gas settings that users specify](./specifying-gas-fee-info.md) become part of the values in the `TxContext` within the `PrivateContextInputs` of the [entrypoint](./tx-setup-and-teardown.md#defining-setup). These values are copied to the `PrivateCircuitPublicInputs`.

The same `TxContext` is provided as part of the `TxRequest` in the `PrivateKernelInitCircuitPrivateInputs`. This is done to ensure that the `TxContext` in the `PrivateCallData` (what was executed) matches the `TxContext` in the `TxRequest` (users' intent).


## Private Kernel Init

The PrivateKernelInit circuit takes in a `PrivateCallData` and a `TxRequest` and outputs a `PrivateKernelCircuitPublicInputs`.

It must:

- check that the `TxContext` provided as in the `TxRequest` input matches the `TxContext` in the `PrivateCallData`
- check that the `TxContext` provided as in the `TxRequest` input matches the `TxContext` in the `PrivateCallData`
- copy the `TxContext` from the `TxRequest` to the `PrivateKernelCircuitPublicInputs.constants.tx_context`
- copy the `Header` from the `PrivateCircuitPublicInputs` to the `PrivateKernelCircuitPublicInputs.constants.historical_header`
- set the min_revertible_side_effect_counter if it is present in the `PrivateCallData`
Expand All @@ -186,7 +186,7 @@ It must:

- check that there are no enqueued public functions or public teardown function
- compute the gas used
- this will only include DA gas *and* any gas specified in the `teardown_gas_allocations`
- this will only include DA gas _and_ any gas specified in the `teardown_gas_allocations`
- ensure the gas used is less than the gas limits
- ensure that `fee_payer` is set, and set it in the `KernelCircuitPublicInputs`
- copy the constants from the `PrivateKernelData` to the `KernelCircuitPublicInputs.constants`
Expand Down Expand Up @@ -250,6 +250,7 @@ Where the `PrivateKernelTailCircuitPublicInputs` may be destined for the base ro
Regardless, it has a `fee_payer` set.

When a node receives a transaction, it must check that:

1. the `fee_payer` is set
2. the `fee_payer` has a balance of [FPA](./fee-payment-asset.md) greater than the computed [transaction fee](./specifying-gas-fee-info.md#transaction-fee) if the transaction has no public component
3. the `fee_payer` has a balance of FPA greater than the computed [max transaction fee](./specifying-gas-fee-info.md#maximum-transaction-fee) if the transaction has a public component
Expand All @@ -259,6 +260,7 @@ See other [validity conditions](../transactions/validity.md).
# Public Kernel Circuits

On the public side, the order of the circuits is:

1. PublicKernelSetup
2. PublicKernelAppLogic
3. PublicKernelTeardown
Expand All @@ -278,7 +280,7 @@ class PublicKernelSetupCircuitPrivateInputs {
+PublicKernelData previous_kernel
+PublicCallData public_call
}
PublicKernelSetupCircuitPrivateInputs --> PublicKernelData
PublicKernelSetupCircuitPrivateInputs --> PublicKernelData
PublicKernelSetupCircuitPrivateInputs --> PublicCallData
class PublicKernelData {
Expand All @@ -299,6 +301,7 @@ PublicKernelCircuitPublicInputs --> CombinedConstantData
class CombinedConstantData {
+Header historical_header
+TxContext tx_context
+GlobalVariables global_variables
}
class PublicConstantData {
Expand Down Expand Up @@ -429,7 +432,7 @@ It must assert that the `revert_code` in the `PublicCircuitPublicInputs` is equa

It must assert that the `public_call.call_stack_item.public_inputs.global_variables.gas_fees` are valid according to the [update rules defined](./published-gas-and-fee-data.md#updating-the-gasfees-object).

It must compute the gas used in the `PublicKernelData` provided, and verify that the `gas_limits` in the `PublicKernelData`'s `TxContext` *minus* the computed `gas_used` is equal to the `start_gas_left` specified on the `PublicCircuitPublicInputs`.
It must compute the gas used in the `PublicKernelData` provided, and verify that the `gas_limits` in the `PublicKernelData`'s `TxContext` _minus_ the computed `gas_used` is equal to the `start_gas_left` specified on the `PublicCircuitPublicInputs`.

This ensures that the public VM was provided with the correct starting gas values.

Expand Down Expand Up @@ -497,7 +500,7 @@ pub fn update_revertible_gas_used(public_call: PublicCallData, circuit_outputs:
It sets the `revert_code` in `PublicKernelCircuitPublicInputs` to `1`.

:::note Gas reserved for public teardown
Recall in the [Private Kernel Tail to Public](#private-kernel-tail-to-public) circuit, the gas allocated for the public teardown function was included in the `end` gas used. This ensures that we have gas available for teardown even though app logic consumed all gas.
Recall in the [Private Kernel Tail to Public](#private-kernel-tail-to-public) circuit, the gas allocated for the public teardown function was included in the `end` gas used. This ensures that we have gas available for teardown even though app logic consumed all gas.
:::

:::warning
Expand Down Expand Up @@ -534,12 +537,10 @@ The interplay between these two `revert_code`s is as follows:
| 1 | 1 | 3 |
| 2 or 3 | (any) | (unchanged) |


# Base Rollup Kernel Circuit

The base rollup kernel circuit takes in a `KernelData`, which contains a `KernelCircuitPublicInputs`, which it uses to compute the `transaction_fee`.

Additionally, it verifies that the max fees per gas specified by the user are greater than the current block's fees per gas.

After the public data writes specific to this transaction have been processed, and a new tree root is produced, the kernel circuit injects an additional public data write based upon that root which deducts the transaction fee from the `fee_payer`'s balance.

2 changes: 2 additions & 0 deletions docs/docs/protocol-specs/rollup-circuits/base-rollup.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,9 +159,11 @@ TxContext *-- GasSettings : gas_settings
class CombinedConstantData {
historical_header: Header
tx_context: TxContext
global_variables: GlobalVariables
}
CombinedConstantData *-- Header : historical_header
CombinedConstantData *-- TxContext : tx_context
CombinedConstantData *-- GlobalVariables : global_variables
class GasSettings {
da.gas_limit: u32
Expand Down
2 changes: 2 additions & 0 deletions docs/docs/protocol-specs/rollup-circuits/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,9 +283,11 @@ TxContext *-- GasSettings : gas_settings
class CombinedConstantData {
historical_header: Header
tx_context: TxContext
global_variables: GlobalVariables
}
CombinedConstantData *-- Header : historical_header
CombinedConstantData *-- TxContext : tx_context
CombinedConstantData *-- GlobalVariables : global_variables
class GasSettings {
da.gas_limit: u32
Expand Down

0 comments on commit cf026d2

Please sign in to comment.