added provable eth call; updated readme;

.gitignore

@@ -43,4 +43,8 @@ dist/
 
 # State server db folder
 crates/state_server/db
-db
+db
+
+# dry-run and sound-run outputs
+dry_run_output.json
+proofs.json

README.md

@@ -163,6 +163,25 @@ Tests also require chain node RPC calls, so make sure your `.env` file is set up
 
 ## Note on On-Chain Finality
 
-Even if all local stages (dry run, proof fetching, sound run) succeed, on-chain settlement depends on the **MMR (Merkle Mountain Range)**. The data for all accessed values must be present in the MMR core module used for settlement.
+Even if all local stages (dry run, proof fetching, sound run) succeed, on-chain settlement depends on the **MMRs (Merkle Mountain Ranges)**. The data for all accessed values must be present in the MMRs inside [Herodotus Satellite contracts](https://github.com/HerodotusDev/satellite) used for settlement.
 
-This means the blocks you are accessing must have been included in the settlement contract's MMR. This is a critical consideration, especially when mixing testnet and mainnet data or for cross-chain access within the same HDP module. If you encounter issues during on-chain settlement, verify that the relevant block numbers have been included in the on-chain MMR.
+This means the blocks you are accessing must have been included in the settlement contract's MMRs. This is a critical consideration, especially when mixing testnet and mainnet data or for cross-chain access within the same HDP module. If you encounter issues during on-chain settlement, verify that the relevant block numbers have been included in the on-chain MMRs.
+
+---
+
+## Mentions
+
+Provable ETH call (located in [hdp_cairo/src/eth_call](./hdp_cairo/src/eth_call/)) makes use of code adapted from [**Kakarot**](https://github.com/kkrt-labs) [(@kkrt-labs/kakarot-ssj)](https://github.com/kkrt-labs/kakarot-ssj) under the [MIT License](https://github.com/kkrt-labs/kakarot-ssj/blob/main/LICENSE).
+
+Thanks for all the hard work guys 🙏
+
+> Original project: https://github.com/kkrt-labs/kakarot-ssj  
+> License file: https://github.com/kkrt-labs/kakarot-ssj/blob/main/LICENSE
+
+---
+
+## License
+
+`hdp-cairo` is licensed under the [Apache-2.0 license](./LICENSE).
+
+---

Scarb.lock

@@ -48,6 +48,11 @@ dependencies = [
  "alexandria_data_structures",
 ]
 
+[[package]]
+name = "corelib_imports"
+version = "0.1.2"
+source = "git+https://github.com/keep-starknet-strange/garaga.git#42643fa19e9618fd880d4fa6bfbc543da6c6abbe"
+
 [[package]]
 name = "example_all_features_combined"
 version = "0.1.0"
@@ -71,6 +76,13 @@ dependencies = [
  "hdp_cairo",
 ]
 
+[[package]]
+name = "example_eth_call"
+version = "0.1.0"
+dependencies = [
+ "hdp_cairo",
+]
+
 [[package]]
 name = "example_injected_state"
 version = "0.1.0"
@@ -102,12 +114,21 @@ dependencies = [
  "hdp_cairo",
 ]
 
+[[package]]
+name = "garaga"
+version = "0.18.2"
+source = "git+https://github.com/keep-starknet-strange/garaga.git#42643fa19e9618fd880d4fa6bfbc543da6c6abbe"
+dependencies = [
+ "corelib_imports",
+]
+
 [[package]]
 name = "hdp_cairo"
 version = "0.1.0"
 dependencies = [
  "alexandria_bytes",
  "alexandria_encoding",
+ "garaga",
 ]
 
 [[package]]

Scarb.toml

@@ -10,6 +10,7 @@ members = [
     "examples/multi_chain_access",
     "examples/most_bridge",
     "examples/all_features_combined",
+    "examples/eth_call",
     "hdp_cairo",
     "tests",
 ]
@@ -20,6 +21,7 @@ alexandria_encoding = { git = "https://github.com/keep-starknet-strange/alexandr
 cairo_test = "2.10.0"
 hdp_cairo = { path = "hdp_cairo" }
 starknet = "2.10.0"
+garaga = { git = "https://github.com/keep-starknet-strange/garaga.git" }
 
 [workspace.tool.fmt]
-sort-module-level-items = true
+sort-module-level-items = true

examples/eth_call/Scarb.toml

@@ -0,0 +1,19 @@
+[package]
+name = "example_eth_call"
+version = "0.1.0"
+edition = "2023_11"
+
+# See more keys and their definitions at https://docs.swmansion.com/scarb/docs/reference/manifest.html
+
+[dependencies]
+starknet = { workspace = true }
+hdp_cairo = { workspace = true }
+
+[[target.starknet-contract]]
+sierra = true
+casm = true
+casm-add-pythonic-hints = true
+allowed-libfuncs = false
+
+[scripts]
+test = "snforge test"

examples/eth_call/run.sh

@@ -0,0 +1,5 @@
+scarb build -p example_eth_call &&\
+hdp dry-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output &&\
+hdp fetch-proofs &&\
+hdp sound-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output --proof_mode &&\
+hdp sound-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output

examples/eth_call/src/lib.cairo

@@ -0,0 +1,48 @@
+#[starknet::contract]
+mod module {
+    use hdp_cairo::HDP;
+    use hdp_cairo::eth_call::hdp_backend::TimeAndSpace;
+    use hdp_cairo::eth_call::utils::helpers::load_word;
+
+    #[storage]
+    struct Storage {}
+
+    #[external(v0)]
+    pub fn main(ref self: ContractState, hdp: HDP) -> u256 {
+        // A long time ago in a galaxy far, far away....
+        let time_and_space = TimeAndSpace { chain_id: 1, block_number: 21370000 };
+        // Sender - vitalik.eth on Ethereum:
+        let vitalik_eth_address = 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.try_into().unwrap();
+        // Target - USDC on Ethereum:
+        let usdc_contract_address = 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.try_into().unwrap();
+        // Getting the calldata for the balanceOf function:
+        // cast calldata "balanceOf(address)" 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+        // Result: 0x70a08231000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045
+        let calldata = [
+            0x70, 0xa0, 0x82, 0x31, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+            0x00, 0x00, 0xd8, 0xda, 0x6b, 0xf2, 0x69, 0x64, 0xaf, 0x9d, 0x7e, 0xed, 0x9e, 0x03,
+            0xe5, 0x34, 0x15, 0xd3, 0x7a, 0xa9, 0x60, 0x45,
+        ]
+            .span();
+
+        // Executing the call:
+        let result = hdp_cairo::execute_eth_call(
+            @hdp, @time_and_space, vitalik_eth_address, usdc_contract_address, calldata,
+        );
+
+        // result.return_data is a Span<u8>, so we need to convert it to a u256:
+        let return_data_len = result.return_data.len();
+        let vitaliks_balance: u256 = load_word(return_data_len, result.return_data);
+
+        println!("Result success: {:?}", result.success);
+        println!("Result gas_used: {:?}", result.gas_used);
+        println!("Result return_data: {:?}", result.return_data);
+        println!("Vitalik's USDC balance: {:?}", vitaliks_balance);
+
+        // If you want you can also read decimals() function from the USDC contract,
+        // and divide the balance by 10^decimals to get the actual balance.
+        // Just make another call and use the result!
+
+        return vitaliks_balance;
+    }
+}

hdp_cairo/Scarb.toml

@@ -9,6 +9,7 @@ edition = "2023_11"
 alexandria_bytes = { workspace = true }
 alexandria_encoding = { workspace = true }
 starknet = { workspace = true }
+garaga = { workspace = true }
 
 [dev-dependencies]
 cairo_test = { workspace = true }