diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ced0e59dd..5b0dfca617 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,6 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. -### [0.1.169](https://github.com/starknet-io/starknet-docs/compare/v0.1.168...v0.1.169) (2023-06-19) - -### [0.1.168](https://github.com/starknet-io/starknet-docs/compare/v0.1.167...v0.1.168) (2023-06-16) - -### [0.1.167](https://github.com/starknet-io/starknet-docs/compare/v0.1.166...v0.1.167) (2023-06-16) - -### [0.1.166](https://github.com/starknet-io/starknet-docs/compare/v0.1.164...v0.1.166) (2023-06-16) - ### [0.1.159](https://github.com/starknet-io/starknet-docs/compare/v0.1.158...v0.1.159) (2023-06-13) ### [0.1.158](https://github.com/starknet-io/starknet-docs/compare/v0.1.157...v0.1.158) (2023-06-13) diff --git a/components/StarkNet/modules/architecture_and_concepts/pages/Contracts/system-calls-cairo0.adoc b/components/StarkNet/modules/architecture_and_concepts/pages/Contracts/system-calls-cairo0.adoc index b8a6812110..620f3d9180 100644 --- a/components/StarkNet/modules/architecture_and_concepts/pages/Contracts/system-calls-cairo0.adoc +++ b/components/StarkNet/modules/architecture_and_concepts/pages/Contracts/system-calls-cairo0.adoc @@ -1,38 +1,41 @@ = System Calls -Starknet smart contracts are written in Cairo. However, Cairo is a general purpose language that you can use for much more than just contract language. For details, see link:https://eprint.iacr.org/2021/1063.pdf[Cairo – a Turing-complete STARK-friendly CPU architecture]. - -So writing smart contracts requires some operations, such as calling another contract or accessing the contract's storage, that standalone programs do not require. - -The Starknet contract language supports these operations by using system calls. System calls enable a contract to require services from the Starknet OS. You can use system calls in a function to get information that depends on the broader state of Starknet, which would otherwise be inaccessible, rather than local variables that appear in the function's scope. +Writing smart contracts requires some operations, such as calling another contract or accessing the contract’s storage, that standalone programs do not require. The Starknet contract language supports these operations by using system calls. System calls enable a contract to require services from the Starknet OS. You can use system calls in a function to get information that depends on the broader state of Starknet, which would otherwise be inaccessible, rather than local variables that appear in the function’s scope. [id="getters"] == getters -Below we describe the collection of system calls that can be used to get information regarding the block, transaction or execution context during runtime (e.g. block number, account address, and caller address). +Below we describe the collection of system calls that can be used to get information regarding the block, transaction, or execution context during runtime (e.g. block number, account address, and caller address). [id="get_block_number"] === `get_block_number` +[discrete] +==== Syntax + [source,cairo,subs="+quotes,+macros"] ---- func get_block_number{syscall_ptr : felt*}() -> (__block_number__ : felt) ---- -.Description +[discrete] +==== Description Gets the number of the block in which the transaction is executed. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_block_number_`:: The number of the block in which the transaction is executed. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L161[`syscalls.cairo`^] @@ -40,84 +43,98 @@ link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412 [id="get_block_timestamp"] === `get_block_timestamp` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func get_block_timestamp{syscall_ptr : felt*}() -> (__block_timestamp__ : felt) ---- -.Description +[discrete] +==== Description Gets the timestamp of the block in which the transaction is executed. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] -'_block_timestamp_':: The timestamp of the block in which the transaction is executed +`_block_timestamp_`:: The timestamp of the block in which the transaction is executed. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L210[`syscalls.cairo`^] -.Common library - [id="get_caller_address"] === `get_caller_address` -.Syntax +[discrete] +==== Syntax + [source,cairo,subs="+quotes,+macros"] ---- func get_caller_address{syscall_ptr : felt*}() -> (__caller_address__ : felt) ---- -.Description +[discrete] +==== Description Returns the address of the calling contract, or 0 if the call was not initiated by another contract. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `__caller_address__`:: The address of the calling contract, or 0 if the call was not initiated by another contract. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L112[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L200[`syscalls.cairo`^] [id="get_contract_address"] === `get_contract_address` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func get_contract_address{syscall_ptr : felt*}() -> (__contract_address__ : felt) ---- -.Description +[discrete] +==== Description Gets the address of the contract who raised the system call. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] -`_contract_address_`:: The address of the contract who raised the system call. +`_contract_address_`:: The address of the contract that raised the system call. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L186[`syscalls.cairo`^] @@ -125,27 +142,32 @@ link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412 [id="get_sequencer_address"] === `get_sequencer_address` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func get_sequencer_address{syscall_ptr : felt*}() -> (__sequencer_address__ : felt) ---- -.Description +[discrete] +==== Description Returns the address of the sequencer that generated the current block. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_sequencer_address_`:: The address of the sequencer that generated the current block. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L138[`syscalls.cairo`^] @@ -153,47 +175,48 @@ link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412 [id="get_transaction_info"] === `get_transaction_info` -Gets information about the original transaction. - -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func get_tx_info{syscall_ptr : felt*}() -> (__tx_info__ : TxInfo*) ---- -.Description +[discrete] +==== Description Gets information about the original transaction. -.Arguments +[discrete] +==== Arguments None. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_tx_info_`:: The following information about the original transaction: + -* the version of the transaction -* the address of the account that initiated this transaction -* the maximum fee that is allowed to be charged for the inclusion of this transaction -* the signature of the account that initiated this transaction -* the transaction's hash -* the intended chain id +* The version of the transaction. +* The address of the account that initiated this transaction. +* The maximum fee that is allowed to be charged for the inclusion of this transaction. +* The signature of the account that initiated this transaction. +* The transaction's hash. +* The intended chain id. -.Common library +[discrete] +==== Common library + +link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L351[`syscalls.cairo`^] -link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L301[`syscalls.cairo`^] [id="call_contract"] == `call_contract` -.Description - -Calls a given contract. This system call expects the address of the called contract, a selector for a function within that contract, and call arguments. - -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -202,7 +225,13 @@ func call_contract{syscall_ptr : felt*}( ) -> (__retdata_size__ : felt, __retdata__ : felt*) ---- -.Arguments +[discrete] +==== Description + +Calls a given contract. This system call expects the address of the called contract, a selector for a function within that contract, and call arguments. + +[discrete] +==== Arguments [horizontal,labelwidth=35] `_contract_address_`:: The address of the contract you want to call. @@ -210,29 +239,32 @@ func call_contract{syscall_ptr : felt*}( `_calldata_size_`:: The size, in number of felts, of the calldata. `_calldata_`:: The calldata. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_retdata_size_`:: The size, in number of felts, of the return data. `_retdata_`:: The return data. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L42[`syscalls.cairo`^] [NOTE] ==== -This is considered a lower level syntax for calling contracts. +This is considered a lower-level syntax for calling contracts. -If the interface of the called -contract is available, then you can use a more straightforward syntax. +If the interface of the called contract is available, then you can use a more straightforward syntax. ==== + [id="deploy"] == `deploy` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -245,62 +277,72 @@ func deploy{syscall_ptr : felt*}( ) -> (__contract_address__ : felt) ---- -.Description +[discrete] +==== Description Deploys a new instance of a previously declared class. -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] -`_class_hash_`:: The class hash of the contract to be deployed +`_class_hash_`:: The class hash of the contract to be deployed. `_contract_address_salt_`:: The salt, an arbitrary value provided by the sender, used in the computation of the xref:Contracts/contract-address.adoc[contract's address]. `_constructor_calldata_size_`:: The number of arguments to pass to the constructor, equal to the number of felts in `_constructor_calldata_`. `_constructor_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. +`__deploy_from_zero__`:: A flag used for the contract address computation. If set, the new contract's deployer address will be `0`. Otherwise, the caller's address will be used. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_contract_address_`:: The address of the deployed contract. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L154[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L157[`syscalls.cairo`^] [id="emit_event"] == `emit_event` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func emit_event{syscall_ptr : felt*}(__keys_len__ : felt, __keys__ : felt*, __data_len__ : felt, __data__ : felt*) ---- -.Description +[discrete] +==== 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:Events/starknet-events.adoc[Starknet events]. +For more information, and for a higher-level syntax for emitting events, see xref:Events/starknet-events.adoc[Starknet events]. -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_keys_len_`:: The number of keys in the event. 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. -`_keys_`:: The event's keys +`_keys_`:: The event's keys. `_data_len_`:: The number of data elements in the event. -`_data_`:: The event's data +`_data_`:: The event's data. -.Return values +[discrete] +==== Return values None. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L301[`syscalls.cairo`^] -.Example +[discrete] +==== Example The following example emits an event with two keys, the https://www.cairo-lang.org/docs/how_cairo_works/consts.html#short-string-literals[strings] `status` and `deposit` and three data elements: `1`, `2`, and `3`. @@ -316,10 +358,12 @@ assert data[2] = 3 emit_event(2, keys, 3, data) ---- + [id="library_call"] == `library_call` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -328,15 +372,15 @@ func library_call{syscall_ptr : felt*}( ) -> (__retdata_size__ : felt, __retdata__ : felt*) ---- -.Description +[discrete] +==== Description -Calls the requested function in any previously declared class. +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. -The class is only used for its logic. - -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The hash of the class you want to use. @@ -344,15 +388,17 @@ The class is only used for its logic. `_calldata_size_`:: The size, in number of felts, of the calldata. `_calldata_`:: The calldata. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_retdata_size_`:: The size, in number of felts, of the return data. `_retdata_`:: The return data. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L84[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L85[`syscalls.cairo`^] [id="library_call_l1_handler"] @@ -364,7 +410,8 @@ This system call is not currently not supported in Cairo 1.0. In practice, this was only used for proxy contracts, which in Cairo 1.0 can be implemented instead via the `replace_class` system call, making `library_call_l1_handler` redundant. ==== -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -373,22 +420,20 @@ func library_call_l1_handler{syscall_ptr : felt*}( ) -> (__retdata_size__ : felt, __retdata__ : felt*) ---- -.Description +[discrete] +==== Description Calls the requested L1 handler in any previously declared class. -Same as the `library_call` system call, but also enables you to call an L1 handler that cannot otherwise be called directly. For more information, see Starknet's xref:L1-L2_Communication/messaging-mechanism.adoc#l1-l2_messages[messaging mechanism]. - -When you invoke an L1 handler with this system call, the sequencer does not consume an L1->L2 message. - -This system call enables an L1 handler to use the logic inside an L1 handler in a different class. +Same as the `library_call` system call, but also enables you to call an L1 handler that cannot otherwise be called directly. For more information, see Starknet's xref:L1-L2_Communication/messaging-mechanism.adoc#l1-l2_messages[messaging mechanism] (note that when you invoke an L1 handler with this system call, the sequencer does not consume an L1->L2 message). [TIP] ==== -It is recommended to raise this system call only inside an L1 handler. +It is recommended to raise this system call only inside an L1 handler in order to use the logic inside an L1 handler of a different class. ==== -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The hash of the class you want to use. @@ -396,21 +441,24 @@ It is recommended to raise this system call only inside an L1 handler. `_calldata_size_`:: The size, in number of felts, of the calldata. `_calldata_`:: The calldata. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_retdata_size_`:: The size, in number of felts, of the return data. `_retdata_`:: The return data. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L105[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L107[`syscalls.cairo`^] [id="send_message_to_L1"] == `send_message_to_L1` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- @@ -419,30 +467,35 @@ func send_message_to_l1{syscall_ptr : felt*}( ) ---- -.Description +[discrete] +==== Description Sends a message to L1. -This system call includes the message parameters as part of the proof's output, and exposes these parameters to the Starknet Core contract on L1 once the state update, including the transaction, is received. +This system call includes the message parameters as part of the proof's output and exposes these parameters to the Starknet Core contract on L1 once the state update, including the transaction, is received. For more information, see Starknet's xref:L1-L2_Communication/messaging-mechanism.adoc[messaging mechanism]. -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_to_address_`:: The recipient's L1 address. `_payload_size_`:: The size of the message payload. `_payload_`:: A pointer to an array containing the contents of the message. -.Return values +[discrete] +==== Return values None. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/messages.cairo[messages.cairo] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/messages.cairo[`messages.cairo`^] -.Example +[discrete] +==== Example The following example sends a message whose content is `(1,2)` to the L1 contract whose address is `3423542542364363`. @@ -454,20 +507,22 @@ payload[1] = 2 send_message_to_l1(3423542542364363,2,payload) ---- + [id="replace_class"] == `replace_class` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- replace_class(class_hash: felt) ---- -.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 . +[discrete] +==== 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. [NOTE] ==== @@ -478,52 +533,61 @@ The new class will be used from the next transaction onwards or if the contract the call_contract syscall in the same transaction (after the replacement). ==== -.Arguments - +[discrete] +==== Arguments [horizontal,labelwidth=35] `_class_hash_`:: The hash of the class you want to use as a replacement. -.Return values +[discrete] +==== Return values -None +None. + +[discrete] +==== Common library -.Common library -link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L84[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/common/syscalls.cairo#L463[`syscalls.cairo`^] [id="storage_read"] == `storage_read` -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func storage_read{syscall_ptr : felt*}(__address__ : felt) -> (__value__ : felt) ---- -.Description +[discrete] +==== Description Gets the value of a key in the storage of the calling contract. -This system call provides direct access to any possible key in storage, in contrast with `balance.read()`, which enables you to read storage variables that are defined explicitly in the contract. +This system call provides direct access to any possible key in storage, in contrast with `var.read()`, which enables you to read storage variables that are defined explicitly in the contract. For information on accessing storage by using the storage variables, see xref:./contract-storage.adoc#storage_variables[storage variables]. -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_address_`:: The address of the storage key you want to read. -.Return values +[discrete] +==== Return values [horizontal,labelwidth=35] `_value_`:: The value of the key. -.Common library +[discrete] +==== Common library link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L264[`syscalls.cairo`^] -.Example +[discrete] +==== Example [source,cairo,subs="+quotes,+macros"] ---- @@ -535,32 +599,37 @@ let value = storage_read(3534535754756246375475423547453) Sets the value of a key in the storage of the calling contract. -.Syntax +[discrete] +==== Syntax [source,cairo,subs="+quotes,+macros"] ---- func storage_write{syscall_ptr : felt*}(__address__ : felt, __value__ : felt) ---- -.Description +[discrete] +==== Description Sets the value of a key in the storage of the calling contract. -This system call provides direct access to any possible key in storage, in contrast with `balance.write()`, which enables you to write to storage variables that are defined explicitly in the contract. +This system call provides direct access to any possible key in storage, in contrast with `var.write()`, which enables you to write to storage variables that are defined explicitly in the contract. For information on accessing storage by using the storage variables, see xref:./contract-storage.adoc#storage_variables[storage variables]. -.Arguments +[discrete] +==== Arguments [horizontal,labelwidth=35] `_address_`:: The address of the storage key to which you want to write. -.`_value_`:: The value to write to the key. +`_value_`:: The value to write to the key. -.Return values +[discrete] +==== Return values None. -.Common library +[discrete] +==== Common library -link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L301[`syscalls.cairo`^] +link:https://github.com/starkware-libs/cairo-lang/blob/2abd303e1808612b724bc1412b2b5babd04bb4e7/src/starkware/starknet/common/syscalls.cairo#L282[`syscalls.cairo`^] diff --git a/package-lock.json b/package-lock.json index 5a25a1254f..120b9c63e4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "starknet-docs", - "version": "0.1.169", + "version": "0.1.165", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "starknet-docs", - "version": "0.1.169", + "version": "0.1.159", "dependencies": { "@antora/lunr-extension": "^1.0.0-alpha.8", "@asciidoctor/tabs": "^1.0.0-beta.3", diff --git a/package.json b/package.json index 5ad3a37415..7af8eb5d7b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "starknet-docs", - "version": "0.1.169", + "version": "0.1.165", "private": true, "scripts": { "pre-release": "standard-version --prerelease --skip.changelog --releaseCommitMessageFormat 'chore(prerelease): {{currentTag}}'",