Feat/add core contract deployer

Cargo.toml

@@ -54,5 +54,5 @@ tokio-util = { version = "0.7.13", default-features = false }
 url = { version = "2.5.4", default-features = false }
 zip = { version = "2.2.2", default-features = false, features = ["deflate"] }
 sqlx = { version = "0.8.2", features = [ "chrono", "macros", "regexp", "runtime-async-std", "runtime-tokio", "sqlite", "uuid" ] }
-piltover = {package = "piltover", git = "https://github.com/cartridge-gg/piltover.git", rev = "ab34aaa" }
+piltover = {package = "piltover", git = "https://github.com/cartridge-gg/piltover.git", rev = "67e65b8928b7ee3c2c188bf36c6b9eddc14addb2" }
 cainome = { version = "0.10.1", features = ["abigen-rs"] }

README.md

@@ -4,69 +4,219 @@ Saya is a settlement service for Katana.
 
 ## Katana provable mode
 
-Katana must be running in provable mode to be proven by Saya.
-All the following Katana commands are available from Dojo `1.3.0` and above.
+Katana must be running in **provable mode** to be proven by Saya.
+All commands described below are available starting from **Dojo `1.3.0`**.
 
-1. Use `katana init` to setup the chain spec, you can use the options or the prompt (default) to setup the chain spec.
+### Important limitation
 
+Provable Katana currently supports only **Starknet v14.0.1**.
+Because of this, Katana’s built-in logic for deploying the core contract **cannot be used**.
+Instead, deployment is handled by **Saya**.
+
+### Correct flow
+
+1. Use Saya to:
+
+   * declare (or use the predeclared) core contract,
+   * deploy the contract,
+   * set the program info and fact registry.
+
+2. From this process, obtain:
+
+   * the **core contract address**,
+   * the **block number** where it was deployed.
+
+3. Use these values when running `katana init`.
+
+---
+
+## Core contract (Piltover)
+
+The `core-contract` subcommand manages the Piltover core contract:
+
+* declaring the class,
+* deploying the contract,
+* setting program info and fact registry.
+
+### Required environment variables
+
+```bash
+export SETTLEMENT_ACCOUNT_PRIVATE_KEY=<PRIVATE_KEY_IN_HEX>
+export SETTLEMENT_ACCOUNT_ADDRESS=<ACCOUNT_ADDRESS_IN_HEX>
+export SETTLEMENT_CHAIN_ID=<STRING_CHAIN_ID>
 ```
-katana init
+
+> This step is optional if you rely on the default class hash used by the `deploy` command (latest compatible Piltover).
+
+---
+
+## Declare the core contract
+
+The only argument is the path to the core contract definition.
+By default, it points to the contract in the repository:
+
+```
+--core-contract-path <CORE_CONTRACT_PATH>
+    [env: CORE_CONTRACT_PATH=]
+    [default: contracts/core_contract.json]
 ```
 
-2. `katana init` generates a directory with configuration file and genesis block. Use `katana config` to list all the local configuration and `katana config <CHAIN_ID>` to display the configuration and the file path if you want to inspect it.
+Command:
 
-3. Start Katana with `katana --chain <CHAIN_ID>` to load the generated parameters at start.
+```bash
+cargo run core-contract declare
+```
 
-> **_NOTE:_** You can define an `--output-path` when working with `katana init` to output the configuration files in the given directory. You will then want to start katana with the `--chain /path` instead of `--chain <CHAIN_ID>`.
+or:
 
-> **_NOTE:_** If piltover settlement contract is already deployed, you can skip the automatic deployment by using the `--settlement-contract` and providing the contract address.
+```bash
+cargo run core-contract declare --core-contract-path <PATH>
+```
 
-4. Block time: when running Katana in provable mode, the block time is important, since each block will be proven by Saya, and eventually settled or posted to a data availability layer (which in both cases is incurring an additional cost).
+Expected output for the unmodified core contract:
 
-   It is then recommended to run Katana with a block time. It is important to note that Katana is starting the block time for the very first transaction received for the block, and will never produce empty blocks.
+```
+[INFO  saya::core_contract::utils] Core contract already declared on-chain.
+[INFO  saya::core_contract::cli] Core contract class hash: 0x5aed647bf20ab45d4ca041823019ab1f98425eba797ce6b998af94237677f5
+```
 
-   ```bash
-   # Example for Katana with a block time of 30 seconds.
-   katana --chain <CHAIN_ID> --block-time 30000
-   ```
+---
+
+## Deploy the core contract
+
+The deploy command accepts the following options:
 
