StarkNet CLI

You can interact with StarkNet via the CLI, which is part of the cairo-lang package. 

Comment (Network parameter): All the CLI commands must take either the network argument or the gateway arguments:

Either

  • --network: the requested L1, currently either alpha-goerli or alpha-mainnet

Or

 

Comment (pending block):  in every CLI command that takes block_number as an argument (contract_call/get_block/get_code/get_storage_at), we can query the StarkNet with respect to the pending block by specifying block_number=pending.

 


Setting up StarkNet CLI

Refer to this documentation to set up your StarkNet CLI environment. 

The CLI contains the following methods:

call Calls a StarkNet contract without affecting the state
invoke Same as call, but allowed to mutate the state
deploy Deploys a new StarkNet contract
get_block Returns the requested block.
get_code Returns the ABI and the byte code of the requested contract. 
get_contract_address Returns the L1 addresses of the GpsStatementVerifier and StarkNet contracts
get_storage_at Queries a contract’s storage at a specific key.
get_transaction Returns the requested transaction.
get_transaction_receipt Returns the receipt associated with the transaction
tx_status Returns the transaction’s status.

 


call

Run the following command to call a StarkNet contract without affecting its state:


starknet call 
  --address <contract_address>
  --abi <contract_abi>
  --function <function_name>
  --inputs <arguments>
  --block_hash <block_hash>
  --block_number <block_number>

 

Method Parameters (those denoted by * are mandatory.)

contract_address* address of the called contract
contract_abi* path to a JSON file containing the called contract’s abi
function_name* name of the function which is called
arguments* inputs to the called function, represented by a list of space-delimited values
block_hash the hash of the block used as the context for the call operation. If this argument is omitted, the latest block is used
block_number same as block_hash, but specifies the context block by number

 


invoke

The following command is the same as the above ‘call’ method, but is allowed to mutate the state:


starknet invoke 
  --address <contract_address>
  --abi <contract_abi>
  --function <function_name>
  --inputs <arguments>

 

Method Parameters (those denoted by * are mandatory.)

contract_address* address of the called contract
contract_abi* path to a JSON file containing the called contract’s abi
function_name* name of the function which is called
arguments* inputs to the called function, represented by a list of space-delimited values

 


deploy

This method deploys a new StarkNet contract:


starknet deploy
  --salt <salt>
  --contract <contract_definition>
  --inputs <constructor_inputs>
  --token <token>

 

Method Parameters (those denoted by * are mandatory.)

salt a seed that is used in the computation of the contract’s address
contract_definition* path to a JSON file containing the contract’s bytecode and abi (can be obtained by executing starknet-compile).
constructor_inputs the arguments given to the contract’s constructor, represented by a list of space-delimited values
token a token allowing contract deployment (can be obtained by applying here). Only used in the Alpha stages and will be deprecated in the future.  

 


get_block


starknet get_block 
--hash <block_hash>
--number <block_number>

 

Method Parameters (those denoted by a * are required.)

Note: At most, you should pass one block_hash and one block_number. If no parameters are passed to the method, the latest block is returned. 

 

block_hash hash of the requested block
block_number number of the requested block

 

Returns

The requested block and all contents. See block structure

An element of what is returned when you call get_block is the block’s status. This will be one of the following objects:

  • PENDING
    • Block is pending, i.e. block is yet to be closed.
  • ABORTED
    • Block failed in the L2 pipeline
  • REVERTED
    • Block rejected on L1
  • ACCEPTED_ON_L2
    • Block created on L2 (not PENDING)
  • ACCEPTED_ON_L1
    • Block accepted on L1

 


get_code


starknet get_block 
--hash <block_hash>
--number <block_number>

 

Method Parameters (those denoted by * are required.)

Note: Either block_hash or block_number should be specified. 

contact_address* address of the requested contract
block_hash the hash of the block used as the context for the operation. If this argument is omitted, the latest block is used
block_number same as block_hash, but specifies the context block by number.

 

Returns

The ABI and byte code for the requested contract. 

 


get_contract_addresses


starknet get_contract_addresses 

 

Returns

L1 addresses of GpsStatementVerifier and StarkNet contracts.

 


get_storage_at


starknet get_storage_at 
  --contract_address <contract_address>
  --key <key> 
  --block_hash <block_hash>
  --block_number <block_number>

 

Method Parameters (those denoted by * are required.)

Note: Either the block_hash or block_number parameter should be specified.

contract_address address of the requested contract
key* the requested key from the given contract’s storage
block_hash the hash of the block relative to which the storage will be provided. In case this argument is not given, the latest block is used
block_number same as block_hash, but specifies the context block by number

 

Returns

A contract’s storage at a specific key.

 


get_transaction


starknet get_transaction --hash <transaction_hash>


Method Parameters
(those denoted by * are required)

transaction_hash* hash of the requested transaction

 

Returns

This method returns the requested transaction; see transaction structure.

 


get_transaction_receipt


starknet get_transaction_receipt --hash 

 

Method Parameters (those denoted by * are required)

transaction_hash* hash of the requested transaction

 

Returns

Receipt associated with the given transaction_hash parameter value.

 


tx_status


starknet tx_status 
  --hash <transaction_hash> 
  --contract <contract_definition> 
  --error_message

 

Method Parameters (those denoted by * are required)

transaction_hash* hash of the requested transaction
contract_definition path to a JSON file containing the compiled contract to which the transaction was addressed. If supplied, the debug information from the compiled contract will be used to add error locations.
error_message if specified, only the error message will be returned (or empty response in case the transaction was successful)

 

Returns

One of the following status objects indicating the status of the translation:

  1. NOT_RECEIVED
  2. RECEIVED
  3. PENDING
  4. REJECTED
  5. ACCEPTED_ON_L2
  6. ACCEPTED_ON_L1

<< StarkNet State | On-Chain Data >>