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.

call_contract

Syntax
func call_contract{syscall_ptr : felt*}(
    contract_address : felt, function_selector : felt, calldata_size : felt, calldata : felt*
) -> (retdata_size : felt, retdata : felt*)
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.

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. For more information, see the Calling contracts in the Hello StarkNet tutorial.

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

deploy

Syntax
func deploy{syscall_ptr : felt*}(
    class_hash : felt,
    contract_address_salt : felt,
    constructor_calldata_size : felt,
    constructor_calldata : felt*,
) -> (contract_address : felt)
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.

Return values
contract_address

The address of the deployed contract.

Common library

syscalls.cairo

emit_event

Syntax
func emit_event{syscall_ptr : felt*}(keys_len : felt, keys : felt*, data_len : felt, data : felt*)
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.

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)

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

library_call

Syntax
func library_call{syscall_ptr : felt*}(
    class_hash : felt, function_selector : felt, calldata_size : felt, calldata : felt*
) -> (retdata_size : felt, retdata : felt*)
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

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
func send_message_to_l1{syscall_ptr : felt*}(
    to_address : felt, payload_size : felt, payload : felt*
)
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.

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

storage_read

Syntax
func storage_read{syscall_ptr : felt*}(address : felt) -> (value : felt)
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
let value = storage_read(3534535754756246375475423547453)

storage_write

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

Syntax
func storage_write{syscall_ptr : felt*}(address : felt, value : felt)
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