From 023f837830c9e40c7fe024c1a84cb85f9898b427 Mon Sep 17 00:00:00 2001 From: Steve Goodman <39279277+stoobie@users.noreply.github.com> Date: Wed, 13 Mar 2024 20:06:41 +0200 Subject: [PATCH] docs: Adding details about the information that `get_execution_info` syscall returns. (#918) * Adding details about the information that `get_execution_info` syscall returns. * Removed extraneous code block delimiter. * Added 0.13.1 info, and added new page describing execution info. * Update components/Starknet/modules/architecture_and_concepts/nav.adoc * SME comments * Added details for `block_timestamp` * SME comments. --- .../architecture_and_concepts/nav.adoc | 5 +- .../pages/Smart_Contracts/execution_info.adoc | 55 ++++++++ .../Smart_Contracts/system-calls-cairo1.adoc | 129 +++++++++++------- 3 files changed, 134 insertions(+), 55 deletions(-) create mode 100644 components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/execution_info.adoc diff --git a/components/Starknet/modules/architecture_and_concepts/nav.adoc b/components/Starknet/modules/architecture_and_concepts/nav.adoc index 8ad01d8911..84cc1c2fb3 100644 --- a/components/Starknet/modules/architecture_and_concepts/nav.adoc +++ b/components/Starknet/modules/architecture_and_concepts/nav.adoc @@ -31,12 +31,13 @@ *** xref:Smart_Contracts/contract-syntax.adoc[Migrating a contract from Cairo v1 to Cairo v2] *** xref:Smart_Contracts/cairo-and-sierra.adoc[Cairo and Sierra] *** xref:Smart_Contracts/universal-deployer.adoc[Universal Deployer Contract] -*** xref:Smart_Contracts/system-calls-cairo1.adoc[System calls] *** xref:Smart_Contracts/serialization_of_Cairo_types.adoc[Serialization of Cairo types] +*** xref:Smart_Contracts/system-calls-cairo1.adoc[System calls] +*** xref:Smart_Contracts/execution_info.adoc[Execution information for the current block] ** Cryptography *** xref:Cryptography/p-value.adoc[The STARK field] *** xref:Cryptography/stark-curve.adoc[The STARK curve] *** xref:Cryptography/hash-functions.adoc[Hash functions] -* xref:Economics-of-Starknet.adoc[The Economics of Starknet] \ No newline at end of file +* xref:Economics-of-Starknet.adoc[The Economics of Starknet] diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/execution_info.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/execution_info.adoc new file mode 100644 index 0000000000..cc62592b87 --- /dev/null +++ b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/execution_info.adoc @@ -0,0 +1,55 @@ +[id="block_execution_info"] += Execution information + +For the most up-to-date information, see the link:https://github.com/starkware-libs/cairo/blob/main/corelib/src/starknet/info.cairo[`info.cairo`] contract. + +The struct `ExecutionInfo` contains the following information about the currently executing block and the transactions in the block. + +== The `ExecutionInfo` struct + +[horizontal,labelwidth="25",role="stripes-odd"] +`block_info: Box`:: Contains information about a block. For details, see xref:#block_info[] +`tx_info: Box`:: Contains information about a transaction. For details, see xref:#tx_info[] +`caller_address`: ContractAddress:: The address of the contract that invokes the `get_execution_info` syscall. +`contract_address`: ContractAddress:: The address of the contract in which the `get_execution_info` syscall appears. +`entry_point_selector`: felt252:: The function that includes the `get_execution_info` syscall. + + +[#block_info] +== The `BlockInfo` struct + +[horizontal,labelwidth="25",role="stripes-odd"] +`_block_number_: u64`:: The number of the block that is currently being executed. When called from an account contract's +`__validate__`+, +`__validate_deploy__`+, or +`__validate_declare__`+ function, this value is rounded down to the nearest multiple of 100. +`_block_timestamp_: u64`:: The timestamp showing the creation time of the block, in seconds since the Unix epoch, based on UTC time, rounded down to the nearest second. When called from an account contract's +`__validate__`+, +`__validate_deploy__`+, or +`__validate_declare__`+ function, this value is rounded down to the nearest hour. +`_sequencer_address_: ContractAddress`:: The address of the Starknet sequencer contract. + +[#tx_info] +== Transaction information: The `TxInfo` struct + +[horizontal,labelwidth="25",role="stripes-odd"] +`_version_: felt252`:: The version of the transaction. It is fixed (currently, 3) in the OS, and should be signed by the account contract. This field allows invalidating old transactions, whenever the meaning of the other transaction fields is changed (in the OS). +`_account_contract_address_: ContractAddress`:: The account contract from which this transaction originates. +`_max_fee_: u128`:: The max_fee field of the transaction. +`_signature_: Span`:: The signature of the transaction. +`_transaction_hash_: felt252`:: The hash of the transaction. +`_chain_id_: felt252`:: The identifier of the chain. +This field can be used to prevent replay of testnet transactions on mainnet. +`_nonce_: felt252`:: The transaction's nonce. +`_resource_bounds_: Span`:: A span of `ResourceBounds` structs. For details, see xref:#resource_bounds[]. +`_tip_: u128`:: The tip. +`_paymaster_data_: Span`:: If specified, the paymaster should pay for the execution of the tx. +The data includes the address of the paymaster sponsoring the transaction, followed by +extra data to send to the paymaster. +`_nonce_data_availability_mode_: u32`:: The data availability mode for the nonce. +`_fee_data_availability_mode_: u32`:: The data availability mode for the account balance from which fee will be taken. +`_account_deployment_data_: Span`:: If nonempty, will contain the required data for deploying and initializing an account +contract: its class hash, address salt and constructor calldata. + +[#resource_bounds] +== The `ResourceBounds` struct + +[horizontal,labelwidth="25",role="stripes-odd"] +`_resource_: felt252`:: The name of the resource. +`_max_amount_: u64`:: The maximum amount of the resource allowed for usage during the execution. +`_max_price_per_unit_: u128`:: The maximum price the user is willing to pay for the resource unit. + diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/system-calls-cairo1.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/system-calls-cairo1.adoc index e3dcdaa404..403c62184e 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/system-calls-cairo1.adoc +++ b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/system-calls-cairo1.adoc @@ -21,11 +21,16 @@ extern fn get_block_hash_syscall( Gets the hash of a specific Starknet block within the range of `[__first_v0_12_0_block__, __current_block__ - 10]`. +[discrete] +=== Arguments + +[horizontal,labelwidth="25",role="stripes-odd"] +`_block_number_ u64`:: The number of the block whose hash you want to get. [discrete] === Return values -Returns the hash of the given block. +The hash of the specified block. [discrete] === Common library @@ -44,7 +49,7 @@ link:https://github.com/starkware-libs/cairo/blob/0c882679fdb24a818cad19f2c18dec == `get_execution_info` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -54,33 +59,50 @@ extern fn get_execution_info_syscall() -> SyscallResult>`. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L10[`syscalls.cairo`^] @@ -131,7 +153,7 @@ If the interface of the called contract is available, then you can use a more st == `deploy` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -144,12 +166,12 @@ extern fn deploy_syscall( ---- [discrete] -==== Description +=== Description Deploys a new instance of a previously declared class. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The class hash of the contract to be deployed. @@ -157,14 +179,15 @@ Deploys a new instance of a previously declared class. `_calldata_`:: The constructor's calldata. An array of felts. `_deploy_from_zero_`:: A flag used for the contract address computation. If not set, the caller address will be used as the new contract's deployer address, otherwise 0 is used. -.Return values +[discrete] +=== Return values * A tuple wrapped with `SyscallResult` where: ** The first element is the address of the deployed contract, of type `ContractAddress`. ** The second element is the response array from the contract's constructor, of type `Span::`. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/main/corelib/src/starknet/syscalls.cairo#L20[`syscalls.cairo`^] @@ -173,7 +196,7 @@ link:https://github.com/starkware-libs/cairo/blob/main/corelib/src/starknet/sysc == `emit_event` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -183,31 +206,31 @@ extern fn emit_event_syscall( ---- [discrete] -==== Description +=== Description Emits an event with a given set of keys and data. For more information, and for a higher-level syntax for emitting events, see xref:architecture_and_concepts:Smart_Contracts/starknet-events.adoc[Starknet events]. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_keys_`:: The event's keys. These are analogous to Ethereum's event topics, you can use the link:https://github.com/starkware-libs/starknet-specs/blob/c270b8170684bb09741672a7a4ae5003670c3f43/api/starknet_api_openrpc.json#L569RPC[starknet_getEvents] method to filter by these keys. `_data_`:: The event's data. [discrete] -==== Return values +=== Return values None. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L30[`syscalls.cairo`^] [discrete] -==== Example +=== Example The following example emits an event with two keys, the strings `key` and `deposit` and three data elements: `1`, `2`, and `3`. @@ -222,7 +245,7 @@ emit_event_syscall(keys, values).unwrap_syscall(); == `library_call` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -232,14 +255,14 @@ extern fn library_call_syscall( ---- [discrete] -==== Description +=== Description Calls the requested function in any previously declared class. The class is only used for its logic. This system call replaces the known delegate call functionality from Ethereum, with the important difference that there is only one contract involved. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The hash of the class you want to use. @@ -247,12 +270,12 @@ This system call replaces the known delegate call functionality from Ethereum, w `_calldata_`:: The calldata. [discrete] -==== Return values +=== Return values * The call response, of type `SyscallResult>`. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L43[`syscalls.cairo`^] @@ -260,7 +283,7 @@ link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994d == `send_message_to_L1` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -270,7 +293,7 @@ extern fn send_message_to_l1_syscall( ---- [discrete] -==== Description +=== Description Sends a message to L1. @@ -279,24 +302,24 @@ This system call includes the message parameters as part of the proof's output a For more information, see Starknet's xref:Network_Architecture/messaging-mechanism.adoc[messaging mechanism]. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_to_address_`:: The recipient's L1 address. `_payload_`:: The array containing the message payload [discrete] -==== Return values +=== Return values None. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L51[`syscalls.cairo`^] [discrete] -==== Example +=== Example The following example sends a message whose content is `(1,2)` to the L1 contract whose address is `3423542542364363`. @@ -312,7 +335,7 @@ send_message_to_l1_syscall(payload).unwrap_syscall(); == `replace_class` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -322,7 +345,7 @@ extern fn replace_class_syscall( ---- [discrete] -==== Description +=== Description Once `replace_class` is called, the class of the calling contract (i.e. the contract whose address is returned by `get_contract_address` at the time the syscall is called) will be replaced by the class whose hash is given by the class_hash argument. @@ -336,25 +359,25 @@ the `call_contract` syscall in the same transaction (after the replacement). ==== [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The hash of the class you want to use as a replacement. [discrete] -==== Return values +=== Return values None. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L77[`syscalls.cairo`^] [id="storage_read"] == `storage_read` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -364,7 +387,7 @@ extern fn storage_read_syscall( ---- [discrete] -==== Description +=== Description Gets the value of a key in the storage of the calling contract. @@ -373,24 +396,24 @@ This system call provides direct access to any possible key in storage, in contr For information on accessing storage by using the storage variables, see xref:./contract-storage.adoc#storage_variables[storage variables]. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_address_domain_`:: The domain of the key, used to separate between different data availability modes. This separation is used in Starknet to offer different data availability modes. Currently, only the onchain mode (where all updates go to L1), indicated by domain `0`, is supported. Other address domains which will be introduced in the future will behave differently in terms of publication (in particular, they will not be posted on L1, creating a tradeoff between cost and security). `_address_`:: The requested storage address. [discrete] -==== Return values +=== Return values * The value of the key, of type `SyscallResult`. [discrete] -==== Common library +=== Common library link:https://github.com/starkware-libs/cairo/blob/cca08c898f0eb3e58797674f20994df0ba641983/corelib/src/starknet/syscalls.cairo#L60[`syscalls.cairo`^] [discrete] -==== Example +=== Example [source,cairo,subs="+quotes,+macros"] ---- @@ -406,7 +429,7 @@ storage_read_syscall(0, storage_address).unwrap_syscall() == `storage_write` [discrete] -==== Syntax +=== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -416,7 +439,7 @@ extern fn storage_write_syscall( ---- [discrete] -==== Description +=== Description Sets the value of a key in the storage of the calling contract. @@ -425,7 +448,7 @@ This system call provides direct access to any possible key in storage, in contr For information on accessing storage by using the storage variables, see xref:./contract-storage.adoc#storage_variables[storage variables]. [discrete] -==== Arguments +=== Arguments [horizontal,labelwidth=35] `_address_domain_`:: The domain of the key, used to separate between different data availability modes. This separation is used in Starknet to offer different data availability modes. Currently, only the onchain mode (where all updates go to L1), indicated by domain `0`, is supported. Other address domains which will be introduced in the future will behave differently in terms of publication (in particular, they will not be posted on L1, creating a tradeoff between cost and security). @@ -433,7 +456,7 @@ For information on accessing storage by using the storage variables, see xref:./ `_value_`:: The value to write to the key. [discrete] -==== Return values +=== Return values None.