feat: update docs

.trunk/trunk.yaml

@@ -7,7 +7,7 @@ cli:
 plugins:
   sources:
     - id: trunk
-      ref: v1.6.0
+      ref: v1.6.2
       uri: https://github.com/trunk-io/plugins
 # Many linters and tools depend on runtimes - configure them here. (https://docs.trunk.io/runtimes)
 runtimes:
@@ -17,15 +17,15 @@ runtimes:
 # This is the section where you manage your linters. (https://docs.trunk.io/check/configuration)
 lint:
   enabled:
-    - [email protected].148
+    - [email protected].255
     - git-diff-check
     - [email protected]
-    - [email protected].1
-    - [email protected].1
-    - [email protected].2
+    - [email protected].5
+    - [email protected].2
+    - [email protected].3
     - [email protected]
-    - trivy@0.52.2
-    - trufflehog@3.79.0
+    - trivy@0.55.2
+    - trufflehog@3.82.2
 actions:
   disabled:
     - trunk-announce

docs/architecture/understanding-kakarot.md

@@ -3,15 +3,19 @@ title: Kakarot ZK-EVM under the hood
 sidebar_position: 2
 ---
 
-## Kakarot, the ZK-EVM built in Cairo
+## Kakarot, the EVM proving engine built in Cairo
 
