Skip to content

Commit

Permalink
add md file
Browse files Browse the repository at this point in the history
  • Loading branch information
enitrat committed Nov 14, 2024
1 parent 6143496 commit be30ef1
Showing 1 changed file with 31 additions and 24 deletions.
55 changes: 31 additions & 24 deletions docs/general/cairo_precompiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,24 +46,30 @@ Cairo contracts that have been thoroughly audited and are known to be secure.
Let's define three different flows to interact with the precompile, and the
expected behavior for each.

1. **Successful Flow**
A participant Alice wants to interact with the `DualVMToken` contract.
The `DualVMToken` contract has been whitelisted by the Kakarot team, meaning that it is authorized to call
the `0x75001` precompile.
Alice calls the `DualVMToken` contract to transfer Starknet Tokens, which will internally call the `0x75001` with a DELEGATECALL.
Because DualVMToken is whitelisted, the call will pass validation and the Cairo contract will be executed.
Alice's tokens are transferred to the recipient.

2. **Failed Flow 1**
A participant Alice wants to interact with a random `Contract_X` contract.
Alice calls `Contract_X`, which then calls the `DualVMToken` contract with a DELEGATECALL.
The `DualVMToken` contract is whitelisted to call the `0x75001` precompile. However, it is forbidden to delegatecall into a contract that is whitelisted to call the `0x75001` precompile. To check this, we verify whether the `evm.message.address.evm` of the call is whitelisted. Here, because of the delegatecall behavior, this resolves to `Contract_X`, which is not whitelisted. The call will thus fail.

3. **Failed Flow 2**
A participant Alice wants to interact with the `NonWhitelistedContract` contract, which is not whitelisted to call the `0x75001` precompile.
Alice calls `NonWhitelistedContract`, which then calls the `0x75001` precompile with a DELEGATECALL.
Because `NonWhitelistedContract` is not whitelisted, the call will fail validation and the transaction will be reverted.
Alice's call to `NonWhitelistedContract` will therefore fail.
1. **Successful Flow** A participant Alice wants to interact with the
`DualVMToken` contract. The `DualVMToken` contract has been whitelisted by
the Kakarot team, meaning that it is authorized to call the `0x75001`
precompile. Alice calls the `DualVMToken` contract to transfer Starknet
Tokens, which will internally call the `0x75001` with a DELEGATECALL. Because
DualVMToken is whitelisted, the call will pass validation and the Cairo
contract will be executed. Alice's tokens are transferred to the recipient.

2. **Failed Flow 1** A participant Alice wants to interact with a random
`Contract_X` contract. Alice calls `Contract_X`, which then calls the
`DualVMToken` contract with a DELEGATECALL. The `DualVMToken` contract is
whitelisted to call the `0x75001` precompile. However, it is forbidden to
delegatecall into a contract that is whitelisted to call the `0x75001`
precompile. To check this, we verify whether the `evm.message.address.evm` of
the call is whitelisted. Here, because of the delegatecall behavior, this
resolves to `Contract_X`, which is not whitelisted. The call will thus fail.

3. **Failed Flow 2** A participant Alice wants to interact with the
`NonWhitelistedContract` contract, which is not whitelisted to call the
`0x75001` precompile. Alice calls `NonWhitelistedContract`, which then calls
the `0x75001` precompile with a DELEGATECALL. Because
`NonWhitelistedContract` is not whitelisted, the call will fail validation
and the transaction will be reverted. Alice's call to
`NonWhitelistedContract` will therefore fail.

```mermaid
sequenceDiagram
Expand Down Expand Up @@ -112,8 +118,9 @@ sequenceDiagram
### 0x75002: Whitelisted Cairo Message Precompile

This precompile allows any whitelisted caller to execute a Cairo contract. The
whitelisting is based on the address of the caller. The purpose of the whitelist is to ensure
that messages sent to L1 are following a specific format (`to`, `sender`, `data`).
whitelisting is based on the address of the caller. The purpose of the whitelist
is to ensure that messages sent to L1 are following a specific format (`to`,
`sender`, `data`).

```mermaid
sequenceDiagram
Expand Down Expand Up @@ -144,11 +151,11 @@ sequenceDiagram

### 0x75003: Multicall Precompile

Allows the caller to execute `n` Cairo calls in a single
precompile call. This precompile cannot be called with DELEGATECALL / CALLCODE. As such, it can
be used permissionlessly by any contract.
Allows the caller to execute `n` Cairo calls in a single precompile call. This
precompile cannot be called with DELEGATECALL / CALLCODE. As such, it can be
used permissionlessly by any contract.

```
```mermaid
sequenceDiagram
participant Alice
participant Contract_X
Expand Down

0 comments on commit be30ef1

Please sign in to comment.