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

getters (Cairo 0)

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

`get_block_number`

func get_block_number{syscall_ptr : felt*}() -> (block_number : felt)

Description

Gets the number of the block in which the transaction is executed.

Arguments

None.

Return values

block_number

The number of the block in which the transaction is executed.

Common library

syscalls.cairo

`get_block_timestamp`

Syntax

func get_block_timestamp{syscall_ptr : felt*}() -> (block_timestamp : felt)

Description

Gets the timestamp of the block in which the transaction is executed.

Arguments

None.

Return values

'block_timestamp'

The timestamp of the block in which the transaction is executed

Common library

syscalls.cairo

`get_caller_address`

Syntax

func get_caller_address{syscall_ptr : felt*}() -> (caller_address : felt)

Description

Returns the address of the calling contract, or 0 if the call was not initiated by another contract.

Arguments

None.

Return values

caller_address

The address of the calling contract, or 0 if the call was not initiated by another contract.

Common library

syscalls.cairo

`get_contract_address`

Syntax

func get_contract_address{syscall_ptr : felt*}() -> (contract_address : felt)

Description

Gets the address of the contract who raised the system call.

Arguments

None.

Return values

contract_address

The address of the contract who raised the system call.

Common library

syscalls.cairo

`get_sequencer_address`

Syntax

func get_sequencer_address{syscall_ptr : felt*}() -> (sequencer_address : felt)

Description

Returns the address of the sequencer that generated the current block.

Arguments

None.

Return values

sequencer_address

The address of the sequencer that generated the current block.

Common library

syscalls.cairo

===get_transaction_info

Gets information about the original transaction.

Syntax

func get_tx_info{syscall_ptr : felt*}() -> (tx_info : TxInfo*)

Description

Gets information about the original transaction.

Arguments

None.

Return values

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

Common library

syscalls.cairo

getters (Cairo 1.0)

In Cairo 1.0, all block/transaction/execution context getters are batched into a single system call: get_execution_info.

`get_execution_info`

Syntax

extern fn get_execution_info_syscall() -> SyscallResult<Box<starknet::info::ExecutionInfo>> implicits(
    GasBuiltin, System
) nopanic;

Description

Gets information about the original transaction.

Arguments

None.

Return values

ExecutionInfo

A struct containing the execution info