-Kakarot is a ZK-EVM built in [Cairo](https://www.cairo-lang.org/), the provable
-language that powers [Starknet](https://starkware.co/starknet/) and all the
-StarknetOS chains (also called CairoVM chains, or Starknet appchains).
+Kakarot is a provable EVM built in [Cairo](https://www.cairo-lang.org/), the ZK
+domain specific language (DSL) that powers
+[Starknet](https://starkware.co/starknet/) and all the StarknetOS chains (also
+called CairoVM chains, or Starknet appchains).
 
-Kakarot enhances and extends Starknet by making it a DualVM environment.
-Starknet effectively becomes EVM compatible; allowing the use of both CairoVM
-and EVM for builders & users. Additionally, Kakarot
+![Kakarot use cases](../../static/diagrams/kakarot_applications.png)
+
+The natural first use case for Kakarot is to be embedded into Starknet, thus
+making it a MultiVM environment. Starknet effectively becomes EVM compatible;
+allowing the use of both CairoVM and EVM for builders & users. Additionally,
+Kakarot Labs
 [strives to push more innovations](https://ethcc.io/archive/Kakarot-zkEVM-beyond-ethereum-compatibility)
 to the L2 space, participating in governance initiative such as
 [Rollup Improvement Proposals](https://github.com/ethereum/RIPs) (RIPs) and
@@ -28,54 +32,64 @@ expanding their options. Additionally, developers who want to launch an EVM
 appchain (a chain tailored to their specific app) with Kakarot benefit from the
 stack being highly auditable, maintainable, and modular!
 
-For users, this means both access to faster and cheaper transactions on
-Starknet, as well as better interoperability with the broader Ethereum
+For EVM native users, this means both access to faster and cheaper transactions
+on Starknet, as well as better interoperability with the broader Ethereum
 ecosystem.
 
 Discover the Kakarot explorer and other useful links on the
 [survival guide](../survival-guide) page.
 
-Note: Kakarot is not a privacy chain. Zero-knowledge technologies can be used
-for two (non-excluding) purposes, Scaling or Privacy. Kakarot uses the former to
-scale Ethereum.
+## Kakarot is not a rollup
+
+- Kakarot is not an appchain or a blockchain. Kakarot Labs is deploying an EVM
+  environment on Starknet Mainnet. This EVM environment is fully enshrined &
+  embedded into Starknet L2. Kakarot transactions and blocks are abstractions
+  over Starknet transactions and block under the hood.
+- Kakarot is not an L3, nor an L2. It is an EVM runtime inside Starknet.
+  Long-term, Kakarot Labs will rename the Kakarot initiative on Starknet:
+  "Starknet EVM" to reduce confusion.
+- Kakarot is not privacy preserving. Zero-knowledge technologies can be used for
+  two (non-excluding) purposes, Scaling or Privacy. The underlying proof system
+  used by Cairo is not privacy-preserving.
 
 ## How does Kakarot work under the hood?
 
 ### Kakarot is an implementation of the EVM in Cairo
 
-Under the hood, Kakarot ZK-EVM is an implementation of the EVM instruction set
-in Cairo.
+Under the hood, Kakarot's core EVM is an implementation of the EVM instruction
+set in Cairo.
 
 > Cairo is the first Turing-complete language for creating provable programs for
 > general computation.
 
 Cairo is like any a programming language, but made for writing provable
-software. It means that whatever is written in Cairo is, by design, _zk_. Using
-Cairo means that we leverage cryptography without having to think about it, it
-sort of "comes for free" just by using this language and not, say, rust.
+software. It means that whatever is written in Cairo is, by design, _zk_. Note
+that we use the term _zk_ here in the sense that execution of provable software
+is "ZK-verifiable", not that it is privacy preserving, or so-called
+"zero-knowledge". Using Cairo means that we leverage the power of STARKs without
+having to think about it, it sort of "comes for free" just by using this
+language and not another high-level language, such as Rust or Python.
 
 ---
 
-Diagram - Kakarot ZK-EVM high-level architecture:
+Diagram - Kakarot on Starknet high-level architecture:
 
-![Kakarot ZK-EVM architecture diagram](../../static/diagrams/kakarot_zkevm.png)
+![Kakarot on Starknet architecture diagram](../../static/diagrams/kakarot_zkevm.png)
 
 ---
 
-Kakarot - the network - is composed of three parts: the Core EVM in Cairo, an
-RPC layer (RPC server and EVM indexer) and an underlying host CairoVM client
-(e.g. Starknet mainnet).
+Kakarot on Starknet is composed of three parts: the Core EVM in Cairo, an RPC
+layer (RPC server and EVM indexer) and an underlying host CairoVM client (e.g.
+Starknet mainnet).
 
 ### Kakarot runs on an underlying StarknetOS client
 
-The Kakarot core EVM, i.e. as said previously our new EVM implementation, is
-deployed on an underlying StarknetOS chain. This means that Kakarot is running
-as a set of Cairo smart contracts on a CairoVM-powered chain. This CairoVM chain
-is "invisible" to the user. Users only interact with Kakarot through the RPC
-layer in an Ethereum-compatible way. The only exposed interface in Kakarot
-ZK-EVM is the Ethereum JSON-RPC specification. Additionally, we allow developers
-to write and use Cairo modules to enhance the performance of their apps,
-similarly to [Arbitrum Stylus](https://arbitrum.io/stylus).
+Kakarot's core EVM is deployed on Starknet. The core EVM is running as a Cairo
+smart contract on Starknet. Users only interact with Starknet MultiVM through
+the RPC layer in an Ethereum-compatible way. The only exposed interface in
+Kakarot is the Ethereum JSON-RPC specification. Additionally, we allow
+developers to write and use Cairo modules to enhance the performance of their
+apps, similarly to [Arbitrum Stylus](https://arbitrum.io/stylus).
 
 ---
 
@@ -86,61 +100,65 @@ Diagram - Kakarot RPC Layer
 ---
 
 To put it simply, Kakarot is composed of an EVM written in Cairo and an RPC
-layer to allow users to interact with it in an Ethereum format. All Cairo
-execution traces are provable by design, which allows Kakarot to batch blocks
-and submit proofs to L1 using the
+layer to allow users to interact with it in an Ethereum format. Starknet's
+allows the deployment of Cairo programs. All Cairo execution traces are provable
+by design, which allows Starknet to batch blocks and submit STARK proofs of
+execution to L1 using the
 [Starkware Shared prover](https://starkware.co/tech-stack/) (SHARP).
 
-In Kakarot ZK-EVM, the design choices regarding EVM programs and their Cairo
-equivalents are explained below. They are subject to architecture changes over
-time. **🎙️ Disclaimer 🎙️: all these designs choices are invisible to the user**:
+In Kakarot on Starknet, the design choices regarding EVM programs and their
+Cairo equivalents are explained below. They are subject to architecture changes
+over time. **🎙️ Disclaimer 🎙️: all these designs choices are invisible to the
+user**:
 
-- every EVM smart contract (so-called _Contract Account_) and EVM user-owned
-  account (so-called _Externally Owned Account (EOA)_) is deployed as a unique
-  Starknet smart contract. This Starknet smart contract stores its own bytecode
-  and EVM storage slots.
+- every EVM Account, i.e. both smart contract (so-called _Contract Account_) and
+  EVM user-owned account (so-called _Externally Owned Account (EOA)_) is
+  deployed as a unique Starknet smart contract. This Starknet smart contract
+  stores its own bytecode and EVM storage slots.
   - It has a Starknet formatted address (31 bytes hex string), which is uniquely
     mapped to its EVM address (20 bytes hex string). For the user, this is
     invisible.
-  - Its native balance in ETH (coin vs. token) is denominated in ERC20 native
-    token under the hood in the Kakarot system. For the user, this is invisible.
+  - Its native balance in ETH (coin vs. token) is denominated in Starknet's ETH
+    ERC20 under the hood in the Kakarot system. For the user, this is invisible.
   - EOAs in Kakarot behave exactly like in Ethereum L1, uses the same signature
     and validation, though it can be extended in the future to support
     innovative features!
 - EVM transactions that are sent by users are wrapped in Starknet transactions.
   The derived EVM Transaction hashes are mapped 1-to-1 with underlying Starknet
   transaction hashes. Since signature verification is done in a Cairo program,
   transactions are provably processed with integrity
-  [despite being wrapped at the RPC level](https://github.com/kkrt-labs/kakarot-rpc/blob/bcadfc9b38ac934f73832b3a3485c15f08d66218/src/eth_rpc/servers/eth_rpc.rs#L236).
+  [despite being wrapped at the RPC level](https://github.com/kkrt-labs/kakarot-rpc).
   For the user, this is invisible.
 - new state roots are computed according to
   [the state trie of Starknet](https://docs.starknet.io/architecture-and-concepts/network-architecture/starknet-state/)
-  (pedersen MPT). Kakarot uses Pedersen hash and not keccak because of the
-  zk-unfriendliness of keccak. This does not hurt EVM compatibility at the
-  applicative level. Note that the transaction trie and receipt trie are both
-  computed as keccak tries for the RPC layer (block explorers, indexers, etc.),
-  but as pedersen tries for the STARK proof generation.
+  (pedersen MPT). Kakarot uses Pedersen hash and not keccak for block hash
+  computation because of the zk-unfriendliness of keccak. This does not hurt EVM
+  compatibility at the applicative level. Note that the transaction trie and
+  receipt trie are both computed as keccak tries for the RPC layer (block
+  explorers, indexers, etc.), but as pedersen tries for the STARK proof
+  generation.
 
 TL;DR - whatever is written in Cairo can be proven. Kakarot implements the EVM
 specification in Cairo. It is provable by design. All the Cairo magic is done
-under the hood. For the user, this is invisible. They are interacting with an
-EVM-compatible network.
+under the hood. For the user, this is invisible. They are interacting with in an
+EVM-compatible manner.
 
 ## The difference between Kakarot and other ZK-EVMs
 
 Remember that a ZK-EVM is an EVM for which transaction execution is provable.
 There are a few ways to build a ZK-EVM. An interesting axis is to check how
 low-level the implementation is. When a ZK-EVM is built using zk-circuits, it is
-considered to be low-level (specialized, hard to maintain & audit, more
-performant on average). If it relies on a general-purpose provable VM (Cairo,
-Risc-Zero, Jolt, etc.), it is considered high-level (agile, sustainable and
-performant thanks to newer proof systems such as
+considered to be low-level (specialized, hard to maintain & audit, historically
+more performant but in reality not anymore). If it relies on a general-purpose
+ZK-VM (Cairo, Risc-Zero, Jolt, etc.), it is considered high-level (agile,
+sustainable and performant thanks to newer proof systems such as
 [Circle STARK](https://vitalik.eth.limo/general/2024/07/23/circlestarks.html)).
 
-Kakarot ZK-EVM is probably the most high-level ZK-EVM in production. On the
-scale of maths language and polynomials to human understandable language,
-Kakarot is closer to human readable language than any other ZK-EVM. This matters
-to users in two ways:
+![ZK-EVM Design Landscape](../../static/diagrams/zkevm_landscape.png)
+
+Kakarot ZK-EVM is among the most high-level ZK-EVM in production. On the scale
+of maths language and polynomials to human understandable language, Kakarot is
+close to human readable language. This matters to users in two ways:
 
 - Because Kakarot is built on Cairo, Kakarot as a codebase is extremely slim (an
   order of magnitude lighter than other ZK-EVMs) and thus extremely easy to

docs/architecture/understanding-zkevm.md

@@ -143,26 +143,31 @@ TL;DR - execute off-chain, verify on-chain, save on costs.
 
 ## What does it mean to prove the EVM: the transition from EVM to ZK-EVM?
 
-A ZK-EVM is simply a zk-Rollup that is compatible with Ethereum. This means that
-users should be able to interact with it as if they were interacting with
-Ethereum (or almost). For instance, users will use the same tools on a ZK-EVM
-than on Ethereum L1, such as the same wallet (e.g. Metamask). Developers' smart
-contracts should be deployable to a ZK-EVM without any (or little) changes.
-
-This is powerful in the sense that the cryptography part is abstracted away.
-Users continue to interact with a high-level abstraction they're familiar with:
-the EVM. In that sense, the iterative "build on existing work" aspect of
-innovation is preserved in the Ethereum ecosystem.
+A ZK-EVM is simply an EVM implementation that is provable. To simplify, some
+people call Ethereum-compatible ZK-Rollups "ZK-EVMs". This means that users
+should be able to interact with it as if they were interacting with Ethereum (or
+almost). For instance, users will use the same tools on a Ethereum-compatible
+ZK-Rollup (e.g. Scroll) than on Ethereum L1, such as the same wallet (e.g.
+Metamask). Developers' smart contracts should be deployable to a ZK-EVM without
+any (or little) changes.
+
+This is powerful in the sense that the cryptography and proving part is
+abstracted away. Users continue to interact with a high-level abstraction
+they're familiar with: the EVM. In that sense, the iterative "build on existing
+work" aspect of innovation is preserved in the Ethereum ecosystem. Builders are
+able to harness the scalability power of SNARKs and STARKs while being able to
+write Solidity and EVM compatible smart contract languages.
 
 Other actors in the zk-Rollup ecosystem have decided to start over and break
 compatibility with the EVM. This includes for instance
-[Starknet](https://www.starknet.io/en), also powered by the CairoVM. Users and
-developers on Starknet need to get used to using new tools and technologies, but
-do not have to suffer from EVM legacy. Kakarot places a somewhat different bet:
-the EVM will remain the dominant common abstraction layer in crypto and Cairo
-will be the strongest ZK-VM. Therefore, it makes sense to both:
-
-- build an EVM in 2024,
+[Starknet](https://www.starknet.io/en), an non-EVM compatible L2 powered by the
+CairoVM. Users and developers on Starknet need to get used to using new tools
+and technologies, but benefit from lower costs since Cairo is specifically built
+for ZK. Kakarot places a somewhat different bet: the EVM will remain the
+dominant common abstraction layer in crypto and Cairo will be the strongest
+ZK-VM. Therefore, it makes sense to both:
+
+- launch an EVM environment on Starknet in 2024, thus making it a MultiVM L2,
 - bet on the Cairo powerhouse for the years to come.
 
 Kakarot users stand to benefit both from the Ethereum network effect and the