-5. Block step limitation: Due to an issue in the CairoVM not yet merged in Katana, to ensure that the block is provable by Saya, the maximum cairo steps in a block must be at most `16_000_000`. If this limit is reached, Katana will mined the block (regardless of the block time).
+```
+--class-hash <CLASS_HASH>  [env: CLASS_HASH=]
+                           [default: latest Piltover hash]
+--salt <SALT>             [env: SALT=]
+```
+
+By default, the class hash is set to the latest compatible Piltover core contract.
 
-   Once this limitation will be removed, the max cairo steps will be `40_000_000` (already enforced by Katana internally).
+Example:
+
+```bash
+cargo run core-contract deploy --salt 0x5
+```
+
+The output contains two important values:
+
+* **block number**,
+* **contract address**.
+
+So save them for future use.
+
+Example output:
+
+```
+[INFO  saya::core_contract::utils] Core contract deployed.
+[INFO  saya::core_contract::utils]  Tx hash   : 0x5bfedaba61dcebb3ab0a8f5856eace3a6bec17f007654142f5004b0ef4f39bf
+[INFO  saya::core_contract::utils]  Deployed on block  : 6180778
+[INFO  saya::core_contract::cli] Core contract address: 0x9da87cf1e8ceccb46e7d044541b51bc7f369c262f332e49152e74b30659b53
+```
+
+---
+
+## Set program info and fact registry
+
+The last step is to set the program info and fact registry (defaults to the Atlantic fact registry).
+
+Options:
+
+```
+--fact-registry-address <FACT_REGISTRY_ADDRESS>
+    [env: FACT_REGISTRY_ADDRESS=]
+
+--core-contract-address <CORE_CONTRACT_ADDRESS>
+    [env: CORE_CONTRACT_ADDRESS=]
+
+--fee-token-address <FEE_TOKEN_ADDRESS>
+    [env: FEE_TOKEN_ADDRESS=]
+    [default: 0x2e7442625bab778683501c0eadbc1ea17b3535da040a12ac7d281066e915eea]
+
+--chain-id <CHAIN_ID>
+    [env: CHAIN_ID=]
+```
+
+Example:
+
+```bash
+cargo run core-contract setup-program \
+  --core-contract-address 0x9da87cf1e8ceccb46e7d044541b51bc7f369c262f332e49152e74b30659b53 \
+  --chain-id example-chain
+```
+
+Example output:
+
+```
+[INFO  saya::core_contract::cli] Starknet OS config hash: 0x1676f3cc88a3ac2bf40e1a6780b73c46ccd5769e0e141ffc5491981a131e5d5
+[INFO  saya::core_contract::cli] Set program info transaction submitted: Hash(0x4a7dbe9d4c8613518acde5d66b69f7daa29efe756c20182b01b83856aed0cda)
+[INFO  saya::core_contract::cli] Fact registry set transaction submitted: Hash(0x27c24c82c0f1b7ac71cba02d4cbf1aa0136094d2bd9f9396b1f3f78afecc167)
+```
+
+---
+
+## Initialize Katana
+
+`katana init` generates:
+
+* a configuration file,
+* a genesis block.
+
+Example:
+
+```bash
+katana init \
+  --settlement-chain sepolia \
+  --id example-chain \
+  --settlement-contract 0x9da87cf1e8ceccb46e7d044541b51bc7f369c262f332e49152e74b30659b53 \
+  --settlement-contract-deployed-block 6180778 
+
+```
+
+Use `katana config` to list all the local configuration and `katana config <CHAIN_ID>` to display the configuration and the file path if you want to inspect it.
+
+1. Start Katana with `katana --chain <CHAIN_ID>` to load the generated parameters at start.
+
+> **_NOTE:_** You can define an `--output-path` when working with `katana init` to output the configuration files in the given directory. You will then want to start katana with the `--chain /path` instead of `--chain <CHAIN_ID>`.
+
+1. Block time: when running Katana in provable mode, the block time is important, since each block will be proven by Saya, and eventually settled or posted to a data availability layer (which in both cases is incurring an additional cost).
+
+   It is then recommended to run Katana with a block time. It is important to note that Katana is starting the block time for the very first transaction received for the block, and will never produce empty blocks.
 
    ```bash
-   katana --chain <CHAIN_ID> --block-time 30000 --sequencing.block-max-cairo-steps 16000000
+   # Example for Katana with a block time of 30 seconds.
+   katana --chain <CHAIN_ID> --block-time 30000
    ```
 
 ## Requirements
 
