The page you’re looking for does not exist. It may have been moved. You can return to the start page, or follow one of the links in the navigation to the left.
+If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken. +If you typed the URL of this page manually, please double check that you entered the address correctly.
+The functions in the table Starknet account interface functions are part of account contracts. Where required, you must include these functions within your account contract. The logic of these functions can be mostly arbitrary, with a few limitations. For information on these limitations, see Limitations on validation.
+| Function name | +When required | +||
|---|---|---|---|
|
+
+ Always required + |
+||
|
+
+
+Always required. The signatures of
+
|
+||
|
+
+ Required for the account to be able to send a |
+||
|
+
+
+Required to allow deploying an instance of the account contract with a
+
|
+||
|
+
+ All contracts have a |
+
When the sequencer receives a transaction, it calls the corresponding validation function with the appropriate input from the transaction’s data, as follows:
+For an INVOKE transaction, the sequencer calls the __validate__ function with the transaction’s calldata as input. The transaction’s calldata will be deserialized to the arguments in the __validate__ function’s signature, it is up to the sender to make sure that the calldata is encoded appropriately according to validate’s signature. After successfully completing validation, the sequencer calls the __execute__ function with the same arguments.
For a DEPLOY_ACCOUNT transaction, the sequencer calls the constructor function with the transaction’s constructor_calldata as input (as above, it is expected that the constructor’s calldata successfully desieralizes to the arguments in the constructor signature). After the successful execution of the constructor, the sequencer validates the transaction by calling the __validate_deploy__ function.
For a DECLARE transaction, the sequencer validates the transaction by calling the __validate_declare__ function.
For more information on the available transaction types and their fields, see Transaction types.
+For more information on the validation and execution stages, see Transaction lifecycle.
+Separating the validation and execution stages guarantees payment to sequencers for work completed and protects them from Denial of Service (DoS) attacks.
+The validation functions have limitations, described below, that are designed to prevent the following DoS attacks on the sequencer:
+An attacker could cause the sequencer to perform a large amount of work before a transaction fails validation. Two examples of such attacks are:
+Spamming INVOKE transactions whose __validate__ requires many steps, but eventually fails
Spamming DEPLOY_ACCOUNT transactions that are invalid as a result of the constructor or __validate_deploy__ failing.
The above attacks are solved by making sure that the validation step is not resource-intensive, e.g. by keeping the maximal number of steps low. However, even if the validation is simple, the following "mempool pollution" attack could still be possible:
+An attacker fills the mempool with transactions that are valid at the time they are sent.
+The sequencer is ready to execute them, thinking that by the time it includes them in a block, they will still be valid.
+Shortly after the transactions are sent, the attacker sends one transaction that somehow invalidates all the previous ones and makes sure it’s included in a block, e.g. by offering higher fees for this one transaction.
+An example of such an attack is having the implementation of __validate__ checks that the value of a storage slot is 1, and the attacker’s transaction later sets it to 0. Restricting validation functions from calling external contracts prevents this attack.
The limitations listed here apply to the following validation functions:
+__validate__, __validate_deploy__, and __validate_declare__.
A constructor, when run in a DEPLOY_ACCOUNT transaction. That is, if an account is deployed from an existing class via the deploy syscall, these limitations do not apply.
The validation functions have the following limitations:
+You cannot call functions in external contracts, only in your account contract.
+| + + | +
+
+
+This restriction enforces a single storage update being able to invalidate only transactions from a single account. However, be aware that an account can always invalidate its own past transactions by e.g. changing its public key. +
+
+This limitation implies that the fees you need to pay to invalidate transactions in the mempool are directly proportional to the number of unique accounts whose transactions you want to invalidate. + |
+
The maximum number of computational steps, measured in Cairo steps, for a validation function is 1,000,000.
+A builtin can be applied a limited number of times. For specific limits for each builtin, see Current limits.
+The get_execution_info syscall behaves differently When raised from one of the validate functions:
sequencer_address is set to zero
block_timestamp returns the time (in UTC), rounded to the most recent hour.
block_number returns the block number, rounded down to the nearest multiple of 100.
The following syscalls cannot be called:
+get_block_hash
get_sequencer_address (this syscall is only supported for Cairo 0 contracts).
When the __validate__, __validate_deploy__, or __validate_declare__, function fails, the account in question does not pay any fee, and the transaction’s status is REJECTED.
A transaction has the status REVERTED when the __execute__ function fails. A reverted transaction is included in a block, and the sequencer is eligible to charge a fee for the work done up to the point of failure, similar to Ethereum.
Thanks to account abstraction, the logic of __execute__ and the different validation functions is up to the party implementing the account.
+To see a concrete implementation, see OpenZeppelin’s account component.
+This implementation adheres to SNIP6, which defines a standard for account interfaces.
Starknet’s account structure is inspired by Ethereum’s EIP-4337, where instead of EOAs, you use smart contract accounts with arbitrary verification logic.
+While not mandatory at the protocol level, you can use a richer standard interface for accounts, defined in Starknet Improvement Proposal #6 (SNIP-6). SNIP-6 was developed by community members at OpenZeppelin, in close collaboration with wallet teams and other Core Starknet developers.
+A valid account contract includes specific functions, depending on the type of the contract. For more information, see Account interface function reference.
+In Starknet, similar to Ethereum, every contract has a nonce, including an account contract. This nonce is sequential. The nonce of a transaction sent from an account must match the nonce of that account. After the transaction is executed, whether or not it is reverted, the nonce is incremented by one.
+| + + | +
+
+
+In Starknet, only the nonce of account contracts, that is, those adhering to the above structure, can be non-zero. +
+
+In contrast, in Ethereum, regular smart contracts, known as Contract Accounts, as opposed to Externally Owned Accounts can increment their nonce by deploying smart contracts, that is, executing the
+
+For more information on accounts in Ethereum, see Ethereum Accounts in the Ethereum documentation. + |
+
A nonce serves two important roles:
+It guarantees transaction hash uniqueness, which is important for a good user experience.
+It provides replay protection to the account: Because the signature is bound to a particular nonce, a malicious party cannot replay the transaction.
+Starknet currently determines the nonce structure at the protocol level to be sequential. In the future, Starknet will consider a more flexible design, extending account abstraction to nonce management, previously referred to as nonce abstraction.
+You can deploy a new account in the following ways:
+Send a DEPLOY_ACCOUNT transaction. This method does not require a preexisting account.
Using the Universal Deployer Contract (UDC). This method requires an existing account to send the INVOKE transaction.
Upon receiving one of these transactions, the sequencer performs the following steps:
+Runs the respective validation function in the contract, as follows:
+When deploying with the DEPLOY_ACCOUNT transaction type, the sequencer executes the __validate_deploy__ function in the deployed contract.
When deploying using the UDC, the sequencer executes the __validate__ function in the contract of the sender’s address.
Executes the constructor with the given arguments.
+Charges fees from the new account address.
+| + + | +
+
+
+If you use a |
+
Sets the account’s nonce as follows:
+1, when deployed with a DEPLOY_ACCOUNT transaction
0, when deployed with the UDC
Starkli simplifies account creation, whether you create an account as a Starknet wallet account, or using the UDC.
+To create and deploy a new account, use Starkli’s starkli account command.
For more information on creating a new account as a Starknet wallet account with a DEPLOY_ACCOUNT transaction, or by using the UDC with an INVOKE transaction , see Accounts in the Starkli Book.
DEPLOY_ACCOUNT constructor restrictionsThe constructor of the DEPLOY_ACCOUNT transaction has the following limitations:
Restricted access to sequencer_address in the get_execution_info syscall. The syscall returns zero values for sequencer_address
Restricted access to the following syscalls:
+get_block_hash for Cairo contracts
get_sequencer_address for Cairo 0 contracts
Accounts in the Starkli Book
+An account represents a user onchain, and enables that user to interact with the blockchain.
+Through an account, you can send transactions and interact with other contracts. In order for you to own an onchain asset, such as an ERC-20 token or an NFT, that asset must be associated with your account address.
+Within Ethereum individual user accounts are known as Externally Owned Accounts (EOAs).
+EOAs differ from smart contracts in that EOAs are not controlled by code, but rather by a pair of private and public keys.
+The account’s address is derived from those keys and only by possessing the private key can you initiate transactions from an account. While Ethereum contracts are passive, that is, they can only change if they were called inside a transaction, EOAs can initiate transactions.
+While simple, because the signature scheme is fixed, EOAs have some drawbacks, including the following:
+Control over the private key gives complete control over +the account, so you must keep your seed phrase secure yet accessible.
+Limited flexibility surrounding wallet functionality
+EIP-4337 is a design proposal for Ethereum that outlines account abstraction, whereby all accounts are managed via a dedicated smart contract on the Ethereum network, as a way to increase flexibility and usability. You can add custom logic on top of the basic EOA functionality, thereby bringing account abstraction into Ethereum.
+Account abstraction enables more flexible account management. Rather than the protocol determining an account’s behavior, an account contract, which is a smart contract with programmable logic, defines a user’s account.
+Using account abstraction you can now program how your account functions.
+For example, you can:
+Determine what it means for a signature to be valid, or what contracts your account is allowed to interact with. This is known as signature abstraction.
+Pay transaction fees in different tokens. This is known as fee abstraction.
+Design your own replay protection mechanism and allow sending multiple uncoupled transactions in parallel.
+In Ethereum, you cannot send two transactions in parallel, you must wait for confirmation of the first before sending the second. Otherwise, the second transaction can be rejected due to an invalid nonce. With account abstraction, a sequential nonce is not required. This is known as nonce abstraction.
+Today, Starknet offers signature abstraction. In the future, we will enrich the current account abstraction design. For example, see the paymaster proposal for fee abstraction in the Starknet Community Forum.
+Two examples of how you might program an account to function using account abstraction are:
+| +Social recovery + | +
+ A process where if you lose your wallet, you are able to retrieve it via a selected social network, vastly improving the typical experience of wallet recovery. + |
+
| +Operating your account via facial recognition + | +
+ With signature abstraction, you can use your phone’s native hardware to sign transactions, making it practically impossible to take control of another user’s account, even if your phone is stolen. + |
+
The key stages of transaction lifetime are:
+The sequencer selects a transaction from the mempool and calls the __validate__ function.
If the transaction is valid, the sequencer calls the __execute__ function.
If __execute__ runs successfully, the sequencer includes the transaction in the block, charges the fee, and proceeds to work on the next transaction.
After completing the block, the sequencer sends the block to the prover.
+The sequencer receives fees in ETH in return for including transactions in a block.
+For more details on how the transaction fee is computed, see Gas and transaction fees.
+The Universal Deployer Contract (UDC) is a singleton smart contract that wraps the deploy syscall to expose it to any contract that doesn’t implement it, such as account contracts. You can think of it as a standardized generic factory for Starknet contracts.
+And since Starknet has no deployment transaction type, it offers a standardized way to deploy smart contracts by following the standard deployer interface and emitting a ContractDeployed event.
For more information see the proposal for the standard deployer interface. +For details on the motivation and the decision making process, see the Universal Deployer Contract proposal.
+The UDC address is 0x041a78e741e5af2fec34b695679bc6891742439f7afb8484ecd7766661ad02bf in Mainnet, Sepolia testnet, and starknet-devnet. This address might change in the future when it is migrated to a modern version of Cairo.
trait IUniversalDeployer {
+ fn deployContract(
+ class_hash: ClassHash,
+ salt: felt252,
+ unique: bool,
+ calldata: Span<felt252>
+ ) -> ContractAddress;
+}Declare the contract with a DECLARE transaction, or ensure that the contract has been declared.
For more information, see the DECLARE transaction.
Call the deployContract function in the UDC.
#[starknet::interface]
+trait IUniversalDeployer<TContractState> {
+ fn deployContract(
+ ref self: TContractState,
+ class_hash: ClassHash,
+ salt: felt252,
+ unique: bool,
+ calldata: Span<felt252>
+ ) -> ContractAddress; }
+
+const UDC_ADDRESS: felt252 = 0x041a78e741e5af2fec34b695679bc6891742439f7afb8484ecd7766661ad02bf;
+
+fn deploy() -> ContractAddress {
+ let dispatcher = IUniversalDeployerDispatcher {
+ contract_address: UDC_ADDRESS.try_into().unwrap()
+ };
+
+ // deployment parameters
+ let class_hash = class_hash_const::<
+ 0x5c478ee27f2112411f86f207605b2e2c58cdb647bac0df27f660ef2252359c6
+ >();
+ let salt = 1234567879;
+ let unique = false;
+ let mut calldata = array![];
+
+ // the UDC returns the deployed contract address
+ dispatcher.deployContract(class_hash, salt, unique, calldata.span())
+}The Universal Deployer Contract offers two types of addresses to deploy: origin-dependent and origin-independent.
+As the names suggest, the origin-dependent type includes the deployer’s address in the address calculation,
+whereas, the origin-independent type does not.
+The unique boolean parameter ultimately determines the type of deployment.
| + + | +
+
+
+When deploying a contract that uses |
+
By making deployments dependent upon the origin address, users can reserve a whole address space to prevent someone else from taking ownership of the address.
+Only the owner of the origin address can deploy to those addresses.
+Achieving this type of deployment necessitates that the origin sets unique to true in the deployContract call.
+Under the hood, the function call leverages the origin’s address and creates a hashchain by hashing the origin’s address with the given salt.
To deploy a unique contract address pass:
+let deployed_addr = udc.deployContract(class_hash, salt, true, calldata.span());Origin-independent contract deployments create contract addresses independent of the deployer and the UDC instance.
+Instead, only the class hash, salt, and constructor arguments determine the address.
+This type of deployment enables redeployments of accounts and known systems across multiple networks.
+To deploy a reproducible deployment, set unique to false.
let deployed_addr = udc.deployContract(class_hash, salt, false, calldata.span());| + + | +
+
+
+The UDC has already been deployed on most networks and development environments.
+The standard requires the UDC to be deployed passing |
+
deployContract methodDeploy a contract through the Universal Deployer Contract.
+fn deployContract(
+ classHash: ClassHash,
+ salt: felt252,
+ unique: bool,
+ calldata: Span<felt252>
+) -> ContractAddressContractDeployed eventEmitted when deployer deploys a contract through the Universal Deployer Contract.
#[derive(Drop, starknet::Event)]
+struct ContractDeployed {
+ address: ContractAddress,
+ deployer: ContractAddress,
+ unique: bool,
+ classHash: ClassHash,
+ calldata: Span<felt252>,
+ salt: felt252,
+}All hashes outputs are eventually mapped to elements in \(\mathbb{F}_P\), where \(P=2^{251}+17\cdot 2^{192}+1\).
+There are three hash functions used throughout Starknet’s specifications:
+\(\text{sn_keccak}: \{0,1\}^* \rightarrow \mathbb{F}_P\)
+\(\text{pedersen}: \mathbb{F}_P^2\rightarrow\mathbb{F}_P\)
+\(\text{poseidon}: \mathbb{F}_P^*\rightarrow \mathbb{F}_P\)
+Starknet Keccak, usually denoted by \(\text{sn_keccak}\), is defined as the first 250 bits of the Keccak256 hash. For Starknet Keccak, Keccak256 is augmented +in order to fit into a field element.
+Pedersen hash makes use of the following STARK friendly elliptic curve over \(\mathbb{F}_P\):
+where
+\(\alpha=1\)
+\(\beta = 3141592653589793238462643383279502884197169399375105820974944592307816406665\)
+Given an input \((a,b)\in\mathbb{F}_P^2\), we begin by breaking it into \(a_{low}, a_{high}, b_{low}, b_{high}\), +where the low part consists of the low 248 bits of the element and the high part consists of the high 4 bits of the element. Our Pedersen hash is then defined by:
+where the values of the constants \(shift\_point, P_0, P_1, P_2, P_3\) can be found in fast_pedersen_hash.py, and \([P]_x\) denotes the \(x\) coordinate of the point \(P\).
+For more information, see STARK curve.
+Poseidon is a family of hash functions designed to be very efficient as algebraic circuits. As such, they can be very useful in ZK-proving systems such as STARKs.
+Poseidon is a sponge construction based on the Hades permutation. Starknet’s version of Poseidon is based on a three-element state permutation.
+A Poseidon hash of up to 2 elements is defined as follows.
+Where \([\cdot]_j\) denotes taking the \(j\)'th coordinate of a tuple.
+Let \(h\) denote the pedersen hash function, then given an array \(a_1,...,a_n\) of \(n\) field elements +we define \(h(a_1,...,a_n)\) to be:
+Let \(\text{hades}:\mathbb{F}_P^3\rightarrow\mathbb{F}_P^3\) denote the Hades permutation, with Starknet’s parameters, then given an array \(a_1,...,a_n\) of \(n\) field elements +we define \(\text{poseidon}(a_1,...,a_n)\) to be the first coordinate of \(H(a_1,...,a_n;0,0,0)\), where:
+For an implementation of the above in Python, see poseidon_hash.py, +and for an equivalent Cairo implementation, see poseidon.cairo in the cairo-lang GitHub repository.
+The STARK field is the finite field \(\mathbb{F}_P\), where \(P\) is a prime number, calculated as follows:
+The Cairo VM uses the STARK field, referred to as a field element, or felt. The felt252 type in Cairo refers to elements of this field.
The STARK curve is an elliptic curve defined as follows:
+where:
+The Generator point used in the ECDSA scheme is:
+The STARK curve is commonly used in smart contracts but not distinguished by the Starknet protocol.
+Starknet is a developing decentralized protocol and the economic mechanisms described here, also known as tokenomics, are subject to change based on governance decisions made by the larger community of Starknet. For more details on Starknet’s governance processes see the Starknet Governance Hub. This document describes certain economic fundamentals of the Starknet token. This document is intended for informational purposes only and is meant to outline the usage and functionalities of the asset within Starknet. It is important to understand that the primary purpose of the Starknet token, STRK, is to facilitate operations and activities on Starknet and it is not intended to serve as an investment.
+Blockchains work through a combination of cryptography and economic incentives. Cryptography limits what actors in the system can do, for example, transactions must be validly signed to be included in the chain. Economic incentives encourage actors to voluntarily perform actions that maintain the network’s capabilities when spending their own resources, for example, miners or stakers actively publish new blocks to the chain because they can receive fees and new tokens as a reward. Blockchains are valuable because they are data structures maintained by diverse and, ideally, large groups of otherwise unaffiliated persons. This gives them resilience: Any one participant can disappear, but the data structure is preserved. This also gives them censorship resistance: No single person can unilaterally decide to forbid certain persons from using the network.
+Starknet operates as a Layer 2 (L2) network on top of Ethereum. Today, Starknet achieves secure low-cost transactions by using the STARK cryptographic proof system to reduce the size of transaction data while preserving and verifying the integrity of that data. Still under development, Starknet will achieve resilience and censorship resistance by using a token, the Starknet token (STRK), to incentivize network participants to sequence transactions for users of the network and to ensure that there is a provably fair mechanism, a proof-of-stake mechanism, to determine who should sequence and submit a proof for the network blocks. A proof-of-stake mechanism might also be used to facilitate data availability solutions and other significant services required for network operations.
+STRK is the mechanism for paying fees to enable operation of the network, maintaining and securing the network by enabling staking for consensus, and deciding on Starknet’s values and technology goals by voting for governance proposals.
+Transaction fees: Originally, fees in Starknet were paid only in Ether (ETH). As of v.0.13.0, fees for transactions on the network can be paid using STRK, as well as ETH.
+A portion of the fees paid in STRK are converted to ETH by the receiving sequencer, in order to cover Ethereum L1 gas costs, which, due to the specifications of the Ethereum protocol, must be paid in ETH.
+Staking: Certain services that are critical to the liveness and security of Starknet may require the staking of Starknet tokens. These services might be offered by multiple providers, and could include sequencing, reaching temporary L2 consensus before L1 finality is reached, STARK-proving services, and data availability provisioning, to name a few examples. These protocol changes are still under discussion within the larger governance community and are targeted for 2024 -2025.
+Governance: Proposals for improving Starknet might require a minimal token support threshold. Voting, either directly or via delegation, will be required for changes to the protocol that are essential to Starknet’s liveness, security, and maintenance. Today, for example, major updates to the Starknet Operating System require the approval of token holders. +For more information about Governance see the Starknet Governance Hub
+| + + | +
+
+
+As discussed above, the Starknet tokens are digital assets intended to support the operation and usage of Starknet and are not offered as an investment. As such, the Starknet tokens do not represent any equity in StarkWare or the Starknet Foundation, nor do they provide any participation right in StarkWare or grant any right of claim from StarkWare or the Starknet Foundation. + |
+
Ten billion Starknet tokens were initially created by StarkWare in May 2022 and minted onchain on November 30, 2022.
+The existing ten billion tokens have been or are planned to be distributed according to the following:
+20.04%: Early Contributors |
+Tokens allocated for StarkWare’s team members and early contributors. These tokens are subject to a lock-up schedule, as further detailed below. |
+
18.17%: Investors |
+Tokens allocated for StarkWare’s investors. These tokens are subject to a lock-up schedule, as further detailed below. |
+
10.76%: StarkWare |
+Tokens allocated for StarkWare for operation services such as to pay fees, provide other services on Starknet, and engage other service providers. |
+
12.93%: Grants including Development Partners (aka DPs) |
+Tokens allocated for grants for research or work done to develop, test, deploy and maintain the Starknet protocol. The process for applications and allocations related to Starknet Foundation Grants will be outlined in a post at a later date. |
+
9.00%: Community Provisions |
+Tokens distributed to those who contributed to Starknet and powered or developed its underlying technology. |
+
9.00%: Community Rebates |
+Tokens allocated for rebates in Starknet tokens to partially cover the costs of onboarding to Starknet from Ethereum. Community rebates are not yet available and will be announced in 2024 in a subsequent post. |
+
10.00%: Foundation Strategic Reserves |
+Tokens allocated for the Starknet Foundation to fund ecosystem activities that are aligned with the Foundation’s mission. |
+
8.10%: Foundation Treasury |
+Token allocated for the Starknet Foundation’s treasury available for operations and other future initiatives by the Starknet Foundation. |
+
2.00%: Donations |
+Tokens reserved for donations to institutions and organizations, such as universities, NGOs, etc, as decided by the Starknet Foundation. |
+
To align long-term incentives of the Investors and Early Contributors with the interests of the Starknet community, and following common practice in decentralized ecosystems, all tokens allocated to Investors and Early Contributors is subject to the following lock-up schedule, where percentages are based on the total token supply:
+Up to 0.64% (64 million tokens) will be unlocked on the 15th of each month, starting April 15, 2024, and going through March 15, 2025, for a total of 7.68% (768 million tokens) unlocked by March 15, 2025.
Up to 1.27% (127 million tokens) will be unlocked on the 15th of each month, starting April 15, 2025, and going through March 15, 2027, for a total of 30.48% (3.048 billion tokens) unlocked by March 15, 2027.
+
+The graph, Estimated supply of STRK in circulation, excludes newly circulating tokens resulting from inflation or staking (see below).
+Token allotments currently retained by the Starknet Foundation, while contractually unlocked, are not considered circulating unless granted, donated, or otherwise allocated out of originating wallets through future grants, provisions, donations, developer initiatives, or other programs.
+Through this lock-up period, token holders cannot transfer, sell, or pledge their STRK tokens. Delegation of voting is permitted with locked tokens and, when available, staking might also be permitted.
+The total circulating supply of tokens is planned to increase over time with the minting of new tokens by the protocol, as staking rewards, block rewards, or other rewards associated with the staking process. Such minting will be made pursuant to a schedule that will be determined with the community at a later point, not before Starknet services are more decentralized. The supply in circulation might not, therefore, remain fixed. However, as long as StarkWare is the sole operator of the Starknet sequencer, there will be no issuance of new tokens for the purpose of block rewards. For more information, see A token-minting proposal to manage inflation.
+Starknet is a developing decentralized protocol and the economic mechanisms described herein are subject to change based on decisions made by the larger community of Starknet builders and users. Starknet relies upon third parties to adopt and implement software and protocols as users and contributors of Starknet. It also relies, in whole or partly, on third parties to develop, supply and otherwise support it. There is no assurance or guarantee that such third parties will continue to participate in the network or that the network will continue to function as intended.
+The technical documents provided herein describe certain planned and specified economic fundamentals of a digital asset, STRK. These materials are intended for informational purposes only and are meant to outline the usage and functionalities of the asset within Starknet. It is important to understand that the primary purpose of STRK is to pay for fees, provide a mechanism for securing consensus, and allow for decentralized governance on Starknet; it is not intended to serve as an investment.
+Starknet relies upon third parties to adopt and implement the software and protocols as users of Starknet. It also relies, in whole or partly, on third parties to develop, supply and otherwise support it. As a Layer 2 network over Ethereum, Starknet also relies upon third parties maintaining and operating the Ethereum network. There is no assurance or guarantee that those third parties will complete their work, properly carry out their obligations, and/or otherwise meet anyone’s needs.
+STRK, as the native token of Starknet, may be subject to the risks of the Starknet network, including, without limitation, the following: (i) the technology associated with Starknet may not function as intended; (ii) the details of the Starknet token economics including the total supply and distribution schedule may be changed due to decisions made by the consensus of participants of the Starknet network; (iii) Starknet may fail to attract sufficient interest from key stakeholders or users; (iv) Starknet may not progress satisfactorily and Starknet tokens may not be useful or valuable; (v) Starknet may suffer from attacks by hackers or other individuals; and (vi) Starknet is comprised of open-source technologies that depend on a network of computers to run certain software programs to process transactions, and because of this model StarkWare and the Starknet Foundation have limited control over Starknet.
+Risks related to blockchain technology in general and Starknet in particular may impact the usefulness of Starknet, and, in turn, the utility or value of STRK. The software and hardware, technology and technical concepts and theories applicable to Starknet and STRK are still in an early development stage and unproven, there is no warranty that Starknet will achieve any specific level of functionality or success, nor that the underlying technology will be uninterrupted or error-free, and there is an inherent risk that the technology could contain weaknesses, vulnerabilities or bugs causing, potentially, the complete loss of any Starknet tokens held by Starknet users.
+As with most commonly used public blockchains, STRK is accessed using a private key that corresponds to the address at which they are stored. If the private key, or the "seed" used to create the address and corresponding private key are lost or stolen, the tokens associated with that address might be unrecoverable and will be permanently lost.
+Public blockchain-based systems, including Starknet and the underlying Ethereum network, depend on independent verifiers, and therefore may be vulnerable to consensus attacks including, but not limited to, double-spend attacks, majority voting power attacks, race condition attacks, and censorship attacks. These attacks, if successful, could result in the permanent loss of STRK.
+Starknet, STRK, and blockchain technology are nascent, and there may be additional risks not described above or that may be new or unanticipated. We recommend only using Starknet or holding STRK if you are familiar with the technology and aware of the risks.
+This document and its contents are not, and should not be construed as, an offer to sell, or the solicitation of an offer to buy, any tokens, nor should it or any part of it form the basis or be relied on in connection with any contract or commitment whatsoever. This document is not advice of any kind, including legal, investment, financial, tax, or any other professional advice. Nothing in this document should be read or interpreted as a guarantee or promise of how the Starknet network or its STRK will develop, be utilized, or accrue value.
+All information in this document is provided on an “as is” basis without any representation or warranty of any kind. This document only outlines current plans, which could change at the discretion of various parties, and the success of which will depend on many factors outside of Starknet Foundation’s control. Such future statements necessarily involve known and unknown risks, which may cause actual performance and results in future periods to differ materially from what we have described or implied in this document. StarkWare and the Starknet Foundation disclaim all warranties, express or implied, to the fullest extent permitted by law with respect to the functionality of Starknet and STRK.
+A Starknet block is a list of transactions and a block header that contains the following fields:
+| Name | +Type | +Description | +
|---|---|---|
|
+
|
+The number, that is, the height, of this block. |
+
|
+
|
+The hash of the block’s parent. |
+
|
+
|
+The state commitment after the block. |
+
|
+
|
+The Starknet address of the sequencer that created the block. |
+
|
+
|
+The time at which the sequencer began building the block, in seconds since the Unix epoch. |
+
|
+
|
+The number of transactions in the block. |
+
|
+
|
+The number of events in the block. |
+
|
+
|
+The sum of number of storage diffs, nonce updates, deployed contracts and declared classes. |
+
|
+
|
+The poseidon hash of the state diff of the block, see below for more details. |
+
|
+
|
+A commitment to the transactions included in the block. +The root of a height-64 binary Merkle Patricia trie. The leaf at index \(i\) corresponds to \({h(\text{transaction_hash}, \text{signature})}\). |
+
|
+
|
+The root of a height-64 binary Merkle Patricia trie. +The leaf at index \(i\) corresponds to the hash of the \(i'th\) event emitted in the block. +See below for a description on how event hashes are computed. |
+
|
+
|
+The root of a height-64 Merkle-Patricia trie. +The leaf at index \(i\) corresponds to the hash of the \(i'th\) transaction receipt. +See below for a description on how receipt hashes are computed. |
+
|
+
|
+The price of L1 gas that was used while constructing the block. L1 gas prices apply to storage updates and L1→L2 messages. As of March 2023, computation is also priced in terms of L1 gas, but this will change in the future.
+The first |
+
|
+
|
+The price of L1 blob gas that was used while constructing the block. If the |
+
|
+
|
+
|
+
|
+
|
+The version of the Starknet protocol used when creating the block. |
+
A block hash is defined as the Poseidon hash of the header’s fields, as follows:
+h(𝐵) = h( + "STARKNET_BLOCK_HASH0", + block_number, + global_state_root, + sequencer_address, + block_timestamp, + transaction_count || event_count || state_diff_length || l1_da_mode, + state_diff_commitment, + transactions_commitment + events_commitment, + l1_gas_price_in_wei, + l1_gas_price_in_fri, + l1_data_gas_price_in_wei, + l1_data_gas_price_in_fri + receipts_commitment + 0, + parent_block_hash +)+
Where:
+h is the Poseidon hash.
|| denotes concatenation, transaction_count, event_count and state_diff_length are given 64 bits each, and l1_da_mode is one bit where 0 denotes CALLDATA and 1 denotes BLOB.
For a reference implementation, see the sequencer repository.
+The state diff commitment is obtained by the chain-hash of the following:
+updates to contract addresses \(c_1,...,c_n\), with diffs \((k^1_1, v^1_1),...,(k^1_{m_1}, v^1_{m_1}),...,(k^n_1, v^n_1),...,(k^n_{m_n},v^n_{m_n})\)
+deployed contracts \((\text{deployed_address}_1, \text{deployed_class_hash}_1),...,(\text{deployed_address}_\ell,\text{deployed_class_hash}_\ell)\)
+declared classes \((\text{declared_class_hash}_1, \text{declared_compiled_class_hash}_1), ..., (\text{declared_class_hash}_d, \text{declared_compiled_class_hash}_d)\)
+replaced classes \((\text{replaced_contract_address}_1, \text{new_class_hash}_1),...,(\text{replaced_contract_address}_r, \text{new_class_hash}_r)\)
+updated nonces \((\text{account}_1, \text{new_nonce}_1),...,(\text{account}_k, \text{new_nonce}_k)\)
+More formally, the state-diff hash is given by:
+Where:
+\(h\) is the Poseidon hash function
+\(1, 0\) in the hash computation are placeholders that may be used in the future
+A transaction receipt consists of the following fields:
+| Name | +Type | +Description | +
|---|---|---|
|
+
|
+the hash of the transaction |
+
|
+
|
+the fee paid on-chain |
+
|
+
|
+ordered list of the events emitted by the transaction |
+
|
+
|
+ordered list of the l2→l1 messages sent by the transaction |
+
|
+
|
+The revert reason, in case the transaction was reverted |
+
|
+
|
+The amount of l1 gas that was consumed |
+
|
+
|
+The amount of l1 data (blob) gas that was consumed |
+
|
+
|
+The amount of l2 gas that was consumed |
+
The hash of the transaction receipt is given by:
+h(receipt) = h( + transaction_hash, + actual_fee, + h(messages), + sn_keccak(revert_reason), + h(l2_gas_consumed, l1_gas_consumed, l1_data_gas_consumed) +)+
Where:
+h is the Poseidon hash function
+given messages \(m_1=(\text{from}_1, \text{to}_1, \text{payload}_1)...m_n=(\text{from}_n, \text{to}_n, \text{payload}_n)\), their hash is given by:
+where each message’s payload is length-prefixed.
+events are omitted from the receipt’s hash since they are committed separately in the block.
+The hash of an event \((\text{keys}, \text{data})\) emitted by a contract whose address is emitter_address and a transaction whose hash is tx_hash is given by:
Where \(h\) is the Poseidon hash function.
+| + + | +
+
+
+Zeros inside the hash computation of an object are used as placeholders, to be replaced in the future by meaningful fields. + |
+
Starknet is a Validity Rollup, which means that after consolidating and proving a set of Layer 2 changes, it updates, on L1, the latest proven L2 state. Alongside the proof, it publishes the state diff on L1. The state diff is the difference between the previous and new states.
+Anyone monitoring Ethereum can use this data to reconstruct the current state of Starknet.
+| + + | +
+
+
+To update the Starknet state on L1, you only need to send a valid proof along with the state difference, and there is no need to include additional details, such as transactions and events. +
+
+Therefore, depending on the use case, you might need more information to track Starknet’s state. + |
+
Starting with Starknet version 0.13.1, the sequencer determines whether to publish the state difference on Ethereum as calldata or blobdata. In extreme situations where blob prices significantly exceed those of calldata, the Starknet sequencer can switch to publish the state diff as calldata. +Under normal conditions, blobs are the default method for publishing Starknet’s state differences.
+The format for state diffs remains the same as in version 0.11.0, but the data sent to Ethereum is a Fast Fourier Transform (FFT) of the original data. To recover Starknet’s state diff based on blobs published onchain, you must first perform an Inverse Fast Fourier Transform (IFFT) on the raw blob, and then proceed with decoding according to the format described below.
+Data availability with EIP-4844 on the Starknet Community Forum
+An example blob published on Ethereum by the Starknet sequencer in a state update transaction
+The state diffs contain information on every contract whose storage was updated and additional information on contract deployments.
+For each affected contract, the following information is sent as calldata on L1:
+The contract address
+A single 32-byte word that includes the nonce and the following meta information about the update:
+class information flag, whose value is one of the following:
+
+0
+ |
+
+ Storage updates only. + |
+
+1
+ |
+
+ The contract was deployed or replaced in this state update. +
+
+When this flag is set to 1, the new class hash occupies an additional word before the storage updates section. + |
+
number of storage updates
+The expected format of this 32-byte word is as follows:
+Each storage update includes the following:
+key - the address inside the contract’s storage where the value is updated
+value - the new value
+Newly declared classes include the following:
+The number of Cairo classes that were declared in the block
+Each class includes the following:
+The class hash
+Consider the following onchain data that was extracted from L1:
+[
+ 1, (1)
+ 2019172390095051323869047481075102003731246132997057518965927979101413600827, (2)
+ 18446744073709551617, (3)
+ 100, (4)
+ 200, (4)
+ 1, (5)
+ 1351148242645005540004162531550805076995747746087542030095186557536641755046, (6)
+ 558404273560404778508455254030458021013656352466216690688595011803280448032 (7)
+]| 1 | +The number of contracts whose state was updated. | +
| 2 | +The address of the first, and only, contract whose state changed. | +
| 3 | +18446744073709551617, which is 264+1, encodes the following:
+
+
|
+
| 4 | +These two elements, 100 and 200, encode the storage update, where the value of key 100 is set to 200. |
+
| 5 | +The new declare section: 1 includes a single declare v2 transaction in this state update. |
+
| 6 | +Encoding of the class hash. | +
| 7 | +Encoding of the compiled class hash of the declared class. | +
The state diffs contain information on every contract whose storage was updated and additional information on contract deployments. Those differences are sent as uint256[] array as part of the calldata, and are encoded as follows:
Number of cells that encode contract deployments
+Each deployed contract has the following:
+contract_address - the address of the deployed contract. See also Data availability.
contract_hash - the hash of the class
Number of contracts whose storage is updated.
+Each such contract has the following:
+contract_address - the address of the contract
num_of_storage_updates - number of storage updates
nonce, num of storage updates - a uint256 value that encodes both the number of storage updates for that contract and the updated nonce:
For each storage update:
+key - the address inside the contract’s storage where the value is updated
value - the new value
The example below shows onchain data that was extracted from L1. An explanation follows, according to the above format.
+[
+ 2,
+ 2472939307328371039455977650994226407024607754063562993856224077254594995194,
+ 1336043477925910602175429627555369551262229712266217887481529642650907574765,
+ 5,
+ 2019172390095051323869047481075102003731246132997057518965927979101413600827,
+ 18446744073709551617,
+ 5,
+ 102,
+ 2111158214429736260101797453815341265658516118421387314850625535905115418634,
+ 2,
+ 619473939880410191267127038055308002651079521370507951329266275707625062498,
+ 1471584055184889701471507129567376607666785522455476394130774434754411633091,
+ 619473939880410191267127038055308002651079521370507951329266275707625062499,
+ 541081937647750334353499719661793404023294520617957763260656728924567461866,
+ 2472939307328371039455977650994226407024607754063562993856224077254594995194,
+ 1,
+ 955723665991825982403667749532843665052270105995360175183368988948217233556,
+ 2439272289032330041885427773916021390926903450917097317807468082958581062272,
+ 3429319713503054399243751728532349500489096444181867640228809233993992987070,
+ 1,
+ 5,
+ 1110,
+ 3476138891838001128614704553731964710634238587541803499001822322602421164873,
+ 6,
+ 59664015286291125586727181187045849528930298741728639958614076589374875456,
+ 600,
+ 221246409693049874911156614478125967098431447433028390043893900771521609973,
+ 400,
+ 558404273560404778508455254030458021013656352466216690688595011803280448030,
+ 100,
+ 558404273560404778508455254030458021013656352466216690688595011803280448031,
+ 200,
+ 558404273560404778508455254030458021013656352466216690688595011803280448032,
+ 300,
+ 1351148242645005540004162531550805076995747746087542030095186557536641755046,
+ 500
+]The first element, 2, is the number of cells that encode contracts deployment.
The next two elements describe a single contract deployment with the following parameters:
+contract_address:
2472939307328371039455977650994226407024607754063562993856224077254594995194+
contract_hash:
1336043477925910602175429627555369551262229712266217887481529642650907574765+
The next element, 5 (index 3 in the array), is the number of contracts whose storage was updated. We will take only the first contract as an example.
contract_address:
2019172390095051323869047481075102003731246132997057518965927979101413600827+
Following the above contract address, we have 18446744073709551617 (index 8 in the array), which is \(2^{64}+1\), thus:
The new contract nonce is 1
One storage key is updated
+The value at key 5 was changed to 102
The next 4 contract storage updates are interpreted in the same manner.
+The data described above is sent across several Ethereum transactions, each holding a part of this array as calldata. Each new Starknet block has its associated state diff transactions.
+You can find the code for extracting this data from Ethereum in Pathfinder’s repo. Pathfinder is the first Starknet full node implementation. You may also take a look at the Python script which extracts the same information.
+This section describes fees that are paid on L2 starting in Starknet 0.13.0. For information about messaging fees that are paid on L1, see L1 → L2 message fees.
+Starting with Starknet v0.13.1, Starknet distinguishes between blocks whose state diffs are sent to L1 as calldata and blocks whose state diffs are sent to L1 as blobs. The l1_da_mode property in the Starknet block header contains this information. The cost of computation remains the same on both options, but the cost related to data availability differs.
This section shows the formula for determining a transaction’s fee. The following sections describe how this formula was derived.
+The following formula describes the overall fee, \(F\), for a transaction:
+where:
+\(v\) is a vector that represents resource usage, where each of its entries, \(v_k\), corresponds to different resource types: Cairo steps and number of applications of each builtin.
+For more information see Calculation of computation costs.
+\(w\) is the CairoResourceFeeWeights vector.
\(n\) is the number of unique contracts updated, which also includes changes to classes of existing contracts and contract deployments, even if the storage of the newly deployed contract is untouched. In other words, \(n\ge\ell\). Notice that \(n\ge 1\) always holds, because the fee token contract is always updated, which does not incur any fee.
+\(m\) is the number of values updated, not counting multiple updates for the same key. Notice that \(m\ge 1\) always holds, because the sequencer’s balance is always updated, which does not incur any fee.
+\(t\) is the number of L2→L1 messages sent, where the corresponding payload sizes are denoted by \(q_1,...,q_t\).
+\(\ell\) is the number of contracts whose class was changed, which happens on contract deployment and when applying the replace_class syscall.
\(D\) is 1 if the transaction is of type DECLARE and 0 otherwise. Declare transactions need to post on L1 the new class hash and compiled class hash which are added to the state.
L2→L1 messaging constants:
+\(\text{message_calldata_cost}\) is 1124 gas per 32-byte word.
+\(\text{l1_log_data_cost}\) is 256 gas.
+\(\text{l1_storage_write_cost}\) is the cost of writing to a new storage slot on Ethereum, which is 20,000 gas.
+\(\text{log_message_to_l1_cost}\) is 1637 gas.
+For more information, see Onchain data: L2→L1 messages.
+\(\text{l2_payload_costs}\) is the gas cost of data sent over L2. This includes calldata, code, and event emission. For more details see L2 payloads: calldata, events, and code.
+\(\text{felt_size_in_bytes}\) is 32, which is the number of bytes required to encode a single STARK field element.
+This section shows the formula for determining a transaction’s fee. The following sections describe how this formula was derived.
+The following formula describes the overall fee, \(F\), for a transaction:
+where:
+The following constants are defined in the same manner as in the blob-based formula:
+\(v, w, n, m, t, \ell, D\)
+\(\text{message_calldata_cost}, \; \text{l1_log_data_cost}, \; \text{log_message_to_l1_cost}, \; \text{l1_storage_write_cost}\)
+\(\text{l2_payload_costs}\)
+\(\text{da_calldata_cost}\) is 551 gas per 32-byte word. This cost is derived as follows:
+512 gas per 32-byte word for calldata.
+~100 gas for onchain hashing that happens for every sent word.
+a 10% discount, because the sequencer does not incur additional costs for repeated updates to the same storage slot within a single block.
+\(240\) is the gas discount for updating the sender’s balance, for the derivation of this number see Onchain data: Storage updates.
+\(\text{contract_update_discount}\) is 312 gas, for the derivation of this discount see Onchain data: Storage updates.
+The fee is charged atomically with the transaction execution on L2. The Starknet OS injects a transfer of the fee-related ERC-20, with an amount equal to the fee paid, the sender equal to the transaction submitter, and the sequencer as a receiver.
+With v3 transactions, users specify the max amount and max price for each resource. At the time of writing, the only available resource is L1 gas. In the future, we will introduce L2 gas which will be used to price L2 work (as opposed to only charging for the proof verification in L1 gas, which is what happens today).
+With older transaction versions, users specify the maximum fee that they are willing to pay for a transaction.
+The only limitation on the sequencer, which is enforced by the Starknet OS, is that the actual fee charged is bounded by max_fee. While not enforced in the proof, the Starknet sequencer usually charges less than max_fee, as it charges in accordance with the above fee formula.
At the time of writing, the following components are contributing to the transaction fee:
+Computational complexity: The marginal cost of verifying the transaction on L1, measured in L1 gas.
+Onchain data: The cost of posting the state diffs induced by the transaction to L1 (for more details, see data availability). This is measured in L1 gas or L1 data gas, depending on whether or not the L2 block in which the transaction was included uses calldata or blobs.
+L2→L1 messages: Messages sent to L1 are eventually sent to the Starknet core contract as L1 calldata by the sequencer; therefore L2 transaction that send L2→L1 messages incur an additional L1 gas cost.
+L2 calldata, events and code: From Starknet 0.13.1 onwards, there is a per-byte (or per felt) price for L2 payloads. For more details, see L2 payloads: calldata, events, and code.
+Each transaction is associated with an estimate of the amount of gas used. Combining this estimate with the price of gas yields the estimated fee.
+For transactions prior to v3, the fee is denominated in WEI. For transactions v3 and later, the fee is denominated in STRK.
+Every 60 seconds, Starknet samples the base price of gas and data gas on L1.
+The price of gas on Starknet is set to the average of the last 60 gas price samples, plus 1 gwei.
+The price of data gas on Starknet is set to the average of the last 60 data gas price samples. The data gas price on Ethereum is derived from the value of excess_blob_gas. For more information, see EIP-4844.
Let’s analyze the correct metric for measuring transaction complexity. For simplicity, we will ignore Cairo’s builtins, and address them later.
+A Cairo program execution yields an execution trace. When proving a Starknet block, we aggregate all the transactions appearing in that block to the execution trace.
+Starknet’s prover generates proofs for execution traces, up to some maximal length \(L\), derived from the specs of the proving machine and the desired proof latency.
+Tracking the execution trace length associated with each transaction is simple. +Each assertion over field elements, such as verifying addition/multiplication over the field, requires the same, constant number of trace cells, which is where our "no-builtins" assumption kicks in: Pedersen occupies more trace cells than addition. Therefore, in a world without builtins, the fee of the transaction \(tx\) is correlated with \(\text{TraceCells}[tx]/L\).
+In the Cairo execution trace each builtin has its own slot, which is important to consider when determining the fee.
+For example, consider that the prover can process a trace with the following limits:
+| up to 500,000,000 Cairo Steps | +up to 20,000,000 Pedersen hashes | +up to 4,000,000 signature verifications | +up to 10,000,000 range checks | +
|---|
The proof is closed and sent to L1 when any of these slots is filled.
+Suppose that a transaction uses 10,000 Cairo steps and 500 Pedersen hashes. At most 40,000 such transactions can fit into the hypothetical trace (20,000,000/500). Therefore, its gas price correlates with 1/40,000 of the cost of submitting proof.
+Notice that this estimate ignores the number of Cairo steps, as it is not the limiting factor, since 500,000,000/10,000 > 20,000,000/500.
+With this example in mind, it is possible to formulate the exact fee associated with L2 computation.
+| + + | +
+
+
+The allocation of resources among builtin operations must be predetermined; it is not possible to decide, post-execution, to include only 20,000,001 Pedersen hashes without additional components. +
+
+This safeguards fairness and prevents manipulation, ensuring integrity in proof generation and fee determination. + |
+
For each transaction, the sequencer calculates a vector, CairoResourceUsage, that contains the following:
The number of Cairo steps.
+The number of applications of each Cairo builtin. For example, five range checks and two Pedersen hashes.
+The sequencer crosses this information with the CairoResourceFeeWeights vector. For each resource type, either a Cairo step or a specific builtin application, CairoResourceFeeWeights has an entry that specifies the relative gas cost of that component in the proof.
Going back to the above example, if the cost of submitting a proof with 20,000,000 Pedersen hashes is roughly 5m gas, then the weight of the Pedersen builtin is 0.25 gas per application (5,000,000/20,000,000). The sequencer has a predefined weights vector, in accordance with the proof parameters.
+The sequencer charges only according to the limiting factor. Therefore the fee is correlated with:
+where \(k\) enumerates the Cairo resource components, that is the number of Cairo steps and builtins used.
+The weights are listed in the table Amount of gas used per Cairo step or per each time a Cairo builtin is applied.
+| Step or builtin | +Gas cost | +
|---|---|
Cairo step |
+0.0025 gas/step |
+
Pedersen |
+0.08 gas/application |
+
Poseidon |
+0.08 gas/application |
+
Range check |
+0.04 gas/application |
+
ECDSA |
+5.12 gas/application |
+
Keccak |
+5.12 gas/application |
+
Bitwise |
+0.16 gas/application |
+
EC_OP |
+2.56 gas/application |
+
The onchain data associated with a transaction is composed of three parts
+Storage updates
+L2→L1 messages
+Deployed contracts
+Declared classes (only relevant for DECLARE transactions, and adds two additional words)
Whenever a transaction updates some value in the storage of some contract, the following data is sent to L1:
+two 32-byte words per contract
+two 32-byte words for every updated storage value
+For information on the exact data and its construction, see Data availability.
+| + + | +
+
+
+Only the most recent value reaches L1. So the transaction’s fee only depends on the number of unique storage updates. If the same storage cell is updated multiple times within the transaction, the fee remains that of a single update. + |
+
The following formula describes the storage update fee for a transaction:
+where:
+\(n\) is the number of unique contracts updated, which also includes changes to classes of existing contracts and contract deployments, even if the storage of the newly deployed contract is untouched. In other words, \(n\ge\ell\). Notice that \(n\ge 1\) always holds, because the fee token contract is always updated at the end of each transaction, in order to update the sequencer’s and the sender’s balances. The fee token contract update is not taken into account when computing the fee.
+\(m\) is the number of values updated, not counting multiple updates for the same key. Notice that \(m\ge 1\) always holds, because the sequencer’s balance is updated at the end of each transaction. The sequencer’s balance update is not taken into account when computing the fee.
+\(\text{contract_update_discount}\) is 312 gas, which is discounted for every updated contract. This discount is a result of the fact that out of the \(2n\) words caused by updating contracts, \(n\) words are short, including at most 6 non-zero bytes:
+three bytes for the nonce
+two bytes for the number of storage updates
+one byte for the class information flag
+Taking into account that zero bytes only cost 4 gas, the cost difference between a full 32-byte word, which does not contain zeros, and a word with only six non-zero bytes is \(32\cdot16-(6\cdot16+26\cdot4)=312\).
+\(240\) is the gas discount for updating the sender’s balance, and is derived by assuming the balance requires at most 12 non-zero bytes, which is enough for 1.2B ETH or STRK, resulting in the following discount: \(512-(20\cdot4+12\cdot16)=240\).
+| + + | +
+
+
+Improvements to the above pessimistic estimation might be gradually implemented in future versions of Starknet. +
+
+For example, if different transactions within the same block update the same storage cell, there is no need to charge for both transactions, because only the last value reaches L1. In the future, Starknet might include a refund mechanism for such cases. + |
+
When a transaction that raises the send_message_to_l1 syscall is included in a state update, the following data reaches L1:
L2 sender address
+L1 destination address
+Payload size
+Payload (list of field elements)
+Consequently, the gas cost associated with a single L2→L1 message is:
+Where:
+\(\text{message_calldata_cost}\) is 1124 gas. This is the sum of the 512 gas paid to the core contract on submitting the state update, and 612 gas paid for the submitting of the same word to the verifier contract (which incurs ~100 additional gas for hashing). That is, messages are sent to Ethereum twice.
+\(\text{log_message_to_l1_cost}\) is 1637 gas. This is the fixed cost involved in emitting a LogMessageToL1 event. This event has two topics and a data array, which adds two data words to the event, resulting in a total of \(375+2\cdot 375+2\cdot 256\) gas (log opcode cost, topic cost, and two data words cost).
\(\text{l1_log_data_cost}\) is 256 gas, which is paid for every payload element during the emission of the LogMessageToL1 event.
\(\text{l1_storage_write_cost}\) is 20,000 gas per message which is paid in order to store the message hash on the Starknet core contract. This recording of the message is what later enables the intended L1 contract to consume the message.
+When a transaction that raises the deploy syscall is included in a state update, the following data reaches L1:
contract address
+number of storage updates and the new nonce
+class hash
+The first two elements are counted in the number of unique modified contracts, denoted by \(n\) throughout this page. So the only additional word comes from publishing the class hash, which adds 551 gas. For more information, see \(\text{da_calldata_cost}\) in the final formula.
+As of Starknet v0.13.1 onwards, L2 data is taken into account during pricing. This includes:
+calldata: this includes transaction calldata (in the case of INVOKE transactions or L1_HANDLER), constructor calldata (in the case of DEPLOY_ACCOUNT transactions), and signatures
events: data and keys of emitted events
+ABI: classes abi in DECLARE transactions (relevant only for DECLARE transactions of version ≥ 2)
CASM bytecode (for all available DECLARE transactions, where in version ≥ 2 this refers to the compiled class)
Sierra bytecode (relevant only for DECLARE transactions of version ≥ 2)
The pricing of the above components in terms of L1 gas is given by the following table:
+| Resource | +Gas cost | +
|---|---|
Event key |
+0.256 gas/felt |
+
Event data |
+0.128 gas/felt |
+
Calldata |
+0.128 gas/felt |
+
CASM bytecode |
+1 gas/felt |
+
Sierra bytecode |
+1 gas/felt |
+
ABI |
+0.032 gas/character |
+
Starknet’s ability to interact with L1 is crucial. Messaging is the mechanism that enables this interaction.
+For example, you can perform computations on L2 and use the result on L1.
+Bridges on Starknet use the L1-L2 messaging mechanism. Consider that you want to bridge tokens from Ethereum to Starknet. You deposit your tokens in the L1 bridge contract, which automatically triggers the minting of the same token on L2. Another good use case for L1-L2 messaging is Defi pooling. For more information, see DeFi pooling on StarkWare’s site and dApps on https://www.starknet.io.
+Be aware that the messaging mechanism is asynchronous and asymmetric.
+Asynchronous: Your contract code, whether Cairo or Solidity, cannot await the result of the message being sent on the other layer within your contract code’s execution.
+Asymmetric: Sending a message from Ethereum to Starknet, L1→L2, is fully automated by the Starknet sequencer, so the message is automatically delivered to the target contract on L2. However, when sending a message from Starknet to Ethereum, L2→L1, the sequencer only sends the hash of the message. You must then consume the message manually using a transaction on L1.
+Contracts on L2 can interact asynchronously with contracts on L1 using the L2→L1 messaging protocol.
+The protocol consists of the following stages:
+During the execution of a transaction, a contract on Starknet sends a message from L2 to L1 by calling the send_message_to_L1 syscall.
The sequencer attaches the message parameters to the block that includes the syscall invocation. The message parameters include the address of the sender on L2, the address of the recipient contract on L1, and the message data.
+For example:
+let mut payload: Array<felt252> = ArrayTrait::new();
+let to_address: EthAddress = 1_felt252.try_into().unwrap();
+payload.append(1);
+// potentially add more elements to payload (payload[1], payload[2], etc.)
+
+send_message_to_l1_syscall(to_address: to_address.into(), payload: payload.span());The prover proves the state update that includes this transaction.
+The sequencer updates the L1 state.
+The message is stored on L1 in the Starknet Core Contract and a counter on the Core Contract increases by one.
The processMessage function, which is part of the Starknet Core Contract, emits the LogMessageToL1 event, which contains the message parameters.
The message recipient on L1 can access and consume the message by calling the consumeMessageFromL2 function, which includes the message parameters within the transaction.
+This function, which is part of the Starknet Core Contract, verifies the following:
The hashes of the L2 sent message parameters, now stored on the Core Contract, and the L1 received message parameters, are the same.
+The entity calling the function is indeed the recipient on L1.
+In such a case, the counter corresponding to the message hash in the Starknet Core Contract decreases by one. For more information, see the consumeMessageFromL2 function in StarknetMessaging.sol.
L2→L1 Messaging mechanism illustrates this flow:
+
+The structure of an L2 → L1 message is described as follows under MSG_TO_L1 in the Starknet API JSON RPC specification:
+from_address (felt252)
+ |
+
+ The address of the L2 contract sending the message. + |
+
+to_address (EthAddress)
+ |
+
+ The target L1 address the message is sent to. + |
+
+payload (Array<felt252>)
+ |
+
+ The payload of the message. + |
+
The hash of an L2 → L1 message is computed on L1 as follows:
+keccak256(
+ abi.encodePacked(
+ FromAddress,
+ uint256(ToAddress),
+ Payload.length,
+ Payload
+ )
+);| + + | +
+
+
+Sending an L2 to L1 message always incurs a fixed cost of 20,000 gas, because the hash of the message being sent must be written to L1 storage in the Starknet Core Contract. + |
+
Contracts on L1 can interact asynchronously with contracts on L2 using the L1→L2 messaging protocol.
+The protocol consists of the following stages:
+An L1 contract induces a message to an L2 contract on Starknet by calling the sendMessageToL2 function on the Starknet Core Contract with the message parameters.
The Starknet Core Contract hashes the message parameters and updates the L1→L2 message mapping to indicate that a message with this hash was indeed sent. The L1 contract records the fee that the sender paid. For more information, see L1 → L2 message fees.
+The message is then decoded into a Starknet transaction that invokes a function annotated with the l1_handler decorator on the target contract. Transactions like this on L2 are called L1 handler transactions.
The Starknet sequencer, upon receiving enough L1 confirmations for the transaction that sent the message, initiates the corresponding L2 transaction.
+The L2 transaction invokes the relevant l1_handler function.
The L1 Handler transaction that was created in the previous step is added to a proof.
+The Core Contract receives the state update.
+The message is cleared from the Core Contract’s storage to consume the message. Clearing the Core Contract’s storage does the following:
+incurs a fixed cost of 5,000 gas
+emits an L1 event logging the message consumption
+At this point, the message is handled.
+An L1→L2 message consists of the following:
+L1 sender’s address
+L2 recipient’s contract address
+Function selector
+Calldata array
+Message nonce
+| + + | +
+
+
+The message nonce is maintained on the Starknet Core Contract on L1, and is incremented whenever a message is sent to L2. The nonce is used to avoid a hash collision between different L1 handler transactions that is caused by the same message being sent on L1 multiple times. +
+
+For more information, see L1→L2 structure. + |
+
| + + | +
+
+
+The flow described here should only be used in edge cases such as bugs on the Layer 2 contract preventing message consumption. + |
+
Consider that Alice sends an L1 asset to a Starknet bridge to transfer it to L2, which generates the corresponding L1→L2 message. Now, consider that the L2 message consumption doesn’t function, which might happen due to a bug in the dApp’s Cairo contract. This bug could result in Alice losing custody of their asset forever.
+To mitigate this risk, the contract that initiated the L1→L2 message can cancel it by declaring the intent to cancel, waiting five days, and then completing the cancellation. This delay protects the sequencer from a DoS attack in the form of repeatedly sending and canceling a message before it is included in L1, rendering the L2 block which contains the activation of the corresponding L1 handler invalid.
+The steps in this flow are as follows:
+The user that initiated the L1→L2 message calls the startL1ToL2MessageCancellation function in the Starknet Core Contract.
The user waits five days until she can finalize the cancellation.
+The user calls the cancelL1ToL2Message function.
An L1 → L2 message induces a transaction on L2, which, unlike regular transactions, is not sent by an account. This calls for a different mechanism for paying the transaction’s fee, for otherwise the sequencer has no incentive of including L1 handler transactions inside a block.
+To avoid having to interact with both L1 and L2 when sending a message, L1 → L2 messages are payable on L1, by sending ETH with the call to the payable function sendMessageToL2 on the Starknet Core Contract.
The sequencer takes this fee in exchange for handling the message. The sequencer charges the fee in full upon updating the L1 state with the consumption of this message.
+The fee itself is calculated in the same manner as +"regular" L2 transactions. You can use the CLI to get an estimate of an L1 → L2 message fee.
+For completeness, L1 → L2 structure describes the precise structure of both the message as it appears on L1 and the induced transaction as it appears on L2.
+| FromAddress | +ToAddress | +Selector | +Payload | +Nonce | ++ |
|---|---|---|---|---|---|
|
+
|
+
|
+
|
+
|
++ |
The hash of the message is computed on L1 as follows:
+keccak256(
+ abi.encodePacked(
+ uint256(FromAddress),
+ ToAddress,
+ Nonce,
+ Selector,
+ Payload.length,
+ Payload
+ )
+);| Version | +ContractAddress | +Selector | +Calldata | +Nonce | ++ |
|---|---|---|---|---|---|
|
+
|
+
|
+
|
+
|
++ |
The hash of the corresponding L1 handler transaction on L2 is computed as follows:
+l1_handler_tx_hash = _h_(
+ "l1_handler",
+ version,
+ contract_address,
+ entry_point_selector,
+ _h_(calldata),
+ 0,
+ chain_id,
+ nonce
+)Where:
+l1_handler is a constant prefix, encoded in bytes (ASCII), as big-endian.
version is the transaction version. Only version 0 is currently supported.
chain_id is a constant value that specifies the network to which this transaction is sent.
h is the Pedersen hash (note that since we’re hashing an array, the # of inputs needs to be appended to the hash).
+0 indicates that L1 to L2 message fees are charged on L1.
| + + | +
+
+
+In an L1 handler transaction, the first element of the calldata is always the sender’s Ethereum address. + |
+
| + + | +
+
+
+Since L1 handler transactions are not initiated by an account, invoking |
+
| Current version | +Deprecated versions | +Unsupported versions | +
|---|---|---|
v0 |
+N/A |
+N/A |
+
send_message_to_L1 syscall
sendMessageToL2 function on the Starknet Core Contract
For more information on how messaging works within the Starknet Core Contract, including details on coding, see L1-L2 Messaging in The Cairo Book: The Cairo Programming Language
+The StarknetMessaging smart contracts include functions and events that are required when sending messages between L1 and L2.
For information on the messaging mechanism, see Messaging mechanism.
+The L1 functions, where available, are defined in the following smart contract:
+| Contract | +Description | +Functions | +
|---|---|---|
| + | The contract that implements messaging functions. +Interfaces are available through |
+
+
|
+
The L1 events, where available, are defined in the following smart contract:
+| Contract | +Description | +Events | +
|---|---|---|
| + | The contract that defines messaging events. |
+
+
|
+
Functions are listed in alphabetical order.
+cancelL1ToL2MessageCancels an L1 to L2 message. Call this function after calling the startL1ToL2MessageCancellation function. The time between the calls to these two functions must be at least the number of seconds defined by the messageCancellationDelay function.
Only a sender can cancel a message.
+If the message is missing, the call reverts.
+Be aware that the message fee is not refunded.
+None.
+
+uint256 toAddress
+ |
+
+ The address of the L2 contract. + |
+
+uint256 selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] calldata payload
+ |
+
+ The payload of the message. + |
+
+uint256 nonce
+ |
+
+ The nonce of the message. + |
+
+bytes32 msgHash
+ |
+
+ The hash of the canceled message. + |
+
Contract: StarknetMessaging.sol
Function: cancelL1ToL2Message
consumeMessageFromL2Consumes a message that was sent from an L2 contract.
+Returns the hash of the message.
+None.
+
+uint256 fromAddress
+ |
+
+ The address of the L2 contract sending the message. + |
+
+uint256[] calldata payload
+ |
+
+ The payload of the message. + |
+
+bytes32 msgHash
+ |
+
+ The hash of the consumed message. + |
+
Contract: StarknetMessaging.sol
Function: consumeMessageFromL2
getMaxL1MsgFeeReturns the maximum fee, in Wei, that Starknet accepts for a single message. If the fee passed is higher than this value, the transaction is not accepted.
+pure
None.
+
+uint256 MAX_L1_MSG_FEE
+ |
+
+ The maximum fee, in Wei, that Starknet accepts for a single message. + |
+
Contract: StarknetMessaging.sol
Function: getMaxL1MsgFee
l1ToL2MessageCancellationsReturns the timestamp of the cancellation request.
+view
+bytes32 msgHash
+ |
+
+ The message hash. + |
+
+uint256 result
+ |
+
+ The Ethereum block timestamp. + |
+
Returns 0 if cancelL1ToL2Message was not called with the message hash msgHash.
Contract: StarknetMessaging.sol
Function: l1ToL2MessageCancellations
l1ToL2MessageNonceReturns the nonce of the next message sent to the L2 contract. So if If n messages have been sent to Starknet, this function returns n + 1.
view
None.
+
+uint256 nonce
+ |
+
+ The nonce of the next message sending to L2 contract. + |
+
Contract: StarknetMessaging.sol
Function: l1ToL2MessageNonce
l1ToL2MessagesIndicates if a pending message is associated with a given message hash.
+view
+bytes32 msgHash
+ |
+
+ The message hash. + |
+
Returns uint256 result, where result is one of the following:
+message_fee + 1
+ |
+
+ A pending message is associated with the |
+
+0
+ |
+
+ No pending message is associated with the |
+
Contract: StarknetMessaging.sol
Function: l1ToL2Messages
l2ToL1MessagesIndicates if a pending message is associated with a given message hash.
+view
+bytes32 msgHash
+ |
+
+ The message hash. + |
+
Returns uint256 result, where result is one of the following:
+1
+ |
+
+ A pending message is associated with the |
+
+0
+ |
+
+ No pending message is associated with the |
+
Contract: StarknetMessaging.sol
Function: l2ToL1Messages
messageCancellationDelayReturns the time interval, in seconds, after which you can cancel a message starting from the moment of calling the startL1ToL2MessageCancellation function. You can get the real value by calling the messageCancellationDelay function on a block explorer, such as Etherscan.
view
None.
+
+uint256 result
+ |
+
+ The time interval. + |
+
Contract: StarknetMessaging.sol
Function: messageCancellationDelay
sendMessageToL2Sends a message to an L2 contract. The message fee is the cost of executing this function.
+payable
+uint256 toAddress
+ |
+
+ The address of the L2 contract. + |
+
+uint256 selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] calldata payload
+ |
+
+ The payload of the message. + |
+
+bytes32 msgHash
+ |
+
+ The hash of the message. + |
+
+uint256 nonce
+ |
+
+ The nonce of the message. + |
+
Contract: StarknetMessaging.sol
Function: sendMessageToL2
startL1ToL2MessageCancellationStarts the cancellation of a message from L1 to L2.
+You can cancel a message after a predefined about of time from the moment this function is called. The amount of time is set by the messageCancellationDelay function.
You can only call this function for a message that is currently pending, and the caller must be the sender of that message.
+None.
+
+uint256 toAddress
+ |
+
+ The address of the L2 contract. + |
+
+uint256 selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] calldata payload
+ |
+
+ The payload of the message. + |
+
+uint256 nonce
+ |
+
+ The nonce of the message. + |
+
+bytes32 msgHash
+ |
+
+ The hash of the cancellation message. + |
+
Contract: StarknetMessaging.sol
Function: startL1ToL2MessageCancellation
Events are listed in alphabetical order.
+ConsumedMessageToL1This event is emitted when a message from L2 to L1 is consumed by the consumeMessageFromL2 function.
+uint256 indexed fromAddress
+ |
+
+ The address of the sender on L2. + |
+
+address indexed toAddress
+ |
+
+ The address of the receiver on L1. + |
+
+uint256[] payload
+ |
+
+ The payload of the consumed message. + |
+
Contract: IStarknetMessagingEvents
Event: ConsumedMessageToL1
LogMessageToL2This event is emitted when a message is sent from L1 to L2 by the sendMessageToL2 function.
+address indexed fromAddress
+ |
+
+ The address of the sender on L1. + |
+
+uint256 indexed toAddress
+ |
+
+ The address of the receiver on L2. + |
+
+uint256 indexed selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] payload
+ |
+
+ The payload of the message. + |
+
+uint256 nonce
+ |
+
+ The nonce of the message. + |
+
+uint256 fee
+ |
+
+ The fee associated with the message. + |
+
Contract: IStarknetMessagingEvents
Event: LogMessageToL2
MessageToL2CanceledThis event is emitted when an L1 to L2 message is canceled by the cancelL1ToL2Message function.
+address indexed fromAddress
+ |
+
+ The address of the sender on L1. + |
+
+uint256 indexed toAddress
+ |
+
+ The address of the receiver on L2. + |
+
+uint256 indexed selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] payload
+ |
+
+ The payload of the canceled message. + |
+
+uint256 nonce
+ |
+
+ The nonce of the canceled message. + |
+
Contract: IStarknetMessagingEvents
Event: MessageToL2Canceled
MessageToL2CancellationStartedThis event is emitted when the cancellation of an L1 to L2 message is started by the startL1ToL2MessageCancellation function.
+address indexed fromAddress
+ |
+
+ The address of the sender on L1. + |
+
+uint256 indexed toAddress
+ |
+
+ The address of the receiver on L2. + |
+
+uint256 indexed selector
+ |
+
+ The function, in the recipient L2 contract, that the message called. + |
+
+uint256[] payload
+ |
+
+ The payload of the message to be canceled. + |
+
+uint256 nonce
+ |
+
+ The nonce of the message to be canceled. + |
+
Contract: IStarknetMessagingEvents
Starknet is a coordinated system, with each component—sequencers, +provers, and nodes—playing a specific yet interconnected role. Although +Starknet is not yet fully decentralized, it’s actively moving toward +that goal. This description of the system’s roles and how they interact should +help you better grasp the intricacies of the Starknet ecosystem.
+Starknet’s operation begins when a transaction is received by a gateway,
+which serves as the Mempool. This stage could also be managed by the
+sequencer. The transaction is initially marked as RECEIVED. The
+sequencer then incorporates the transaction into the network state and
+tags it as ACCEPTED_ON_L2. The final step involves the prover, which
+executes the operating system on the new block, calculates its proof,
+and submits it to Layer 1 (L1) for verification.
For more information on the transaction flow, see Transaction lifecycle.
+
+In essence, Starknet’s architecture involves multiple components:
+The sequencer receives transactions, orders +them, and produces blocks. It operates similarly to validators in +Ethereum or Bitcoin.
+The prover generates proofs for the created blocks +and transactions. It uses the Cairo Virtual Machine (Cairo VM) to run provable +programs, thereby creating execution traces necessary for generating +STARK proofs.
+L1, in this case, Ethereum, hosts a smart contract capable +of verifying these STARK proofs. If the proofs are valid, Starknet’s +state root on L1 is updated.
+Starknet’s state is a comprehensive snapshot maintained through Merkle +trees, much like in Ethereum. This establishes the architecture of the +validity roll-up and the roles of each component.
+Sequencers are the backbone of the Starknet network, similar to Ethereum’s +validators. They usher transactions into the system.
+Validity Rollups, also known as ZK-Rollups, excel at offloading some network chores, like bundling +and processing transactions, to specialized players. This setup is +similar to how Ethereum and Bitcoin delegate security to miners. +Sequencing, like mining, demands hefty resources.
+Validity Rollups like Starknet outsource transaction processing to specialized +entities and then verify their work. These specialized entities, in the +context of Validity Rollups, are known as sequencers.
+Instead of providing security, as miners do, sequencers provide +transaction capacity. They order, that is, sequence, multiple transactions into a +single batch, execute them, and produce a block that is later +proved by the prover and submitted to the Layer 1 network as a single, +compact proof, known as a rollup. Just as validators +in Ethereum and miners in Bitcoin are specialized actors securing the +network, sequencers in Validity Rollup-based networks are specialized +actors that provide transaction capacity.
+This mechanism enables Validity Rollups to handle a higher volume +of transactions while maintaining the security of the underlying +Ethereum network, enhancing scalability without compromising on +security.
+Sequencers follow a systematic method for processing transactions:
+Sequencing: They collect transactions from users and order them.
+Executing: Sequencers then process these transactions.
+Batching: Transactions are grouped together in batches for +efficiency.
+Block Production: Sequencers produce blocks that contain batches of +processed transactions.
+Sequencers must be reliable and highly available, as their role is +critical to the network’s smooth functioning. They need powerful and +well-connected machines to perform their role effectively, as they must process transactions rapidly and continuously.
+The current roadmap for Starknet includes decentralizing the sequencer +role. This shift towards decentralization will enable more participants +to become sequencers, contributing to the robustness of the network.
+Provers serve as the second line of verification in the Starknet +network. Their main task is to validate the work of the sequencers, when +they receive the block produced by the sequencer, and to generate proofs +that these processes were correctly performed.
+A prover does the following:
+Receives blocks: Provers receive blocks of processed transactions +from sequencers.
+Processes blocks: Provers process these blocks a second time, ensuring +that all transactions within the block have been correctly handled.
+Generates a proof: After processing, provers generate a proof of +correct transaction processing.
+Sends the proof to Ethereum: Finally, the proof is sent to the +Ethereum network for validation. If the proof is correct, the +Ethereum network accepts the block of transactions.
+Provers need even more computational power than sequencers because they +have to calculate and generate proofs, a process that is computationally +heavy. However, the work of provers can be split into multiple parts, +allowing for parallelism and efficient proof generation. The proof +generation process is asynchronous, meaning it doesn’t have to occur +immediately or in real-time. This flexibility allows for the workload to +be distributed among multiple provers. Each prover can work on a +different block, allowing for parallelism and efficient proof +generation.
+The design of Starknet relies on these two types of actors—sequencers +and provers—working in tandem to ensure efficient processing and +secure verification of transactions.
+The relationship between sequencers and provers in blockchain technology +often sparks debate. A common misunderstanding suggests that either the +prover or the sequencer is the main bottleneck. To set the record +straight, let’s discuss the optimization of both components.
+Starknet, which uses the Cairo programming language, currently supports +only sequential transactions. Plans are in place to introduce parallel +transactions in the future. However, as of now, the sequencer operates +one transaction at a time, making it the bottleneck in the system.
+In contrast, provers operate asynchronously and can execute multiple +tasks in parallel. The use of proof recursion allows for task +distribution across multiple machines, making scalability less of an +issue for provers.
+When it comes to defining what nodes do in Bitcoin or Ethereum, people +often misinterpret their role as keeping track of every transaction +within the network. This, however, is not entirely accurate.
+Nodes serve as auditors of the network, maintaining the state of the +network, such as how much Bitcoin each participant owns or the current +state of a specific smart contract. They maintain network state by processing +transactions and preserving a record of all transactions, but that is a +means to an end, not the end itself.
+In Validity Rollups and specifically within Starknet, this concept is +somewhat reversed. Nodes don’t necessarily have to process transactions +to get the state. In contrast to Ethereum or Bitcoin, Starknet nodes +aren’t required to process all transactions to maintain the state of the +network.
+You can access network state data by using the Starknet API, which uses the JSON RPC protocol, to communicate with a node. Previously, Starknet’s Gateway and Feeder Gateway APIs enabled querying the sequencer, but as the network has matured, the JSON RPC has become the standard. +Operating your own node is typically faster than using a shared architecture, like the +gateway.
+It’s worth noting that more people running nodes increases +the resilience of the network and prevents server flooding, which has +been an issue in other L2 networks.
+Currently, there are primarily three methods for a node to keep track of +the network’s state and nodes can implement any of these +methods:
+Replaying Old Transactions: Like Ethereum or Bitcoin, a node can +take all the transactions and re-execute them. Although this approach is +accurate, it isn’t scalable unless you have a powerful machine that’s +capable of handling the load. If you can replay all transactions, you +can become a sequencer.
+Relying on L2 Consensus: Nodes can trust the sequencer to +execute the network correctly. When the sequencer updates the state and +adds a new block, nodes accept the update as accurate.
+Checking Proof Validation on L1: Nodes can monitor the state of +the network by observing L1 and ensuring that every time a proof is +sent, they receive the updated state. This way, they don’t have to trust +anyone and only need to keep track of the latest valid transaction for +Starknet.
+Each type of node setup comes with its own set of hardware requirements +and trust assumptions.
+Nodes that replay transactions require powerful machines to track and +execute all transactions. These nodes don’t have trust assumptions; they +rely solely on the transactions they execute, guaranteeing that the +state at any given point is valid.
+Nodes that rely on L2 consensus require less computational power. They +need sufficient storage to keep the state but don’t need to process a +lot of transactions. The tradeoff here is a trust assumption. +Currently, Starknet revolves around one sequencer, so these nodes +trust StarkWare not to disrupt the network. However, once a consensus +mechanism and leader election amongst sequencers are in place, these +nodes will only need to trust that a sequencer who staked their stake to +produce a block is not willing to lose it.
+Nodes that only update their state based on proof validation on L1 +require the least hardware. They have the same requirements as an +Ethereum node, and once Ethereum light nodes become a reality, +maintaining such a node could be as simple as using a smartphone. The +only tradeoff is higher latency. Proofs are sent to Ethereum intermittently, not for every block, resulting in delayed state updates. Plans are in +place to produce proofs more frequently, even if they are not sent to +Ethereum immediately, lowering node latency.
+Starknet’s state consists of:
+| +Contract classes + | +
+ a mapping +between the class hash and the class definition + |
+
| +Contract instances + | +
+ a mapping between addresses (251-bit field elements) and the contract’s state + |
+
A contract instance’s state consists of:
+| +Class hash + | +
+ defines the functionality of the contract + |
+
| +Contract storage + | +
+ a key-value mapping where the key/values are field elements + |
+
| +Contract nonce + | +
+ the number of transactions sent from this contract + |
+
A transaction \(tx\) transitions the system from state \(S\) to state \(S'\) if:
+\(tx\) is an Invoke transaction, and the storage of \(S'\) is the result of executing the target contract code with respect to the previous state \(S\). The arguments, +contract instance’s address, and the specific function entry point are part of the transaction.
+\(tx\) is a Deploy account transaction, and \(S'\) contains the new contract instance’s state at the contract instance’s address. Additionally, the storage of \(S\) is updated +according to the execution of the contract instance’s constructor.
+\(tx\) is a Declare transaction, and \(S'\) contains the class hash and definition in the contract class’s mapping
+The state commitment is a digest that represents the state.
+In Starknet, the state commitment combines the roots of two binary Merkle-Patricia tries of height 251 in the following manner:
+state_commitment = hPos( + "STARKNET_STATE_V0", + contract_trie_root, + class_trie_root +)+
Where:
+hPos is the Poseidon hash
+function.
STARKNET_STATE_V0 is a constant prefix string encoded in ASCII (and represented as a field element).
contract_trie_root is the root of the contract trie, a Merkle-Patricia trie whose leaves are the contracts' states.
class_trie_root is the root of the class trie, a Merkle-Patricia trie whose leaves are the compiled class hashes.
As with Ethereum, this trie is a two-level structure, whose leaves correspond to distinct contracts. The address of each contract determines the path from the trie’s root to its corresponding leaf, whose content encodes the contract’s state.
+The information stored in the leaf is as follows:
+hPed( + hPed( + hPed( + class_hash, + storage_root + ), + nonce + ), + 0 +)+
Where:
+hPed is the Pedersen hash function.
class_hash is the hash of the contract’s definition.
storage_root is the root of another Merkle-Patricia trie of height 251 that is constructed from the contract’s storage.
nonce is the current nonce of the contract.
The class trie encodes the information about all existing +classes in Starknet’s state. This trie maps class hashes to their +compiled class hashes. The information stored in a leaf at a path corresponding to some class hash is as follows:
+hPos(
+ CONTRACT_CLASS_LEAF_V0,
+ compiled_class_hash
+)Where:
+hPos is the Poseidon hash function
CONTRACT_CLASS_LEAF_V0 is a constant prefix string encoded in ASCII (and represented as a field element).
compiled_class_hash is the hash of the Cairo assembly resulting from compiling the given class via the Sierra-to-Casm compiler.
| + + | +
+
+
+Compiled class hash
+The compiled class hash identifies the output of a specific Casm compilation as unique. +
+
+Cairo classes that are part of the state commitment are defined with Sierra, an intermediate representation between Cairo and Cairo assembly (Casm). However, the prover only works with Casm. +
+
+So in order to prevent needing to compile from Sierra to Casm in every block in which the class is used, the state commitment must have some information about the corresponding Cairo assembly. The compiled class hash provides this information. +
+
+For more information, see Cairo and Sierra. +
+
+The party that declares the contract signs the compiled class hash, which they obtain using an SDK, as part of the
+
+In the future, when Sierra-to-Casm compilation becomes part of the Starknet OS, this value might be updated via a proof of the Sierra-to-Casm compiler execution, showing that compiling the same class with a newer compiler version results in some new compiled class hash. + |
+
The state commitment scheme uses a binary Merkle-Patricia trie with the Pedersen hash function.
+Each node in the trie is represented by a triplet \((length, path, value)\), where:
+| +\(length\) + | +
+ is the length of the path, measured in nodes. + |
+
| +\(path\) + | +
+ is the path from the current node to its unique non-empty subtrie. +
+
+\(path\) is an integer in the set \(\{0,\ldots,2^{length}-1\}\), and the binary expansion of \(path\) indicates how to proceed along the trie, as follows: +
+
+
|
+
| +\(value\) + | +
+ is the value of the node, which can be either data, or the hash of two non-empty child nodes. + |
+
An empty node is one whose triplet values are \((0,0,0)\). Leaf nodes and internal nodes can be empty. A subtrie rooted at a node \((length, path, value)\) has a single non-empty subtrie, rooted at the node obtained by following the path specified by \(path\).
+| + + | +
+
+
+Length is specified, and cannot be deduced from \(path\), because the numbers in the triplet \((length, path, value)\) are field elements of fixed size, 251 bits each. +
+
+For a node where \(length>0\), \(path\) leads to the highest node whose left and right children are not empty. + |
+
The following rules specify how the trie is constructed from a given set of leaves:
+The hash of a node \(N =(length, path, value)\), denoted by \(H(N)\), is:
+| + + | +
+
+
+All arithmetic operations in the above description of \(H\) are done in the STARK field, as described in The STARK field. + |
+
The triplet representing the parent of the nodes \(left=(\ell_L, p_L, v_L)\), \(right=(\ell_R, p_R, v_R)\) is defined as follows:
+The diagram A three-level Merkle-Patricia trie illustrates the construction of a three-level-high Merkle-Patricia trie from the leaves whose values are \((0,0,1,0,0,1,0,0)\):
+
+Where \(r=h_{Ped}(H(2,2,1),H((2,1,1))\). Notice that the example does not skip from the root, whose length is zero, so the final state commitment to the trie is \(H((0,0,r))=r\).
+Suppose that you want to prove, with respect to the state commitment just computed, that the value of the leaf whose path is given by \(101\) is \(1\). In a standard Merkle trie, the proof would consist of data from three nodes, which are siblings along the path to the root.
+In a Merkle-Patricia trie, because the trie is sparse, you only need to send the two children of the root, which are \((2,2,1)\) and \((2,1,1)\). These two children are enough to reproduce the state commitment \(r\), and because you know that the height of the trie is three, and that it is fixed, you know that the path \(01\) of length \(2\) specified by the right-hand child, \((2,1,1)\), leads to the desired leaf.
+Starknet uses special contract addresses to provide distinct capabilities beyond regular contract deployment.
+Two such addresses are 0x0 and 0x1. These addresses are reserved for specific purposes and are
+characterized by their unique behavior in comparison to traditional contract addresses.
0x0Address 0x0 functions as the default caller_address for external calls, including interactions with the L1 handler or deprecated Deploy transactions. Unlike regular contracts, address 0x0 does not possess a storage structure and does not accommodate storage mapping.
0x1Address 0x1 is another special contract address within Starknet’s architecture. It functions as a storage space for mapping block numbers to their corresponding block hashes. The storage structure at this address is organized as follows:
| +Keys + | +
+ Block numbers between \(\text{first_v0_12_0_block}\) and \(\text{current_block - 10}\). + |
+
| +Values + | +
+ Corresponding block hashes for the specified blocks. + |
+
| +Default Values + | +
+ For all other block numbers, the values are set to |
+
The storage organization of address 0x1 supports the efficient retrieval of block hashes based on block numbers within a defined range and is also used by the get_block_hash system call.
+The high-level steps in the Starknet transaction lifecycle are as follows:
+Transaction submission: A transaction is submitted to one of the gateways, which functions as the mempool, and marks the transaction status as RECEIVED.
Mempool validation:
+The mempool performs a preliminary validation on the transaction, such as ensuring that the current account balance exceeds the value of max_fee (prior to v3 transactions) or assuring the transaction’s calldata length is within the legal limit. If the transaction is invalid, it does not proceed.
Mempool validation in this context is analogous to Ethereum’s signature checking, including running the account’s __validate__ function on an INVOKE transaction, __validate_declare__ on a DECLARE transaction, or __validate_deploy__ on a DEPLOY_ACCOUNT transaction, ensuring that the current account balance exceeds the value of max_fee (prior to v3 transactions), and more.
Sequencer validation: The sequencer performs preliminary validation on the transaction before executing it to ensure that the transaction is still valid. If the transaction is invalid, it does not proceed.
+This validation stage repeats the same validation run during the mempool validation.
+Execution: The sequencer operation sequentially applies all transactions that passed the preliminary validation to the state. If a transaction fails during execution, it is included in the block with the status REVERTED.
Proof generation and verification: The Prover executes the operating system on the new block, computes the proof, and transmits it to the L1 verifier, which verifies the proof. At this point, the L1 state is updated to include the transaction.
+The diagram below illustrates how each transaction status fits into the overall transaction flow:
+
+The following are the possible statuses of a transaction from the moment a user sends it until the moment it passes the L1 verifier:
+| Status type | +Status | +Explanation | +||
|---|---|---|---|---|
Finality |
+
|
+The transaction is not yet known to the sequencer. |
+||
|
+
+
+The transaction was received by the mempool. The transaction now either executes successfully, is rejected, or reverted. +
+ The transaction has no execution status. + |
+|||
|
+
+
+The transaction was received by the mempool but failed validation in the sequencer. Such transactions are not included in a block. +
+
+The transaction has no execution status. +
+
|
+|||
|
+The transaction was executed and entered an actual created block on L2. |
+|||
|
+The transaction was accepted on Ethereum. |
+|||
Execution |
+
|
+
+
+The transaction passed validation but failed during execution in the sequencer. It is included in the block with the status
+
|
+||
|
+The transaction was successfully executed by the sequencer. It is included in the block. |
+
When a transaction is marked as REVERTED, the following state implications occur:
| +Nonce increases + | +
+ The nonce value for the account of the failed transaction iterates despite the failure. + |
+
| +Fee charge + | +
+ The sequencer charges a fee for the execution of the transaction up to the point of failure. A |
+
| +Partial reversion + | +
+ All changes that occurred during the validation stage are not reverted. However, all changes that occurred during the execution stage are reverted, including all messages to L1 or any events that were emitted during this stage. +
+
+Events might still be emitted from the validation stage or the fee charge stage. + |
+
| +Fee calculation + | +
+ The fee charged for
+
+
|
+
The resources used for the execution of the transaction up to the point of failure. This includes Cairo steps, builtins, syscalls, L1 messages, events, and state diffs during the validation and execution stages.
+To get a receipt, use the JSON RPC method starknet_getTransactionReceipt.
The transaction receipt contains the following fields:
+
+transaction_hash
+ |
+
+ The hash of the transaction. + |
+
+actual_fee
+ |
+
+ The actual fee paid for the transaction. + |
+
+finality_status
+ |
+
+ The finality status of the transaction. + |
+
+execution_status
+ |
+
+ The execution status of the transaction. + |
+
+block_hash
+ |
+
+ The hash of the block that includes the transaction + |
+
+block_number
+ |
+
+ The sequential number of the block that includes the transaction + |
+
+messages_sent
+ |
+
+ A list of messages sent to L1. + |
+
+events
+ |
+
+ The events emitted. + |
+
+execution_resource
+ |
+
+ A summary of the execution resources used by the transaction. + |
+
+type
+ |
+
+ The type of the transaction. + |
+
The following is an example of a receipt:
+{
+ "jsonrpc": "2.0",
+ "result": {
+ "actual_fee": "0x221db5dbf6db",
+ "block_hash": "0x301fc0d09c5810600af7bb9610be10596ad6f4e6d28a60d397dd148f0962a88",
+ "block_number": 906096,
+ "events": [
+ {
+ "data": [
+ "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7",
+ "0x0",
+ "0x9184e72a000",
+ "0x0"
+ ],
+ "from_address": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
+ "keys": [
+ "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
+ ]
+ },
+ {
+ "data": [
+ "0x764da020183e28a48ee38a9474f84e7e5ff13194",
+ "0x9184e72a000",
+ "0x0",
+ "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7"
+ ],
+ "from_address": "0x73314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
+ "keys": [
+ "0x194fc63c49b0f07c8e7a78476844837255213824bd6cb81e0ccfb949921aad1"
+ ]
+ },
+ {
+ "data": [
+ "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7",
+ "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
+ "0x221db5dbf6db",
+ "0x0"
+ ],
+ "from_address": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
+ "keys": [
+ "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
+ ]
+ }
+ ],
+ "execution_status": "SUCCEEDED",
+ "finality_status": "ACCEPTED_ON_L2",
+ "messages_sent": [
+ {
+ "from_address": "0x73314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
+ "payload": [
+ "0x0",
+ "0x764da020183e28a48ee38a9474f84e7e5ff13194",
+ "0x9184e72a000",
+ "0x0"
+ ],
+ "to_address": "0xc3511006c04ef1d78af4c8e0e74ec18a6e64ff9e"
+ }
+ ],
+ "transaction_hash": "0xdeadbeef",
+ "type": "INVOKE"
+ },
+ "id": 1
+}Starknet supports the following types of transactions, as defined in the Starknet API:
+
+DECLARE
+ |
+
+ Declares new contract classes, enabling new contract instances. + |
+
+INVOKE
+ |
+
+ Invokes an existing function in a contract. + |
+
+DEPLOY_ACCOUNT
+ |
+
+ Deploys new account contracts in smart wallets. + |
+
To see how these transaction types appear in the Starknet API, see starknet_api_openrpc.json.
+This topic describes the available fields for these transaction types and how each transaction’s hash is calculated.
+When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.
+Deprecated transaction versions are still supported, but support will be removed in a future release of Starknet.
+| Transaction name | +Current version | +Deprecated versions | +Unsupported versions | +
|---|---|---|---|
|
+v3 |
+v1, v0 |
+N/A |
+
|
+v3 |
+v2, v1 |
+v0 |
+
|
+v3 |
+v0 |
+N/A |
+
|
+N/A |
+N/A |
+v0 |
+
Additionally, see information on the L1 handler transaction type.
+| + + | +
+
+
+Do not submit a transaction that uses an unsupported transaction type, because it cannot be included in a proof, and so cannot become part of a Starknet block. + |
+
| + + | +
+
+
+While the |
+
INVOKE transactionThe INVOKE transaction type invokes a function in an existing contract instance. The contract code of the account that sends the INVOKE transaction determines how to process the transaction.
| + + | +
+
+
+Because an account’s |
+
Every INVOKE transaction in Starknet undergoes the validation and execution stages, initiated by the __validate__ and __execute__ functions. The validation stage verifies that the account that sent the transaction approves it.
| Field name | +Type | +Description | +||
|---|---|---|---|---|
|
+
|
+For future use. +Currently this value is always empty. +For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+The arguments that are passed to the validate and execute functions. |
+||
|
+
|
+The id of the chain to which the transaction is sent. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+The transaction nonce. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+For future use. +Currently this value is always empty. +For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+
+
+Used for enabling the fee market. +
+
+A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction. +
+
|
+||
|
+
|
+The address of the account initiating the transaction. |
+||
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+||
|
+
|
+For future use. Currently this value is always |
+||
|
+
|
+
+
+The transaction’s version.
+
+Transaction version, where
+
|
+
The INVOKE v3 transaction hash is calculated as a Poseidon hash over the given transaction elements,
+specifically:
invoke_v3_tx_hash = h( + "invoke", + version, + nonce, + sender_address, + h(tip, l1_gas_bounds, l2_gas_bounds), + h(paymaster_data), + chain_id, + data_availability_modes, + h(account_deployment_data), + h(calldata) +)+
Where:
+invoke is a constant prefix string, encoded in ASCII.
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
l1_gas_bounds is constructed as follows:
l2_gas_bounds is constructed as follows:
data_availability_modes is a concatenation of fee_data_availability_mode
+and nonce_data_availability_mode, as follows:
h is the Poseidon hash.
| Name | +Type | +Description | +
|---|---|---|
|
+
|
+The address of the sender of this transaction. |
+
|
+
|
+The arguments that are passed to the |
+
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+
|
+
|
+The maximum fee that the sender is willing to pay for the transaction |
+
|
+
|
+The transaction nonce. |
+
|
+
|
+The transaction’s version. The value is 1. |
+
The INVOKE v1 transaction hash is calculated as a hash over the given transaction elements,
+specifically:
invoke_v1_tx_hash = h( + "invoke", + version, + sender_address, + 0, + h(calldata), + max_fee, + chain_id, + nonce +)+
Where:
+invoke is a constant prefix string, encoded in ASCII.
The placeholder zero is used to align the hash computation for the different types of transactions.
+chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
h is the Pedersen hash
DECLARE transactionThe DECLARE transaction introduces new contract classes into the state of Starknet, enabling other contracts to deploy instances of those classes or use them in a library call. For more information, see contract classes.
| Field name | +Type | +Description | +||
|---|---|---|---|---|
|
+
|
+For future use. +Currently this value is always empty. +For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+The id of the chain to which the transaction is sent. |
+||
|
+
|
+The hash of the compiled class. For more information, see Class hash. |
+||
|
+
|
+The class definition. For more information, see Class hash. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+The transaction nonce. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+For future use. +Currently this value is always empty. +For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+
+
+Used for enabling the fee market. +
+
+A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction. +
+
|
+||
|
+
|
+The address of the account initiating the transaction. |
+||
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+||
|
+
|
+For future use. Currently this value is always |
+||
|
+
|
+
+
+The transaction’s version.
+
+Transaction version, where
+
|
+
The hash of a v3 DECLARE transaction is computed as follows:
declare_v3_tx_hash = h( + "declare", + version, + sender_address, + h(tip, l1_gas_bounds, l2_gas_bounds), + h(paymaster_data), + chain_id, + nonce, + data_availability_modes, + h(account_deployment_data), + class_hash, + compiled_class_hash +)+
Where:
+declare is a constant prefix string, encoded in ASCII.
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
l1_gas_bounds is constructed as follows:
l2_gas_bounds is constructed as follows:
data_availability_modes is a concatenation of fee_data_availability_mode
+and nonce_data_availability_mode, as follows:
h is the Poseidon hash.
class_hash is the hash of the contract class. See Class Hash
+for details about how the
+hash is computed
compiled_class_hash is the hash of the compiled class
+generated by the Sierra→Casm compiler that is used in Starknet
| Name | +Type | +Description | +
|---|---|---|
|
+
|
+The id of the chain to which the transaction is sent. |
+
|
+
|
+The (Cairo 1.0) class. |
+
|
+
|
+The hash of the compiled class (see here for more information) |
+
|
+
|
+The address of the account initiating the transaction. |
+
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+
|
+
|
+The maximum fee that the sender is willing to pay for the transaction. |
+
|
+
|
+The transaction nonce. |
+
|
+
|
+The transaction’s version. The value is 2. |
+
The hash of a v2 DECLARE transaction is computed as follows:
declare_v2_tx_hash = h( + "declare", + version, + sender_address, + 0, + h(class_hash), + max_fee, + chain_id, + nonce, + compiled_class_hash +)+
Where:
+h is the Poseidon hash function
class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed
compiled_class_hash is the hash of the compiled class generated by the Sierra→Casm compiler that is used in Starknet
This transaction version was used to declare Cairo 0 classes.
+| Name | +Type | +Description | +
|---|---|---|
|
+
|
+The class object. |
+
|
+
|
+The address of the account initiating the transaction. |
+
|
+
|
+The maximum fee that the sender is willing to pay for the transaction. |
+
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+
|
+
|
+The transaction nonce. |
+
|
+
|
+The transaction’s version. Possible values are 1 or 0. |
+
The hash of a v1 DECLARE transaction is computed as follows:
declare_v1_tx_hash = h( + "declare", + version, + sender_address, + 0, + h(class_hash), + max_fee, + chain_id, + nonce +)+
Where:
+declare is a constant prefix string, encoded in ASCII.
class_hash is the hash of the contract class. See Class Hash for details about how the hash is
+computed.
The placeholder zero is used to align the hash computation for the different types of transactions.
+chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
h is the Pedersen hash
This transaction version was used to declare Cairo 0 classes.
+The hash of a v0 DECLARE transaction is computed as follows:
declare_v0_tx_hash = h( + "declare", + version, + sender_address, + 0, + h(), + max_fee, + chain_id, + class_hash +)+
Where:
+declare is a constant prefix string, encoded in ASCII.
The placeholder zeros are used to align the hash computation for the different types of transactions.
+h is the Pedersen hash
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.
DEPLOY_ACCOUNT transactionSince StarkNet v0.10.1 the DEPLOY_ACCOUNT
+transaction replaces the DEPLOY transaction
+for deploying account contracts.
To use it, you should first pre-fund your new account address so that you can pay the
+transaction fee. You can then send the DEPLOY_ACCOUNT transaction.
For more information, see Deploying a new account.
+| Field name | +Type | +Description | +||
|---|---|---|---|---|
|
+
|
+The id of the chain to which the transaction is sent. |
+||
|
+
|
+The hash of the desired account class. For more information, see Class hash. |
+||
|
+
|
+The arguments to the account constructor. |
+||
|
+
|
+A random salt that determines the account address. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+The transaction nonce. |
+||
|
+
|
+For future use. +Currently this value is always For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+For future use. +Currently this value is always empty. +For more information, see SNIP 8: Transaction V3 Structure |
+||
|
+
|
+
+
+Used for enabling the fee market. +
+
+A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction. +
+
|
+||
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+||
|
+
|
+For future use. Currently this value is always |
+||
|
+
|
+
+
+The transaction’s version.
+
+Transaction version, where
+
|
+
The hash of a DEPLOY_ACCOUNT transaction is computed as follows:
deploy_account_v3_tx_hash = h( + "deploy_account", + version, + contract_address, + h(tip, l1_gas_bounds, l2_gas_bounds), + h(paymaster_data), + chain_id, + nonce, + data_availability_modes, + h(constructor_calldata), + class_hash, + contract_address_salt +)+
Where:
+deploy_account is a constant prefix string, encoded in ASCII.
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
l1_gas_bounds is constructed as follows:
l2_gas_bounds is constructed as follows:
data_availability_modes is a concatenation of fee_data_availability_mode
+and nonce_data_availability_mode, as follows:
h is the Poseidon hash.
class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.
contract_address is the address of the newly deployed account. For information on how this address is calculated, see Contract address.
| Name | +Type | +Description | +
|---|---|---|
|
+
|
+The hash of the desired account class. |
+
|
+
|
+The arguments to the account constructor. |
+
|
+
|
+A random salt that determines the account address. |
+
|
+
|
+Additional information given by the sender, used to validate the transaction. |
+
|
+
|
+The maximum fee that the sender is willing to pay for the transaction |
+
|
+
|
+The transaction nonce. |
+
|
+
|
+The transaction’s version. The value is 1. |
+
The hash of a DEPLOY_ACCOUNT transaction is computed as follows:
deploy_account_v1_tx_hash = h( + "deploy_account", + version, + contract_address, + 0, + h(class_hash, contract_address_salt, constructor_calldata), + max_fee, + chain_id, + nonce +)+
Where:
+deploy_account is a constant prefix string, encoded in ASCII.
The placeholder zero is used to align the hash computation for the different types of transactions.
+h is the Pedersen hash
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.
DEPLOY (unsupported) transaction hash calculationIf you need to retrieve the hash of an existing DEPLOY transaction, you can use this information to calculate the hash of the transaction.
Before you can calculate the transaction hash, get the deployed contract address. The DEPLOY transaction’s hash is calculated as shown in the following pseudo code:
deploy_tx_hash = h(
+ "deploy",
+ version,
+ contract_address,
+ sn_keccak("constructor"),
+ h constructor_calldata),
+ 0,
+ chain_id
+)
+Where:
+The placeholder zero is used to align the hash computation for the different types of transactions.
+deploy and constructor are constant strings encoded in ASCII.
h is the Pedersen hash and
+sn_keccak is Starknet Keccak.
chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.
contract_address is calculated as described here.
While Starknet does not have a specific signature scheme built into the protocol, the Cairo language, in which smart contracts are written, does have an efficient implementation for ECDSA signature with respect to a STARK-friendly curve.
+The generator used in the ECDSA algorithm is \(G=\left(g_x, g_y\right)\) where:
+\(g_x=874739451078007766457464989774322083649278607533249481151382481072868806602\) \(g_y=152666792071518830868575557812948353041420400780739481342941381225525861407\)
+Estimate the fees of transactions with the starknet_estimateFee API call, which is part of Starknet’s API v0.7.0 and above. For more information, see the Starknet JSON RPC specification. For more information on how to construct the appropriate resource_bounds based on the response of starknet_estimateFee, see How to use the new fee estimates? on the Starknet community forum.
Chain IDs are given as numbers, representing the ASCII encoding of specific constant strings, as illustrated by the following Python snippet:
+chain_id = int.from_bytes(value, byteorder="big", signed=False)The following constants are currently used. They correspond to the chain IDs that Starknet currently supports:
+SN_MAIN for Starknet’s main network.
SN_SEPOLIA for Starknet’s public testnet on Sepolia.
| + + | +
+
+
+Sepolia testnet replaces Goerli testnet. +
+
+Goerli testnet support is now removed. +
+
+For more information, including bridge support for Sepolia, see Starknet Goerli Deprecation in the Starknet Dev News newsletter. + |
+
| + + | +
+
+
+This topic previously appeared in the Starknet Book. + |
+
This topic explores the role and functionality of nodes in the Starknet ecosystem, their interactions with sequencers, and their overall importance.
+A node in the Starknet ecosystem is a computer equipped with Starknet software, contributing significantly to the network’s operation. Nodes are vital for the Starknet ecosystem’s functionality, security, and overall health. Without nodes, the Starknet network would not be able to function effectively.
+Nodes in Starknet are categorized into two types:
+Full nodes: Store the entire Starknet state and validate all transactions, crucial for the network’s integrity.
+Light nodes: Do not store the entire Starknet state but rely on full nodes for information. Light nodes are faster and more efficient but offer less security than full nodes.
+Nodes are fundamental to the Starknet network, performing a variety of critical functions:
+Transaction validation: Nodes ensure transactions comply with Starknet’s rules, helping prevent fraud and malicious activities.
+Block Creation and Propagation: Nodes create and circulate blocks to maintain a consistent blockchain view across the network.
+State maintenance: Nodes track the Starknet network’s current state, including user balances and smart contract code, essential for transaction processing and smart contract execution.
+API endpoint provision: Nodes provide API endpoints, aiding developers in creating applications, wallets, and tools for network interaction.
+Transaction relay: Nodes relay user transactions to other nodes, improving network performance and reducing congestion.
+Nodes and sequencers are interdependent:
+Nodes and block production: Nodes depend on sequencers to create blocks and update the network state. Sequencers integrate the transactions validated by nodes into blocks, maintaining a consistent and current Starknet state.
+Sequencers and transaction validation: Sequencers rely on nodes for transaction validation and network consensus. Prior to executing transactions, sequencers work with nodes to confirm transaction legitimacy, deterring fraudulent activities. Nodes also contribute to the consensus mechanism, ensuring uniformity in the blockchain state.
+The relationship between nodes and clients in the Starknet ecosystem is characterized by a client-server model:
+Client requests and node responses: Clients send requests, like transaction submissions or state queries. Nodes process these requests, validating transactions, updating the network state, and providing clients with the requested data.
+Client experience: Clients receive node responses, updating their local view with the latest network information. This loop enables user interaction with Starknet DApps, with nodes maintaining network integrity, while clients provide a user-friendly interface.
+The mempool acts as a holding area for unprocessed transactions:
+Transaction validation and mempool storage: Upon receiving a transaction, a node validates it. Valid transactions are added to the mempool and broadcast to other network nodes.
+Transaction selection and block inclusion: Nodes select transactions from the mempool for processing, incorporating them into blocks that are added to the blockchain.
+Each Starknet node implementation has its own strengths:
+Pathfinder, by Equilibrium: Pathfinder is a full node written in Rust. Pathfinder excels in high performance, scalability, and aligns with the Starknet Cairo specification.
+Juno, by Nethermind: Juno, is a full node written in Golang. Juno is known for user-friendliness, ease of deployment, and compatibility with Ethereum tools.
+Papyrus, by StarkWare: Papyrus is also a full node written in Rust. Papyrus focuses on security and robustness. It’s integral to the upcoming Starknet Sequencer, expected to boost network throughput.
+These implementations are continuously being improved, with new features and enhancements. The choice of implementation depends on user or developer preferences and requirements.
+Key characteristics of each node implementation are summarized below:
+| Node Implementation | +Language | +Strengths | +
|---|---|---|
Pathfinder |
+Rust |
+High performance, scalability, Cairo specification adherence |
+
Papyrus |
+Rust |
+Security, robustness, Starknet Sequencer foundation |
+
Juno |
+Golang |
+User-friendliness, ease of deployment, Ethereum compatibility |
+
| + + | +
+
+
+This topic previously appeared in the Starknet Book. + |
+
The only Prover in use on Starknet as of this writing is SHARP.
+SHARP is like public transportation for proofs on Starknet, aggregating multiple Cairo programs to save costs and boost efficiency. It uses recursive proofs, enabling parallelization and optimization, making it more affordable for all users. Critical services like the gateway, validator, and Prover work together with a stateless design for flexibility. SHARP’s adoption by StarkEx and Starknet highlights its significance and potential for future optimization.
+This topic discusses SHARP, how it has evolved to incorporate recursive proofs, and its role in reducing costs and improving efficiency within the Starknet network.
+SHARP, which stands for Shared Prover, is a mechanism that aggregates multiple Cairo programs from different users, each containing different logic. These Cairo programs are then executed together, generating a single proof common to all the programs. Rather than sending the proof directly to the Solidity Verifier in Ethereum, it is initially sent to a STARK Verifier program written in Cairo. The STARK Verifier generates a new proof to confirm that the initial proofs were verified, which can be sent back into SHARP and the STARK Verifier. Details for this recursive proof process appear below. Ultimately, the last proof in the series is sent to the Solidity Verifier on Ethereum. In other words, there are many proofs generated until we reach Ethereum and the Solidity Verifier.
+The primary benefit of SHARP lies in its ability to decrease costs and enhance efficiency within the Starknet network. It achieves this by aggregating multiple Cairo jobs, which are individual sets of computation. This aggregation enables the protocol to leverage the exponential amortization offered by STARK proofs.
+Exponential amortization means that as the computational load of the proofs increases, the cost of verifying those proofs rises at a slower logarithmic rate than the computation increase. As a result, the cost of each transaction within the aggregated set is significantly reduced, making the overall process more cost-effective and accessible for users.
+| + + | +
+
+
+In the context of SHARP and Cairo context, a jobs refer to the individual Cairo programs or tasks submitted by different users. These jobs contain specific logic or computations that must be executed on the Starknet network. + |
+
Additionally, SHARP enables smaller users with limited computation to benefit from joining other jobs and share the cost of generating the proofs. This collaborative approach is similar to using public transportation instead of a private car, where the cost is distributed among all participants, making it more affordable for everyone.
+One of the most powerful features of SHARP is its use of recursive proofs. Rather than directly sending the generated proofs to the Solidity Verifier, they are first sent to a STARK Verifier program written in Cairo. This Verifier, which is also a Cairo program, receives the proof and creates a new Cairo job that is sent to the Prover. The Prover then generates a new proof to confirm that the initial proofs were verified. These new proofs can be sent back into SHARP and the STARK Verifier, restarting the process.
+This process continues recursively, with each new proof being sent to the Cairo Verifier until a trigger is reached. At this point, the last proof in the series is sent to the Solidity Verifier on Ethereum. This approach enables greater parallelization of the computation and reduces the time and cost associated with generating and verifying proofs.
+Generated Proofs +￬ +STARK Verifier program (in Cairo) +￬ +Cairo Job +￬ +Prover +￬ +New Proof Generated +￬ +Repeat Process +￬ +Trigger Reached (last proof) +￬ +Solidity Verifier |
+
At first glance, recursive proofs may seem more complex and time-consuming. However, there are several benefits to this approach:
+Parallelization: Recursive proofs enable work parallelization, reducing user latency and improving SHARP efficiency.
+Cheaper onchain costs: Parallelization enables SHARP to create larger proofs, which were previously dependent on the limited availability of large cloud machines. As a result, onchain costs are reduced.
+Lower cloud costs: Since each job is shorter, the required memory for processing is reduced, resulting in lower cloud costs.
+Optimization: Recursive proofs enable SHARP to optimize for various factors, including latency, onchain costs, and time to proof.
+Cairo support: Recursive proofs only require support in Cairo, without the need to add support in the Solidity Verifier.
+| + + | +
+
+
+Latency in Starknet encompasses the time taken for processing, confirming, and including transactions in a block. Latency is affected by factors like network congestion, transaction fees, and system efficiency. Minimizing latency ensures faster transaction processing and user feedback. +
+
+Time to proof, however, specifically pertains to the amount of time required to generate and verify cryptographic proofs for transactions or operations. + |
+
SHARP’s backend architecture consists of several services that work together to process Cairo jobs and generate proofs. These services include:
+Gateway: Cairo jobs enter SHARP through the gateway.
+Job Creator: This service prevents job duplication and ensures that the system operates consistently, regardless of multiple identical requests.
+Validator: The validator service runs validation checks on each job, ensuring they meet the requirements and can fit within the Prover machines. Invalid jobs are tagged as such and do not proceed to the Prover.
+Scheduler: The scheduler service creates trains that aggregate jobs and send them to the Prover. Recursive jobs are paired and sent to the Prover together.
+Cairo Runner: This service runs Cairo for the Prover’s needs. The Cairo Runner service runs Cairo programs, executing the necessary computations and generating the execution trace as an intermediate result. The Prover then uses this execution trace.
+Prover: The Prover computes the proofs for each train.
+Dispatcher: The Dispatcher serves two functions in the SHARP system.
+In the case of a recursive proof, the Dispatcher runs the Cairo Verifier program on the proof it has received from the Prover, resulting in a new Cairo job that goes back to the Validator.
+In the case of a proof that is to be published onchain, the Dispatcher creates packages from the proof, which can then be sent to the Blockchain Writer.
+Blockchain Writer: Once the packages have been created by the Dispatcher, they are sent to the Blockchain Writer. The Blockchain Writer is responsible for sending the packages to the appropriate blockchain, such as Ethereum, for verification. This step in the SHARP system ensures that the proofs are properly verified and that the transactions are securely recorded on the blockchain.
+Catcher: The Catcher monitors onchain transactions to ensure that they have been accepted. While the Catcher is relevant for internal monitoring purposes, be aware that if a transaction fails, the fact won’t be registered onchain in the Fact Registry. As a result, the soundness of the system is still preserved even without the Catcher.
+SHARP is designed to be stateless. That is, each Cairo job is executed in its own context and has no dependency on other jobs, enabling greater flexibility in processing jobs.
+Currently, the primary users of SHARP include:
+StarkEx
+Starknet
+Optimizing the Prover involves the numerous challenges and potential projects on which the Starkware team and the community are currently working, including:
+Exploring more efficient hash functions for Cairo, the Prover, and Solidity.
+Investigating smaller fields for recursive proof steps could lead to more efficient computations.
+Adjusting various parameters of the STARK protocol, such as FRI parameters and block factors.
+Optimizing the Cairo code to make it faster, resulting in a faster recursive Prover.
+Developing dynamic layouts, which should enable Cairo programs to scale resources as needed.
+Improving scheduling algorithm. This optimization path is external to the Prover.
+Dynamic layouts enable SHARP to determine and scale the required resources for a specific job and adjust the layout accordingly, instead of relying on predefined layouts with fixed resources. Scaling resources can lead to more efficient computation and better resource utilization. This approach can provide tailored solutions for each job, improving overall efficiency.
+In conclusion, SHARP is a critical component of Starknet’s architecture, providing a more efficient and cost-effective solution for processing Cairo programs and verifying their proofs. By leveraging the power of STARK technology and incorporating recursive proofs, SHARP plays a vital role in improving the overall performance and scalability of the Starknet network. The stateless nature of SHARP and the reliance on the cryptographic soundness of the STARK proving system make it an innovative and valuable addition to the blockchain ecosystem.
+Before Starknet Alpha v0.11.0 a developer would write contracts in Cairo 0 and compile them locally to Cairo assembly (or Casm for short).
+Next, the developer would submit the compilation output, the contract class, to the Starknet sequencer via a DECLARE transaction.
Starting with Cairo 1.0, the contract class resulting from compiling Cairo 1.0 does not include Casm. Instead of Casm, it includes instructions in an intermediate representation called Safe Intermediate Representation, Sierra for short. +This new contract class is then compiled by the sequencer, via the Sierra → Casm compiler, to generate the Cairo assembly associated with this class. The Casm code is then executed by the Starknet OS.
+Starknet is a validity rollup, which means that the execution inside every block needs to be proven, and this is where STARKs come in handy. +However, STARK proofs can address statements that are formulated in the language of polynomial +constraints, and have no knowledge of smart contract execution. +To overcome this gap, we developed Cairo.
+Cairo instructions, previously referred to as Casm, are translated to polynomial constraints that enforce the correct execution of a program according to the Cairo semantics defined in Cairo-a Turing-complete STARK-friendly CPU architecture.
+Thanks to Cairo, we can formulate the statement "This Starknet block is valid" in a way that we can prove. +Be aware that we can only prove things about Casm. That is, regardless of what the user sends to the Starknet sequencer, what’s proven is the correct Casm execution.
+This means that we need a way to translate Sierra into Casm, and this is achieved with the Sierra → Casm compiler.
+To understand why we chose to add an additional layer between the code that the user writes (Cairo 1.0) and the code that is being proven (Casm), +we need to consider more components in the system, and the limitations of Cairo.
+A crucial property of every decentralized L2 is that the sequencers are guaranteed to be compensated for the work they do. +The notion of reverted transactions is a good example: even if the user’s transaction failed mid execution, the sequencer should be able to include it in a block and charge execution fees up to the point of failure.
+If the sequencer cannot charge for such transactions, then sending transactions that will eventually fail (after a lot of computation steps) is an obvious DoS attack on the sequencer. +The sequencer cannot look at a transaction and conclude that it would fail without actually doing the work (this is equivalent to solving the halting problem).
+The obvious solution to the above predicament is to include such transactions in the block, similar to Ethereum. However, this may not be as simple to do in a validity rollup. +With Cairo 0, there is no separating layer between user code and what is being proven.
+This means that users can write code which is unprovable in some cases. In fact, such code is very easy to write, e.g. assert 0=1 is a valid
+Cairo instruction that cannot be proven, as it translates to polynomial constraints that are not satisfiable. Any Casm execution that contains this instruction cannot be proven.
+Sierra is the layer between user code and the provable statement, that allows us to make sure all transactions are eventually provable.
The method by which Sierra guarantees that user code is always provable is by compiling Sierra instructions to a subset of Casm, which we call "safe Casm".
+The important property that we require from safe Casm is being provable for all inputs. A canonical example for safe Casm is using if/else instructions instead of assert, that is, making sure all failures are
+graceful.
To better understand the considerations that go into designing the Sierra → Casm compiler,
+consider the find_element function from the common library of Cairo 0:
func find_element{range_check_ptr}(array_ptr: felt*, elm_size, n_elms, key) -> (elm_ptr: felt*) {
+ alloc_locals;
+ local index;
+ %{
+ ...
+ %}
+ assert_nn_le(a=index, b=n_elms - 1);
+ tempvar elm_ptr = array_ptr + elm_size * index;
+ assert [elm_ptr] = key;
+ return (elm_ptr=elm_ptr);
+}| + + | +
+
+
+Below we abuse the "Casm" notation by not distinguishing Cairo 0 from Casm and referring to the +above as Casm (while we actually refer to the compilation result of the above). + |
+
For brevity, we have omitted the hint in the above snippet, but it’s clear that this function can only execute correctly if the requested element exists in the array (otherwise it would fail for every possible hint -
+there is nothing we can substitute index for, that makes the following lines run successfully).
Such Casm cannot be generated by the Sierra→Casm compiler. +Furthermore, simply replacing the assertion with an if/else statement doesn’t do, as this results in non-deterministic execution. That is, for the same input, different hint values can yield different results. +A malicious prover can use this freedom to harm the user - in this example, they are able to make it seem as if an element isn’t part of the array, even though it actually is.
+The safe Casm for finding an element in an array behaves like the above snippet in the happy flow (element is there): an index is given in a hint, and we verify that the array at the hinted index contains the requested element. +However, in the unhappy flow (element isn’t there), we must go over the entire array to verify this.
+This was not the case in Cairo 0, as we were fine with certain paths not being provable (in the above snippet, the unhappy flow in which the element isn’t in the array is never provable).
+| + + | +
+
+
+Sierra’s gas metering adds further complications to the above example. Even looking through the array to verify that the element isn’t there may leave some flexibility to the prover. +
+
+If we take gas limitations into consideration, the user may have enough gas for the happy flow, but not for the unhappy one, making the execution stop mid-search, and allowing the prover to get away with lying about the element not being present. +
+
+The way we plan to handle this is by requiring the user to have enough gas for the unhappy flow before actually calling |
+
Smart contracts written with Cairo 1.0 cannot contain user defined hints. This is already true with Cairo 0 contracts (only whitelisted hints are accepted), but with Cairo 1.0 the hints in use are +determined by the Sierra → Casm compiler. Since this compilation is there to ensure that only +"safe" Casm is generated, there is no room for hints that are not generated by the compiler.
+In the future, native Cairo 1.0 may contain hint syntax similar to Cairo 0, but it will not be available in Starknet smart contracts (L3s on top of Starknet may make use of such functionality). +Note that this is currently not part of Starknet’s roadmap.
+Builtins in Cairo are predefined optimized low-level execution units that the Cairo VM refers to in order to perform predefined computations that are expensive to perform in standard Cairo. Builtins enhance the functionality of the Cairo VM, enabling you to perform certain tasks, such as using the Poseidon hash, range-checks, or ECDSA signature verifications, more efficiently, using fewer trace cells.
+In contrast to CairoZero, where you needed to consciously write code to take advantage of builtin optimizations, in Cairo, you simply write code without doing anything special, and when the Cairo VM executes the code, certain operations use builtins internally to optimize your program.
+| Name of builtin | +Description | +
|---|---|
Pedersen |
+Computes the Pedersen hash over two elements. Used internally in |
+
Poseidon |
+Computes the Hades permutation on three field elements. Used internally in |
+
Range check |
+
+
+Checks whether a field element is in the range [0,2128-1]. +
+
+Used when instantiating and comparing the various integer types. +
+ All arithmetic comparisons use the range check builtin. + |
+
ECDSA |
+Verifies the validity of an ECDSA signature over the STARK curve. +This is used in CairoZero, but is not used in Cairo because it fails on invalid signatures. In Cairo ECDSA verification is performed with high-level code, applying the |
+
Keccak |
+Computes the keccak-f[1600] permutation. For more information see Keccak page on the Keccak Team site. +For high level Cairo keccak functions that use this builtin internally, see |
+
Bitwise |
+Computes the bitwise operations Used internally when performing bitwise operations using the ` |
+
|
+EC_OP |
+
The class hash is a hash chain of the components that define the class.
+Classes written in Cairo are compiled into Sierra code. The Sierra code generated is an intermediate representation of the class. This new contract class is then compiled by the sequencer, via the Sierra → Casm compiler, to generate the Cairo +assembly associated with this class. The resulting Casm code is then executed by the Starknet OS.
+For information on how the compiler converts code from Cairo to Sierra, see Cairo and Sierra.
+The components that define a class are:
+| +contract_class_version + | +
+ The version of the contract class object. Currently, the Starknet OS +supports version 0.1.0 + |
+||
| +Array of external functions entry points + | +
+ An entry point is a pair
+
+
|
+||
| +Array of L1 handlers entry points + | +
+ - + |
+||
| +Array of constructors entry points + | +
+ Currently, the compiler allows only one constructor. + |
+||
| +ABI + | +
+ A string representing the ABI of the class. The ABI hash (which affects the class hash) is given by: +
+
+
+
+
+
+
|
+||
| +Sierra program + | +
+ An array of field elements representing the Sierra instructions. + |
+
The hash of the class is the chain hash of its components, computed as follows:
+class_hash = ℎ(
+ contract_class_version,
+ external_entry_points,
+ l1_handler_entry_points,
+ constructor_entry_points,
+ abi_hash,
+ sierra_program_hash
+)Where
+| + + | +
+
+
+The Starknet OS currently supports contract class version 0.1.0, which is represented in the above hash computation as the ASCII encoding of the string |
+
For more details, see the Cairo implementation.
+The compiled class hash is a cryptographic hash that results from the compilation process of a Cairo class
+from its intermediate representation (Sierra) to Cairo assembly (Casm). This process is managed by the Sierra→Casm compiler.
+The compiled class hash is crucial for ensuring the uniqueness and integrity of compiled classes within Starknet. Whether you are a developer deploying contracts or a party interested in the inner workings of Starknet’s state commitment, understanding the compiled class hash is essential.
+For developers, the hash is an important part of the contract declaration process, ensuring that each compiled class is uniquely identifiable and verifiable. For those involved in maintaining the network, it contributes to the efficiency and performance of Starknet by optimizing the state commitment process.
+The state commitment uses the Sierra code that results when compiling Cairo classes. Sierra acts as an intermediate representation between Cairo and Casm. Provers, however, operate solely with Casm.
+In order to avoid recompiling, from Sierra to Casm, each block in which the class is deployed, the state commitment gets the information it needs about the corresponding Casm from the the information contained in the compiled class hash.
+When declaring a contract, the party administering the contract endorses the compiled class hash, procured using an SDK, as an integral component of the DECLARE transaction. Following the inclusion of the transaction in a block, the compiled class hash integrates into the state commitment.
Uniqueness: The compiled class hash ensures the uniqueness of each compiled class. It is essentially a fingerprint for the compiled output, allowing the network to verify the integrity and uniqueness of the class.
+State Commitment: In Starknet, state commitment includes various components, including the Cairo classes. These classes are initially defined using Sierra. However, for the prover to function efficiently, it requires Casm.
+Efficiency: By including the compiled class hash in the state commitment, Starknet avoids the need to recompile from Sierra to Casm in every block where the class is used. This optimization significantly enhances the network’s efficiency and performance.
+When a new contract is declared on Starknet, the compiled class hash plays a pivotal role. Here’s how:
+Declaration Process: The party declaring the contract computes the compiled class hash using an SDK provided by Starknet.
+DECLARE Transaction: This hash is then included as part of the DECLARE transaction is a specific type of transaction in Starknet used to register new contracts.
Inclusion in State Commitment: Once the DECLARE transaction is included in a block, the compiled class hash becomes part of the state commitment. This inclusion ensures that the network recognizes and stores the unique compiled output of the contract.
Prospectively, as Sierra-to-Casm compilation integrates into the Starknet OS, the value might undergo updates via proof of the Sierra-to-Casm compiler execution. Such verification demonstrates that compiling the same class with an updated compiler version yields a fresh compiled class hash. +The compiled class hash is a basic element in Starknet’s architecture, enabling efficient state commitment and ensuring the integrity and uniqueness of compiled classes.
+A contract ABI is a representation of a Starknet contract interface. It is formatted as JSON and describes the functions, structs and events which are defined in the contract.
+You can get the contract’s ABI by using starknet-compile:
cargo run --bin starknet-compile -- --single-file </path/to/input.cairo> </path/to/output.json>The following is an example contract ABI:
+Cairo v2
+Cairo v1
+[
+ {
+ "type": "impl",
+ "name": "CounterContract",
+ "interface_name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract"
+ },
+ {
+ "type": "interface",
+ "name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract",
+ "items": [
+ {
+ "type": "function",
+ "name": "increase_counter",
+ "inputs": [
+ {
+ "name": "amount",
+ "type": "core::integer::u128"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "decrease_counter",
+ "inputs": [
+ {
+ "name": "amount",
+ "type": "core::integer::u128"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "get_counter",
+ "inputs": [],
+ "outputs": [
+ {
+ "type": "core::integer::u128"
+ }
+ ],
+ "state_mutability": "view"
+ }
+ ]
+ },
+ {
+ "type": "constructor",
+ "name": "constructor",
+ "inputs": [
+ {
+ "name": "initial_counter",
+ "type": "core::integer::u128"
+ },
+ {
+ "name": "other_contract_addr",
+ "type": "core::starknet::contract_address::ContractAddress"
+ }
+ ]
+ },
+ {
+ "type": "event",
+ "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased",
+ "kind": "struct",
+ "members": [
+ {
+ "name": "amount",
+ "type": "core::integer::u128",
+ "kind": "data"
+ }
+ ]
+ },
+ {
+ "type": "event",
+ "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased",
+ "kind": "struct",
+ "members": [
+ {
+ "name": "amount",
+ "type": "core::integer::u128",
+ "kind": "data"
+ }
+ ]
+ },
+ {
+ "type": "event",
+ "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::Event",
+ "kind": "enum",
+ "variants": [
+ {
+ "name": "CounterIncreased",
+ "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased",
+ "kind": "nested"
+ },
+ {
+ "name": "CounterDecreased",
+ "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased",
+ "kind": "nested"
+ }
+ ]
+ }
+][
+ {
+ "type": "function",
+ "name": "constructor",
+ "inputs": [
+ {
+ "name": "name_",
+ "type": "core::felt252"
+ },
+ {
+ "name": "symbol_",
+ "type": "core::felt252"
+ },
+ {
+ "name": "decimals_",
+ "type": "core::integer::u8"
+ },
+ {
+ "name": "initial_supply",
+ "type": "core::integer::u256"
+ },
+ {
+ "name": "recipient",
+ "type": "core::starknet::contract_address::ContractAddress"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "get_name",
+ "inputs": [],
+ "outputs": [
+ {
+ "type": "core::felt252"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "get_symbol",
+ "inputs": [],
+ "outputs": [
+ {
+ "type": "core::felt252"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "get_decimals",
+ "inputs": [],
+ "outputs": [
+ {
+ "type": "core::integer::u8"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "get_total_supply",
+ "inputs": [],
+ "outputs": [
+ {
+ "type": "core::integer::u256"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "balance_of",
+ "inputs": [
+ {
+ "name": "account",
+ "type": "core::starknet::contract_address::ContractAddress"
+ }
+ ],
+ "outputs": [
+ {
+ "type": "core::integer::u256"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "allowance",
+ "inputs": [
+ {
+ "name": "owner",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "spender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ }
+ ],
+ "outputs": [
+ {
+ "type": "core::integer::u256"
+ }
+ ],
+ "state_mutability": "view"
+ },
+ {
+ "type": "function",
+ "name": "transfer",
+ "inputs": [
+ {
+ "name": "recipient",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "amount",
+ "type": "core::integer::u256"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "transfer_from",
+ "inputs": [
+ {
+ "name": "sender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "recipient",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "amount",
+ "type": "core::integer::u256"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "approve",
+ "inputs": [
+ {
+ "name": "spender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "amount",
+ "type": "core::integer::u256"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "increase_allowance",
+ "inputs": [
+ {
+ "name": "spender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "added_value",
+ "type": "core::integer::u256"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "function",
+ "name": "decrease_allowance",
+ "inputs": [
+ {
+ "name": "spender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "subtracted_value",
+ "type": "core::integer::u256"
+ }
+ ],
+ "outputs": [],
+ "state_mutability": "external"
+ },
+ {
+ "type": "event",
+ "name": "Transfer",
+ "inputs": [
+ {
+ "name": "from",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "to",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "value",
+ "type": "core::integer::u256"
+ }
+ ]
+ },
+ {
+ "type": "event",
+ "name": "Approval",
+ "inputs": [
+ {
+ "name": "owner",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "spender",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "value",
+ "type": "core::integer::u256"
+ }
+ ]
+ }
+]With Cairo v2.3.0 the limitations on the Event enum have been relaxed, allowing more flexibility on the events that can be emitted from a given contract.
For example:
+It is no longer enforced that the Event enum variants are structs of the same name as the variant, they can now be a struct or an enum of any name.
Enum variants inside event ABI entries (entries in the abi with "type": "event" and "kind": "enum") now have two possible kinds. Before v2.3.0 it was always "kind": "nested", now "kind: "flat" is also possible.
v2.3.0 is backward compatible with version ≥ 2.0.0 ABI, so the same structure of the ABI is kept, while allowing flexibility.
| + + | +
+
+
+Between versions
+
+With |
+
To illustrate this, consider the following example:
+//high-level code defining the events
+
+#[event]
+#[derive(Drop, starknet::Event)]
+enum Event {
+ ComponentEvent: test_component::Event,
+ TestCounterIncreased: CounterIncreased,
+ TestCounterDecreased: CounterDecreased,
+ TestEnum: MyEnum
+}
+
+#[derive(Drop, starknet::Event)]
+struct CounterIncreased {
+ amount: u128
+}
+
+#[derive(Drop, starknet::Event)]
+struct CounterDecreased {
+ amount: u128
+}
+
+#[derive(Copy, Drop, starknet::Event)]
+enum MyEnum {
+ Var1: MyStruct
+}
+
+#[derive(Copy, Drop, Serde, starknet::Event)]
+struct MyStruct {
+ member: u128
+}In v2.3.0 enum variant types can now have any name.
As an example the TestCounterIncreased variant and the CounterIncreased type, as they appear in the ABI:
{
+ "type": "event",
+ "name": "<namespace>::Event",
+ "kind": "enum",
+ "variants": [
+ {
+ "name": "ComponentEvent",
+ "type": "<namespace>::test_component::Event",
+ "kind": "nested"
+ },
+ {
+ "name": "TestCounterIncreased",
+ "type": "<namespace>::CounterIncreased",
+ "kind": "nested"
+ },
+ {
+ "name": "TestCounterDecreased",
+ "type": "<namespace>::CounterDecreased",
+ "kind": "nested"
+ },
+ {
+ "name": "TestEnum",
+ "type": "<namespace>::MyEnum",
+ "kind": "nested"
+ }
+ ]
+},
+{
+ "type": "event",
+ "name": "<namespace>::CounterIncreased",
+ "kind": "struct",
+ "members": [
+ {
+ "name": "amount",
+ "type": "core::integer::u128",
+ "kind": "data"
+ }
+ ]
+}When the contract emits the TestCounterIncreased event, for example by writing self.emit(CounterIncreased { amount })), the event that is emitted has the following keys and data:
One key based on the variant name: sn_keccak(TestCounterIncreased). This information only appears in the <namespace>::Event type entry in the ABI,
+as the name TestCounterIncreased does not appear in the "kind": "struct" ABI entry. This did not matter in previous versions when the variant name and type had to be equal.
One data element based on the struct CounterIncreased which is associated with TestCounterIncreased via one of the Event type variants.
The introduction of components allows variants of Event to be enums.
+In the following example, we have two such variants: TestEnum (unrelated to components) and ComponentEvent.
The serialization to keys and data is the same in both cases, so this example will focus on TestEnum:
This example shows the TestEnum variant entry inside Event:
{
+"name": "TestEnum",
+"type": "<namespace>::MyEnum",
+"kind": "nested"
+}This example shows the MyEnum event entry:
{
+ "type": "event",
+ "name": "<namespace>::MyEnum",
+ "kind": "enum",
+ "variants": [
+ {
+ "name": "Var1",
+ "type": "<namespace>::MyStruct",
+ "kind": "nested"
+ }
+ ]
+}This example shows the MyStruct event entry:
{
+ "type": "event",
+ "name": "<namespace>::MyStruct",
+ "kind": "struct",
+ "members": [
+ {
+ "name": "member",
+ "type": "core::integer::u128",
+ "kind": "data"
+ }
+ ]
+}| + + | +
+
+
+If a |
+
When the event is emitted, the serialization to keys and data happens as follows:
+Since the TestEnum variant has kind nested, add the first key: sn_keccak(TestEnum), and the rest of the serialization to keys and data is done recursively via the starknet::event trait implementation of MyEnum.
Next, you can handle a "kind": "nested" variant (previously it was TestEnum, now it’s Var1), which means you can add another key depending on the sub-variant: sn_keccak(Var1), and proceed to serialize according to the starknet::event
+implementation of MyStruct.
Finally, proceed to serialize MyStruct, which gives us a single data member.
This results in keys = [sn_keccak(TestEnum), sn_keccak(Var1)] and data=[5]
| + + | +
+
+
+Allowing variants that are themselves enums ( |
+
For example, if the high level code is changed to:
+#[event]
+#[derive(Drop, starknet::Event)]
+enum Event {
+ ComponentEvent: test_component::Event,
+ TestCounterIncreased: CounterIncreased,
+ TestCounterDecreased: CounterDecreased,
+ TestEnum: MyEnum
+}
+
+#[derive(Copy, Drop, starknet::Event)]
+enum MyEnum {
+ Var1: AnotherEnum
+}
+
+#[derive(Copy, Drop, Serde, starknet::Event)]
+enum AnotherEnum {
+ Var2: MyStruct
+}
+
+#[derive(Copy, Drop, Serde, starknet::Event)]
+struct MyStruct {
+ member: u128,
+}then self.emit(Event::TestEnum(MyEnum::Var1(AnotherEnum::Var2(MyStruct { member: 5 }))))
+(as before, Into implementations can shorten this) will emit an event with keys = [sn_keccak(TestEnum), sn_keccak(Var1), sn_keccak(Var2)] and data=[5].
This will look as follows in the ABI (only the relevant parts are shown):
+{
+ "type": "event",
+ "name": "<namespace>::Event",
+ "kind": "enum",
+ "variants": [
+ // ignoring all the other variants for brevity
+ {
+ "name": "TestEnum",
+ "type": "<namespace>::MyEnum",
+ "kind": "nested"
+ }
+ ]
+},
+{
+ "type": "event",
+ "name": "<namespace>::MyEnum",
+ "kind": "enum",
+ "variants": [
+ {
+ "name": "Var1",
+ "type": "<namespace>::AnotherEnum",
+ "kind": "nested"
+ }
+ ]
+},
+{
+ "type": "event",
+ "name": "<namespace>::AnotherEnum",
+ "kind": "enum",
+ "variants": [
+ {
+ "name": "Var2",
+ "type": "<namespace>::MyStruct",
+ "kind": "nested"
+ }
+ ]
+}As TestEnum, Var1 and Var2 are of kind nested, a selector should be added to the list of keys, before continuing to recursively serialize.
You might not want to nest enums when serializing the event. For example, if you write an ERC-20 as a component, not a contract, that is pluggable anywhere, you might not want the contract to modify the keys of known events such as Transfer.
To avoid nesting, write the following high level code:
+#[event]
+#[derive(Drop, starknet::Event)]
+enum Event {
+ ComponentEvent: test_component::Event,
+ TestCounterIncreased: CounterIncreased,
+ TestCounterDecreased: CounterDecreased,
+ #[flat]
+ TestEnum: MyEnum
+}By writing the above, the TestEnum variant entry in the ABI will change to:
{
+"name": "TestEnum",
+"type": "<namespace>::MyEnum",
+"kind": "flat"
+}This means that self.emit(Event::TestEnum(MyEnum::Var1(MyStruct {member: 5}))) will emit an event with keys=[sn_keccak(Var1)] and data=[5].
With the transition to v2.0.0, the contract ABI underwent some changes.
Consider the following high level code that generates the ABI in the following example:
+#[starknet::interface]
+trait IOtherContract<TContractState> {
+ fn decrease_allowed(self: @TContractState) -> bool;
+}
+
+#[starknet::interface]
+trait ICounterContract<TContractState> {
+ fn increase_counter(ref self: TContractState, amount: u128);
+ fn decrease_counter(ref self: TContractState, amount: u128);
+ fn get_counter(self: @TContractState) -> u128;
+}
+
+#[starknet::contract]
+mod counter_contract {
+ use starknet::ContractAddress;
+ use super::{
+ IOtherContractDispatcher, IOtherContractDispatcherTrait, IOtherContractLibraryDispatcher
+ };
+
+ #[storage]
+ struct Storage {
+ counter: u128,
+ other_contract: IOtherContractDispatcher
+ }
+
+ #[event]
+ #[derive(Drop, starknet::Event)]
+ enum Event {
+ CounterIncreased: CounterIncreased,
+ CounterDecreased: CounterDecreased
+ }
+
+ #[derive(Drop, starknet::Event)]
+ struct CounterIncreased {
+ amount: u128
+ }
+
+ #[derive(Drop, starknet::Event)]
+ struct CounterDecreased {
+ amount: u128
+ }
+
+ #[constructor]
+ fn constructor(
+ ref self: ContractState, initial_counter: u128, other_contract_addr: ContractAddress
+ ) {
+ self.counter.write(initial_counter);
+ self
+ .other_contract
+ .write(IOtherContractDispatcher { contract_address: other_contract_addr });
+ }
+
+ #[external(v0)]
+ impl CounterContract of super::ICounterContract<ContractState> {
+ fn get_counter(self: @ContractState) -> u128 {
+ self.counter.read()
+ }
+
+ fn increase_counter(ref self: ContractState, amount: u128) {
+ let current = self.counter.read();
+ self.counter.write(current + amount);
+ self.emit(CounterIncreased { amount });
+ }
+
+ fn decrease_counter(ref self: ContractState, amount: u128) {
+ let allowed = self.other_contract.read().decrease_allowed();
+ if allowed {
+ let current = self.counter.read();
+ self.counter.write(current - amount);
+ self.emit(CounterDecreased { amount });
+ }
+ }
+ }
+}Since the CounterContract impl is annotated with the #[external(v0)] attribute, you’ll find the following impl entry in the ABI:
{
+ "type": "impl",
+ "name": "CounterContract",
+ "interface_name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract"
+}
+----This means that every function appearing in the ICounterContract interface
+is a possible entry point of the contract.
| + + | +
+
+
+Standalone functions in the contract outside an external |
+
In Cairo v2, a dedicated type for the contract’s events was introduced. Currently, the contract event type must be an enum named Event, whose variants are structs of the same name as the variant. Types that can be emitted via self.emit(_) must implement the Event trait, which defines how this type should be serialized into two felt252 arrays, keys and data.
The Event enum variants appear in the ABI under "type" = "event" rather than regular structs.
For such entries, each member has an additional kind field that specifies how the serialization into keys and data takes place:
If the kind is key, then this member or variant are serialized into the event’s keys.
If the kind is data, then this member or variant are serialized into the event’s data.
If the kind is nested, then the member or variant are serialized according to the Event attribute, potentially adding to both keys and data.
| + + | +
+
+
+This feature is not yet supported, so no high level code written in Cairo |
+
You can find a JSON schema specification of the ABI in the starknet-specs repository.
For a UI-friendly version, you can use the OPEN-RPC playground.
+The contract address is a unique identifier of the contract on Starknet. It is a chain hash of the following information:
+
+prefix
+ |
+
+ The ASCII encoding of the constant string |
+
+deployer_address
+ |
+
+ One of the following: +
+
+
|
+
+salt
+ |
+
+ The salt passed by the contract calling the syscall, provided by the transaction sender. + |
+
+class_hash
+ |
++ + | +
+constructor_calldata_hash
+ |
+
+ Array hash of the inputs to the constructor. + |
+
The address is computed as follows:
+contract_address = pedersen(
+ “STARKNET_CONTRACT_ADDRESS”,
+ deployer_address,
+ salt,
+ class_hash,
+ constructor_calldata_hash)| + + | +
+
+
+A random
+
+It also thwarts replay attacks by influencing the transaction hash with a unique sender address. + |
+
For more information on the address computation, see contract_address.cairo in the Cairo code repository.
+As in object-oriented programming, Starknet distinguishes between a contract and its implementation by separating contracts into classes and instances.
+A contract class is the definition of a contract. It includes Cairo byte code, hint information, entry point names, and everything that defines its semantics.
+Each class is uniquely identified by its class hash, comparable to a class name in traditional object-oriented programming languages.
+A contract instance is a deployed contract that corresponds to a class. Only contract instances act as true contracts, in that they have their own storage and can be called by transactions or other contracts.
+A contract class does not necessarily have a deployed instance in Starknet.
+| + + | +
+
+
+A contract class does not necessarily require a deployed instance in Starknet. + |
+
A contract instance has a nonce, the value of which is the number of transactions originating from this address plus 1. For example, when you deploy an account with a DEPLOY_ACCOUNT transaction, the nonce of the account contract in the transaction is 0. After the DEPLOY_ACCOUNT transaction, until the account contract sends its next transaction, the nonce is 1.
| +Adding new classes + | +
+ To introduce new classes to Starknet’s state, use the |
+
| +Deploying instances + | +
+ To deploy a new instance of a previously declared class, use the |
+
| +Using class functionality + | +
+ To use the functionality of a declared class without deploying an instance, use the |
+
The contract’s storage is a persistent storage space where you can read, write, modify, and persist data. The storage is a map with \(2^{251}\) slots, where each slot is a felt which is initialized to 0.
+The basic function for writing to storage writes, value to key is:
+storage_write_syscall(address_domain, address, value)storage_read is a basic function that is used for getting the storage address, this function is created by the compiler when defining a storage variable, as explained below. This function returns the address of the storage variable. Below we discuss
+how this
+address is determined from the variable’s name and keys.
Both storage_read and storage_write are system calls that can be imported by adding the line:
use starknet::syscalls::storage_read_syscall;
+use starknet::syscalls::storage_write_syscall;The most common way to interact with a contract’s storage is through storage variables.
+The #[storage] attribute above the Storage struct declares that the contents of this struct are part of the contract storage. The storage variables stored inside this struct can consist of a single felt, or it can be a mapping from multiple arguments to a tuple of felts or structs.
To use this variable, the var.read(args), var.write(args, value) and var.address(args) functions are automatically created by the #[storage] attribute, for reading the storage value, writing the storage value and getting the storage address, respectively.
The Starknet contract compiler generates the Cairo code that maps the storage variable’s name and argument values to an address — so that it can be part of the generated proof.
+The address of a storage variable is computed as follows:
+If it is a single value, then the address is sn_keccak(variable_name), where variable_name is the ASCII encoding of the variable’s name.
If it is a (nested) mapping, then the address of the value at key k_1,...,k_n is
+h(...h(h(sn_keccak(variable_name),k_1),k_2),...,k_n) where \(h\) is the
+Pedersen hash and the final value is taken \(\bmod 2^{251}-256\)
If it is a mapping to complex values (e.g., tuples or structs), then this complex value lies in a continuous segment starting from the address calculated in the previous point. Note that 256 field elements is the current limitation on the maximal size of a complex storage value.
+Note that when calling var.address(args) for a storage variable with complex values, the returned value is the address of the first element in the storage.
We can summarize the above as follows:
+storage variable address := pedersen(keccak(variable name), keys)
The following example defines storage variables with complex values.
+#[storage]
+struct Storage {
+ name: felt252,
+ symbol: felt252,
+ decimals: u8,
+ total_supply: u256,
+ balances: LegacyMap::<ContractAddress, u256>,
+ allowances: LegacyMap::<(ContractAddress, ContractAddress), u256>,
+}With the v2.0.0 release of the Cairo compiler, the Starknet contract syntax has evolved, affecting the organization of functions, storage, and events.
+For more information on the latest syntax changes, see the Community Forum post Cairo 1: Contract Syntax is Evolving.
+A contract written with the Cairo compiler v1
+The most recent version of the Cairo compiler
+Change the contract annotation from #[contract] to #[starknet::contract]. For example::
Cairo v1
+Cairo v2
+#[contract]
+mod CounterContract {
+ ...
+}#[starknet::contract]
+mod CounterContract {
+ ...
+}Annotate the Storage struct with the #[storage] attribute. For example:
Cairo v1
+Cairo v2
+struct Storage {
+ counter: u128,
+ other_contract: IOtherContractDispatcher
+}#[storage]
+struct Storage {
+ counter: u128,
+ other_contract: IOtherContractDispatcher
+}Gather your contract’s external and view function signatures under a trait annotated with
+#[starknet::interface] as follows:
Add a generic parameter to the trait. In the following example, the name TContractState
+represents the state of your contract.
For view functions, add the self: @TContractState argument.
For external functions, add the ref self: TContractState argument.
Static functions that do not touch storage or emit events do not require an additional argument.
+For example:
+Cairo v1
+Cairo v2
+#[contract]
+mod CounterContract {
+ #[external]
+ fn increase_counter(amount: u128) { ... }
+ #[external]
+ fn decrease_counter(amount: u128) { ... }
+ #[view]
+ fn get_counter() -> u128 { ... }
+}#[starknet::interface]
+trait ICounterContract<TContractState> {
+ fn increase_counter(ref self: TContractState, amount: u128);
+ fn decrease_counter(ref self: TContractState, amount: u128);
+ fn get_counter(self: @TContractState) -> u128;
+}
+#[starknet::contract]
+mod CounterContract {
+ ...
+}Add the external and view function bodies under an impl of the interface trait, and mark the
+impl with the [external(v0)] attribute, which generates the type of dispatcher that is used to call the contract.
For example:
+Cairo v1
+Cairo v2
+#[contract]
+mod CounterContract {
+ #[external]
+ fn increase_counter(amount: u128) { ... }
+ #[external]
+ fn decrease_counter(amount: u128) { ... }
+ #[view]
+ fn get_counter() -> u128 { ... }
+}#[starknet::interface]
+trait ICounterContract<TContractState> {
+ fn increase_counter(ref self: TContractState, amount: u128);
+ fn decrease_counter(ref self: TContractState, amount: u128);
+ fn get_counter(self: @TContractState) -> u128;
+}
+#[starknet::contract]
+mod CounterContract {
+ #[external(v0)]
+ impl CounterContract of super::ICounterContract<ContractState> {
+ fn increase_counter(ref self: ContractState, amount: u128) { ... }
+ fn decrease_counter(ref self: ContractState, amount: u128) { ... }
+ fn get_counter(self: @ContractState) -> u128 { ... }
+ }
+}Replace the #[abi] attribute with #[starknet::interface].
| + + | +
+
+
+While it doesn’t affect the generated code, adding to the trait a generic parameter |
+
For example:
+Cairo v1
+Cairo v2
+#[abi]
+trait IOtherContract {
+ fn decrease_allowed() -> bool;
+}#[starknet::interface]
+trait IOtherContract<TContractState> {
+ fn decrease_allowed(self: @TContractState) -> bool;
+}Modify storage accesses to happen through ContractState or @ContractState.
| + + | +
+
+
+No external functions in the contract that access storage also need to get it as an argument. + |
+
For example:
+Cairo v1
+Cairo v2
+let current = counter::read();let current = self.counter.read();Unify all the contract’s events under the Event enum, and add a corresponding struct for every
+variant.
| + + | +
+
+
+All the structs must derive the |
+
For example:
+Cairo v1
+Cairo v2
+#[event]
+fn counter_increased(amount: u128) {}
+#[event]
+fn counter_decreased(amount: u128) {}#[event]
+#[derive(Drop, starknet::Event)]
+enum Event {
+ CounterIncreased: CounterIncreased,
+ CounterDecreased: CounterDecreased
+}
+#[derive(Drop, starknet::Event)]
+struct CounterIncreased {
+ amount: u128
+}
+#[derive(Drop, starknet::Event)]
+struct CounterDecreased {
+ amount: u128
+}Emit events via the ContractState type. For example:
Cairo v1
+Cairo v2
+fn increase_counter(amount: u128) {
+ ...
+ counter_increased(amount);
+}fn increase_counter(ref self: ContractState, amount: u128) {
+ ...
+ self.emit(Event::CounterIncreased(CounterIncreased { amount }));
+}For the most up-to-date information, see the info.cairo contract.
The struct ExecutionInfo contains the following information about the currently executing block and the transactions in the block.
ExecutionInfo struct
+block_info: Box<BlockInfo>
+ |
+
+ Contains information about a block. For details, see The |
+
+tx_info: Box<TxInfo>
+ |
+
+ Contains information about a transaction. For details, see Transaction information: The |
+
+caller_address: ContractAddress
+ |
+
+ The address of the contract that invokes the |
+
+contract_address: ContractAddress
+ |
+
+ The address of the contract in which the |
+
+entry_point_selector: felt252
+ |
+
+ The function that includes the |
+
BlockInfo struct
+block_number: u64
+ |
+
+ The number of the block that is currently being executed. When called from an account contract’s `__validate__`, `__validate_deploy__`, or `__validate_declare__` function, this value is rounded down to the nearest multiple of 100. + |
+
+block_timestamp: u64
+ |
+
+ The timestamp showing the creation time of the block, in seconds since the Unix epoch, based on UTC time, rounded down to the nearest second. When called from an account contract’s `__validate__`, `__validate_deploy__`, or `__validate_declare__` function, this value is rounded down to the nearest hour. + |
+
+sequencer_address: ContractAddress
+ |
+
+ The address of the Starknet sequencer contract. + |
+
TxInfo struct
+version: felt252
+ |
+
+ The version of the transaction. It is fixed (currently, 3) in the OS, and should be signed by the account contract. This field allows invalidating old transactions, whenever the meaning of the other transaction fields is changed (in the OS). + |
+
+account_contract_address: ContractAddress
+ |
+
+ The account contract from which this transaction originates. + |
+
+max_fee: u128
+ |
+
+ The max_fee field of the transaction. + |
+
+signature: Span<felt252>
+ |
+
+ The signature of the transaction. + |
+
+transaction_hash: felt252
+ |
+
+ The hash of the transaction. + |
+
+chain_id: felt252
+ |
+
+ The identifier of the chain. +This field can be used to prevent replay of testnet transactions on mainnet. + |
+
+nonce: felt252
+ |
+
+ The transaction’s nonce. + |
+
+resource_bounds: Span<ResourceBounds>
+ |
+
+ A span of |
+
+tip: u128
+ |
+
+ The tip. + |
+
+paymaster_data: Span<felt252>
+ |
+
+ If specified, the paymaster should pay for the execution of the tx. +The data includes the address of the paymaster sponsoring the transaction, followed by +extra data to send to the paymaster. + |
+
+nonce_data_availability_mode: u32
+ |
+
+ The data availability mode for the nonce. + |
+
+fee_data_availability_mode: u32
+ |
+
+ The data availability mode for the account balance from which fee will be taken. + |
+
+account_deployment_data: Span<felt252>
+ |
+
+ If nonempty, will contain the required data for deploying and initializing an account +contract: its class hash, address salt and constructor calldata. + |
+
ResourceBounds struct
+resource: felt252
+ |
+
+ The name of the resource. + |
+
+max_amount: u64
+ |
+
+ The maximum amount of the resource allowed for usage during the execution. + |
+
+max_price_per_unit: u128
+ |
+
+ The maximum price the user is willing to pay for the resource unit. + |
+
When you interact with contracts, especially if you are a library or SDK developer that wants to construct transactions, you need to understand how Cairo handles types that are larger than 252 bits so you can correctly formulate the calldata in a transaction.
+The field element (felt252), which contains 252 bits, is the only actual type in the Cairo VM. So all high-level Cairo types that are larger than 252 bits, such as u256 or arrays, are ultimately represented by a list of felts. In order to interact with a contract, you need to know how to encode its arguments as a list of felts so you can correctly formulate the calldata in the transaction.
+SDKs, such as starknet.js, encode the calldata for you, so you can simply specify any type and the SDK properly formulates the calldata. For example, you don’t need to know that a u256 value is represented by two felt252 values. You can simply specify a single integer in your code, and the SDK takes care of the serialization and encoding.
The following types are smaller than 252 bits. For these types, each value is serialized as a single-member list that contains one felt252 value.
ContractAddress
EthAddress
StorageAddress
ClassHash
Unsigned integers smaller than 252 bits: u8, u16, u32, u64, u128, and usize
bytes31
felt252
Signed integers smaller than 252 bits: i8, i16, i32, i64, and i128.
A negative value, \(-x\), is serialized as \(P-x\), where:
+For example, -5 is serialized as \(P-5\). For more information on the value of \(P\), see The STARK field.
The following Cairo data types have non-trivial serialization:
+u256 and u512
arrays
+enums
+structs
+ByteArray, which represents strings
Among unsigned integers, only u256 and u512 have non-trivial serialization.
u256 valuesA u256 value in Cairo is represented by two felt252 values, as follows:
The first felt252 value contains the 128 least significant bits, usually referred to as the low part of the original u256 value.
The second felt252 value contains the 128 most significant bits, usually referred to as the high part of the original u256 value.
For example:
+A u256 variable whose decimal value is 2 is serialized as [2,0]. To understand why, examine the binary representation of 2 and split it into two 128-bit parts, as follows:
A u256 variable whose decimal value is 2128 is serialized as [0,1]. To understand why, examine the binary representation of 2128 and split it into two 128-bit parts, as follows:
A u256 variable whose decimal value is 2129+2128+20, is serialized as [20,3]. To understand why, examine the binary representation of the 2129+2128+20 and split it into two 128-bit parts, as follows:
Arrays are serialized as follows:
+<array_length>, <serialized_member_0>,…, <serialized_member_n>
For example, consider the following array of u256 values:
let POW_2_128: u256 = 0x100000000000000000000000000000000
+let array: Array<u256> = array![10, 20, POW_2_128]Each u256 value in the array is represented by two felt252 values. So the array above is serialized as follows:
Combining the above, the array is serialized as follows: [3,10,0,20,0,0,1]
An enum is serialized as follows:
+<index_of_enum_variant>,<serialized_variant>
Note that enum variants indices are 0-based, not to confuse with their storage layout, which is 1-based, to distinguish the first variant from an uninitialized storage slot.
+Consider the following definition of an enum named Week:
enum Week {
+ Sunday: (), // Index=0. The variant type is the unit type (0-tuple).
+ Monday: u256, // Index=1. The variant type is u256.
+}Now consider instantiations of the Week enum’s variants as shown in the table below:
| Instance | +Description | +Serialization | +
|---|---|---|
|
+Index= |
+
|
+
|
+
+ Index= |
+
|
+
Consider the following definition of an enum named MessageType:
enum MessageType {
+ A,
+ #[default]
+ B: u128,
+ C
+}Now consider instantiations of the MessageType enum’s variants as shown in the table below:
| Instance | +Description | +Serialization | +
|---|---|---|
|
+Index= |
+
|
+
|
+
+ Index= |
+
|
+
|
+Index= |
+
|
+
As you can see about, the #[default] attribute does not affect serialization. It only affects the storage layout of MessageType, where the default variant
+B will be stored as 0.
You serialize a struct by serializing its members one at a time.
+Its members are serialized in the order in which they appear in the definition of the struct.
+For example, consider the following definition of the struct MyStruct:
struct MyStruct {
+ a: u256,
+ b: felt252,
+ c: Array<felt252>
+}The serialization is the same for both of the following instantiations of the struct’s members:
+
+
+
+ |
+
+
+
+ |
+
The serialization of MyStruct is determined as shown in the table Serialization for a struct in Cairo.
| Member | +Description | +Serialization | +
|---|---|---|
|
+For information on serializing |
+[ |
+
|
+One |
+
|
+
|
+An array of three |
+[ |
+
Combining the above, the struct is serialized as follows: [0,2,5,3,1,2,3]
A string is represented in Cairo as a ByteArray type. A byte array is actually a struct with the following members:
data: Array<felt252>
+Contains 31-byte chunks of the byte array. Each felt252 value has exactly 31 bytes. If the number of bytes in the byte array is less than 31, then this array is empty.
pending_word: felt252
+The bytes that remain after filling the data array with full 31-byte chunks. The pending word consists of at most 30 bytes.
pending_word_len: usize
+The number of bytes in pending_word.
Consider the string hello, whose ASCII encoding is the 5-byte hex value 0x68656c6c6f. The resulting byte array is serialized as follows:
0, // Number of 31-byte words in the data array.
+ 0x68656c6c6f, // Pending word
+ 5 // Length of the pending word, in bytesConsider the string Long string, more than 31 characters., which is represented by the following hex values:
0x4c6f6e6720737472696e672c206d6f7265207468616e203331206368617261 (31-byte word)
0x63746572732e (6-byte pending word)
The resulting byte array is serialized as follows:
+ 1, // Number of 31-byte words in the array construct.
+ 0x4c6f6e6720737472696e672c206d6f7265207468616e203331206368617261, // 31-byte word.
+ 0x63746572732e, // Pending word
+ 6 // Length of the pending word, in bytesInteger types in The Cairo Programming Language.
+A contract may emit events throughout its execution. Each event contains the following fields:
+from_address: address of the contract emitting the events
keys: a list of field elements
data: a list of field elements
The keys can be used for indexing the events, while the data may contain any information that we wish to log (note that we are dealing with two separate lists of possibly varying size, rather than a list of key-value pairs).
+Events can be defined in a contract using the @event decorator. Once an event E has been defined, the compiler automatically adds the function E.emit(). The following example illustrates how an event is defined and emitted:
#[event]
+fn Transfer(from: ContractAddress, to: ContractAddress, value: u256) {}Transfer(12345, 12345, 1)The emit function emits an event with a single key, which is an identifier of the event, given by \(\text{sn_keccak}(event\_name)\), where \(event\_name\) is the ASCII encoding of the event’s name and \(\text{sn_keccak}\) is defined here.
+To emit custom keys, one should use the low level emit_event system call:
use starknet::syscalls::emit_event_syscall;
+
+let keys = array!['key', 'deposit'];
+let values = array![1, 2, 3];
+emit_event_syscall(keys, values).unwrap_syscall();The above code emits an event with two keys, the strings key and deposit (think of those as identifiers of the event that can be used for indexing) and three data elements 1, 2, 3.
| + + | +
+
+
+When using the higher level
+
+
+
+ |
+
The emitted events are part of the transaction receipt. For more information, see Transaction receipt.
+The event definition appears in the contract’s ABI. It contains the list of data fields, with the name and type for each, and the list of the custom keys, that is, all keys except the event identifier discussed above. Below is an example of an event inside the ABI:
+{
+ "type": "event",
+ "name": "Transfer",
+ "inputs": [
+ {
+ "name": "from",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "to",
+ "type": "core::starknet::contract_address::ContractAddress"
+ },
+ {
+ "name": "value",
+ "type": "core::integer::u256"
+ }
+ ]
+}The event hash is given by:
+Where:
+\(keys\_hash\) and \(data\_hash\) are the hashes of the keys list and data list respectively. For more information, see Array hashing.
+\(h\) is the Pedersen hash function.
+The event hashes are included in the event_commitment field of a block.
architecture-and-concepts:cryptography/hash-functions.adoc#array_hashing
+The event_commitment field in Block structure
Writing smart contracts requires various associated 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.
+get_block_hashextern fn get_block_hash_syscall(
+ block_number: u64
+) -> SyscallResult<felt252> implicits(GasBuiltin, System) nopanic;Gets the hash of a specific Starknet block within the range of [first_v0_12_0_block, current_block - 10].
+block_number: u64
+ |
+
+ The number of the block whose hash you want to get. + |
+
The hash of the specified block.
+
+Block number out of range
+ |
+
+
|
+
+0
+ |
+
+
|
+
get_execution_infoextern fn get_execution_info_syscall() -> SyscallResult<Box<starknet::info::ExecutionInfo>> implicits(
+ GasBuiltin, System
+) nopanic;Gets information about the currently executing block and the transactions in the block. For a complete description of this information, see Execution information
+This single system call contains all information for a block, transaction, and execution context.
+When an account’s __validate__, __validate_deploy__, or __validate_declare__ function calls get_execution_info, the return values for block_timestamp and block_number are modified as follows:
block_timestamp returns the hour, rounded down to the nearest hour.
block_number returns the block number, rounded down to the nearest multiple of 100.
None.
+
+ExecutionInfo
+ |
+
+ A struct that contains information about the currently executing function, transaction, and block. + |
+
This example shows how to pull the block number from the ExecutionInfo struct.
let execution_info = get_execution_info().unbox();
+let block_info = execution_info.block_info.unbox();
+let block number = block_info.block_number;call_contractextern fn call_contract_syscall(
+ address: ContractAddress, entry_point_selector: felt252, calldata: Span<felt252>
+) -> SyscallResult<Span<felt252>> implicits(GasBuiltin, System) nopanic;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.
+| + + | +
+
+
+An internal call can’t return
+
+If |
+
+address: ContractAddress
+ |
+
+ The address of the contract you want to call. + |
+
+entry_point_selector: felt252
+ |
+
+ A selector for a function within that contract. + |
+
+calldata: Span<felt252>
+ |
+
+ The calldata array. + |
+
The call response, of type SyscallResult<Span<felt252>>.
| + + | +
+
+
+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. + |
+
deployextern 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;Deploys a new instance of a previously declared class.
+
+class_hash: ClassHash
+ |
+
+ The class hash of the contract to be deployed. + |
+
+contract_address_salt: felt252
+ |
+
+ The salt, an arbitrary value provided by the sender, used in the computation of the contract’s address. + |
+
+calldata: Span<felt252>
+ |
+
+ The constructor’s calldata. An array of felts. + |
+
+deploy_from_zero: bool
+ |
+
+ A flag that determines whether the deployer’s address affects the computation of the contract address. When not set, or when set to |
+
A tuple wrapped with SyscallResult where:
The first element is the address of the deployed contract, of type ContractAddress.
The second element is the response array from the contract’s constructor, of type Span::<felt252>.
emit_eventextern fn emit_event_syscall(
+ keys: Span<felt252>, data: Span<felt252>
+) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;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.
+
+keys: Span<felt252>
+ |
+
+ The event’s keys. These are analogous to Ethereum’s event topics, you can use the starknet_getEvents method to filter by these keys. + |
+
+data: Span<felt252>
+ |
+
+ The event’s data. + |
+
None.
+The following example emits an event with two keys, the strings key and deposit and three data elements: 1, 2, and 3.
let keys = array!['key', 'deposit'];
+let values = array![1, 2, 3];
+emit_event_syscall(keys, values).unwrap_syscall();library_callextern fn library_call_syscall(
+ class_hash: ClassHash, function_selector: felt252, calldata: Span<felt252>
+) -> SyscallResult<Span<felt252>> implicits(GasBuiltin, System) nopanic;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.
+
+class_hash: ClassHash
+ |
+
+ The hash of the class you want to use. + |
+
+function_selector: felt252
+ |
+
+ A selector for a function within that class. + |
+
+calldata: Span<felt252>
+ |
+
+ The calldata. + |
+
The call response, of type SyscallResult<Span<felt252>>.
send_message_to_L1extern fn send_message_to_l1_syscall(
+ to_address: felt252, payload: Span<felt252>
+) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;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.
+
+to_address: felt252
+ |
+
+ The recipient’s L1 address. + |
+
+payload: Span<felt252>
+ |
+
+ The array containing the message payload + |
+
None.
+The following example sends a message whose content is (1,2) to the L1 contract whose address is 3423542542364363.
let payload = ArrayTrait::new();
+payload.append(1);
+payload.append(2);
+send_message_to_l1_syscall(payload).unwrap_syscall();replace_classextern fn replace_class_syscall(
+ class_hash: ClassHash
+) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;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
+
+The new class will be used from the next transaction onwards or if the contract is called via
+the |
+
+class_hash_: ClassHash
+ |
+
+ The hash of the class you want to use as a replacement. + |
+
None.
+storage_readextern fn storage_read_syscall(
+ address_domain: u32, address: StorageAddress
+) -> SyscallResult<felt252> implicits(GasBuiltin, System) nopanic;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 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 storage variables.
+
+address_domain: u32
+ |
+
+ The domain of the key, used to separate between different data availability modes. This separation is used in Starknet to offer different data availability modes. Currently, only the onchain mode (where all updates go to L1), indicated by domain |
+
+address: StorageAddress
+ |
+
+ The requested storage address. + |
+
The value of the key, of type SyscallResult<felt252>.
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_writeextern fn storage_write_syscall(
+ address_domain: u32, address: StorageAddress, value: felt252
+) -> SyscallResult<()> implicits(GasBuiltin, System) nopanic;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 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 storage variables.
+
+address_domain: u32
+ |
+
+ The domain of the key, used to separate between different data availability modes. This separation is used in Starknet to offer different data availability modes. Currently, only the onchain mode (where all updates go to L1), indicated by domain |
+
+address: StorageAddress
+ |
+
+ The requested storage address. + |
+
+value: felt252
+ |
+
+ The value to write to the key. + |
+
None.
+| + + | +
+
+
+This topic previously appeared in the Starknet Book. + |
+
Starknet’s Solidity verifier ensures the truth of transactions and smart contracts.
+The Solidity verifier is an L1 Solidity smart contract, designed to validate STARK proofs from SHARP.
+The current Verifier is a set of multiple smart contracts, rather than being a singular, monolithic structure.
+Some key smart contracts associated with the Verifier are:
+GpsStatementVerifier: This is the primary contract of the SHARP verifier. It verifies a proof and then registers the related facts using verifyProofAndRegister. It acts as an umbrella for various layouts, each named CpuFrilessVerifier. Every layout has a unique combination of built-in resources.
+The system routes each proof to its relevant layout.
+MemoryPageFactRegistry: This registry maintains facts for memory pages, primarily used to register outputs for data availability in rollup mode. The Fact Registry is a separate smart contract ensuring the verification and validity of attestations or facts. The verifier function is separated from the main contract to ensure each segment works optimally within its limits. The main proof segment relies on other parts, but these parts operate independently.
MerkleStatementContract: This contract verifies Merkle paths.
FriStatementContract: It focuses on verifying the FRI layers.
The SHARP Verifier Contract Map contains roughly 40 contracts, detailing various components of the Solidity verifier. The images below display the contracts and their Ethereum Mainnet addresses.
+These are currently the entire stack of contracts that comprise the SHARP verifier, with their Ethereum Mainnet addresses.
+| +Proxy + | +
+ 0x47312450B3Ac8b5b8e247a6bB6d523e7605bDb60 + |
+
| +CallProxy + | +
+ 0xD4C4044ACa68ebBcB81B13cC2699e1Bca2d3F458 + |
+
| +GpsStatementVerifier + | +
+ 0x6cB3EE90C50a38A0e4662bB7e7E6e40B91361BF6 + |
+
| +MemoryPageFactRegistry + | +
+ 0xFD14567eaf9ba941cB8c8a94eEC14831ca7fD1b4 + |
+
| +MerkleStatementContract + | +
+ 0x5899Efea757E0Dbd6d114b3375C23D7540f65fa4 + |
+
| +FriStatementContract + | +
+ 0x3E6118DA317f7A433031F03bB71ab870d87dd2dd + |
+
| +CairoBootloaderProgram + | +
+ 0x5d07afFAfc8721Ef3dEe4D11A2D1484CBf6A9dDf + |
+
| +PedersenHashPointsXColumn + | +
+ 0xc4f21318937017B8aBe5fDc0D48f58dBc1d18940 + |
+
| +PedersenHashPointsYColumn + | +
+ 0x519DA5F74503dA351EbBED889111377d33096002 + |
+
| +EcdsaHashPointsXColumn + | +
+ 0x593a71DC43e9B67FE009d7C76B6EfA925FB329B1 + |
+
| +EcdsaHashPointsYColumn + | +
+ 0xcA59f6FD499ffF50c78Ffb420a9bcd0d273abf29 + |
+
| +CpuFrilessVerifier0 + | +
+ 0x217750c27bE9147f9e358D9FF26a8224F8aCC214 + |
+
| +CpuOods0 + | +
+ 0x3405F644F9390C3478f42Fd205CE6920CcAF3280 + |
+
| +CpuConstraintPoly0 + | +
+ 0x943248dA0FFd5834Da56c5AD5308E2E2991378EB + |
+
| +CpuFrilessVerifier1 + | +
+ 0x630A97901Ac29590DF83f4A64B8D490D54caf239 + |
+
| +CpuOods1 + | +
+ 0x8518F459A698038B4CCED66C042c48C6bB5B17fe + |
+
| +CpuConstraintPoly1 + | +
+ 0x4CF5c11321d54b83bDAE84bBbd018c26621d2950 + |
+
| +CpuFrilessVerifier2 + | +
+ 0x8488e8f4e26eBa40faE229AB653d98E341cbE57B + |
+
| +CpuOods2 + | +
+ 0x52314e0b25b024c34480Ac3c75cfE98c2Ed6aa4a + |
+
| +CpuConstraintPoly2 + | +
+ 0xBE8bd7a41ba7DC7b995a53368e7fFE30Fd2BC447 + |
+
| +CpuFrilessVerifier3 + | +
+ 0x9E614a417f8309575fC11b175A51599661f2Bd21 + |
+
| +CpuOods3 + | +
+ 0xED219933b58e9c00E66682356588d42C7932EE8E + |
+
| +CpuConstraintPoly3 + | +
+ 0x297951a67D1BF7795500C3802d21a8C846D9C962 + |
+
| +CpuFrilessVerifier4 + | +
+ 0xC879aF7D5eD80e4676C203FD300E640C297F31e3 + |
+
| +CpuOods4 + | +
+ 0x4bf82e627D57cB3F455E740bcDA25848cDbd2FF7 + |
+
| +CpuConstraintPoly4 + | +
+ 0x0C099caf7a87e4eB28bcd8D0608063f8a69bb434 + |
+
| +CpuFrilessVerifier5 + | +
+ 0x78Af2BFB12Db15d35f7dE8DD77f29C299C78c590 + |
+
| +CpuOods5 + | +
+ 0x43A1C0bBa540e1C98d4b413F876250bdCFd0b9e0 + |
+
| +CpuConstraintPoly5 + | +
+ 0x691ca565B7416B681e4f9Fb56A1283Ae8b34E55e + |
+
| +CpuFrilessVerifier6 + | +
+ 0xe9664D230490d5A515ef7Ef30033d8075a8D0E24 + |
+
| +CpuOods6 + | +
+ 0x68293272FEA2D6e74572BC18ffaD11F21344e090 + |
+
| +CpuConstraintPoly6 + | +
+ 0xd0aAdECA2d25AEFde0da214d27b04b6ea20D7418 + |
+
| +PoseidonPoseidonFullRoundKey0Column6 + | +
+ 0x37070Fd8051f63E5A6D7E87026e086Cc19db1aBe + |
+
| +PoseidonPoseidonFullRoundKey1Column6 + | +
+ 0xb4711a4614368516529d6118C97905aB4B28e267 + |
+
| +PoseidonPoseidonFullRoundKey 2Column6 + | +
+ 0x4FB05b7CC348C5a72C59a3f307baf66e3CA1F835 + |
+
| +PoseidonPoseidonPartialRoundKey0Column6 + | +
+ 0x812c2AD2161D099724A99C8114c539b9e5b449cd + |
+
| +PoseidonPoseidonPartialRoundKey1Column6 + | +
+ 0x4d0E80AB34ee2B19295F2CaC3101d03452D874b8 + |
+
| +CpuFrilessVerifier7 + | +
+ 0x03Fa911dfCa026D9C8Edb508851b390accF912e8 + |
+
| +CpuOods7 + | +
+ 0xc9E067AF5d00eb4aA2E73843ac36AfF83C5CeeD3 + |
+
| +CpuConstraintPoly7 + | +
+ 0x89B7a7276cBc8Cb35Ec11fAE9da83b20Db3edf20 + |
+
These contracts function as follows:
+Proxy: This contract facilitates upgradability. It interacts with the GpsStatementVerifier contract using the delegate_call method. Notably, the state resides in the GpsStatementVerifier contract, not in the proxy.
CallProxy: Positioned between the Proxy and the GpsStatementVerifier contracts, it functions like a typical proxy. However, it avoids the delegate_call method and calls the function in the implementation contract directly.
CairoBootloaderProgram: Comprising numerical Cairo programs, it validates the Cairo program of a statement. The bootloader manages the logic executing Cairo programs to generate proof and program hash.
+PedersenHashPoints (X & Y Columns): These lookup tables store vast amounts of data. Validation functions consult them to compute the Pedersen hash.
+EcdsaPoints (X & Y Column): Similar to the Pedersen hash, these tables assist in calculating the elliptic curve.
+CpuFrilessVerifier/CpuOods/CpuConstantPoly (0 - 7): These Verifier contracts vary in layout as shown in the GpsStatementVerifier layout image. Each layout encompasses resources, built-ins, constraints, and more, designed for a specific task. Each has unique parameters for its constructor.
+PoseidonPoseidon: These contracts back the new Poseidon built-in and contain Poseidon-specific lookup tables.
+When constructing the primary Verifier contracts, specific parameters are employed to facilitate functionality. These parameters reference other auxiliary contracts, decentralizing the logic and ensuring the main contract remains under the 24kb deployment limit.
+Below is a visual representation of these parameters in relation to key contracts CpuFrilessVerifiers and GpsStatementVerifier:
+
+CpuFrilessVerifiers is designed to handle a diverse range of tasks. Its parameters encompass:
+Auxiliary Polynomial Contracts: These include CpuConstraintPoly, PedersenHashPointsxColumn, PedersenHashPointsYColumn, EcdsaPointsXColumn, and EcdsaPointsYColumn.
Poseidon-Related Contracts: Several PoseidonPoseidonFullRoundKey and PoseidonPoseidonPartialRoundKey contracts.
Sampling and Memory: The contract uses CpuOods for out-of-domain sampling and MemoryPageFactRegistry for memory-related tasks.
Verification: It integrates with MerkleStatementContract for Merkle verification and FriStatementContract for Fri-related tasks.
Security: The num_security_bits and min_proof_of_work_bits contracts ensure secure operation.
| + + | +
+
+
+For instances like |
+
The GpsStatementVerifier functions as the hub of verifier operations, necessitating various parameters for effective functioning:
Bootloader: It references the CairoBootloaderProgram to initiate the system.
Memory Operations: This is facilitated by the MemoryPageFactRegistry contract.
Sub-Verifiers: It integrates a series of sub-verifiers (CpuFrilessVerifier0 through CpuFrilessVerifier7) to decentralize tasks.
Verification: The hashes, hashed_supported_cairo_verifiers and simple_bootloader_program_hash, are essential for validation processes.
The GpsStatementVerifier serves as the primary verifier contract, optimized for minimal logic to fit within deployment size constraints. To function effectively:
It relies on smaller verifier contracts, which are already deployed and contain varied verification logic.
+These smaller contracts, in turn, depend on other contracts, established during their construction.
+In essence, while the diverse functionalities reside in separate contracts for clarity and size efficiency, they are all interlinked within the GpsStatementVerifier.
For future enhancements or adjustments, the proxy and callproxy contracts facilitate upgradability, allowing seamless updates to the GpsStatementVerifier without compromising its foundational logic.
+The SHARP dispatcher transmits all essential transactions for verification, including:
+MemoryPages (usually many).
MerkleStatements (typically between 3 and 5).
FriStatements (generally ranging from 5 to 15).
The SHARP dispatcher then forwards the proof using verifyProofAndRegister.
Applications, such as the Starknet monitor, validate the status. Once verification completes, they send an updateState transaction.
| + + | +
+
+
+The Starknet CLI is deprecated. Instead, use StarkLi CLI. + |
+
To enter a Starknet command, use the following syntax:
+$ starknet <command> <options>Where:
+<command> represents a single command that executes an operation on Starknet.
<options> represents zero or more command line options, each of which modifies the operation of the command.
You need to set your Starknet network environment to use either testnet or Mainnet.
+You can set the environment using either a command-line option or an environment variable.
+Possible values are:
+sepoliaSets the Starknet network to testnet
+mainnetSets the Starknet network to Mainnet
+When you enter any command, include the --network option. For example to use Mainnet, enter a command as follows:
$ starknet <command> --network alpha-mainnet <options>| + + | +
+
+
+You can place the |
+
Set the STARKNET_NETWORK environment variable as follows:
$ export STARKNET_NETWORK=<starknet_network>For example, to use testnet, enter the following command:
+$ export STARKNET_NETWORK=sepoliaWhen working with the CLI, you can manually set the endpoints for the gateways that enable you to +interact with Starknet, by including the following options:
+--feeder_gateway_urlSets the custom endpoint for read commands.
+--gateway_urlSets the custom endpoint for write commands.
+The following are the endpoints for Starknet testnet and Mainnet:
+Testnet feeder gateway URL: https://alpha4.starknet.io/feeder_gateway/
+Mainnet feeder gateway URL: https://alpha-mainnet.starknet.io/feeder_gateway/
+Testnet gateway URL: https://alpha4.starknet.io/gateway/
+Mainnet gateway URL: https://alpha-mainnet.starknet.io/gateway/
+The following command returns the ABI using the Mainnet feeder gateway.
+$ starknet get_code --feeder_gateway_url https://alpha-mainnet.starknet.io/feeder_gateway/ <options>The following command sends a transaction to the Starknet sequencer +using the Mainnet gateway.
+$ starknet invoke --gateway_url https://alpha-mainnet.starknet.io/gateway/ <options>starknet callstarknet call
+ --address <contract_address>
+ --abi <contract_abi>
+ --function <function_name>
+ --inputs <arguments>
+ --block_hash <block_hash>
+ --block_number <block_number>
+ --signature <signature_information>
+ --wallet <wallet_name>
+ --nonce <nonce>Calls a Starknet contract without affecting the state, accepts the following arguments:
+contract_address* - address of the contract being called
contract_abi* - a path to a JSON file that contains the abi of the contract being called
function_name* - name of the function which is called
arguments* - inputs to the function being called, 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 or tag
signature_information - list of field elements as described here
wallet_name - the name of the desired wallet, use deploy_account to set-up new accounts in the CLI
nonce - account nonce, only relevant if the call is going through an account
| + + | +
+
+
+Block Tag
+A block context can be specified via the |
+
starknet declarestarknet declare
+--contract <contract_class>Declares a new contract class on Starknet, accepts the following argument:
+contract_class - path to a JSON file containing the contract’s compiled code
starknet deploystarknet deploy
+ --salt <salt>
+ --contract <contract_definition>
+ --inputs <constructor_inputs>
+ --token <token>Deploys a new contract, accepts the following arguments:
+salt - a seed that is used in the computation of the contract’s address (if not specified, the sequencer will choose a random string)
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
| + + | +
+
+
+The deploy token is a temporary measure which will be deprecated when fees are incorporated in the system. Only relevant for Mainnet. + |
+
starknet deploy_accountstarknet deploy_account
+ --wallet <wallet_provider>
+ --account <account_name>Deploys an account contract, accepts the following arguments:
+account_name - the name given to the account, used for managing multiple accounts from the CLI (if not specified, the name
+__default__ is used.
wallet_provider* - the path to module which manages the account (responsible for key generation, signing, etc.)
| + + | +
+
+
+Today, the Starknet CLI only works with the OpenZeppelin account contract.
+The CLI uses this specific wallet provider.
+To use this provider, either set up the following environment variable or pass the same value directly to the
+
+
+
+ |
+
| + + | +
+
+
+Using the built-in wallet providers that are part of the cairo-lang package (starkware.starknet.wallets…) is not secure (for example, the private key may be kept not encrypted and without backup in your home directory). You should only use them if you’re not overly concerned with losing access to your accounts (for example, for testing purposes). + |
+
starknet estimate_feestarknet estimate_fee
+ --address <contract_address>
+ --abi <contract_abi>
+ --function <function_name>
+ --inputs <arguments>Returns the fee estimation for a given contract call. Accepts the following arguments:
+address* - the address of the contract being called
contract_abi* - a path to a JSON file that contains the abi of the contract being called
function_name*- the name of the function being called
arguments* - inputs to the function being called, represented by a list of space-delimited values`
starknet estimate_message_feestarknet estimate_message_fee
+ --from_address <sender_address>
+ --to_address <contract_address>
+ --function <function_name>
+ --inputs <arguments>Returns the fee estimation for a given L1 handler application. Accepts the following arguments:
+from_address* - the L1 address of the sender
to_address* - the L2 address of the recipient
contract_abi* - a path to a JSON file containing the abi of the receiving contract on L2
function_name*- the name of the desired L1 handler
arguments* - inputs to the called handler, represented by a list of space-delimited values
starknet get_blockstarknet get_block
+ --hash <block_hash>
+ --number <block_number>Returns the requested block, exactly one of the following arguments must be given:
+block_hash - hash of the requested block
block_number - number or tag of the requested block
starknet get_codestarknet get_code
+ --contract_address <contact_address>
+ --block_hash <block_hash>
+ --block_number <block_number>Returns the ABI and the byte code of the requested contract, accepts the following arguments:
+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 or tag
starknet get_storage_atstarknet get_storage_at
+ --contract_address <contract_address>
+ --key <key>
+ --block_hash <block_hash>
+ --block_number <block_number>Queries a contract’s storage at a specific key, accepts the following arguments:
+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 or tag
starknet get_transactionstarknet get_transaction --hash <transaction_hash>Returns the requested transaction, expects the following argument:
+transaction_hash* - hash of the requested transaction
starknet get_transaction_receiptstarknet get_transaction_receipt --hash <transaction_hash>Returns the receipt associated with the transaction, expects the following argument:
+transaction_hash* - hash of the requested transaction
+starknet invoke
+starknet tx_status
starknet invokestarknet invoke
+ --address <contract_address>
+ --abi <contract_abi>
+ --function <function_name>
+ --inputs <arguments>
+ --signature <signature_information>
+ --wallet <wallet_name>
+ --nonce <nonce>Sends a transaction to the Starknet sequencer, accepts the following arguments:
+address* - the address of the contract being called
contract_abi* - a path to a JSON file that contains the abi of the contract being called
function_name*- the name of the function being called
arguments* - inputs to the function being called, represented by a list of space-delimited values
signature_information - list of field elements as described here
wallet_name - the name of the desired wallet, use deploy_account to set-up new accounts in the CLI.
nonce - account nonce, only relevant if the call is going through an account
| + + | +
+
+
+Today, interaction with Starknet may be done either via account or by a direct call. The |
+
starknet tx_statusstarknet tx_status
+ --hash <transaction_hash>
+ --contract <contract_definition>
+ --error_messageReturns the transaction status, accepts the following arguments:
+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)
The possible statuses of a transaction are:
+NOT_RECEIVED
RECEIVED
PENDING
REJECTED
ACCEPTED_ON_L2
ACCEPTED_ON_L1
For more information, see Transaction lifecycle.
+When the Starknet compiler is installed, you can view this command-line help in a terminal by entering the following command:
+starknet-compile --helpstarknet-compile [-h] [--abi ABI] [--disable_hint_validation]
+ [--account_contract] [--dont_filter_identifiers] [-v]
+ [--prime PRIME] [--cairo_path CAIRO_PATH]
+ [--preprocess] [--output OUTPUT] [--no_debug_info]
+ [--debug_info_with_source]
+ [--cairo_dependencies CAIRO_DEPENDENCIES]
+ [--no_opt_unused_functions]
+ file [file ...]The following example compiles the file contract.cairo. It generates two files:
| +contract_compiled.json + | +
+ The contract class. This file contains the bytecode and all other information necessary to execute a contract. For information on contract classes, see Contract classes and instances. + |
+
| +contract_abi.json + | +
+ The contract’s ABI. + |
+
starknet-compile contract.cairo \
+ --output contract_compiled.json \
+ --abi contract_abi.json--dont_filter_identifiersDisable the filter-identifiers-optimization.If True, all the identifiers will be kept, instead of just the ones mentioned in hints or 'with_attr' statements.
+--cairo_path CAIRO_PATHA list of directories, separated by ":" to resolve import paths. The full list will consist of directories defined by this argument, followed by the environment variable CAIRO_PATH, the working directory and the standard library path.
+Refers to the capability of users to define their own account logic instead of it being dictated by the protocol.
+An L2 smart contract, with programmable logic, that implements a user account on Starknet. An account contract implements special methods that enable initiating transactions.
+The Starknet Node API uses the Remote Procedure Call (RPC) architectural style, written in JSON format. For complete information on the Starknet Node API in JSON RPC format, see starknet_api_openrpc.json on Github.
An ordered set of Starknet transactions. Blocks are built by the sequencer.
+A block has the following identifiers:
+| +block hash + | +
+ A unique identifier that can be used to query and refer to the block. + |
+
| +block number + | +
+ A number representing the location of the block in the sequence of accepted blocks in Starknet. + |
+
An optimized low-level execution unit that is added to the Cairo CPU board to perform predefined computations that are expensive to perform in standard Cairo, including range-checks, Pedersen hash calculations, and ECDSA.
+The smallest unit of execution within the Cairo VM, typically involving mathematical, logical, or control-flow operations that collectively define the behavior of a program.
+The Cairo Virtual Machine (VM) is software that knows how to execute compiled Cairo byte-code. The result of this execution is the program trace that can then be sent to a STARK prover in order to prove the validity of the instruction expressed in the Cairo code.
+The definition of a contract. It includes Cairo byte code, entry point names, and everything that defines its semantics.
+A deployed contract that corresponds to a class. Only contract instances act as true contracts, in that they have their own storage and can be called by transactions or other contracts.
+A machine that runs the Starknet execution protocol. A full node stays synchronized with the latest state of the network, stores past blocks and transactions, and enables users to interact with the network, such as by querying its state or by broadcasting new transactions.
+The base layer of a blockchain network, such as Ethereum, where transactions are directly recorded and validated. It includes the underlying protocol and consensus mechanism that establish the foundational rules for the blockchain.
+Exists on top of an L1 blockchain, such as Ethereum, in order to add value to the L1, by providing features such as massive computation scale without compromising on Ethereum’s composability and security.
+A single transaction that executes multiple bundled transactions, which are signed once on Starknet. If one call fails, the entire operation is aborted.
+The entity that receives the output of Cairo programs and generates proofs to be verified. In the context of Starknet, the prover generates proofs of the computational integrity of the work performed by the sequencer. It then submits the proof to the verifier on L1, which registers the fact.
+The Starknet RPC API provides clients an interface to retrieve information on the state of the chain and to interact with it, such as by posting transactions or estimating the fee of a transaction before it is sent.
+A set of services that together receive transactions from the network, put them in order, check their validity, and build blocks.
+The Shared Prover (SHARP) is a mechanism used in Starknet that aggregates multiple Cairo programs from different users, each containing different logic. These Cairo programs are then executed together, generating a single proof common to all the programs.
+An intermediate representation between Cairo and Casm. Sierra code is then compiled into a Casm program with the property that, for any input, the program’s execution is provable. In particular, it ensures that the execution of a transaction is provable regardless of whether the execution succeeded or was reverted due to an error.
+A proof system that uses cryptography to provide polylogarithmic verification resources and proof size, with minimal and post-quantum-secure assumptions.
+A smart contract deployed on Ethereum. Its address is 0xc662c410c0ecf747543f5ba90660f6abebd9c8c4. It defines the state of Starknet
+ by storing:
The commitment to the L2 state.
+The Starknet OS program hash – effectively defines the version of Starknet the network is running.
+The committed state on the L1 Core Contract acts as the consensus mechanism of Starknet, that is, the system is secured by the L1 Ethereum consensus. In addition to maintaining the state, the Starknet L1 Core Contract is the main hub of operations for Starknet on L1. Specifically:
+It stores the list of allowed verifier contracts that can verify state update transactions
+It deals with cross-layer interaction between L1 and L2.
+A permissionless Validity-Rollup, also known as a zero-knowledge rollup (ZK rollup) for Ethereum. Starknet is a Layer 2 (L2) blockchain, enabling any dApp to achieve massive computation scale without compromising Ethereum’s composability and security.
+Starknet aims to achieve secure, low-cost transactions and high performance by using the STARK cryptographic proof system. Starknet contracts and the Starknet OS are written in Cairo, a custom-built and specialized programming language.
+The Cairo program that, upon receiving a set of transaction as input, executes the state transition. For more information, see Starknet state. The integrity of this computation is what is actually proven and verified.
+The set of all the contracts' code and all the memory slots and their values, in every contract’s storage.
+A transaction can be seen as a message containing a set of instructions that describe a state transition. The Starknet protocol has the following types of transactions, which affect different parts of the state:
+DECLARE
INVOKE
DEPLOY_ACCOUNT
The data describing the difference between two states. It contains information on every contract whose storage was updated and additional information on contract deployments.
+Starknet is a permissionless Validity-Rollup, also known as a zero-knowledge rollup (ZK rollup) for Ethereum. As a Layer 2 (L2) blockchain, Starknet enables any dApp to achieve massive computation scale without compromising on Ethereum’s composability +and security.
+Starknet aims to achieve secure, low-cost transactions and high performance by using the STARK cryptographic proof system. Starknet contracts and the Starknet OS are written in Cairo, a custom-built and +specialized programming language.
+Want to contribute to Starknet documentation? Get started here:
+See the different ways to contribute.
+Review these basic writing guidelines to help you write better and be a more valuable contributor.
+Use the Starknet documentation supplementary style guide to help you write with the Starknet voice.
+| Notation | +Explanation | +
|---|---|
bold |
+
+
|
+
italics |
+Indicates the first occurrence of a new term, titles of documents or topics, and user-supplied or variable values. |
+
|
+Indicates code, commands, file paths, or other text that should be displayed in a fixed-width font to differentiate it from the surrounding text. |
+
|
+Indicates user-supplied or variable values in code, commands, file paths, or other text that should be displayed in a monospace font. +Can also refer to generic types. For example: |
+
\(\text{string_in_math_notation}\) |
+A normal (non-italics) serif typeface indicates a fixed element or constant specified in mathematical notation. |
+
… |
+An ellipsis indicates that the preceding element can repeat multiple times. |
+
[item, …] |
+
+ Square brackets indicate that the enclosed items are optional. Also can indicate a range of numbers, where the enclosed items are included. For example, in [0,100], 0 and 100 are part of the specified range. + |
+
+ (item1, item2) + |
+Parentheses indicate a range of numbers, where the enclosed items are not included. For example, in (0,100), 0 and 100 are not part of the specified range. |
+
item1 | item2 |
+A vertical bar (|) indicates a choice between item1 and item2. |
+
+ {item1, item2} + |
+Curly brackets indicates a list or set of possible values. |
+
/ |
+A forward slash indicates a division operator or a path separator in URLs and file paths. |
+
Ensure that the below commands are working properly on your system.
+
+ 
+ 
+ starkli --version
+scarb --versionIf either of the above commands fails, see Setting up your environment.
+Deploying a smart contract in Starknet requires two steps:
+Declaring the class of your contract, i.e. sending your contract’s code to the network.
+Deploying a contract, i.e. creating an instance of the code you previously declared.
+
+| + + | +
+
+
+If you require a smart contract for testing, you can use this sample contract, |
+
Declaration is the process of submitting your contract’s code to the Starknet network, making it available for future deployments. It’s a one-time process for each unique contract code. Think of declaration as registering a blueprint for your contract with the network.
+We can draw a parallel with C++ programming:
+Writing the contract code is similar to defining a class in C++.
+Declaring the contract is analogous to compiling that class into object code.
+Deploying an instance of the contract is like creating an object of that class.
+Another parallel with Java:
+Writing the contract is like writing a Java class.
+Declaring is similar to compiling the Java class into bytecode.
+Deploying is like instantiating an object of that class in the JVM.
+Just as you can create multiple objects from a single class in C++, you can deploy multiple instances of a declared contract in Starknet.
+Separating declaration from deployment offers several advantages:
+Gas Optimization: The contract code is stored on the network only once, reducing gas costs for subsequent deployments.
+Reusability: Multiple instances of the same contract can be deployed without repeatedly sending the full code.
+Version Control: It allows for better management of contract versions across different deployments.
+You can compile a smart contract using the Scarb compiler.
+To compile a smart contract, create a directory containing a Scarb.toml file and a subdirectory named src containing your contract source code.
Add the following code to the Scarb.toml file:
[package]
+name = "contracts"
+version = "0.1.0"
+
+[dependencies]
+starknet = ">=2.2.0"
+
+[[target.starknet-contract]]
+sierra = trueNavigate into the newly created directory:
+cd <dir_name>Run the following command:
+scarb buildThe compiled contract will be saved in the target/dev/ directory.
The contract is now compiled and ready to be deployed. Next you will need to declare an RPC provider within your contract.
+To interact with the Starknet network, you need to set an RPC endpoint within Starkli.
+The following are the RPC providers available for Starknet:
+| Provider name | +Description | +
|---|---|
Infura or Alchemy |
+Use a provider like Infura or Alchemy. |
+
Custom configuration |
+Set up your own node and use the RPC provider of your node. More information on this can be found within the Starknet Book. |
+
For demonstration purposes, the Starknet Sequencer’s Gateway is used in the below steps.
+A contract can be declared on Starknet using the following command:
+starkli declare target/dev/<NAME>.json --network=sepolia --compiler-version=2.1.0| + + | +
+
+
+The
+
+The |
+
You can find the compiler version supported by Starkli by running:
+starkli declare --helpIn the --compiler-version flag you will see possible versions of the compiler:
--compiler-version <COMPILER_VERSION>
+ Statically-linked Sierra compiler version [possible values: 2.0.1, 2.1.0]However, the Scarb compiler version may be 2.2.0, you can find this out by running:
scarb --versionThis is because Starkli and Scarb are not always in sync.
+In this case you would need to use the compiler version that Starkli is using by installing a previous version of Scarb. See the Scarb github repo for more detail.
+You can do this by running the following command for installing Scarb version 0.6.1:
curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh -s -- -v 0.6.1If you were using a provider like Infura or Alchemy, the declaration command would look like this:
+starkli declare target/dev/contracts_Ownable.sierra.json \
+ --rpc=https://starknet-sepolia.infura.io/v3/<API_KEY> \
+ --compiler-version=2.6.0The result of the declaration command is a contract class hash:
+Class hash declared: <CLASS_HASH>This hash is the identifier of the contract class in Starknet. You can think of it as the address of the contract class. You can use a block explorer like StarkScan to see the contract class hash in the blockchain.
+Using Starkli: You can use the following command to retrieve the contract class by its hash:
+starkli class-by-hash <CLASS_HASH> --network=sepoliaIf the contract is successfully declared, this command will return the contract class details.
+If the contract you are declaring has previously been declared by someone else, you will get an output like this:
+Not declaring class as its already declared. Class hash: <CLASS_HASH>In this case, you can still use the methods above to verify the existing declaration.
+Ensure that the below commands are working properly on your system.
+starkli --version
+scarb --versionIf either of the above commands fail, please visit Setting up your environment.
+Deploying a smart contract in Starknet requires two steps:
+Declaring the class of your contract, i.e. sending your contract’s code to the network.
+Deploying a contract, i.e. creating an instance of the code you previously declared.
+
+Deployment is the process of creating a live, functional instance of your declared smart contract on the Starknet network. It’s like bringing a blueprint to life by constructing an actual building.
+Let’s use a factory production analogy:
+Declaration is like creating a product blueprint and registering it with the factory.
+Deployment is like using that blueprint to manufacture an actual product on the assembly line.
+Each deployed contract is a unique product instance, even though they’re all based on the same blueprint.
+Deploying a smart contract involves instantiating it on Starknet. The deployment command requires the class hash of the smart contract and any arguments expected by the constructor.
+For our example, the constructor expects an address to assign as the owner:
+starkli deploy \
+ <CLASS_HASH> \
+ <CONSTRUCTOR_INPUTS> \
+ --network=sepoliaWith the class hash and constructor inputs, the command looks like this:
+starkli deploy \
+ 0x00e68b4b07aeecc72f768b1c086d9b0aadce131a40a1067ffb92d0b480cf325d \
+ 0x02cdAb749380950e7a7c0deFf5ea8eDD716fEb3a2952aDd4E5659655077B8510 \
+ --network=sepoliaThink of <CLASS_HASH> as the product code in our factory analogy, and <CONSTRUCTOR_INPUTS> as the specific settings for this product instance.
+After running the command and adding your password, you will see an output similar to this:
+Deploying class 0x00e68b4b07aeecc72f768b1c086d9b0aadce131a40a1067ffb92d0b480cf325d with salt 0x04bc3fc2284c8e41fb3d2a37bb0354fd0506131cc77a8c91e4e67ce3aed1d19e...
+The contract will be deployed at address 0x014825acb37c36563d3b96c450afe363d2fdfa3cfbd618b323f95b68b55ebf7e
+Contract deployment transaction: 0x0086972e7463d5673d8b553ae521ec2df974a97c2ce6aafc1d1c20d22c6b96c6
+Contract deployed: 0x014825acb37c36563d3b96c450afe363d2fdfa3cfbd618b323f95b68b55ebf7eThe smart contract has now been deployed to Starknet.
+To verify your contract deployment:
+Using Starkli: +You can use the following command to retrieve the class hash of your deployed contract:
+starkli class-hash-at <CONTRACT_ADDRESS> --network=sepoliaUsing a Block Explorer:
+You can use block explorers like https://voyager.online/ or https://starkscan.co/ to search for the contract address.
+| + + | +
+
+
+Remember to select the Sepolia testnet in these block explorers when searching for your deployed contract. + |
+
Your smart contract is now live on the Starknet network, ready to interact with users and other contracts.
+When using Starknet SDKs like starknet.js, starknet.py, or starknet-rs, you might encounter the following error during deployment:
+Requested ContractAddress(PatriciaKey(<CONTRACT_ADDRESS>)) is unavailable for deployment.This error means that a contract is already deployed at the computed address. The address is a function of the class_hash, deployer_address (if specified), salt, and constructor_calldata_hash.
+To resolve this issue, make sure to provide a different salt value. This ensures you’re not attempting to override an already deployed contract.
+| + + | +
+
+
+This topic previously appeared in the Starknet Book. + |
+
To compile, deploy, and interact with our smart contract, use the Starknet Remix plugin. This tool enables you to start to develop for Starknet without the need for any local installations on your machine.
+Go to the Remix IDE website with the Starknet plugin activated.
+Click the File Explorer 
tab to review the details of the example project.
Click the Starknet 
tab, and click the Settings. Select the latest version of Cairo available in Remix.
In the File explorer, open the Scarb.toml file to verify the version of your project. Ensure it matches the version specified originally, and correct any discrepancies, if necessary.
Ownable contract| + + | +
+
+
+For this tutorial, a default example project is provided. Modify or remove certain files and directories as needed. + |
+
Rename the root directory to ownable. In your Scarb.toml, under the [package] section, set the name to ownable.
Under src/, delete the balance.cairo and forty_two.cairo files, if they exist.
Open lib.cairo and delete all its contents.
ownable Starknet smart contractExplore the Example Ownable contract, crafted in Cairo for Starknet. It includes:
An ownership system.
+A method to transfer ownership.
+A method to check the current owner.
+An event notification for ownership changes.
+ownable Cairo contractuse starknet::ContractAddress; (1)
+
+#[starknet::interface]
+trait OwnableTrait<T> { (1)
+ fn transfer_ownership(ref self: T, new_owner: ContractAddress); (2)
+ fn get_owner(self: @T) -> ContractAddress; (2)
+}
+
+#[starknet::contract]
+mod Ownable {
+ use super::ContractAddress;
+ use starknet::get_caller_address;
+
+ #[event]
+ #[derive(Drop, starknet::Event)]
+ enum Event {
+ OwnershipTransferred: OwnershipTransferred, (3)
+ }
+
+ #[derive(Drop, starknet::Event)]
+ struct OwnershipTransferred { (3)
+ #[key]
+ prev_owner: ContractAddress,
+ #[key]
+ new_owner: ContractAddress,
+ }
+
+ #[storage]
+ struct Storage { (4)
+ owner: ContractAddress,
+ }
+
+ #[constructor]
+ fn constructor(ref self: ContractState, init_owner: ContractAddress) { (5)
+ self.owner.write(init_owner);
+ }
+
+ #[abi(embed_v0)]
+ impl OwnableImpl of super::OwnableTrait<ContractState> {
+ fn transfer_ownership(ref self: ContractState, new_owner: ContractAddress) {
+ self.only_owner();
+ let prev_owner = self.owner.read();
+ self.owner.write(new_owner);
+ self.emit(Event::OwnershipTransferred(OwnershipTransferred {
+ prev_owner: prev_owner,
+ new_owner: new_owner,
+ }));
+ }
+
+ fn get_owner(self: @ContractState) -> ContractAddress {
+ self.owner.read()
+ }
+ }
+
+ #[generate_trait]
+ impl PrivateMethods of PrivateMethodsTrait {
+ fn only_owner(self: @ContractState) { (6)
+ let caller = get_caller_address();
+ assert(caller == self.owner.read(), 'Caller is not the owner');
+ }
+ }
+}| 1 | +Dependencies and Interface: + starknet::ContractAddress: Represents a Starknet contract address.
+OwnableTrait: Defines essential functions for transferring and retrieving ownership. |
+
| 2 | +External Functions: Contains functions for transferring ownership and fetching information about the current owner. | +
| 3 | +Events: OwnershipTransferred indicates changes in ownership, providing details about the previous and new owners. |
+
| 4 | +Storage: Stores the contract’s state, including the address of the current owner. | +
| 5 | +Constructor: Sets up the contract by assigning an initial owner. | +
| 6 | +Private Methods: only_owner validates if the caller is the current owner. |
+
To compile using Remix:
+Click the File Explorer tab, open the lib.cairo file and insert the code from Example: ownable Cairo contract.
Click the Starknet tab, then click Home.
Under (1) Compile, click Compile lib.cairo.
+Grant the necessary permissions when prompted. Select Remember my choice for a smoother compilation process in the future.
+The compilation process creates an artifacts directory containing the compiled contract in two formats: a Sierra file, in JSON format, and a Casm file. For Starknet deployment, Remix uses the Sierra file.
Deploying a smart contract in Starknet requires two high-level steps:
+Declare the class of your contract, that is, send your contract’s code to the network.
+When you declare the contract class, you establish an initial owner by calling the class’s constructor function.
Deploy an instance of the contract class.
+This tutorial uses a development network (devnet) to deploy your smart contract. A devnet is a Starknet instance that you run as a local node. A devnet enables much quicker development than is possible using testnet, as well as providing privacy prior to launching on testnet.
+Select the network by clicking the Starknet tab, and then clicking the Remote Devnet menu.
+Under Devnet account selection, open the menu to view a list of accounts specific to the designated devnet.
+Select a devnet account from the list and note its address for later use.
+Click the Declare lib.cairo button.
Remix’s terminal provides various logs with important details such as:
+transaction_hash: This unique hash identifies the transaction and can be used to track its status.
class_hash: Similar to an identifier, the class hash contains the definition of the smart contract.
ownable contract------------------------ Declaring contract: lib.cairo ------------------------
+{
+ "transaction_hash": "0x36dabf43f4962c97cf67ba132fb520091f268e7e33477d77d01747eeb0d7b43",
+ "class_hash": "0x540779cd109ad20f46cb36d8de1ce30c75469862b4dc75f2f29d1b4d1454f60"
+}
+---------------------- End Declaring contract: lib.cairo ----------------------After Remix declares the contract class, the Declare button says Declared lib.cairo.
+Now you’re ready to deploy an instance of the contract class.
+Paste the Devnet account address you used into the init_owner variable.
Click Deploy.
+After deployment, Remix’s terminal displays various logs, including a transaction receipt, containing important details, such as:
+transaction_hash: This unique hash identifies the transaction and can be used to track its status.
contract_address: The address of the deployed contract. You can use this address to interact with your contract.
data: Contains the init_owner address provided to the constructor.
Ownable class in lib.cairo------------------------ Deploying contract: lib.cairo ------------------------
+
+{
+ "transaction_hash": "0x624f5b9f57e53f6b5b62e588f0f949442172b3ad5d04f0827928b4d12c2fa58",
+ "contract_address": [
+ "0x699952dc736661d0ed573cd2b0956c80a1602169e034fdaa3515bfbc36d6410"
+ ]
+ ...
+ "data": [
+ "0x6b0ee6f418e47408cf56c6f98261c1c5693276943be12db9597b933d363df",
+ ...
+ ]
+ ...
+}
+---------------------- End Deploying contract: lib.cairo ----------------------Now that the contract is operational on the development network, you can start interacting with it on the Starknet tab, under + (3) Interact.
+Under Read you should see the get_owner() function. Click the Call button. The function doesn’t require any arguments so the calldata field remains empty. This function reads data, so its invocation is referred to as a call.
The terminal displays the output, showing the owner’s address, which you provided during the contract’s deployment within the calldata for the constructor:
+------------------- Calling get_owner ------------------------
+{
+ "resp": {
+ "result": [
+ "0x6b0ee6f418e47408cf56c6f98261c1c5693276943be12db9597b933d363df"
+ ]
+ },
+ "contract": "lib.cairo",
+ "function": "get_owner"
+}
+------------------- End calling get_owner --------------------This call doesn’t consume gas because the function doesn’t modify the contract’s state.
+Under (3) Interact, select Write, where functions that alter the contract’s state are listed.
+Select the transfer_ownership() function, which requires providing the new owner address as input.
Fill in the new_owner field with any Devnet address other than the one you used to deploy the contract.
| + + | +
+
+
+Under Devnet account selection, open the menu, select a Devnet account from the list, and copy its address. + |
+
Click the Call button. The terminal displays the transaction hash indicating the change in the contract’s state. Because this interaction is an INVOKE transaction, and it modifies the contract’s state. An INVOKE transaction requires the signature of the account executing the function.
For INVOKE transactions, the terminal logs include a finality_status parameter indicating the outcome. A status of ACCEPTED_ON_L2 indicates approval by the Sequencer, the entity responsible for receiving and processing transactions, indicating inclusion in an upcoming block. Conversely, a REJECTED status indicates that the Sequencer did not approve the transaction, preventing its inclusion in the next block. Typically, transactions of this nature are approved, resulting in a modification of the contract’s state.
---------- Invoke transfer_ownership transaction receipt ----------------
+{
+ "resp": {
+ "transaction_hash": "0x5495d56633745aa3b97bdb89c255d522e98fd2cb481974efe898560839aa472"
+ },
+ "contract": "lib.cairo",
+ "function": "get_owner"
+}
+----------End Invoke transfer_ownership transaction receipt -------------After testing your smart contract on a development network, the next step is deploying it onto the Starknet testnet. The Starknet testnet is a public platform accessible to all, providing an excellent environment for testing smart contracts and encouraging collaboration among developers.
+Before deploying your smart contract on Starknet, it’s crucial to address transaction costs. While deploying on the Starknet testnet is free, having an operational smart wallet account is essential. You can set up a smart wallet and a Starknet account using either of the following platforms:
+Both options offer robust Starknet wallets with advanced security measures and enhanced accessibility features enabled by the capabilities of the Cairo VM.
+Install the recommended browser extension corresponding to your chosen wallet.
+Follow the instructions provided by your wallet provider to deploy your account on testnet.
+Use the Starknet Faucet to fund your account.
+Execute the deployment of your account onto the network, typically completed within approximately 10 seconds.
+Once the setup is complete, you are primed to deploy your smart contracts onto the Starknet testnet.
+Proceed as per the aforementioned deployment steps.
+Within the Environment selection tab, Select Wallet.
+Select your Starknet account and proceed with the deployment and interaction processes for your contract.
+You can monitor transaction hashes and addresses by using various Starknet block explorers such as:
+These block explorers offer a graphical depiction of transactions and modifications to the contract state. Noteworthy is the visibility provided when altering contract ownership through the transfer_ownership() function, as the emitted event by the contract becomes observable within the block explorer. This mechanism serves as a potent means to monitor contractual events.
In order to interact with Starknet and compile Cairo code, you need to install several tools.
+The following tools are recommended to begin developing on Starknet:
+| Tool name | +Description | +Documentation | +Code Repository | +
|---|---|---|---|
Starkli |
+A command-line interface that allows you to interact with Starknet. |
++ | + |
Scarb |
+A build toolchain and package manager for Cairo and Starknet ecosystems. |
++ | + |
The steps for installing Starkli and upgrading Starkli are identical.
+Install Starkliup, the installer for the Starkli environment:
+curl https://get.starkli.sh | shStarkliup should now be installed.
+Restart the terminal.
+Install Starkli:
+starkliupStarkli should now be installed.
+Restart the terminal and run the following command to verify the installation:
+starkli --versionStarkli prints the current version.
+For the majority of flags available on Starkli you can set environment variables to make the commands shorter and easier to manage.
+Setting environment variables for Starkli significantly simplifies command execution and management, thereby enhancing efficiency, readability, and control when using Starkli.
+The two primary environment variables that are vital for effective usage of Starkli’s CLI are:
+
+STARKNET_ACCOUNT
+ |
+
+ The location of the Account Descriptor file. + |
+
+STARKNET_KEYSTORE
+ |
+
+ The location of the keystore file for the Signer. + |
+
Set these environment variables as follows:
+export STARKNET_ACCOUNT=~/.starkli-wallets/deployer/account.json
+export STARKNET_KEYSTORE=~/.starkli-wallets/deployer/keystore.jsonScarb is compatible with macOS, Linux, and Windows operating systems.
+The steps for installing Scarb and upgrading Scarb are identical.
+Open a terminal and execute the following command:
+curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | shRestart the terminal and run the following command to verify the installation:
+scarb --versionScarb should now be installed.
+Scarb’s installation on Windows requires manual setup.
+Follow the steps in the Scarb documentation.
+Restart the terminal and run the following command to verify the installation:
+scarb --versionScarb should now be installed.
+Ensure that the below commands are working properly on your system.
+starkli --version
+scarb --versionIf either of the above commands fail, see Setting up your environment.
+Starkli enables interaction with smart contracts via two primary methods:
+call for read-only functions.
invoke for write functions that modify the state.
The call command allows querying a smart contract function without sending a transaction.
As an example you can use the get_owner function which doesn’t expect any arguments and returns the address of the current owner:
starkli call \
+ 0x014825acb37c36563d3b96c450afe363d2fdfa3cfbd618b323f95b68b55ebf7e \
+ get_owner --network=sepoliaThis will return the address that we passed to the constructor during deployment:
+[
+ "0x02cdab749380950e7a7c0deff5ea8edd716feb3a2952add4e5659655077b8510"
+]To modify the state of the smart contract, use the invoke command. Unlike the call command, invoke submits a transaction to the network.
In this example, we’ll invoke the transfer_ownership function to transfer the ownership from our deployer address to a different smart wallet address:
starkli invoke \
+ 0x014825acb37c36563d3b96c450afe363d2fdfa3cfbd618b323f95b68b55ebf7e \
+ transfer_ownership \
+ 0x011088d3cbe4289bc6750ee3a9cf35e52f4fa4e0ac9f42fb0b62e983139e135a \
+ --network=sepoliaAfter the transaction is accepted on L2, you can confirm the state transition by calling the get_owner function again:
starkli call \
+ 0x014825acb37c36563d3b96c450afe363d2fdfa3cfbd618b323f95b68b55ebf7e \
+ get_owner \
+ --network=sepoliaThe get_owner function now returns the new owner address, confirming the successful ownership transfer.
| + + | +
+
+
+This guide shows you how to set up a Starknet account and wallet in the context of a smart contract deployment. +
+
+For information on creating a Starknet wallet as an end user, see Getting Started Using Starknet: Setting Up a Starknet Wallet. + |
+
Starkli is installed correctly. Ensure that the following command shows the version information for Starkli:
+starkli --versionIf this command fails, see Setting up your environment.
+A Starknet wallet is installed, either Argent X or Braavos. For information on a specific wallet, including installation instructions, see that wallet’s site.
+A smart wallet is composed of two parts:
+A Signer: A smart contract that can sign transactions.
+An Account Descriptor: A json file that contains information about the smart wallet, such as its address and +public key.
+After creating and funding your smart wallet with ETH you can deploy it to Starknet. For demonstration purposes, this page uses Starknet’s testnet.
+For testnet transactions you can fund your wallet using one of the Starknet Sepolia faucets.
+A Signer is a smart contract that can sign transactions. It’s a crucial component of accounts in Starknet. To create a Signer you will need the private key of your smart wallet (the public key can be derived from it).
+Starkli has the ability to create a keystore file that securely stores the private key of smart wallets each with a password. The accounts in the keystore file can be used to sign transactions using Starkli. The main advantage of this approach +is that it prevents storing the private key as plain text on your computer. Instead, a password is used to create an encrypted file in a location of choice.
+Normally, the keystore file is stored in the default location of the Starkli CLI.
+The following command creates a keystore file for a smart wallet in the default location in ~/.starkli-wallets/deployer:
Create a new directory:
+mkdir -p ~/.starkli-wallets/deployerCreate a keystore file within the directory:
+starkli signer keystore from-key ~/.starkli-wallets/deployer/keystore.json
+
+Enter private key:
+Enter password:
+Created new encrypted keystore file: /home/parallels/.starkli-wallets/deployer/keystore.json
+Public key: 0x0550…| + + | +
+
+
+In the private key prompt, paste the private key of your smart wallet. +
+
+In the password prompt, enter a password of your choice. +
+
+You will need this password to sign transactions using Starkli. + |
+
Next export the private key from your Argent X or Braavos wallet:
+Navigate to: Settings section → Privacy and Security → Export Private Key.
While knowing the private key of a smart wallet is necessary to sign transactions, it’s not sufficient. We also need to inform Starkli about the signing mechanism employed by our smart wallet created by Argent X or Braavos.
+Starkli offers a command to collect all the required information from a smart wallet by providing its onchain address. Using this data, the CLI generates a json file that can be used to sign transactions:
+starkli account fetch --help
+Fetch account config from an already deployed account contractThe fetch command supports both Argent X and Braavos smart wallets. Make sure your wallet address is already deployed and enter the following command to create and save the account descriptor file:
starkli account fetch <SMART_WALLET_ADDRESS> --output ~/.starkli-wallets/deployer/account.json --rpc <YOUR_RPC_ENDPOINT_HERE>You can obtain access to a JSON-RPC endpoint in one of the following ways:
+Host your own node with Pathfinder, Juno, Deoxys, or Papyrus.
+Use a third-party JSON-RPC API provider. For information on providers, see Full nodes and API services.
+The following command shows the details of the account descriptor:
+cat ~/.starkli-wallets/deployer/account.jsonThe account descriptor should have the following structure:
+{
+ "version": 1,
+ "variant": {
+ "type": "argent",
+ "version": 1,
+ "implementation": "<ARGENT_CLASS_HASH>",
+ "signer": "<SMART_WALLET_PUBLIC_KEY>",
+ "guardian": "0x0"
+ },
+ "deployment": {
+ "status": "deployed",
+ "class_hash": "<SMART_WALLET_CLASS_HASH>",
+ "address": "<SMART_WALLET_ADDRESS>"
+ }
+}| + + | +
+
+
+If you are working with Braavos wallet, the type is defined as |
+
Once you have an account file, you can deploy the account contract with the starkli account deploy command.
This command sends a DEPLOY_ACCOUNT transaction, which requires the account to contain enough ETH to pay for the transaction fee.
To deploy your account, run the following command:
+starkli account deploy ~/.starkli-wallets/deployer/account.json| + + | +
+
+
+This command requires a signer. If you receive an error after running this command, ensure you have the |
+
When run, the command shows:
+The address where the contract will be deployed.
+Instructions for the user to fund the account before proceeding.
+Here’s an example command output:
+The estimated account deployment fee is 0.000011483579723913 ETH. However, to avoid failure, fund at least:
+ 0.000017225369585869 ETH
+to the following address:
+ 0x01cf4d57ba01109f018dec3ea079a38fc08b789e03de4df937ddb9e8a0ff853a
+Press [ENTER] once youve funded the address.You have now successfully deployed a new account to Starknet.
+For a faster and more private development process, it is often preferable to use a local version of Starknet – also known as a development network (devnet) – which can be easily set up by either Starknet Devnet or Katana.
+Starkli is installed correctly. Ensure that the following command shows the version information for Starkli:
+starkli --versionIf this command fails, see Setting up your environment.
+Install Devnet:
+cargo install starknet-devnetand start it using:
+starknet-devnet --seed 42| + + | +
+
+
+Upon initialization, Devnet predeploys a fee token, universal deployer, and a set of funded accounts. By default, the set of predeployed accounts changes on each initialization, but specifying the same |
+
The result should be similar to the following:
+Predeployed FeeToken
+ETH Address: 0x49D36570D4E46F48E99674BD3FCC84644DDD6B96F7C741B1562B82F9E004DC7
+STRK Address: 0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d
+Class Hash: 0x046ded64ae2dead6448e247234bab192a9c483644395b66f2155f2614e5804b0
+
+Predeployed UDC
+Address: 0x41A78E741E5AF2FEC34B695679BC6891742439F7AFB8484ECD7766661AD02BF
+Class Hash: 0x7B3E05F48F0C69E4A65CE5E076A66271A527AFF2C34CE1083EC6E1526997A69
+
+Chain ID: SN_SEPOLIA (0x534e5f5345504f4c4941)
+
+| Account address | 0x34ba56f92265f0868c57d3fe72ecab144fc96f97954bbbc4252cef8e8a979ba
+| Private key | 0xb137668388dbe9acdfa3bc734cc2c469
+| Public key | 0x5a5e37c60e77a0318643b111f88413a76af6233c891a0cfb2804106372006d4
+...As previously described, import Devnet’s first predeployed accounts to an account file (notice that the address of the fetched account is the same as the one printed out by Devnet):
+starkli account fetch --rpc http://127.0.0.1:5050 0x34ba56f92265f0868c57d3fe72ecab144fc96f97954bbbc4252cef8e8a979ba --output ~/.starkli-wallets/devnet/account.json| + + | +
+
+
+
|
+
and create the corresponding keystore file by executing:
+starkli signer keystore from-key ~/.starkli-wallets/devnet/keystore.jsonand entring 0xb137668388dbe9acdfa3bc734cc2c469 as private key (the same one as the one printed out by Devnet)
Now that you have an account set up, you can use Starkli to freely interact with Devnet. For example, you can redeploy Devnet’s predeployed universal deployer using the following command:
+starkli deploy --rpc http://127.0.0.1:5050 --account ~/.starkli-wallets/devnet/account.json --keystore ~/.starkli-wallets/devnet/keystore.json 0x7B3E05F48F0C69E4A65CE5E076A66271A527AFF2C34CE1083EC6E1526997A69Install Katana:
+git clone https://github.com/dojoengine/dojo
+cd dojo
+cargo install --path ./bin/katana --locked --forceand start it using:
+katana| + + | +
+
+
+Upon initialization, Katana predeploys a fee token, universal deployer contract (UDC), and a set of funded accounts. By default, Katana predeploys the same set of accounts. + |
+
The result should be similar to the following:
+PREDEPLOYED CONTRACTS
+==================
+
+| Contract | Fee Token
+| Address | 0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7
+| Class Hash | 0x02a8846878b6ad1f54f6ba46f5f40e11cee755c677f130b2c4b60566c9003f1f
+
+| Contract | Universal Deployer
+| Address | 0x41a78e741e5af2fec34b695679bc6891742439f7afb8484ecd7766661ad02bf
+| Class Hash | 0x07b3e05f48f0c69e4a65ce5e076a66271a527aff2c34ce1083ec6e1526997a69
+
+| Contract | Account Contract
+| Class Hash | 0x05400e90f7e0ae78bd02c77cd75527280470e2fe19c54970dd79dc37a9d3645c
+
+
+PREFUNDED ACCOUNTS
+==================
+
+| Account address | 0xb3ff441a68610b30fd5e2abbf3a1548eb6ba6f3559f2862bf2dc757e5828ca
+| Private key | 0x2bbf4f9fd0bbb2e60b0316c1fe0b76cf7a4d0198bd493ced9b8df2a3a24d68a
+| Public key | 0x640466ebd2ce505209d3e5c4494b4276ed8f1cde764d757eb48831961f7cdea
+...Starkli comes with several built-in accounts for Katana’s default initialization, which can be used to freely interact with Katana without any setup (for the full list of account addresses, see BUILTIN_ACCOUNT in Starkli’s accounts.rs file). For example, you can redeploy Katana’s predeployed universal deployer using the following command:
starkli deploy --rpc http://0.0.0.0:5050 --account katana 0x07b3e05f48f0c69e4a65ce5e076a66271a527aff2c34ce1083ec6e1526997a69| + + | +
+
+
+
|
+
Staking on Starknet is designed to enhance network security and decentralization by allowing users to stake their STRK tokens directly or delegate them to other validators. The architecture is modular, with different contracts handling specific responsibilities to ensure flexibility, security, and ease of upgrades. For more details on the staking architecture, visit the following link: Starknet Staking Repository.
+Staking is divided into several key components, each responsible for different aspects of the staking process.
+The following contracts handle the core functionalities of the staking system:
+Contract |
+Description |
+
Staking Contract |
+The central contract that manages the staking process. It handles direct staking, rewards distribution, and interactions with delegation pools. Validators interact with this contract to stake their tokens, claim rewards, and initiate unstaking. |
+
Delegation Pooling Contract |
+This contract manages the delegation process, allowing delegators to assign their tokens to a validator for staking. The contract is responsible for tracking each delegator’s share, calculating their rewards, and managing the delegation and unstaking processes. |
+
Reward Supplier Contract |
+A dedicated contract that calculates and supplies the rewards for validators and delegators. It interfaces with the staking contract to distribute rewards based on the defined minting curve. |
+
Minting Curve Contract |
+A contract responsible for implementing the minting curve logic that governs the reward distribution mechanism. It adjusts rewards dynamically based on the total staked amount and the overall supply of STRK tokens. |
+
The following data structures are stored within the contracts and play a crucial role in managing validators' and delegators' information within the staking protocol:
+Structure |
+Description |
+
StakerInfo Structure |
+A data structure stored within the staking contract that holds detailed information about each validator, including their staked amount, unclaimed rewards, delegation details, and operational parameters. This structure ensures that validators' information is accurately tracked and updated. |
+
PoolMemberInfo Structure |
+A data structure stored within the delegation pooling contract that holds information about each delegator’s contributions, rewards, and status within the pool. This structure helps manage and calculate the delegation and reward distribution processes for pool members. |
+
For more technical details, you can refer to the full staking specification document available in: Staking Repository Spec.
+The staking contract is the core of the staking system. It manages the lifecycle of validators, from the initial stake to claiming rewards and unstaking. The contract ensures that the validator’s tokens are securely locked and that rewards are distributed according to the minting curve.
+Key Functions and Responsibilities:
+stake: Allows users to stake their STRK tokens directly into the contract. The function initializes the validator’s information, locks the tokens, and optionally deploys a delegation pool if pooling is enabled.
+increase_stake: Lets existing validators add more tokens to their stake. The contract recalculates rewards and updates the validator’s information accordingly.
+unstake_intent: Initiates the unstaking process by locking the validator’s tokens for a specified exit period. No rewards are earned during this period.
+unstake_action: Finalizes the unstaking process after the exit period has passed, releasing the staked tokens back to the validator.
+claim_rewards: Calculates and transfers the validator’s accumulated rewards to their designated reward address.
The delegation pooling contract enables users to delegate their tokens to a validator without having to manage the staking process themselves. This contract tracks each delegator’s contribution, calculates their rewards, and manages the delegation lifecycle.
+Key Functions and Responsibilities:
+enter_delegation_pool: Allows users to delegate their tokens to the pool associated with a validator. This function transfers the tokens, updates the delegator’s record, and integrates them into the validator’s pool.
+add_to_delegation_pool: Enables existing delegators to increase their delegation amount. The contract updates the pool’s total and recalculates the member’s rewards.
+exit_delegation_pool_intent: Initiates the process for a delegator to exit the pool. Similar to validators, the delegator’s funds are locked for a period before they can be withdrawn.
+exit_delegation_pool_action: Finalizes the exit process for a delegator, returning their tokens and any unclaimed rewards.
+switch_delegation_pool: Allows a delegator to transfer their delegated stake from one validator’s pool to another, facilitating dynamic delegation strategies.
+claim_rewards: Transfers the delegator’s earned rewards to their specified reward address.
The reward supplier contract is responsible for calculating and supplying the staking rewards based on the minting curve. It ensures that the rewards are distributed fairly and in accordance with the protocol’s economic parameters.
+Key Functions and Responsibilities:
+calculate_staking_rewards: Computes the rewards based on the current staking rate and the minting curve, updating the staking contract with the amount to be distributed.
+claim_rewards: Handles the transfer of rewards to the staking contract, ensuring that the correct amount is distributed to validators and delegators.
The minting curve contract defines the economic model that governs reward distribution. It ensures that the network’s inflation is managed while incentivizing participation in staking.
+Key Functions and Responsibilities:
+yearly_mint: Returns the amount of STRK tokens to be minted annually based on the current staking rate. This function uses a square root formula to balance rewards and inflation.
+update_total_supply: Updates the total supply of STRK tokens, ensuring that the minting calculations remain accurate.
The staking architecture on Starknet is designed with security and upgradability in mind. Each contract is modular, allowing for targeted upgrades and improvements without affecting the entire system. Access control mechanisms are in place to ensure that only authorized parties can make critical changes, further enhancing the security of the staking process.
+Staking rewards on Starknet accumulate over time as your staked STRK tokens contribute to network security. To claim these rewards, you need to interact with the staking contract (if you are a validator) or the specific delegation pooling contract associated with the validator you have staked with (if you are a delegator) and execute the appropriate functions.
+The validator or delegator address must have an existing stake in the respective contract.
+The caller must be either the validator/delegator or their respective reward address.
+Using a Starknet block explorer, navigate to the appropriate contract:
+For validators: Navigate to the staking contract.
+For delegators: Navigate to the delegation pooling contract associated with the validator you have staked with.
+In the contract interface, locate and select the claim_rewards function.
Enter the following parameters:
+In staker_address or pool_member, enter the address of the validator or delegator for whom you are claiming the rewards.
Submit the transaction to initiate the rewards claim.
+| + + | +
+
+
+Ensure that the address entered is either the validator’s or delegator’s main address or their respective reward address. If the address is not authorized, the function will fail. + |
+
Once the transaction is successful, the rewards will be transferred to the designated reward address associated with the staked tokens.
+Delegating your stake on Starknet involves adding your stake to a validator’s delegation pool managed by the staking contract. This approach offers the advantage of lower capital requirements and relieves you of the need to manage the operational aspects of staking, as the validator handles these responsibilities.
+The delegation process includes joining a validator’s delegation pool by interacting with the enter_delegation_pool function.
Using a Starknet block explorer, navigate to the delegation pooling contract associated with the validator you want to delegate to.
+In the contract interface, locate and select the enter_delegation_pool function.
Enter the following parameters:
+In amount, enter the number of STRK tokens you want to delegate to the validator.
In reward_address, enter the address where you wish to receive your staking rewards.
Submit the transaction to join the delegation pool.
+Upon successful execution, your STRK tokens will be added to the validator’s delegation pool, and you will begin earning rewards as part of the pooled staking process.
+Using the Starknet staking contract to stake STRK tokens requires interacting with the stake function. The stake function does the following:
Locks the specified amount of STRK tokens from the validator’s account into the staking contract.
+Records the validator’s details, including reward and operational addresses, in the staking contract.
+If pooling is enabled, deploys a new delegation pool contract associated with the validator.
+Subsequently, the validator’s tokens will be locked in the staking contract, and the validator will begin earning rewards based on their stake.
+For more information on what happens during the staking process, see Staking Contract Architecture.
+Validators are expected to run full nodes in preparation for the following stages of the protocol. You can use any full node implementation you choose:
+Pathfinder by EQLabs - Spec.
+A Starknet-compatible block explorer or CLI tool.
+Sufficient STRK token balance in your wallet.
+Pre-approval of the STRK ERC20 contract (Starkscan, Voyager) +on Starknet for the transfer of tokens from your address to the staking contract.
+Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the stake function.
Enter the following parameters:
+In reward_address, enter the address where the rewards will be sent.
In operational_address, enter the operational address associated with this stake.
In amount, enter the number of STRK tokens you want to stake.
In pooling_enabled, enter true if you wish to enable delegation pooling, otherwise enter false.
In commission, enter the commission rate for any delegated staking. The rate should be entered as a percentage with precision, where 10000 represents 100%. For example, to set a 5% commission, you would enter 500.
Submit the transaction to execute the staking operation.
+Exiting the staking protocol involves either unstaking your STRK tokens as a validator or undelegating your stake as a delegator. Both processes require you to first signal your intent to exit, followed by an action to finalize the process after a waiting period.
+Validators can unstake their STRK tokens, which involves pausing rewards and exiting the staking contract.
+The validator must not currently be in the unstake process.
+Signal Unstake Intent:
+Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the unstake_intent function.
Submit the transaction to initiate the unstake process. This will record the unstake intent, pause rewards collection, and set a waiting period.
+Finalize Unstake:
+After the waiting period has passed, return to the staking contract.
+In the contract interface, locate and select the unstake_action function.
Enter the following parameters:
+In staker_address, enter the validator’s address.
Submit the transaction to finalize the unstaking process and transfer the staked STRK tokens back to the validator’s account.
+| + + | +
+
+
+Any address can initiate the |
+
| + + | +
+
+
+Ensure that enough time has passed since signaling your unstake intent. If the waiting period has not expired, the |
+
Delegators can undelegate their stake from a validator’s delegation pool by following a similar process.
+A Starknet-compatible block explorer or CLI tool.
+The delegator must not currently be in the undelegation process.
+The contract address of the delegation pooling contract. (TODO: Check if this really needs to be mentioned.)
+Signal Undelegation Intent:
+Using a Starknet block explorer, navigate to the delegation pooling contract.
+In the contract interface, locate and select the exit_delegation_pool_intent function.
Submit the transaction to initiate the undelegation process. This will record the undelegation intent, pause rewards collection, and set a waiting period.
+Finalize Undelegation:
+After the waiting period has passed, return to the delegation pooling contract.
+In the contract interface, locate and select the exit_delegation_pool_action function.
Enter the following parameters:
+In pool_member, enter the delegator’s address.
Submit the transaction to finalize the undelegation process and transfer the undelegated STRK tokens back to the delegator’s account.
+| + + | +
+
+
+Any address can initiate the |
+
| + + | +
+
+
+Ensure that enough time has passed since signaling your undelegation intent. If the waiting period has not expired, the |
+
When a validator unstakes, any unclaimed rewards are automatically transferred to the reward address before the stake is returned.
+Similarly, when a delegator undelegates, any unclaimed rewards are automatically transferred to the delegator’s reward address.
+For more details on the staking and delegation processes, see Staking Contract Architecture.
+Staking events in Starknet provide critical information about changes in the staking process, such as balance updates, delegation pool creation, and exit intents. This section guides you through the process of handling these events and responding to them.
+The staking and pooling contracts allow validators and delegators to increase their existing stake. Validators use the increase_stake function, which is called from the staking contract, while delegators use the add_to_delegation_pool function, which is called from the delegation pooling contract. These functions add the specified amount of STRK tokens to the current stake, recalculate rewards before the staked amount is updated, and update the total staked amount.
Sufficient STRK token balance in your Starknet wallet.
+The validator/delegator must have pre-approved the relevant contract (staking contract for validators, delegation pooling contract for delegators) to transfer the specified STRK amount from their account.
+The validator/delegator must not be in an unstake/undelegate process.
+The caller must be either the validator/delegator or their respective reward address.
+Using a Starknet block explorer, navigate to the relevant contract (staking contract for validators, delegation pooling contract for delegators).
+In the contract interface, locate and select the increase_stake function (for validators) or the add_to_delegation_pool function (for delegators).
Enter the following parameters:
+In address, enter the address of the validator (for increase_stake) or the delegator (for add_to_delegation_pool) whose stake you want to increase. This can be either the validator’s/delegator’s address or their respective reward address.
In amount, enter the number of STRK tokens you want to add to the existing stake.
Submit the transaction to execute the stake increase.
+| + + | +
+
+
+Ensure that the validator/delegator is not in an unstake/undelegate process before attempting to increase the stake. If they are currently unstaking/undelegating, this function will fail. + |
+
This guide outlines how both validators and delegators can manage various aspects of their staking and delegation activities on Starknet. Validators can perform operations such as opening delegation pools, updating commission rates, and changing operational and reward addresses. Delegators can manage their participation by changing their reward addresses associated with delegation pools.
+Validators have several functions available to effectively manage their staking and delegation settings.
+An existing stake in the staking contract.
+An existing delegation pool if updating pool-specific settings.
+If a validator does not yet have a delegation pool, they can open one by calling the set_open_for_delegation function.
Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the set_open_for_delegation function.
Enter the following parameter:
+commission: Enter the commission rate for the delegation pool, expressed as a percentage with precision (where 10000 represents 100%). For example, to set a 5% commission, enter 500.
Submit the transaction to create the delegation pool.
+Once created, the delegation pool will be associated with the validator’s staking contract, allowing delegators to delegate their stake to the validator.
+Validators can update the commission rate of their delegation pool using the update_commission function. Note: The commission rate can only be decreased or kept the same; it cannot be increased.
Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the update_commission function.
Enter the following parameter:
+commission: Enter the new commission rate, which must be equal to or less than the current rate, expressed as a percentage with precision (where 10000 represents 100%). For example, to set a 5% commission, enter 500.
Submit the transaction to update the commission rate.
+Validators can change their operational address by interacting with the change_operational_address function.
Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the change_operational_address function.
Enter the following parameter:
+operational_address: Enter the new operational address.
Submit the transaction to update the operational address.
+Validators can update the reward address associated with their staking contract using the change_reward_address function.
Using a Starknet block explorer, navigate to the staking contract.
+In the contract interface, locate and select the change_reward_address function.
Enter the following parameter:
+reward_address: Enter the new reward address.
Submit the transaction to change the reward address.
+Delegators can change their reward address by interacting with the change_reward_address function in the delegation pooling contract.
Using a Starknet block explorer, navigate to the delegation pooling contract associated with your delegation.
+In the contract interface, locate and select the change_reward_address function.
Enter the following parameter:
+reward_address: Enter the new reward address.
Submit the transaction to update the reward address.
+For more information on how the staking and delegation pooling systems work, refer to the Staking Contract Architecture.
+Staking on Starknet involves locking STRK tokens in the staking protocol, contributing to network security and performance. Users can either stake directly or delegate their tokens to others, with rewards based on their level of participation and contribution.
+The key terms used in this document are:
+Stake: Locking STRK tokens into the staking protocol.
+Delegate: Assigning STRK tokens to a validator to participate indirectly.
+Reward: Earnings from participating in staking.
+| + + | +
+
+
+STRK tokens never leave the Starknet protocol during these operations. + |
+
Starknet Staking repository.
+For Staking contract addresses, see Staking Contract Architecture.
+The staking protocol features two main options:
+Staking: Users can stake any amount of STRK, with a minimum threshold set at 20,000 STRK. Validators are expected to run full nodes and eventually handle additional responsibilities as the protocol evolves.
+Stake Delegation: Users can delegate their STRK to validators without running their own nodes. Delegators share in the rewards earned by the validators they choose.
+Validators and delegators can both unstake their funds, subject to network-defined latencies for security.
+Rewards are distributed based on the amount staked and the commission policy constant \(CP\) set by the validator. The rewards are calculated using the following formulas:
+Here, \(\text{rewards_constant}\) is determined by the minting curve, which adjusts rewards based on the total staked amount.
+The minting curve balances participation and inflation by adjusting rewards based on the total STRK locked in the protocol. It is defined by the formula:
+Where:
+\(S\) is the staking rate as a percentage of the total token supply.
+\(M\) is the annual minting rate as a percentage of the total token supply.
+\(C\) is the maximum theoretical inflation percentage.
+For the first stage, \(C\) is proposed to be 1.6%.
+Current Version: Immediate entry and exit from the staking protocol. However, funds are subject to a 21-day security lockup after withdrawal.
+Future Versions: Introduction of epochs to determine entry/exit latencies and continued 21-day lockup after withdrawal.
+| + + | +
+
+
+Stake delegators can switch between validators without waiting for the full lockup period, promoting a competitive delegation market. + |
+
The proposed economic parameters are:
+Minimum STRK for Staking: 20,000 STRK
+Withdrawal Security Lockup: 21 days
+Minting Curve Yearly Inflation Cap (\(C\)): 1.6% (see here for the relevant voting proposal)
+Commission Policy Parameter (\(CP\)): Set by the validator (0 - 1)
+These values are our proposed starting points for this version of the protocol. As part of the rationale behind this version, they are subject to change and may be adjusted to better suit the protocol’s needs under the proper governance procedures.
+Switching your delegated stake from one validator’s delegation pool to another allows you to optimize your staking strategy by moving your funds to a different validator. This process involves interacting with the switch_delegation_pool function in the delegation pooling contract, which coordinates with the staking contract to move your stake.
An existing delegation in a validator’s pool with a STRK token balance equal to or greater than the amount you wish to switch.
+The delegator must have initiated an undelegation process before attempting to switch pools.
+The target validator must have an active delegation pool associated with their staking contract.
+Using a Starknet block explorer, navigate to the delegation pooling contract associated with the validator from whose pool you wish to switch.
+In the contract interface, locate and select the switch_delegation_pool function.
Enter the following parameters:
+In to_staker, enter the address of the validator whose pool you want to switch to.
In to_pool, enter the address of the target delegation pooling contract associated with the new validator.
In amount, enter the number of STRK tokens you want to move to the new delegation pool.
Submit the transaction to execute the delegation pool switch.
+| + + | +
+
+
+Ensure that you have initiated the undelegation process before attempting to switch pools. If the undelegation intent has not been set, this function will fail. + |
+
Upon successfully switching pools, any unclaimed rewards from your previous delegation pool will be transferred to your designated reward address. Your subsequent rewards will be based on the performance of the new validator’s delegation pool.
+For more details on the staking architecture and how delegation pools work, see Staking Contract Architecture.
+StarkGate supports permissionless bridging.
+Want to learn how to enroll a token bridge on StarkGate? Check out this Community Guide.
+enrollTokenBridge in the StarkGate function reference
While StarkGate is referred to as a bridge, technically, each supported token has its own bridge, each of which is defined in a corresponding pair of L1 and L2 contracts, as described in Components of a bridge for an individual token.
+L1 |
+
+
|
+
L2 |
+
+
|
+
| + + | +
+
+
+StarkGate 2.0 provides a contract that enables seamless backward compatibility with the previous version of StarkGate. +
+
+When you update the code in your contract, make sure that you use the most up-to-date versions of all StarkGate contracts. + |
+
You can check if a token is currently supported with the L1 function getBridge.
You can permissionlessly add support for ERC-20 tokens to the multi-token bridge using the enrollTokenBridge function.
StarkGate includes the following administration components:
+is responsible for adding bridges
+contains the addresses to all supported bridges
+enables a bridge developer to stop servicing an existing bridge
+All token bridges that existed prior to StarkGate 2.0 (Mainnet: January 2024) besides supporting all StarkGate 2.0 functionality, are backward compatible. Each token was bridged with a unique, custom pair of L1 and L2 bridge contracts. The L1 bridge is an instance of LegacyBridge.sol, and the L2 bridge is an instance of legacy_bridge_eic.cairo.
L1 ERC-20 contract address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
L2 ERC-20 contract address: 0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8
L1 bridge contract address: 0xF6080D9fbEEbcd44D89aFfBFd42F098cbFf92816
L2 bridge contract address: 0x05cd48fccbfd8aa2773fe22c217e808319ffcc1c5a6a463f7d8fa2da48218196
Consider the deposit functions for the L1 bridge contract for USDC on Etherscan: 0xf6080d9fbeebcd44d89affbfd42f098cbff92816#writeProxyContract
This contract has the following two deposit functions: deposit (0x0efe6a8b) and deposit (0xe2bbb158), which shows that the bridge includes support for the legacy functionality as well as the modern functionality:
+deposit (0x0efe6a8b)
+ |
+
+ The StarkGate 2.0 contract, which includes support for all tokens within a single contract, requiring that you enter the address of the token in the deposit function. + |
+
+deposit (0xe2bbb158)
+ |
+
+ The legacy contract, which is labeled Support Legacy ABI. This function does not include the |
+
The following tokens have legacy contracts as well as StarkGate 2.0 contracts:
+Starknet Token (STRK)
+Starknet Voting Token (vSTRK)
+Wrapped BTC (WBTC)
+USD Coin (USDC)
+Tether USD (USDT)
+Ether (ETH)
+Dai Stablecoin (DAI)
+Dai Stablecoin (DAI) (Dai v0)
+Wrapped liquid staked Ether 2.0 (wstETH)
+Rocket Pool ETH (rETH)
+R Stablecoin (R)
+Frax (FRAX)
+Frax Share (FXS)
+Staked Frax Ether (sfrxETH)
+LUSD Stablecoin (LUSD)
+Uniswap (UNI)
+For complete details, see the bridged_tokens directory on GitHub.
By default, StarkGate imposes no limit on withdrawals. However, in order to mitigate risks associated with critical vulnerabilities that could result in the loss of user funds, StarkGate can enable a withdrawal limit.
+If a serious security issue arises, the security agent in the StarkGate contract can limit withdrawals to 5% of the Total Value Locked (TVL) per day for any affected token by calling the setWithdrawLimitPCT() function in the WithdrawalLimit.sol contract. A dedicated team can then investigate and resolve the issue.
Only a security admin quorum can disable the withdrawal limit. The quorum will consist of Starknet Foundation members, Starknet ecosystem contributors, and StarkWare representatives. This diverse group will ensure that decisions reflect the Starknet community’s broad interests.
+This approach, blending manual oversight with automated detection, aims to minimize potential losses.
+The StarkGate function reference. Lists functions exposed by the Registry, Manager, and the bridge itself, including:
+L1 contracts on GitHub
+L2 contracts on GitHub
+A Smart Deposit is a deposit that moves funds from L1 to L2 and then triggers subsequent actions. For example, a user can deposit funds and transfer those funds to another recipient, such as an exchange.
+The depositWithMessage function enables a Smart Deposit. depositWithMessage is similar to the deposit function, with an additional 256-bit message, which can contain instructions for executing additional actions.
Upon completion, the depositWithMessage function triggers a call to a callback function, named on_receive, on the L2 contract that receives the deposit. The on_receive function receives the deposit message as input.
on_receive must return true for the deposit to succeed. If on_receive returns false, or if the recipient contract does not include the on_receive function, the depositWithMessage function’s L1 handler fails. The user can recover their funds using the depositWithMessageCancelRequest function.
Implement the on_receive function in the L2 contract that should receive deposits.
Use the depositWithMessage function to transfer funds from L1 to L2.
To ensure self-custody, StarkGate enables you to cancel a deposit if, after depositing funds with the deposit function on L1, you don’t see your funds appear on L2 within a reasonable amount of time.
You can only cancel a deposit that you yourself deposited.
+In order to guard against an attack, it takes approximately five days to cancel a deposit. From the moment StarkGate receives the cancellation request, a counter begins. When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit.
+To cancel a deposit, call the depositCancelRequest request function.
When StarkGate receives the cancellation request, a counter begins to count five days.
+When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit by calling depositReclaim.
| + + | +
+
+
+As long as the
+
+Only the depositor is allowed to cancel +a deposit, and only before depositReclaim was performed. + |
+
depositCancelRequest in the StarkGate function reference.
depositReclaim in the StarkGate function reference.
Using StarkGate to deposit L1 funds into the L2 Starknet requires StarkGate’s deposit function. The deposit function does the following:
Transfers the funds from the user’s Ethereum account to the StarkGate L1 contract.
+Emits a Deposit event that includes the L1 and L2 addresses of the user, and the amount deposited.
Sends a message to the corresponding L2 bridge with the amount deposited, and the recipient’s address.
+Subsequently, the funds should be transferred to Starknet so that you can begin using them.
+For more information on what happens during the transfer process, see L1→L2 transfer (deposit).
+An Ethereum block explorer, such as Etherscan.
+Funds to transfer from L1 to L2, including enough to pay the fees required for the transfer.
+The L1 address of the StarkGate bridge for the token you want to deposit. To view the token addresses for tokens on Mainnet or Sepolia testnet, see Bridged tokens and addresses.
+Using an Ethereum block explorer, go to the StarkGate contract and click Write as Proxy. For example, using Etherscan, go to 0xae0ee0a63a2ce6baeeffe56e7714fb4efe48d419
+Click the StarkGate 2.0 deposit function (0x0efe6a8b).
Enter the following:
+In payableAmount, enter the maximum amount of ETH that you’re willing to pay for the deposit transaction fee.
In token (address), enter the address of the L1 contract for the token that you want to deposit to L2.
In amount (uint256), enter an integer for the amount of the token that you want to deposit to L2.
In l2Recipient (uint256), enter the address of the recipient on L2.
Click Write. The deposit function initiates a deposit.
StarkGate enforces a minimum fee for all transactions to account for the L1 → L2 message costs. For more information, see L1 → L2 message fees.
+You can estimate the fee using the following L1 functions:
+
+estimateDepositFeeWei
+ |
+
+ Estimates the fee for a deposit transaction. + |
+
+estimateEnrollmentFeeWei
+ |
+
+ Estimates the fee for an enrollment transaction. + |
+
The StarkGate smart contracts include functions that you use to implement various flows in a dApp.
+For information on the movement of funds between Ethereum and Starknet, see StarkGate bridge overview.
+| + + | +
+
+
+StarkGate 2.0 provides a contract that enables seamless backward compatibility with the previous version of StarkGate. +
+
+When you update the code in your contract, make sure that you use the most up-to-date versions of all StarkGate contracts. + |
+
The L1 functions and their interfaces, where available, are defined in the following smart contracts:
+| Contract | +Name | +Functions | +
|---|---|---|
| + | The StarkGate Manager. +Use the Manager to enroll a new token. +An interface is available through |
+
+
|
+
| + |
+
+The StarkGate Registry. +
+
+Use the Registry to view the addresses of existing bridges and to stop servicing a specific token. +
+ An interface is available through |
+
+
|
+
| + | The primary StarkGate bridge contract. The functions and events in this reference that provide the main user bridge functionality are defined in this contract. |
+
+
|
+
| + | An interface to check if a contract is servicing a token. |
+
+
|
+
The L2 functions and their interfaces, where available, are defined in the following smart contracts:
+| Contract | +Description | +Functions | +
|---|---|---|
| + | The StarkGate bridge implementation on L2. This contract includes the standard functions for a token bridge. +An interface is available through |
+
+
|
+
Functions are listed in alphabetical order.
+depositDeposits the specified amount of an ERC-20 token to the L1 StarkGate bridge contract.
+The deposit function does the following:
+Transfers the funds from the caller’s account to the Starknet bridge contract
+Emits the Deposit event with the sender’s address on L1, the recipient’s address on L2, and the amount
external
payable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
None.
+Deposit
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce for the L1 transaction. + |
+
+uint256 fee
+ |
+
+ The Starknet fee sent with the transaction. + |
+
Contract: StarknetTokenBridge.sol
depositCancelRequestSends a request to StarkGate to cancel a deposit.
+You can send a cancellation request if the funds you transfer from L1 to L2 do not appear on L2 within a reasonable amount of time.
+In order to guard against an attack on Starknet, it takes approximately five days to cancel a deposit. When StarkGate receives the cancellation request, a counter begins. When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit using the depositReclaim function.
The depositReclaim function can only be used once for any deposit cancellation request.
external
nonpayable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
None.
+DepositCancelRequest
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
Contract: StarknetTokenBridge.sol
Function: depositCancelRequest
Event: DepositCancelRequest
depositReclaimReclaims a deposit after a five day period has passed from the time that StarkGate received a deposit cancellation request from the depositCancelRequest function.
external
nonpayable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
None.
+event DepositReclaimed
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
Contract: StarknetTokenBridge.sol
Function: depositReclaim
Event: DepositReclaimed
depositWithMessageSimilar to deposit, with a message attached.
With this function, a deposit transaction can trigger subsequent actions. For example, you can deposit funds and include a message to transfer those funds to another address. depositWithMessage lets you execute these two separate transactions with a single user action.
After depositing to another recipient, the L1 handler in token_bridge.cairo calls the on_receive function in the contract of the recipient.
If on_receive returns true, then the on_receive function succeeded. If it returns false, or if it doesn’t return any value because the on_receive function is not implemented in the recipient contract, the operation fails and the transaction is reverted.
external
payable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
+uint256[] calldata message
+ |
+
+ The message attached to the deposit. + |
+
None.
+DepositWithMessage
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256[] message
+ |
+
+ The message attached to the deposit. + |
+
+uint256 nonce
+ |
+
+ The nonce for the L1 transaction. + |
+
+uint256 fee
+ |
+
+ The Starknet fee sent with the transaction. + |
+
Contract: StarknetTokenBridge.sol
+Function: depositWithMessage
Event: DepositWithMessage
depositWithMessageCancelRequestSends a request to StarkGate to cancel a deposit sent with depositWithMessage.
Similar to depositCancelRequest.
external
nonpayable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
+uint256[] calldata message
+ |
+
+ The message attached to the deposit. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
None.
+DepositWithMessageCancelRequest
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256[] message
+ |
+
+ The message attached to the deposit. + |
+
+uint256 nonce
+ |
+
+ The nonce for the L1 transaction. + |
+
Contract: StarknetTokenBridge.sol
+Function: depositWithMessageCancelRequest
depositWithMessageReclaimSends a request to StarkGate to cancel a deposit sent with depositWithMessage.
Similar to depositCancelRequest.
Reclaims a deposit sent with a message after a five day period has passed from the time that StarkGate received a deposit cancellation request from the depositWithMessageCancelRequest function.
external
nonpayable
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 l2Recipient
+ |
+
+ The L2 address of the recipient. + |
+
+uint256 nonce
+ |
+
+ The nonce of the deposit. + |
+
None.
+DepositWithMessageCancelRequest
+address indexed sender
+ |
+
+ The L1 address of the account that sent the deposit. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the deposit. + |
+
+uint256 indexed l2Recipient
+ |
+
+ The L2 address of the recipient. +The L2 address of the recipient. + |
+
+uint256[] message
+ |
+
+ The message attached to the deposit. + |
+
+uint256 nonce
+ |
+
+ The nonce for the L1 transaction. + |
+
Contract: StarknetTokenBridge.sol
+Function: depositWithMessageReclaim
Event: DepositWithMessageReclaimed
enrollTokenBridgeCreates a Starknet bridge for the specified ERC-20 token contract address in the multi-token bridge contracts and adds the token to the StarkGate Registry.
+Does not work for any ERC-20 token bridge’s contract address that is already in the registry.
+Enrolling a new bridge creates a new ERC-20 contract on L2. You can see the class hash for this contract using get_erc20_class_hash.
| + + | +
+
+
+Enrolling a new bridge does not add it to the StarkGate GUI. You can use a block explorer to use the newly created bridge. + |
+
external
payable
The message payload needs to include funds to cover the Starknet (L2) fee for executing this transaction. You can include this payload using a standard wrapper such as web3.js.
+
+address token
+ |
+
+ The address of the contract for the desired ERC-20 token. + |
+
None.
+TokenEnrollmentInitiated
Function: enrollTokenBridge in StarkgateManager.sol
Event: TokenEnrollmentInitiated in StarknetTokenBridge.sol
estimateDepositFeeWeiReturns an estimate of the fee, in Wei, for depositing funds to the L1 StarkGate bridge contract.
+external
view
None.
+
+uint256
+ |
+
+ An estimate of the fee, in Wei, for depositing funds to the L1 StarkGate bridge contract. + |
+
None.
+estimateDepositFeeWei in StarknetTokenBridge.sol
estimateEnrollmentFeeWeiReturns an estimate of the fee, in Wei, for creating and registering a new bridge using the enrollTokenBridge function.
external
view
None.
+
+uint256
+ |
+
+ An estimate of the fee, in Wei, for creating and registering a new bridge. + |
+
None.
+estimateEnrollmentFeeWei in StarknetTokenBridge.sol
getBridgeReturns the address of the bridge for the specified token, or a value indicating if the bridge does not exist, is blocked, or is deactivated.
+external
view
+address token
+ |
+
+ The address of the contract for the desired ERC-20 token. + |
+
+address address
+ |
+
+ The address of the bridge for the specified token. + |
+
+Address(0)
+ |
+
+ The bridge does not exist. + |
+
+Address(1)
+ |
+
+ The bridge is blocked or deactivated. + |
+
None.
+getBridge in IStarkgateRegistry.sol
getRegistryReturns the address of the StarkGate Registry contract.
+Only the Manager uses this function.
+external
view
None
+
+address
+ |
+
+ The address of the Registry contract. + |
+
None.
+getRegistry in StarkgateManager.sol
getStatusReturns the status of a token in StarkGate.
+deploy transaction triggered by the enrollTokenBridge API.
external
view
+address token
+ |
+
+ The address of the contract for the desired ERC-20 token. + |
+
+TokenStatus
+ |
+
+ One of the following values: +
+
+
|
+
None.
+getStatus in StarknetTokenBridge.sol
getWithdrawalBridgesRetrieves a list of all bridge addresses that have ever facilitated withdrawals for the specified token.
+In a case where an inactive bridge for a specific token might still have funds locked, you can use this function to identify all bridges that ever serviced that token.
+If you used a bridge for a given token that subsequently was replaced with a new or updated bridge, but you still have funds locked on the first bridge, you might not know the address of the old bridge. This function returns
+external
view
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+address[] memory bridges
+ |
+
+ An array of addresses of all bridges that ever serviced |
+
None.
+getWithdrawalBridges in StarkgateRegistry.sol.
identifyReturns the name and version of the StarknetTokenBridge.sol contract.
external
pure
None.
+
+string memory
+ |
+
+ The name and version of the |
+
None.
+identify in StarknetTokenBridge.sol
isServicingTokenChecks whether the calling contract is currently providing a service for the specified token.
+external
view
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+true
+ |
+
+ The calling contract is currently providing a service for the token. + |
+
+false
+ |
+
+ The calling contract is not currently providing a service for the token. + |
+
None.
+isServicingToken in IStarkgateService.sol.
withdrawTransfers the specified amount of the specified token to the address of the recipient specified in the l1_recipient parameter of the initiate_token_withdraw function on L2.
Anyone can call this function, but only after the withdraw message has been recorded on the Starknet Core Contract.
+
+address token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the withdrawal. + |
+
+address recipient
+ |
+
+ (Optional) +The recipient. +If you don’t specify this parameter, the withdraw function uses the sender’s address. + |
+
nonpayable
None.
+Withdrawal
+address indexed recipient
+ |
+
+ The recipient. + |
+
+address indexed token
+ |
+
+ The address of the contract for the desired token. + |
+
+uint256 amount
+ |
+
+ The amount of the withdrawal. + |
+
Contract: StarknetTokenBridge.sol
Function: withdraw
Event: Withdrawal
Functions are listed in alphabetical order.
+get_erc20_class_hashReturns the current class hash of the implementation used by the ERC-20 contract. Use the class hash as the type when deploying the ERC-20 contract on L2.
+| + + | +
+
+
+If StarkWare changes the class hash such that it is no longer the class hash that you used when deploying your bridge contract, this function returns the new class hash. If you want to refer to the class hash that you used when deploying your contract, see your deployed contract on Starknet. + |
+
None.
+
+ClassHash
+ |
+
+ The class hash of the ERC-20 token contract. + |
+
get_erc20_class_hash in token_bridge.cairo.
get_identityReturns a string in a felt252 type with the identity of StarkGate.
+None.
+
+felt252
+ |
+
+ The identity of StarkGate. + |
+
get_identity in token_bridge_interface.cairo.
get_l1_tokenReturns the L1 address that corresponds to the matching L2 address of an ERC-20 token contract.
+
+l2_token_address: ContractAddress
+ |
+
+ The L2 address of the ERC-20 token contract. + |
+
+EthAddress
+ |
+
+ The L1 address of the ERC-20 token contract. + |
+
+EthAddressZeroable::zero()
+ |
+
+ The token is not found in the bridge. + |
+
get_l1_token in token_bridge_interface.cairo.
get_l2_tokenReturns the L2 address that corresponds to the matching L1 address of an ERC-20 token contract.
+If the token is not found in the bridge, this function returns 0.
+l1_token_address
+ |
+
+ The L1 address of the ERC-20 token contract. + |
+
+ContractAddress address
+ |
+
+ The L2 address of the ERC-20 token contract. + |
+
+ContractAddressZeroable::zero()
+ |
+
+ The token is not found in the bridge. + |
+
get_l2_token in token_bridge_interface.cairo.
get_remaining_withdrawal_quotaReturns the amount that the user can withdraw within the current 24-hour time period. The time period begins at 00:00 UTC.
+
+l1_token_address
+ |
+
+ The L1 address of the ERC-20 token contract. + |
+
+u256
+ |
+
+ The amount that can currently be withdrawn from the bridge, in units defined by the ERC-20 token contract. + |
+
get_remaining_withdrawal_quota in token_bridge_interface.cairo
get_versionReturns the current version of StarkGate.
+None.
+
+felt252
+ |
+
+ The current version of StarkGate. + |
+
get_version in token_bridge_interface.cairo.
initiate_token_withdrawInitiates a withdrawal from L2. After initiating the withdrawal, the function does the following:
+Burns the transferred amount of tokens from the balance of the withdrawal’s initiator.
+Sends a message to the relevant L1 bridge with the amount to be transferred, and the recipient’s address.
+
+l1_token: EthAddress
+ |
+
+ The L1 address of the ERC-20 token contract. + |
+
+l1_recipient: EthAddress
+ |
+
+ The L1 address of the recipient. + |
+
+amount uint256
+ |
+
+ The amount to transfer. + |
+
None.
+initiate_token_withdraw in token_bridge_interface.cairo.
on_receiveAn interface to an implementation of the on_receive function that you must provide in your L2 contract in order to enable the depositWithMessage function to succeed.
The L2 contract that receives the message that is sent with the depositWithMessage function must implement a callback function named on_receive.
Upon completion, the depositWithMessage function triggers a call to the on_receive callback function on the receiving L2 contract. The on_receive function receives the deposit message as input, and it must return true for the deposit to succeed.
If on_receive returns false, or if the receiving contract does not implement on_receive, the depositWithMessage L1 handler fails, and the user can only recover their funds using the depositWithMessageCancelRequest function.
+l2_token: ContractAddress
+ |
+
+ The L2 address of the ERC-20 token contract. + |
+
+amount: uint256
+ |
+
+ The amount deposited. + |
+
+depositor: EthAddress
+ |
+
+ L1 address of the deposit sender. + |
+
+message: Span<felt252>
+ |
+
+ The message that was sent with the |
+
+true
+ |
+
+ The |
+
+false
+ |
+
+ The |
+
| +No value + | +
+ If the recipients’s smart contract does not implement the |
+
on_receive in receiver_interface.cairo.
StarkGate, developed by StarkWare, bridges ETH and ERC-20 tokens between Ethereum and Starknet. Each supported token is associated with an L1 and L2 bridge contract that communicates via Starknet’s messaging mechanism.
+To use the StarkGate web app, go to https://starkgate.starknet.io.
+A bridge enables you to fund your L2 wallet with ETH and ERC-20 tokens that reside on L1.
+The terms deposit, transact, and transfer refer to various operations involving a bridge, even though ETH and ERC-20 tokens never actually leave Ethereum.
+| + + | +
+
+
+StarkGate 2.0 provides a contract that enables seamless backward compatibility with the previous version of StarkGate. +
+
+When you update the code in your contract, make sure that you use the most up-to-date versions of all StarkGate contracts. + |
+
L1 and L2 addresses for StarkGate bridges and supported tokens are listed in the JSON files in the Starknet GitHub repository shown in the table StarkGate bridged tokens and their addresses.
+| Network | +StarkGate bridged tokens JSON file | +
|---|---|
Mainnet |
++ |
Sepolia testnet |
++ |
StarkGate supports many tokens, including ETH, WBTC, USDC, DAI, and many more.
+For a comprehensive list of tokens that StarkGate supports, including their L1 and L2 addresses, see the JSON files in the Starknet GitHub repository shown in the table StarkGate bridged tokens and their addresses.
+| + + | +
+
+
+Previously, StarkGate placed limitations for each supported token on the amount that could be deposited and the total value locked in the L1 bridge contract on Mainnet. These limits have been removed. + |
+
A call to the L1 deposit function initiates a deposit.
The function does the following:
+Transfers the funds from the user’s account to the Starknet bridge.
+Emits a Deposit event that includes the L1 and L2 addresses of the user, and the amount deposited.
Sends a message to the corresponding L2 bridge with the amount deposited, and the recipient’s address.
+Starknet’s sequencer is now aware of the deposit transaction.
+The sequencer waits for enough L1 block confirmations to fill its quota to run before the corresponding deposit transaction is initiated on L2. During this period of time, the status of the L2 deposit transaction is NOT_RECEIVED.
The sequencers refer to the deposit
+request by triggering the L1 handler using the
+handle_deposit function on the L2 bridge.
The handle_deposit function verifies that the deposit indeed came from the corresponding L1 bridge. It then calls the relevant token’s contract on Starknet and mints the specified amount of the token on L2 for the user.
The sequencers complete constructing the block.
+The status of the deposit request is now ACCEPTED_ON_L2.
Starknet’s provers prove the validity of the block and submit a state update to L1.
+The message confirming transfer of the funds is cleared from the Starknet Core Contract, and the fact that the user has transferred their funds is part of the now finalized state of Starknet.
+| + + | +
+
+
+If the message wasn’t on L1 to begin with, that is, if the deposit request was fraudulently created on Starknet, the state update fails. + |
+
A call to the L2 initiate_token_withdraw function initiates a withdrawal.
The function does the following:
+Burns the transferred amount of tokens from the balance of the withdrawal’s initiator.
+Sends a message to the relevant L1 bridge with the amount to be transferred and the recipient’s address.
+The sequencer completes the block construction
+Starknet’s provers prove the validity of the block and submit a state update to L1.
+The message from the previous step is stored in the Starknet Core Contract.
+After the withdrawal message has been recorded on the Starknet Core Contract, anyone can finalize the transfer on L1 from the bridge back to the user, by calling the withdraw function.
| + + | +
+
+
+This step is permissionless, anyone can do it. The recipient’s address is part of the recorded message on L1, so they receive the funds regardless of who calls the |
+
The StarkGate developer’s reference:
+handle_deposit function on the L2 bridge
Using StarkGate to withdraw funds from Starknet requires StarkGate’s initiate_token_withdraw function to initiate a withdrawal. The function does the following:
Burns the transferred amount of tokens from the L2 balance of the withdrawal’s initiator.
+Sends a message to the relevant L1 bridge with the amount to be transferred and the recipient’s Ethereum address.
+Subsequently, the funds should be transferred to the recipient’s Ethereum address.
+For more information on what happens during the transfer process, see L2→L1 transfer (withdrawal).
+A Starknet block explorer. For a list of Starknet block explorers, see Block explorers, indexers & Enhanced API on the Starknet site.
+An Ethereum block explorer, such as Etherscan.
+Funds to transfer from L2 to L1, including enough to pay the fees required for the transfer.
+The L2 address of the StarkGate bridge for the token you want to withdraw. To view the token addresses for tokens on Mainnet or Sepolia testnet, see Bridged tokens and addresses.
+Using a Starknet block explorer, go to the StarkGate contract for the token you want to withdraw. For example, to withdraw USDC:
+If using Voyager, go to the USDC StarkGate bridge and click Write Contract.
+If using StarkScan, go to the USDC StarkGate bridge and click .
+Click the initiate_token_withdraw function and enter the following:
In l1_token, enter the L1 address of the ERC-20 contract for the token you want to withdraw, in this case, USDC.
+In l1_recipient, enter the L1 address of the recipient.
In amount, enter the amount to transfer.
Click Transact for Voyager, or Write for StarkScan. The function initiates a withdrawal.
+Using an Ethereum block explorer, go to the StarkGate contract and click Write as Proxy. For example, using Etherscan, go to 0xae0ee0a63a2ce6baeeffe56e7714fb4efe48d419
+Click the StarkGate 2.0 withdraw (0x69328dec) function.
+Enter the following:
+
+recipient (address)
+ |
+
+ The recipient. + |
+
+token (address)
+ |
+
+ The address of the contract for the desired token. + |
+
+amount (uint256)
+ |
+
+ The amount of the withdrawal. + |
+
Click Write.
+The withdraw function withdraws the funds to the recipient’s L1 address. The funds should be available after the next L1 state update.
The features on this page are deprecated, unsupported, or removed from Starknet.
+| +Deprecated + | +
+ Refers to a feature or capability that is still supported, but support will be removed in a future release of Starknet. +Future fixes or enhancements are unlikely. If necessary, an alternative is available. + |
+
| +Unsupported + | +
+ Refers to a feature or capability that is no longer supported. + |
+
| +Removed + | +
+ Refers to a feature or capability that has been entirely removed. + |
+
| Name | +Description | +
|---|---|
Starknet CLI |
+Support for the Starknet CLI has been removed. Instead use Starkli. +Support for Starknet CLI is removed in Starknet v0.13.0. |
+
Cairo 0 |
+Starknet v0.11.0 introduces Cairo 1.0 smart contracts. |
+
| Name | +Description | +||||||||
|---|---|---|---|---|---|---|---|---|---|
Goerli testnet |
+
+
+Goerli testnet support was removed April 2, 2024. Sepolia testnet replaces Goerli testnet. +
+
+Starknet started migrating to Sepolia testnet on November 15th, 2023. For more information on the Goerli deprecation, see the deprecation announcement on Ethereum’s site. +
+
+Full nodes, API services, SDKs, and other Starknet developer tools have migrated to Sepolia as well. +
+
|
+||||||||
Starknet feeder gateway |
+
+
+The Starknet feeder gateway, a temporary solution for querying the sequencer’s state, is being replaced by Starknet full nodes (Pathfinder, Juno, Deoxys, Papyrus) and RPC services. For more information, see Full nodes and API services. +
+
+Support for the feeder gateway queries that are not required for full nodes to synchronize on the state of Starknet will stop according to the following schedule: +
+
+Queries that are required for full nodes to synchronize on the state of Starknet are still supported. +
+ For more information, see the Community Forum post Feeder Gateway Deprecation. + |
+||||||||
Free L1→ L2 messaging |
+Previously, sending a message from L1 to L2 had an optional fee associated. +From Starknet v0.11.0, the fee mechanism is enforced and the ability to send L1→L2 messages without the corresponding L2 fee has been removed. +See here for more details. |
+||||||||
|
+
|
+||||||||
|
+
|
+||||||||
|
+The To deploy new contract instances, you can use the |
+
+Juno is a golang Starknet node implementation by Nethermind with the aim of decentralizing Starknet.
+See the official Juno GitHub repository for more details.
+Support for upcoming Starknet v0.12.3, improved RPC performance with a new global class cache, allowing for higher request throughput and optimized resource usage. We’ve updated blockifier, which includes an important wallet integration fix. On top of that, expect new metrics and ongoing enhancements to the P2P layer, among other improvements. Here’s what’s new:
+The blockifier library has been updated, now supporting the query bit in the version field for transactions.
+PR by @joshklop in #1401.
Subscription handling has been moved to the synchronizer for improved efficiency.
+PR by @joshklop in #1373.
Ongoing enhancements to the P2P layer, including the implementation of a Receipt Handler and Adapter and a new GetBlockBodies feature.
+PRs by @IronGauntlets in #1352 and by @kirugan in #1359.
Prometheus metrics have been expanded to include version information, latency on Transaction.Commit(), and read metrics on blockchain operations.
+PRs by @omerfirmak in #1394, #1396, and #1395.
Kubernetes pods now have a correctly set GOMAXPROCS setting, aligning performance with CPU resources.
+PR by @omerfirmak in #1397.
Fallback to feeder traces for blocks ⇐ 0.12.2.
+PR by @omerfirmak in #1405.
You can pull the Docker image for this release with the following command:
+docker pull nethermind/juno:v0.7.3The primary goal of this release is to introduce support for Starknet JSON-RPC v0.5.0. Juno now supports multiple versions via /v0_5 and /v0_4 endpoints. The default version at the root / endpoint has been updated from 0.4.0 to 0.5.0.
Starknet v0.5.0 Compatibility:
+Implemented starknet_specVersion @omerfirmak
Renamed juno_getTransactionStatus to starknet_getTransactionStatus. @omerfirmak
Removed pendingTransactions endpoint for cleanup. @omerfirmak
Added new fields like execution resources and message hash to RPC receipt. @omerfirmak
+Building and calculating state diffs. @omerfirmak
+Make starknet_traceBlockTransactions get a block id @kirugan
Add txn type to traces
+Add message_hash field for L1_HANDLER_TXN_RECEIPT
+Add starknet_getTransactionStatus and remove starknet_pendingTransactions
Support multiple RPC versions: v0.4.0 and v0.5.0 @omerfirmak
+Performance Metrics: Moved metric counting out of various components for cleaner code. @omerfirmak
+Websocket Enhancements: Full-duplex comms and fixes related to over-reading websocket requests. @joshklop
+RPC Optimization: Reduced allocations in RPC requests for better performance. @joshklop
+Refactored Error Handling: Improved global error usage and better error handling in various components. @omerfirmak
+Websocket Reading: Fixed over-reading issues in Websocket requests.@joshklop
+Error Handling: Resolved potential nil pointer dereferences and panic issues. @omerfirmak
+New Trace RPC Methods:
+starknet_traceTransaction
starknet_traceBlockTransactions
starknet_simulateTransactions
Juno RPC Schema: A dedicated schema to streamline RPC interactions for Juno’s method.
+Juno Console Enhancement: Pretty printing of Juno console logs for an enriched user experience.
+Comprehensive Documentation: Official documentation now hosted on GitHub Pages.
+RPC Schema Consistency: Revised to ensure our RPC schema is consistent with the Starknet specification.
+Command-line switches have been restructured to provide clearer access control:
+docker run -d
+--name juno
+-p $httpPort:$httpPort
+-p $metricsPort:$metricsPort
+-v /root/juno:/var/lib/juno
+nethermind/juno:v0.6.0
+--db-path /var/lib/juno
+--http
+--http-port $httpPort
+--metrics
+--metrics-port $metricsPort
+--eth-node <YOUR-ETH-NODE>(Note: Ensure to adjust the variables like $httpPort, $metricsPort and others as per your configuration.)
This release adds support for the upcoming Starknet v0.12.1 upgrade and includes compatibility with v0.4.0 of the RPC specification.
+Support for Starknet v0.12.1
+Compatibility with v0.4.0 of the RPC specification
+New RPC method: starknet_estimateMessageFee
Health Check Endpoint: A GET request to the / endpoint will now return a 200 status code for a healthy Juno node
+Added Prometheus metrics support: Use --metrics and --metrics-port to enable this feature
Log the incoming RPC requests in Pull Request #907
+Update types for 0.12.1 in Pull Request #895
+Parallelize per-contract storage updates in Pull Request #900
+Add missing From field to rpc.MsgToL1 in Pull Request #908
+| + + | ++This release has breaking changes and database is not compatible with the previous version. + | +
New RPC Methods:
+starknet_call
starknet_estimateFee
starknet_addDeclareTransaction
starknet_addDeployAccountTransaction
starknet_addInvokeTransaction
juno_getTransactionStatus
juno_version
L1 Verifier: Verification of state from Layer 1 has been implemented.
+Block Reorg Detection and Handling: A feature to detect and handle block reorganizations has been implemented.
+gRPC Service: To accommodate users requiring direct access to the database, a gRPC service has been exposed.
+Database Migration: The system has been improved to handle database changes more gracefully. It’s no longer necessary to sync from the start when some database changes occur.
+Starknet v0.12.0 support: includes integration with the Rust VM.
+Updated the behavior of synced nodes, which will now return false to starknet_syncing.
Resolved issue with NumAsHex(0) being omitted in RPC.
Fixed a Goerli sync issue by relaxing decoder max array elements limit.
+Full Changelog: [v0.3.0…v0.3.1]
+Starknet v0.11.2 support
+History for contracts, nonce, and class hash.
+Implemented StateSnapshot.
+New RPC endpoints:
+starknet_syncing
starknet_getNonce
starknet_getStorageAt
starknet_getClassHashAt
starknet_getClass
starknet_getClassAt
starknet_getEvents
| + + | ++For new RPC endpoints to fully work with data before the new version, the node needs to be resynced. + | +
Optimized TransactionStorage encoding and refactored memStorage.
+Refactored RPC implementation for better organization and maintainability.
+Parallelized and refactored sync tests for faster execution, improved readability, and maintainability.
+Updated handling of non-existent keys to return a zero value.
+Full Changelog: v0.3.0…v0.3.1
+This patch release fixes handling of block versioning and ensures compatibility with non-sem-ver compliant Starknet.
+Ignore or add digits to block version string as necessary.
+Full Changelog: v0.2.1…v0.2.2
+This minor release introduces an important optimization that enhances sync performance.
+Update gnark-crypto version:
+Implement precomputed point multiplication results for Pedersen hash operations.
+Full Changelog: v0.2.0…v0.2.1
+This release adds support for Staknet v0.11.0.
| + + | ++This release has breaking changes and database is not compatible with the previous version. + | +
Starknet v0.11.0 support:
Add Poseidon hash for new state commitment.
+Add DeclareTransaction version 2.
Add and Store Cairo 1/Sierra class definition and hash calculations.
+pprof option is added for profiling and monitoring.
Verify Class Hashes.
+Starknet v0.11.0 support:
Update InvokeTransaction version 1’s contract address to sender address.
Update current JSON RPC endpoints to [v.0.3.0-rc1](https://github.com/starkware-libs/starknet-specs/tree/v0.3.0-rc1).
Rename the verbosity option to log-level and log-level accepts string instead of uint8. See help for details.
network option accepts string instead of uint8. See help for details.
Database table is updated to account for Starknet v0.11.0 changes.
Graceful shutdown: ensure all services have returned before exiting.
+Full Changelog: v0.1.0…v0.2.0
+This is Juno’s first release (compatible with Starknet v0.10.3) with the following features:
Starknet state construction and storage using a path-based Merkle Patricia trie.
+Pedersen and starknet_keccak hash implementation over starknet field.
Feeder gateway synchronization of Blocks, Transactions, Receipts, State Updates and Classes.
+Block and Transaction hash verification.
+JSON-RPC Endpoints:
+starknet_chainId
starknet_blockNumber
starknet_blockHashAndNumber
starknet_getBlockWithTxHashes
starknet_getBlockWithTxs
starknet_getTransactionByHash
starknet_getTransactionReceipt
starknet_getBlockTransactionCount
starknet_getTransactionByBlockIdAndIndex
starknet_getStateUpdate
Pathfinder is a Starknet full node giving you a safe view into Starknet.
+It provides the following features:
+Access the full Starknet state history
+Verifies state using Ethereum
+Implements the Starknet JSON-RPC API
+Run Starknet functions without requiring a Starknet transaction
+Ability to do fee estimation for transactions
+See the official Pathfinder GitHub repository for more details.
+starknet_estimateMessageFee for JSON-RPC v0.3.1 to estimate message fee from L1 handler.
sync-related metrics
+current_block: the currently sync’d block height of the node
highest_block: the height of the blockchain
block_time: timestamp difference between the current block and its parent
block_latency: delay between current block being published and sync’d locally
block_download: time taken to download current block’s data excluding classes
block_processing: time taken to process and store the current block
configuration for new block polling interval: --sync.poll-interval <seconds>
Starknet v0.12.0 support
+sierra v2.0.0 support
+cairo-lang upgraded to 0.12.0a0
Starknet v0.11.2 support
+Sierra compiler v1.1.0-rc0
+cairo-lang upgraded to 0.11.2a0
Subscription to newHead events via websocket using the method pathfinder_subscribe_newHeads, which can
+be managed by the following command line options
rpc.websocket, which enables websocket transport
rpc.websocket.capacity, which sets the maximum number of websocket subscriptions per subscription type
Authors: [Shramee Srivastav](https://github.com/shramee) and [Matthieu Auger](https://github.com/matthieuauger)+
RPC emits connection logs and warnings
+Fee estimate mismatch between gateway and pathfinder
+Gateway uses a new gas price sampling algorithm which was incompatible with pathfinders.
+Fee estimate returns error when submitting Cairo 1.0.0-rc0 classes.
+Historic L1 handler transactions are served as Invoke V0
+Older databases contain L1 handler transactions from before L1 handler was a specific transaction type. These were +stored as Invoke V0. These are now correctly identified as being L1 Handler transactions.
+RPC emits connection logs and warnings
+Fee estimate mismatch between gateway and pathfinder
+Gateway uses a new gas price sampling algorithm which was incompatible with pathfinders.
+Historic L1 handler transactions are served as Invoke V0
+Older databases contain L1 handler transactions from before L1 handler was a specific transaction type. These were +stored as Invoke V0. These are now correctly identified as being L1 Handler transactions.
+The primary focus of this release is to provide support for Starknet v0.11.1, and will continue to work for v0.11.0. Since this release is required for v0.11.1, you should update your node before the network is updated.
+Starknet v0.11.1 support
+CORS support via the rpc.cors-domains configuration option
Transaction hashes are now verified as part of the sync process. Previously, these were not verified as the exact algorithm was underdocumented and the transaction format was still evolving.
+RPC server panic for unprefixed unregistered method names
+Data can temporarily appear to go missing when transitioning from PENDING to ACCEPTED ON L2
This was commonly seen when rapidly monitoring a new transaction, which would go from PENDING to TXN_HASH_NOT_FOUND to ACCEPTED_ON_L2 as pathfinder moved the ephemeral pending data to latest data on disk.
Fixes for minor issues and inconsistencies.
+max-rpc-connections command-line argument. This sets the maximum number incoming RPC connections the pathfinder node will accept. This defaults to 1024 if not specified.
cairo-lang upgraded to 0.11.0.2
starknet_simulateTransaction data model inconsistency
poll-pending default value restored to false
incoming RPC connections limited to 100. This limit was accidentally introduced in v0.5.2 as part of a dependency upgrade, whereas before it was unlimited. The default is now 1024 and can be configured using --max-rpc-connections.
handling of invalid JSON-RPC requests
+This release fixes a few RPC bugs and adds support for bulk fee estimation and transaction simulation (traces) as part of v0.3 RPC specification.
+In addition it also adds a pathfinder_getTransactionStatus endpoint which lets you track a transactions status — including REJECTED and RECEIVED — in the same fashion as the gateway.
support starknet_estimateFee in the JSON-RPC v0.3 API
supports estimating multiple transactions
+this includes declaring and immediately using a class (not currently possible via the gateway)
+support starknet_simulateTransaction for JSON-RPC v0.3
supports simulating multiple transactions
+this includes declaring and immediately using a class (not currently possible via the gateway)
+support pathfinder_getTransactionStatus which is exposed on all RPC routes
this enables querying a transactions current status, including whether the gateway has received or rejected it
+starknet v0.11.0 support
+RPC API v0.3 partial support
+removed several deprecated config options
+requires python 3.9 or 3.10 (no longer 3.8)
+support for state commitment and class commitment in pathfinder_getProof
support for starknet v0.11
+partial support for RPC specification v0.3
+exposed on /rpc/v0.3/ route
missing support for starknet_estimateFee and starknet_simulate
starknet_call and starknet_estimateFee JSON-RPC methods return more detailed error messages
python version requirement has changed to 3.9 or 3.10 (was 3.8 or 3.9 previously)
RPC accepts hex inputs for Felt without '0x' prefix. This led to confusion especially when passing in a decimal string which would get silently interpreted as hex.
+using a Nethermind Ethereum endpoint occasionally causes errors such as <block-number> could not be found to be logged.
sync can miss new block events by getting stuck waiting for pending data.
+--config configuration option (deprecated in [v0.4.1](https://github.com/eqlabs/pathfinder/releases/tag/v0.4.1))
--integration configuration option (deprecated in [v0.4.1](https://github.com/eqlabs/pathfinder/releases/tag/v0.4.1))
--sequencer-url configuration option (deprecated in [v0.4.1](https://github.com/eqlabs/pathfinder/releases/tag/v0.4.1))
--testnet2 configuration option (deprecated in [v0.4.1](https://github.com/eqlabs/pathfinder/releases/tag/v0.4.1))
starknet_addDeployTransaction as this is no longer an allowed transaction since starknet v0.10.3
RPC api version 0.1, which used to be served on path /rpc/v0.1
We added support for v0.3 and removed v0.1. We still support v0.2 at both /rpc/v0.2 and /rpc (default) routes. In summary:
/ # serves v0.2
+/rpc/v0.2/ # serves v0.2
+/rpc/v0.3/ # serves v0.3We are missing starknet_estimateFee and starknet_simulate support for v0.3, which will be added in an upcoming release.
Note: this only applies if you are building from source. This does not impact docker users.
+Pathfinder requires python to support the starknet VM used to simulate starknet transactions and function calls. Previous versions of the VM only worked with python 3.8 or 3.9 which was a hassle because most operating systems no longer directly support it. The new version of the VM bundled with starknet v0.11 now requires python version 3.9 or 3.10.
+Several configuration options are now removed, after they were deprecated in pathfinder v0.4.1. Here is a migration guide:
+--testnet2: use --network testnet2 instead
--integration: use --network integration instead
--sequencer-url: use --network custom in combination with --feeder-gateway-url and gateway-url
--config: use environment variables or env files as an alternative
Hotfix for a bug introduced in the previous version v0.4.4, which prevented a new node from syncing on blocks near genesis.
+This minor release contains some nice performance improvements for starknet_call and starknet_estimateFee as well as some minor bug fixes.
Also included is a major new feature: storage proofs - big thanks @pscott for his hard work on this feature! This is available via the pathfinder_getProof method which is served from both the pathfinder and Starknet endpoints for convenience:
<node-url>/rpc/pathfinder/v0.1/pathfinder_getProof
+<node-url>/rpc/v0.2/pathfinder_getProofThe method is specified here.
+Its results can be used to formally verify what a contract’s storage values are without trusting the pathfinder node.
+This is achieved by validating the merkle-proof that pathfinder returns and confirming that it correctly matches the known Starknet state root.
+starknet_getEvents returns all events when from_block="latest"
v0.1 starknet_getStateUpdate does not contain nonces
The primary purpose of this release is to properly support testnet2 after the Starknet v0.10.3 update.
+The v0.10.3 update changed the testnet2 chain ID which impacts transaction signatures which in turn meant that starknet_estimateFee would fail for any signed transaction.
This release updates pathfinder to use the correct chain ID.
+Soft deprecation of some configuration options
+Support custom Starknet gateways
+Pathfinder RPC extensions at /rpc/pathfinder/ with pathfinder_version method
starknet_events optimisations
fix block timestamp in pending calls
+Custom Starknet gateway support
+This release introduces support for custom Starknets. You can select this network by setting --network custom and specifying the --gateway-url and --feeder-gateway-url options.
Several configuration options have been soft deprecated. This means using them will continue to work as before (no breaking change), but they will emit a warning when used. They will be removed in a future version, so please migrate to the newer options.
+To re-emphasize: your current configuration setup will continue to work as is.
+--testnet2 and --integration have been deprecated in favor of --network testnet2 and --network integration.
--sequencer-url has been deprecated in favor of --network custom along with --gateway-url, --feeder-gateway-url and --chain-id. In addition, you will need to rename your existing database file to custom.sqlite as this will be the expected filename for custom networks.
--config has been deprecated and will not be supported in the future. The utility this provided was valuable. Unfortunately it is starting to severely hinder how fast we can implement configuration changes and we decided to remove it.
We suggest using environment variables along with environment files to configure pathfinder in a similar fashion.
+The following configuration options are now marked as deprecated: --testnet2, --integration, --config, --sequencer-url
+Optimized starknet_events for queries with both a block range and a from address
This release contains a breaking change, and also adds support for Starknet v0.10.2.
+The changes themselves are quite simple, but please read through each section as there are some caveats which might impact you when you apply this update.
+This release changes the version of the RPC that is served at the root route, from v0.1 to v0.2 of the RPC specification. Version v0.1 is still available at the /rpc/v0.1/ endpoint. This is the only breaking change in this release.
Here is a summary of what routes are currently available, and what’s changed:
+/ serves v0.2 (changed from v0.1)
/rpc/v0.1 serves v0.1 (no change)
/rpc/v0.2 serves v0.2 (no change)
If possible, we recommend that you use the version specific routes as this will prevent such breaking changes from impacting you.
+This release includes an update to the cairo-vm embedded in pathfinder in order to support the upcoming v0.10.2 Starknet release. This bundled vm is a pre-release and may therefore contain differences to the final version used once Starknet updates testnet and mainnet. We will of course issue a new release if / when there is a new vm.
+| + + | +
+
+
+Since these changes are not yet live on testnet nor mainnet, this means upgrading to this release will cause deviations between what pathfinder outputs and what can be expected on the network. More specifically,
+
+If you don’t need the RPC route changes, it may be pertinent to delay updating until closer to the v0.10.2 release dates on testnet and mainnet. The expected timeline for these upgrades is ~17/11 for testnets and ~24/11 for mainnet. + |
+
You can subscribe to get the latest version updates delivered to your inbox at Starknet Roadmap & version updates.
+For information on the current version of Starknet, see the Starknet release notes.
+The following release notes cover the ongoing version changes to Starknet. You can subscribe to get the latest version updates delivered to your inbox at Starknet Roadmap & version updates.
+Within Starknet’s deployment pipeline, there are separate and distinct networks that operate independently of each other for testing before deployment.
+| + + | +
+
+
+Sepolia testnet replaces Goerli testnet. +
+
+Goerli testnet support is now removed. +
+
+For more information, including bridge support for Sepolia, see Starknet Goerli Deprecation in the Starknet Dev News newsletter. + |
+
| Environment | +Starknet version | +Sierra version | +Cairo version | +
|---|---|---|---|
Mainnet |
+0.13.2 |
+1.6.0 |
+2.0.0 - 2.8.2 |
+
Sepolia Testnet |
+0.13.2 |
+1.6.0 |
+2.0.0 - 2.8.2 |
+
Optimistic parallelization in the sequencer.
+Applicative recursion ("blockpacking"): pack a contiguous sequence of blocks into a single L1 state update, instead of just one block. This change also affects the Starknet core contract on L1 and the structure of data availability:
+The contract will store also the hash of the "aggregator" program, alongside the hash of the Starknet OS.
+The LogStateUpdate event will be emitted once for every sequence of blocks in an applicative tree, rather than for every block.
+The data posted on L1 is now the output of the aggregator, instead of the OS. The OsOutputHeader struct will contain four new fields: prev_block_number, prev_block_hash, os_program_hash, full_output.
New block hash definition: see the reference implementation here.
+All objects containing the block hash will use the new block hash computation.
+Receipts will contain a new property total_gas_consumed, only for transactions after v0.13.2.
Three new builtins can appear in the builtin_instance_counter property of execution_resources in the transaction receipts: add_mod, mul_mod and range_check96.
End support for the endpoints get_block_traces and get_transaction_trace.
No changes in v0.13.2. The new JSON RPC version v0.8.0 will be released alongside Starknet v0.13.3.
+A new compiler version will be released for v0.13.2, Cairo v2.7.0. This includes a Sierra upgrade to v1.6.0, i.e. contracts compiled with the new compiler will only be accepted on Starknet v0.13.2 onwards.
+The Starknet-related features that will be added in this Cairo version include:
+sha256 syscall - syscall for computing sha256 on an arbitrary length input:
+High level code for using sha256/
+Syscall cost - the dominant part of the syscall is ~1.1k bitwise builtin applications which today costs ~180 L1 gas (the 2k steps are negligible in comparison). The syscall is applied once for ~14 u32.
Circuit builtin - the new compiler version will introduce a way to define ad-hoc algebraic circuits in Cairo. Circuits use the new mul_mod and add_mod builtins under the hood.
Example usage can be found in circuit_test.cairo.
+Errors prettifying: execution errors are becoming more structured, which will be the basis for better error handling in the next JSON RPC version, resulting in nice error displays by wallets.
+Community Forum Posts:
+In response to community feedback, Starknet 0.13.1.1 reduces class declaration fees and increases the calldata limit:
+| Resource | +Gas cost (0.13.1) | +Gas cost (0.13.1.1) | +
|---|---|---|
CASM bytecode |
+28 gas/felt |
+1 gas/felt |
+
Sierra bytecode |
+28 gas/felt |
+1 gas/felt |
+
ABI |
+0.875 gas/character |
+0.032 gas/character |
+
| Entity | +Limit (0.13.1) | +Limit (0.13.1.1) | +
|---|---|---|
Calldata length (felts) |
+4,000 |
+5,000 |
+
Cheaper data availability (DA): Starknet uses EIP-4844. State diffs are now blobs, rather than calldata, requiring the addition of data_gas to the Starknet block header.
Time-related syscalls when called from an account contract’s __validate__, __validate_deploy__, __validate_declare__, or constructor function:
block_timestamp returns the hour, rounded down.
block_number returns the block number, rounded down to the nearest multiple of 100.
Optimization: Load into memory only the functions in a contract that are actually used when generating the proof.
+The block header includes the following new fields:
+l1_da_mode: A string enum that takes the value CALLDATA or BLOB, and indicates whether EIP-4844 is the data availability solution that is used for the block. Also appears in pending block.
l1_data_gas_price: Contains price_in_wei and price_in_fri, where 1 fri is 10-18 STRK. Also appears in pending block.
l1_gas_price: Replaces eth_l1_gas_price and strk_l1_gas_price. Contains the data gas price (EIP-4844) in addition to the regular gas price.
Starknet 0.13.1 is backward compatible with starknet_api_openrpc.json v0.6.0. Responses from 0.13.1 can be mapped naturally into v0.6.0 objects.
A new version of starknet_api_openrpc.json, 0.7.0, accommodates the changes introduced by Starknet using EIP-4844.
BLOCK_HEADER includes two new fields to support EIP-4844:l1_data_gas_price: contains price_in_wei and price_in_fri (10-18 denominations, similar to v0.6.0).
l1_da_mode: An enum that indicates whether this block will use calldata or blobdata and can take the following values:
CALLDATA
BLOB
FEE_ESTIMATEIncludes two new fields:
+data_gas_consumed
data_gas_price
overall_fee is now:
+gas_consumed × gas_price + data_gas_consumed × data_gas_price
Fee estimates will change depending on the data availability solution used by current Starknet blocks. For example, if you estimate the fee against the pending block, and it’s currently using CALLDATA, then nodes are expected to return data_gas_consumed=0 and compute the fee similarly to today, that is, get higher estimates.
COMMON_RECEIPT_PROPERTIES, the main receipt object, now includes a new entry: execution_resources.
The EXECUTION_RESOURCES object now includes the field data_availability. Note that the resources of internal calls will remain the same/
For more information, see the PR for the API JSON RPC specs
+EXECUTION_RESOURCESComputation resources are separated from data availability resources. This is done by introducing the data_availability property, which includes l1_gas and l1_data_gas, which were consumed due to DA requirements. One of these will always be zero, depending on whether or not the block uses calldata or blobs, as specified by the l1_da_mode field in the block header.
Syscall costs are now included in the execution resources of traces and receipts. These are costs that are already being paid for but were not reported so far.
+A Cairo step now costs 0.0025 gas/step, a 50% reduction.
+All builtins costs are accordingly reduced by 50%.
+Each felt in the calldata and signature arrays of all transaction types now costs 0.128 gas/felt.
+Each felt of a sierra_program in the contract class and of bytecode in the compiled contract class now costs 28 gas/felt.
+| + + | +
+
+
+v1 |
+
Each character in the ABI costs 0.875 gas.
+An additional felt to the data array of an event now costs 0.128 gas/felt, similar to calldata.
+An additional felt to the keys array now costs 0.256 gas/felt.
+Starknet now supports multiple L1 providers.
+Community Forum Posts:
+Starknet v0.13.0 is live on Mainnet.
+Starknet 0.13.0 includes the following changes:
+v3 transactions, including:
+Fee payment in STRK
+Reserved fields for future features, such as Volition and payment master
+get_block API: The gas_price field is replaced by the eth_l1_gas_price and strk_l1_gas_price fields. This change applies also to existing blocks. For more information on the new fields, see the JSON RPC API Spec on GitHub
Sierra v1.4.0. This new version of Sierra is part of Crate v2.4.0, in the Cairo 2.4.0 package. For more information, see Cairo v2.4.0 is out! on the Community forum.
+Improved performance of secp256k1_mul and secp256r1_mul syscalls
Computation cost is reduced by approximately 50% as a result of reduced Cairo steps and increased use of builtins. L1 data availability cost is reduced by approximately 10%-25%. For an ERC-20 transfer, the DA fee reduction is 25%.
+Starknet v0.12.3 is live on Mainnet.
+This release partially removes support for the Starknet feeder gateway. For details, see Feeder Gateway Deprecation in Development Proposals on the Starknet community forum.
+Additionally, this version includes the following changes:
+Performance optimizations in the gateway, the computation of the Patricia storage root, and block hash
+Support for secp256r1 syscalls in the Starknet OS.
Restriction for __validate__ and the constructor of DeployAccount transactions:
Restrict access to sequencer_address in the get_execution_info syscall by returning 0's for the address.
Restrict access to the following syscalls:
+Cairo contracts: get_block_hash
Cairo 0 contracts: get_sequencer_address
This version is available on both Goerli and Sepolia testnets.
+Move structs that are common to secp256k1 and secp256r1 to a separate file.
Starknet v0.12.2 is live on Mainnet.
+This version includes the following changes:
+Enabling P2P Authentication: An additional endpoint in the sequencer gateway to provide a signature on the state diff commitment and block hash.
+Resolving Mismatches in Queries: An extension to the get_state_update endpoint in the sequencer gateway that returns both the pending state diff and the pending block together.
Increased maximum Cairo steps per transaction from 1 million to 3 million.
+Starknet v0.12.1 is live on Mainnet.
+This version includes the following changes:
+Mempool Validation.
+Inclusion of Failed Transactions.
+Keccak builtin.
+Starknet v0.12.0 is live on Mainnet.
+This version contains the following changes:
+Use the rust blockifier and LambdaClass’s Cairo VM to accelerate the sequencer’s time to handle transactions.
+Support version 2.0.0 of the Cairo compiler.
+Replace the PENDING status of transactions to ACCEPTED_ON_L2 - once a transaction is in that status it means that it will be included in a block, this applies to transactions - blocks still have the PENDING status.
Add an experimental get_block_hash syscall.
Change HTTP error code from 500 to 400 on API errors.
+Starknet v0.11.2 is live on Mainnet.
+This version contains the following changes:
+Upgrade Cairo 1.0 version to v1.0.0-rc0 (Cairo 1.0 activated on Starknet!)
+Starknet v0.11.1 is live on Mainnet.
+This version contains the following changes:
+Upgrade Cairo 1.0 version to v1.0.0-rc0.
+Charged transaction fee is now based on an average Ethereum gas price instead of a single sample +(estimation API is unaffected).
+API changes:
+Remove the state root in get_state_update for pending blocks to allow faster responses
+in future versions.
Testing framework:
+Allow declaring (and interacting with) Cairo 1.0 contracts.
+Currently, the Cairo 1.0 ABI is not supported yet, so a Cairo 0 ABI should be supplied to
+declare() manually.
Split deploy() to two phases declare and deploy: deprecated_declare() (for Cairo 0 contract) or
+declare() (for Cairo 1.0 contracts) and deploy() (for both).
Add current block hash to the Starknet Core Contract (currently not verified by the Starknet OS):
+Breaking change: The LogStateUpdate event’s data is changed to include blockHash.
Starknet v0.11.0 is live on Mainnet.
+| + + | +
+
+
+
|
+
In Starknet v0.11.0, you can declare, deploy and run Cairo 1.0 smart contracts. We also introduce a new system call that allows a smooth transitioning of existing contracts to a Cairo 1.0 implementation.
+Historically, contract classes have been defined in terms of Cairo assembly, or Casm for short (the class definition also included more information needed for execution, e.g., hint data). The novelty of Cairo 1.0 is the introduction of Sierra (Safe Intermediate Representation), an intermediate layer between Cairo 1.0 and Casm.
+The introduction of Cairo 1.0 and Sierra has several effects on the system. Below we list the effects on each component; of particular note are:
+A new version of the declare transaction, which allows sending the new class structure
The state commitment will now include contract classes
+Changes to the onchain data format
+New system call - replace_class
| + + | +
+
+
+The |
+
This version contains the following changes:
+Starknet
+Performance - Separate the state commitment computation from the execution of the transactions
+Add starknet-class-hash command to compute the class hash of a compiled Starknet contract
Cairo:
+Autoformatter: Automatically break lines inside expressions
+This version introduces sequencer parallelization! This is the first step in our roadmap of performance upgrades. Details about the specific mechanism of parallelization and the roadmap in general are described in this medium post.
+A new endpoint, estimate_fee_bulk, is added to the feeder gateway. This will allow estimating the fee of several transactions at once, where each transaction is executed relative to the resulting state from applying the previous one.
Sequencing performance improvements
+Builtin ratio changes, which affects builtin costs
+Add estimate_fee_bulk API that computes the fee of multiple transactions that will be executed consecutively
As part of this version, we will also increase the finality of transactions in the pending block, by fixing the timestamp at the time of the block creation. This will solve the issue of transactions moving from pending to rejected on account of too old timestamp
+This version contains the following changes:
+Starknet:
+Add DeployAccount transaction (which will replace the Deploy transaction for deploying account contracts). To use it, you should first add enough funds to your account address to pay the transaction fee, and then you can invoke DeployAccount
Split the starknet deploy_account CLI command into starknet new_account and starknet deploy_account
Account contracts that are expected to be deployed this way should implement the`validate_deploy()` entry point, which should check the signature of the DeployAccount transaction
Improve L1 fee computation: the fee is computed according to the diff of the storage state
+API: Remove entry_point_type field from transaction information
Cairo:
+Add uint256_mul_div_mod to uint256.cairo
This version introduces the next step in Starknet’s account abstraction design, specifically the validate/execute separation. See here for more information.
+This version contains the following changes:
+Starknet:
+Contract (breaking changes):
+@external and @view functions should be imported directly by the main compiled file. Otherwise, they will not be usable as external functions
+Forbid using the same storage variable name in two modules
+New transaction version (version 1) for invoke and declare transactions:
Transactions of version 0 are deprecated and will not be supported in Starknet from the next version (v0.11.0). Please update your systems to use the new version
+| + + | +
+
+
+In order to use transactions of version 1 you will need to upgrade your account contracts + |
+
Add nonce field to the transactions. Nonce validation is now part of the Starknet protocol and is enforced to be executed sequentially
+Invoke:
Split execute to two functions:` validate` (only validates the transaction) and execute (only executes the transaction)
Remove the selector (which is now always execute) field, following the above change.
Declare:
+declare transaction should now be sent from an account (and is validated using validate_declare in the account contract)
Support fee for sending L1 messages. At this point, it’s not mandatory and messages with no fee will still be handled. Starting from the next version it will become mandatory.
+Cairo:
+Syntax changes in Cairo (to make it more similar to rust and C++):
+You can use the cairo-migrate script to convert old code to the new syntax. Use the -i flag to apply the changes to the files
End statements with ;
| + + | +
+
+
+New lines are still part of the language at this point, and you cannot put more than one instruction per line. This will change in Cairo1.0. + |
+
Use { … } for code blocks (instead of : and end)
Add () around the condition of if statements
Remove the member keyword in structs
+Change comment to use // instead of #
Use …, ap` instead of `...; ap in low level Cairo code
Support return types that are not tuples. For example, func foo() → felt (instead of func foo() → (r: felt))
+As a result, it’s now mandatory to specify return types. func foo() → (res) should be replaced by func foo() → (res: felt). The cairo-migrate tool does that automatically.
Return statement accepts expressions, rather than only tuples. For example, you can write let x = (5,); return x;
A few standard library functions were changed to return felt. The cairo-migrate script also fixes calls to those functions
+Support using functions as expressions
+This only applies to functions with → felt signature`, whose ap change is known at compile-time (e.g., recursive functions cannot be used this way)
+Fix a bug in the secp signature verification code that allowed a malicious prover to ignore the value of v (this does not let the prover fake a signature, but allows it to claim that a valid signature is invalid).
Add Cairo code for the recursive STARK verifier
+Technical changes: +* Move from python3.7 to python3.9
+This version contains the following changes:
+Starknet:
+API changes:
+Add get_block_traces API - returns all the transaction traces of a given block
Add a list of declared contracts in get_state_update
Add a 0x prefix for class hash in the API
+Add starknet_version field for blocks (only applies to new blocks)
Starknet CLI:
+Change the default block number to pending
+Using a wallet is the default, --no_wallet must be specified explicitly to override this
Deploying contracts:
+Add deploy_contract function to the account contract created by starknet deploy_account
Use this function to deploy contract (unless using --no_wallet). In particular, deploy should be used after declaring the contract (it expects the contract class hash)
Support --dry_run to get the transaction information without signing or sending it
Support deploy_from_zero in the deploy syscall to deploy a contract to an address that does not depend on the deployer
Cairo:
+* Support and in if statements (if x == y and z == w).
| + + | +
+
+
+At the moment other boolean combinations are not supported + |
+
This version introduces the contract class/instance paradigm into Starknet. See here for more information.
+This version contains the following changes:
+Starknet:
+Enforce fees - max_fee must not be set to zero, and selector must be execute
Split the concepts of contract class and contract instance.
+Add declare transaction type
New API and CLI commands:
+declare - Declares a contract class
get_class_by_hash - Returns the contract class given its hash
get_class_hash_at - Returns the class hash for a given contract instance address
Rename delegate_call to library_call, and change the contract address argument to class hash.
Add a deploy system call.
Rename ContractDefinition to ContractClass
Reduce the compiled contract file’s size by removing unnecessary identifiers (this optimization can be disabled using --dont_filter_identifiers)
Cairo:
+Initial support for the EC-op builtin (scalar multiplication over the STARK curve). Not supported in Starknet yet.
Add additional helper methods to blake2s.cairo, including big-endian support
Technical changes:
+* Change function’s return type from a struct to a named tuple. In particular, foo.Return.SIZE is no longer supported.
A list of recommended full-nodes, open API endpoints, and API providers.
+For complete information on the Starknet Node API in JSON RPC format, see starknet_api_openrpc.json on GitHub.
| Provider | +Open API endpoint, where relevant | +Version support, where relevant | +
|---|---|---|
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | Use the |
+
| + | + | + |
| + | + | Use the |
+
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| + | + | + |
| Provider name | +Description | +More information | +
|---|---|---|
Deoxys |
+A Starknet full-node written in Rust and powered by Substrate by Kasar |
++ |
Juno |
+A Starknet full-node written in go-lang by Nethermind. +You can use the Juno Node runner on AWS. |
++ |
Papyrus |
+A Starknet full-node written in Rust by StarkWare |
++ |
Pathfinder |
+A Starknet full-node written in Rust by Equilibrium |
++ |
Building a Starknet project and want your contract to be audited?
+The companies listed below have designated teams that provide auditing services to Starknet +contracts.
+| Company name | +URL | +
|---|---|
ABDK |
++ |
Beosin |
++ |
Chain Security |
++ |
Consensys Diligence |
++ |
Extropy |
++ |
Nethermind |
++ |
Open Zeppelin |
++ |
OtterSec |
++ |
PeckShield |
++ |
Trail of Bits |
++ |
Zellic |
++ |
Ginger Security |
++ |
The tokens that are currently bridged to Starknet, including their L1 and L2 addresses, are listed in the following .json files:
+mainnet.json
+ |
+
+ The addresses of the tokens currently bridged to Starknet Mainnet. + |
+
+sepolia.json
+ |
+
+ The addresses of the tokens currently bridged to Starknet Sepolia testnet. + |
+
Each token has the following parameters:
+
+name
+ |
+
+ Token name. + |
+
+symbol
+ |
+
+ Token symbol. + |
+
+decimals
+ |
+
+ Number of decimal places used to get the user representation. + |
+
+l1_token_address
+ |
+
+ Address of the L1 ERC-20 contract. + |
+
+l2_token_address
+ |
+
+ Address of the L2 ERC-20 contract. + |
+
+l1_bridge_address
+ |
+
+ Address of the L1 bridge contract. + |
+
+l2_bridge_address
+ |
+
+ Address of the L2 bridge contract. + |
+
Following Maker DAO’s announcement on Jan 25th, StarkWare launched a new DAI contract and bridge on Starknet.
+The new DAI token and bridge are a part of StarkGate and compatible with StarkGate 2.0 features.
+You can withdraw old DAI tokens (DAI v0) without any limitation. Depositing using the DAI v0 bridge are disabled. You are encouraged to migrate to the new DAI token. You can use swap services on Starknet to swap DAI v0 for DAI.
+Maker DAO’s DAI token on Starknet is written in Cairo0 and is not upgradeable. Without upgradability, it cannot support StarkGate’s latest features, such as Smart Deposits and Withdrawal Limits, and over time it will stop being compatible with Starknet altogether (Regenesis). This means that a transition plan is necessary.
+On January 25th, StarkWare launched a new set of DAI bridge and token contracts under StarkGate, written in Cairo. This new DAI token will retain the same contract ’symbol’ and ’name’ as the existing one. To differentiate between the two on Apps and other UIs, we refer to the old DAI as “DAI v0” and the new DAI simply as “DAI.”
+Use one of the following methods:
+Swap your DAI v0 for DAI using an L2 swap app or aggregator within the Starknet ecosystem, such as the following:
+ +Use StarkGate:
+Withdraw your current DAI (DAI v0) to L1 using StarkGate
+Re-deposit your L1 DAI using StarkGate.
+StarkGate automatically issues the new DAI.
+Starkli is a fast command-line interface for interacting with the Starknet network. It supports fetching data from the Starknet network, deploying accounts, and interacting with contracts. Developed by Jonathan Lei. +Starkli also includes useful utilities for developers, such as:
+Compute class hashes from the Cairo file that defines the class.
+Compute a function’s selector.
+Encode messages.
+Deploying new accounts or fetching existing accounts
+Submitting multi-calls to your account
+GitHub: starkli on GitHub
+Documentation: Starkli Book
+Starkli: The New Starknet CLI, on Medium, includes information on getting started, including installation instructions.
+Starknet Cast, part of the Starknet Foundry suite, is a command line tool for interacting with the Starknet network, with deep integration with Starknet Foundry projects.
+Built using NextJS, Starknet.js, Scarb, Starknet-React, Starknet Foundry and Typescript. Designed to make it easier for developers to create, deploy and interact with smart contracts.
+Website: Scaffold-Stark website
+Docs: Scaffold-Stark Docs
+GitHub: starknetkit on GitHub
+An open-source, up-to-date toolkit for building decentralized applications (dapps) on Starknet. Move from prototyping to production-grade apps seamlessly.
+Website: Starknet-Scaffold website
+Docs: Starknet-Scaffold Docs
+GitHub: Starknet-Scaffold on GitHub
+A Starknet devnet is a local Starknet node implementations, aimed for testing and development. A devnet behaves just like a real Starknet node, but everything is executed locally. This enables much faster and more private development of Starknet applications.
+starknet-devnet-rs can is a Rust implementation of a local Starknet node. Developed by SpaceShard.
+With starknet-devnet-rs includes many featured tailored for testing and development, which are not present on testnet/mainnet. +Some of the features include:
+Pre-deployed and pre-funded accounts
+Forking the chain at a specific block.
+Dumping current state (and loading in future runs)
+Impersonating account
+Mock L1<>L2 communication
+GitHub: starknet-devnet-rs on GitHub
+Crates: starknet-devnet-rs on Crates
+Documentation: starknet-devnet-rs Docs
+Support: devnet channel on Starknet Discord
+Katana, developed by the Dojo team, is an extremely fast devnet designed to support local development with Dojo, which is a gaming engine for Starknet. You can use Katana as a general purpose devnet as well.
+GitHub: Dojo Engine on GitHub
+Documentation: Katana Docs
+Decentralized applications are at the heart of Starknet. These libraries help developers build Dapps on Starknet, and connect to prominent Starknet wallets.
+Starknet React is a collection of React hooks for Starknet. It is inspired by wagmi, powered by starknet.js. Developed by Apibara.
+GitHub: starknet-react on GitHub
+Package: starknet-react on NPM
+Documentation: Starknet-React Docs
+Beta Version Documentation: Starknet-React V3 Docs
+Starknet wallet<>Dapp connection bridge. Easy discovery and UI for Starknet wallets.
+Supporting popular Starknet browser wallets
+ArgentX
+Braavos
+Metamask Snaps
+OKx
+GitHub: get-starknet on GitHub
+Package: get-starknet on NPM
+A Starknet wallet connection kit, built by Argent. Built using Starknet.js and starknet-react.
+Website: strknetkit website
+Docs: starknetkit Docs
+GitHub: starknetkit on GitHub
+Cairo is a turing complete language for writing provable programs. It is also the language used for writing smart contracts for Starknet. Starknet uses a different model than the Ethereum Virtual Machine (EVM), and as such, requires specialized tools for development.
+
+| + + | +
+
+
+This list of tools is dynamic and is being updated as more tools are added. If a tool you are using is missing, please consider editing this page and creating a Pull Request. + |
+
A Software Development Kit (SDK) is a library that abstracts the complexities of Starknet when building transactions and interacting with the blockchain, including the following:
+Read the chain state.
+Account creation and management.
+Cryptography: signature verification and signing, computing hashes used by Starknet.
+Contract declaration and deployment.
+Contract interactions: ABI import, constructing transactions.
+SDKs implement the Starknet JSON RPC specification, and are updated to support the latest API changes. There are SDKs for various languages, so you can choose the SDK according to your needs.
+| SDK name | +Github | +Package | +Docs | +Support | +Maintainer | +
|---|---|---|---|---|---|
Starknet.js |
++ | + | + | starknet.js channel on Starknet Discord |
++ |
Starknet.py |
++ | + | + | + | + |
Starknet-rs |
++ | + | + | + | + |
Starknet.go |
++ | + | + | + | + |
starknet-jvm |
++ | + | + | + | + |
starknet.swift |
++ | + | + | + | + |
starknet.dart |
++ | + | + | + | + |
Sierra-Analyzer is a security toolkit for analyzing Sierra files, developed by FuzzingLabs.
+Supported featrued include:
+Decompile a Sierra file
+Print the contracts Control Flow Graph
+Run Static Analysis detectors
+Links:
+The following tools are the recommended tools for developing Starknet smart contracts. These cover compilation, package management, testing and deployment.
+Scarb is a package manager for Cairo, but it is much more than that. It is the easiest and recommended way to build and maintain Cairo code. Think Cargo for Rust. +Scarb is developed by Software Mansion.
+Scarb includes the following features:
+Initiating a new Cairo project.
+Compiling Cairo projects.
+Adding and removing Cairo dependencies.
+Generating Cairo documentation.
+Fetching and uploading packages Scarbs.xyz, the Cairo Registry.
+Integration with the Cairo Language Server
+It integrates with other tools in the Cairo ecosystem, such as Starknet Foundry and the Dojo gaming engine.
+GitHub: Scarb on GitHub
+Documentation: Scarb Docs
+Support: Scarb on Telegram
+Cairo Registry: scarbs.xyz
+Starknet Foundry is the go-to toolchain for developing Starknet smart contracts. Similarly to its EVM counterpart, Starknet Foundry supports a plethora of features focused on testing Cairo smart contracts for Starknet.
+Starknet Forge, and snforge_std allow the use of "cheatcodes" to test various aspects of the contracts.
For example:
+Setting caller address
+Manipulating the timestamp and block number
+Forking the chain at a specific block and testing with that state
+Fuzz testing
+Getting accurate gas and resource reports
+Profiling
+Starknet Cast is a command line tool for interacting with the Starknet network, with deep integration with Starknet Foundry projects.
+With sncast it is possible to:
Declare and deploy contracts
+Read from Starknet contracts
+Deploy accounts
+Interact with contracts
+GitHub: starknet-foundry on GitHub
+Documentation: starknet-foundry Docs
+Support: Starknet Foundry Support on Telegram
+Remix is a browser-based integrated development environment (IDE) for Ethereum that you can use for learning, experimenting and finding vulnerabilities in smart contracts, without installing anything. The Starknet Remix plugin lets you use Remix for testing Starknet smart contracts, so you can focus on learning Cairo and Starknet in the comfort of your browser.
+Remix and the Starknet Remix plugin include the following features:
+Integrated compiling.
+You can deploy contracts to testnet, mainnet and the plugin’s own integrated devnet.
+You can call functions of contracts that you have already deployed, to facilitate testing and interaction.
+The Starknet Remix Plugin is integrated with Starknet By Example, a rich repository of practical learning content.
+Remix Project: Remix Project site.
+Blogpost: Unlocking Onboarding to Starknet: An Overview of the Starknet Remix Plugin.
+GitHub Starknet Remix on GitHub.
+While not under any specific category, these tools can be helpful in various stages of development.
+While Scarb compiles full projects, and produces both Sierra and CASM files, it is often needed to only compile a single Sierra file to CASM (for example, when getting a class from Starknet mainnet). The Universal Sierra Compiler supports all sierra versions, and can compile the the a CASM file.
+| + + | +
+
+
+The USC comes bundled with Starknet Foundry and does not need to be installed separately if Starknet Foundry is installed. + |
+
The Starknet RPC Request Builder is a useful tool to generate RPC queries for Starknet, with support for basic example for JavaScript, Go and Rust.
+The Open Zeppelin Contract Wizard is a tool that helps you create smart contracts with Open Zeppelin libraries. Easily toggle on and off features for popular smart contract patterns, and the wizard will generate the code for you.
+Cairo-profiler can be used to create profiles of Cairo executions from execution traces. +These can be analyzed and displayed to show Flame Graphs, and other useful information.
+| + + | +
+
+
+Cairo-profiler is currently integrated into Starknet Foundry, but can be used as a standalone tool. + |
+
If want to dive deep into the Cairo VM, and experiment writing Cairo online, and don’t want to deploy a smart contract on Starknet, the Cairo Playground is a great way to do so.
+A JavaScript package, abstracting the Starknet Devnet API, making it easier to interact with starknet-devnet-rs. +This simplifies writing end-to-end tests using Devnet, including tests for L1<>L2 communications.
+Notable features:
+Spawn a new Devnet instance without installing it
+Wrapping RPC calls to Devnet
+Abstracting complex L1<>L2 communication setup with a local L1 node (e.g. Anvil)
+An extension for the Microsoft VSCode IDE that provides assistance when writing Cairo smart contracts, by using the Cairo Language Server. It integrates with Scarb, and works best when Scarb is installed via asdf.
Features include:
+Live diagnostic highlighting for compile errors
+Quick fixes with suggestions
+Go to definition
+Code formatting
+Code completion for imports
+| + + | +
+
+
+Sepolia testnet replaces Goerli testnet. +
+
+Goerli testnet support is now removed. +
+
+For more information, including bridge support for Sepolia, see Starknet Goerli Deprecation in the Starknet Dev News newsletter. + |
+
| +The Starknet Core Contract + | ++ + | +
| +Verifier address + | ++ + | +
| +Sequencer base URL for API routing + | +
+ https://alpha-mainnet.starknet.io + |
+
| +The Starknet Core Contract + | ++ + | +
| +Verifier address + | ++ + | +
| +Sequencer base URL for API routing + | +
+ https://alpha-sepolia.starknet.io + |
+
The Starknet fee tokens are STRK and ETH.
+| +L2 STRK address (Mainnet and testnet) + | +
+
|
+
| +L2 ETH address (Mainnet and testnet) + | +
+
|
+
The Starknet voting token is vSTRK. For information on vSTRK, see vSTRK overview on the Starknet Governance Hub.
+| +Mainnet address + | +
+
|
+
| +Sepolia testnet address + | +
+
|
+
Starknet currently has a number of limits in place in order to keep the network stable and optimized for the best performance.
+Blockifier-related constants and limits are defined, for each Starknet version starting from v0.13.0, in a JSON file called versioned_constants in this directory.
| + + | +
+
+
+These are subject to revisions and change on a regular basis + |
+
| + + | +
+
+
+Sepolia testnet replaces Goerli testnet. +
+
+Goerli testnet support is now removed. +
+
+For more information, including bridge support for Sepolia, see Starknet Goerli Deprecation in the Starknet Dev News newsletter. + |
+
| Entity | +Description | +Sepolia | +Mainnet | +
|---|---|---|---|
Block time |
+The maximum amount of time within which a pending block is closed, if no other limit is met. |
+30 seconds |
+30 seconds |
+
Block limit (Cairo steps) |
+The maximum number of Cairo steps that can be completed +within each block to ensure block production times remain consistent and predictable. |
+40,000,000 |
+40,000,000 |
+
Block limit (gas) |
+Certain Starknet operations, such as sending messages between L1 and L2, consume Ethereum gas. The current L1 state update +mechanism involves an Ethereum transaction for each Starknet block. +The gas limit for Starknet blocks is therefore inherited from the gas limit for Ethereum blocks. |
+5,000,000 |
+5,000,000 |
+
Max transaction size (Cairo steps) |
+The maximum number of computational steps, measured in Cairo steps, that a transaction can contain when processed on the Starknet network. +This limit is important for ensuring the efficient execution of transactions and preventing potential congestion. |
+10,000,000 |
+10,000,000 |
+
Max number of events per transaction |
+The maximum number of events that a transaction can emit during its execution. |
+1,000 |
+1,000 |
+
Max number of data felts per event |
+The maximum number of felts that an event can contain in its |
+300 |
+300 |
+
Max number of key felts per event |
+The maximum number of felts that an event can contain in its |
+50 |
+50 |
+
Max Cairo steps for |
+The maximum number of computational steps, measured in Cairo steps, for a |
+1,000,000 |
+1,000,000 |
+
Max contract bytecode size (Number of felts in the program) |
+The maximum size of the bytecode or program that a smart contract can have on Starknet. +Bytecode is the low-level code that comprises smart contracts. Limiting this size helps manage the complexity of contracts and the overall efficiency of the network. |
+81,290 |
+81,290 |
+
Max contract class size |
+The maximum size for a contract class within Starknet. +Contract classes are a fundamental building block for smart contracts, and limiting their size can have implications for the network’s scalability and security. |
+4,089,446 bytes |
+4,089,446 bytes |
+
IP address limits (read/write) |
+In order to reduce network spam, Starknet limits the amount of contract reads and writes that a single IP +address can make. |
+200 per min per IP address |
+200 per min per IP address |
+
Signature length (felts) |
++ | 4,000 |
+4,000 |
+
Calldata length (felts) |
++ | 4,000 |
+4,000 |
+
A block explorer, or blockchain explorer, enables you to see transactions, blockchain metrics and other information.
+The following block explorers provide information on Starknet.
+| Block explorer name | +URL | +
|---|---|
Starkscan |
++ |
ViewBlock |
++ |
Voyager |
++ |
oklink |
++ |
NFTScan (NFT explorer) |
++ |
The Starknet Book serves as a comprehensive guide to understanding Starknet, Cairo, and introduces you to the Starknet ecosystem.
+The Starknet Book caters to various objectives and interests. Mix and match these chapters to customize your learning experience based on your unique interests and requirements. Whether you’re exploring smart contract development, frontend integration, or learning about the core architecture, The Starknet Book is your trusted companion on the journey of deepening your understanding of Starknet.
+| Chapter | +Description | +
|---|---|
Chapter 1 |
+Introduction to Starknet and Cairo +How to quickly get started with Starknet and Cairo development. |
+
Chapter 2 |
+Starknet tooling +An overview of the available tooling for Starknet. |
+
Chapter 3 |
+Starknet architecture +Learn how Starknet works under the hood. Learn how sequencer, prover and nodes interact. |
+
chapter 4 |
+Account abstraction +Account abstraction is one of the main usability features of Starknet. Learn how this works and how you can utilize it. |
+