`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

Cairo 0
Cairo 1.0

func call_contract{syscall_ptr : felt*}(
    contract_address : felt, function_selector : felt, calldata_size : felt, calldata : felt*
) -> (retdata_size : felt, retdata : felt*)

extern fn call_contract_syscall(
    address: ContractAddress, entry_point_selector: felt252, calldata: Span<felt252>
) -> SyscallResult<Span<felt252>> implicits(GasBuiltin, System) nopanic;

Arguments

`contract_address`	The address of the contract you want to call.
`function_selector`	A selector for a function within that contract.
`calldata_size`	The size, in number of felts, of the calldata.
`calldata`	The calldata.

Return values

`retdata_size`	The size, in number of felts, of the return data.
`retdata`	The return data.

Common library

syscalls.cairo

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.

`deploy`

Syntax

Cairo 0
Cairo 1.0

func deploy{syscall_ptr : felt*}(
    class_hash : felt,
    contract_address_salt : felt,
    constructor_calldata_size : felt,
    constructor_calldata : felt*,
    deploy_from_zero: felt,
) -> (contract_address : felt)

extern fn deploy_syscall(
    class_hash: ClassHash,
    contract_address_salt: felt252,
    calldata: Span<felt252>,
    deploy_from_zero: bool,
) -> SyscallResult<(ContractAddress, Span::<felt252>)> implicits(GasBuiltin, System) nopanic;

Description

Deploys a new instance of a previously declared class.

Arguments

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

Return values

contract_address

The address of the deployed contract.

Common library

syscalls.cairo

`emit_event`

Syntax

Cairo 0
Cairo 1.0

func emit_event{syscall_ptr : felt*}(keys_len : felt, keys : felt*, data_len : felt, data : felt*)

extern fn emit_event_syscall(
    keys: Span<felt252>, data: Span<felt252>
) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;

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 Starknet events.

Arguments

`keys_len`	The number of keys in the event. Analogous to Ethereum’s event topics, you can use the starknet_getEvents method to filter by these keys.
`keys`	The event’s keys
`data_len`	The number of data elements in the event.
`data`	The event’s data

Return values

None.

Common library

syscalls.cairo

Example

The following example emits an event with two keys, the strings status and deposit and three data elements: 1, 2, and 3.

Cairo 0
Cairo 1

let (keys : felt*) = alloc()
assert keys[0] = 'status'
assert keys[1] = 'deposit'
let (data : felt*) = alloc()
assert data[0] = 1
assert data[1] = 2
assert data[2] = 3
emit_event(2, keys, 3, data)

let keys = ArrayTrait::new();
keys.append('key');
keys.append('deposit');
let values = ArrayTrait::new();
values.append(1);
values.append(2);
values.append(3);
emit_event_syscall(keys, values).unwrap_syscall();

`library_call`

Syntax

Cairo 0
Cairo 1.0

func library_call{syscall_ptr : felt*}(
    class_hash : felt, function_selector : felt, calldata_size : felt, calldata : felt*
) -> (retdata_size : felt, retdata : felt*)

extern fn library_call_syscall(
    class_hash: ClassHash, function_selector: felt252, calldata: Span<felt252>
) -> SyscallResult<Span<felt252>> implicits(GasBuiltin, System) nopanic;

Description

Calls the requested function in any previously declared class.

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

`class_hash`	The hash of the class you want to use.
`function_selector`	A selector for a function within that class.
`calldata_size`	The size, in number of felts, of the calldata.
`calldata`	The calldata.

Return values

`retdata_size`	The size, in number of felts, of the return data.
`retdata`	The return data.

Common library

syscalls.cairo

`library_call_l1_handler`

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

func library_call_l1_handler{syscall_ptr : felt*}(
    class_hash : felt, function_selector : felt, calldata_size : felt, calldata : felt*
) -> (retdata_size : felt, retdata : felt*)

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

It is recommended to raise this system call only inside an L1 handler.

Arguments

`class_hash`	The hash of the class you want to use.
`function_selector`	A selector for an L1 handler function within that class.
`calldata_size`	The size, in number of felts, of the calldata.
`calldata`	The calldata.

Return values

`retdata_size`	The size, in number of felts, of the return data.
`retdata`	The return data.

Common library

syscalls.cairo

`send_message_to_L1`

Syntax

Cairo 0
Cairo 1.0

func send_message_to_l1{syscall_ptr : felt*}(
    to_address : felt, payload_size : felt, payload : felt*
)

extern fn send_message_to_l1_syscall(
    to_address: felt252, payload: Span<felt252>
) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;

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.

For more information, see Starknet’s messaging mechanism.

Arguments

`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

None.

Common library

messages.cairo

Example

The following example sends a message whose content is (1,2) to the L1 contract whose address is 3423542542364363.

Cairo 0
Cairo 1

let payload = alloc()
payload[0] = 1
payload[1] = 2
send_message_to_l1(3423542542364363,2,payload)

let payload = ArrayTrait::new();
payload.append(1);
payload.append(2);
send_message_to_l1_syscall(payload).unwrap_syscall();

`replace_class`

Syntax

Cairo 0
Cairo 1.0

replace_class(class_hash: felt)

extern fn replace_class_syscall(
    class_hash: ClassHash
) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;

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 .

After calling replace_class, the code currently executing from the old class will finish running.

The new class will be used from the next transaction onwards or if the contract is called via the call_contract syscall in the same transaction (after the replacement).

Arguments

class_hash

The hash of the class you want to use as a replacement.

Return values

None

Common library

syscalls.cairo

`storage_read`

Syntax

Cairo 0
Cairo 1.0

func storage_read{syscall_ptr : felt*}(address : felt) -> (value : felt)

extern fn storage_read_syscall(
    address_domain: u32, address: StorageAddress,
) -> SyscallResult<felt252> implicits(GasBuiltin, System) nopanic;

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.

For information on accessing storage by using the storage variables, see storage variables.

Arguments

address

The address of the storage key you want to read.

Return values

value

The value of the key.

Common library

syscalls.cairo

Example

Cairo 0
Cairo 1.0

let value = storage_read(3534535754756246375475423547453)

use starknet::storage_access::storage_base_address_from_felt252;

...

let storage_address = storage_base_address_from_felt252(3534535754756246375475423547453)
storage_read_syscall(0, storage_address).unwrap_syscall()

`storage_write`

Sets the value of a key in the storage of the calling contract.

Syntax

Cairo 0
Cairo 1.0

func storage_write{syscall_ptr : felt*}(address : felt, value : felt)

extern fn storage_write_syscall(
    address_domain: u32, address: StorageAddress, value: felt252
) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;

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.

For information on accessing storage by using the storage variables, see storage variables.

Arguments

`address`	The address of the storage key to which you want to write.
.`value`	The value to write to the key.

Return values

None.

Common library

syscalls.cairo