System calls

System calls are how requests to the Koinos Blockchain Framework are made. Each system call provides important functionality to be utilized from smart contracts or other parts of the framework.

Each system call has its base functionality implemented natively in a function known as a "thunk". What differentiates a system call from its thunk, is that the system call can have its functionality overridden by a special type of smart contract known as a "system contract".

System Call	Description
get_head_info	Retrieves the current head block information
apply_block	Applies a block to the blockchain
apply_transaction	Applies a transaction to the current block
apply_upload_contract_operation	Applies an upload contract operation to the current transaction
apply_call_contract_operation	Applies a call contract operation to the current transaction
apply_set_system_call_operation	Applies a set system call operation to the current transaction
apply_set_system_contract_operation	Applies a set system contract operation to the current transaction
pre_block_callback	Callback prior to block application
post_block_callback	Callback after block application
pre_transaction_callback	Callback prior to transaction application
post_transaction_callback	Callback after transaction application
get_chain_id	Retrieves the current chain ID
process_block_signature	Handles block signatures during block application
get_transaction	Retrieves the current transaction
get_transaction_field	Retrieves a field from the current transaction
get_block	Retrieves the current block
get_block_field	Retrieves a field from the current block
get_last_irreversible_block	Retrieves the last irreversible block height
get_account_nonce	Retrieves the last account nonce
verify_account_nonce	Verifies the account nonce
set_account_nonce	Sets an account nonce
check_system_authority	Verifies whether the system authorizes the action
get_operation	Retrieves the current operation
get_account_rc	Retrieves the current account resource credits
consume_account_rc	Consumes resource credits on an account
get_resource_limits	Retrieves the current resource limits
consume_block_resources	Consumes resource credits for the block
put_object	Inserts data into a key value store
remove_object	Deletes data in the key value store
get_object	Retrieves data from the key value store
get_next_object	Iterates forward through the key value store
get_prev_object	Iterates backwards through the key value store
log	Emits a log entry
event	Emits an event
hash	Performs a hashing algorithm on given data
recover_public_key	Recovers a public key
verify_merkle_root	Validates a merkle root given leaves
verify_signature	Validates a signature
verify_vrf_proof	Validate a verifiably random proof
call	Calls another smart contract
exit	Stops smart contract execution
get_arguments	Retrieves arguments passed to a smart contract
get_contract_id	Retrieves the current smart contract ID
get_caller	Retrieves the caller of the smart contract
check_authority	Validates authorization was given
get_contract_name	Retrieves the name of a smart contract given the address from the name service
get_contract_address	Retrieves the address of a smart contract given the name from the name service

Table 1. A comprehensive list of system calls.

Detailed information regarding the arguments and return values of system calls are defined as protocol buffer messages in the Koinos Proto repository.

Overriding system calls

While any system call can be overridden by a contract that simply calls the underlying thunk, the underlying functionality of some of them cannot be reproduced in the VM. Table 1 lists system calls which cannot be fully replaced by an override, and the reason it cannot be overridden.

Table 2. System calls which cannot be overridden

System Call	Reason
apply_block	Requires access to the execution context
apply_set_system_call_operation	Requires call to get_transaction
apply_set_system_contract_operation	Requires call to get_transaction
apply_transaction	Requires state access
call	Requires stack frame access
event	Requires event recorder access
exit	Would cause infinite recursion
get_caller	Requires stack frame access and caller access on execution environment
get_arguments	Requires access to contract call arguments on execution environment
get_contract_id	Requires access to contract id on execution environment
get_head_info	Requires state access
get_last_irreversible_block	Requires state access
get_next_object	Requires state access
get_object	Requires state access
get_prev_object	Requires state access
put_object	Requires state access