-- Katana up and running in provable mode.
-- Herodotus Dev account with API key, which can be obtained from https://herodotus.cloud.
+* Katana up and running in provable mode.
+* Herodotus Dev account with API key, which can be obtained from <https://herodotus.cloud>.
 
 ### Sovereign mode
 
-- Celestia node up and running that you can send blob to using a celestia token (only for sovereign mode at the moment). A script is available in `scripts/celestia.sh` to help with the setup.
-- An account to send the blobs (usually configured with the light node you are running).
+* Celestia node up and running that you can send blob to using a celestia token (only for sovereign mode at the moment). A script is available in `scripts/celestia.sh` to help with the setup.
+* An account to send the blobs (usually configured with the light node you are running).
 
 ### Persistent mode
 
-- Piltover settlement contract must be deployed on the settlement chain, see [piltover repository](https://github.com/keep-starknet-strange/piltover) or `katana init` can handle it too.
-- An account on the settlement chain with funds to verify the proof.
+* Piltover settlement contract must be deployed on the settlement chain, see [piltover repository](https://github.com/keep-starknet-strange/piltover) or `katana init` can handle it too.
+* An account on the settlement chain with funds to verify the proof.
 
 ## Cairo programs
 
-Saya currently requires the following Cairo programs to work. Use the scripts in the `scripts` folder to compile them.
+Saya currently requires the following Cairo program to work. Use the script in the `scripts` folder to compile it.
 
 ```bash
-./scripts/generate_snos.sh
-
 ./scripts/generate_layout_bridge.sh
 ```
 
 The scripts rely on docker to be installed and available, you may set `SUDO` variable based on your environment:
 
 ```bash
-SUDO=sudo ./scripts/generate_snos.sh
+SUDO=sudo ./scripts/generate_layout_bridge.sh
 ```
 
 > **_NOTE:_** The `starknet/cairo-lang` docker image is only available for `linux/amd64` architecture, emulation adds a significant overhead to build the `layout_bridge` program, which already requires a large amount of RAM (~32GB).
@@ -114,24 +264,27 @@ Before running Saya, you must first change the fact registry address for the pil
 > **_NOTE:_** `0x01eda48cc753670a9a00313afd08bac6e1606943d554ea4a6040cd2953d67867` is a deployed mock fact registry address on Sepolia that returns the expected fact confirmation for any fact.
 
 ```
-starkli invoke <PILTOVER_ADDRESS> set_facts_registry 0x01eda48cc753670a9a00313afd08bac6e1606943d554ea4a6040cd2953d67867
-```
+cargo run core-contract --settlement-chain-id sepolia setup-program   --core-contract-address <PILTOVER_ADDRESS>   --chain-id example-chain  --fact-registry-address 0x01eda48cc753670a9a00313afd08bac6e1606943d554ea4a6040cd2953d67867```
 
 Then you can run Saya with:
 
 ```
+
 saya persistent start \
-    --mock-layout-bridge-program-hash 0x193641eb151b0f41674641089952e60bc3aded26e3cf42793655c562b8c3aa0
+    --mock-layout-bridge-program-hash 0x43c5c4cc37c4614d2cf3a833379052c3a38cd18d688b617e2c720e8f941cb8
+
 ```
 
 By doing so, Saya will mock the layout bridge proof and call the `update_state` function of the settlement contract.
 
 In order to also mock the SNOS proof, you can use the following command:
 
 ```
+
 saya persistent start \
-    --mock-layout-bridge-program-hash 0x193641eb151b0f41674641089952e60bc3aded26e3cf42793655c562b8c3aa0 \
+    --mock-layout-bridge-program-hash 0x43c5c4cc37c4614d2cf3a833379052c3a38cd18d688b617e2c720e8f941cb8 \
     --mock-snos-from-pie
+
 ```
 
 This will generates the SNOS's PIE, and mock the proof from it.

bin/saya/Cargo.toml

@@ -14,7 +14,11 @@ anyhow.workspace = true
 clap.workspace = true
 env_logger.workspace = true
 starknet-types-core.workspace = true
-starknet.workspace = true
 tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal", "time"] }
 url.workspace = true
 log.workspace = true
+cairo-lang-starknet-classes = "2.12.3"
+starknet_api = "0.16.0-rc.1"
+serde_json.workspace = true
+dojo-utils = { git = "https://github.com/dojoengine/dojo", branch = "main" }
+starknet = { git = "https://github.com/dojoengine/starknet-rs", branch = "feat/types-rs-100-blake2s" }