Readme update

.gitignore

@@ -26,8 +26,7 @@ scripts/katana/katana.log
 *.pb
 
 vendor/
-.env.*
-
+.env
 .env.local
 .env.sepolia
 .env.mainnet

README.md

@@ -36,6 +36,43 @@ docker buildx version  # Should work after installing buildx
 
 You should see version numbers for both commands. If you get any errors, consult the [Docker troubleshooting guide](https://docs.docker.com/troubleshoot/).
 
+## Environment Configuration
+
+Before proceeding, you'll need to set up the appropriate environment files:
+
+1. For Docker-based setup (Quick Start):
+   - `.env`: Contains only the database address for building Rust crates
+   - `.env.docker`: Contains configuration for running the application
+   Example files are provided in `config/`:
+   ```bash
+   cp config/.env.example .env
+   cp config/.env.docker.example .env.docker
+   ```
+
+2. For Local Development (Minimal Setup):
+   - `.env.local`: Additional configuration for local development
+   ```bash
+   cp config/.env.local.example .env.local
+   ```
+
+> **Note:** Example configurations can be found in the `config/` directory.
+
+## Dependencies (Non-Docker Setup Only)
+
+The following dependencies are only required if you're NOT using Docker (i.e., for Minimal Setup).
+If you're using the Docker-based Quick Start, you can skip this section.
+
+1. Rust toolchain:
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+2. Risc0 zkVM toolchain:
+   ```bash
+   curl -L https://risczero.com/install | bash
+   rzup
+   ```
+
 ## Quick Start with Docker
 
 The easiest way to get started is using Docker. This method handles all dependencies and environment setup automatically.
@@ -45,6 +82,9 @@ The easiest way to get started is using Docker. This method handles all dependen
 - Docker
 - Docker Compose
 - Docker Buildx (for Linux users)
+- IPFS Node:
+  - Install [IPFS Desktop](https://github.com/ipfs/ipfs-desktop)
+  - Ensure the IPFS daemon is running before proceeding
 
 ### Building the Images
 
@@ -169,144 +209,99 @@ docker network rm fossil-network
 # Network will be automatically created when running docker-compose up
 ```
 
-## Advanced: Manual Setup with Local Tools
+## Minimal Setup for State Proof Testing
 
-If you need to run the components locally without Docker, follow these instructions.
+This section describes how to run a minimal subset of the application focused on MMR building and state proof verification.
 
-### Dependencies
+### Prerequisites
 
-Required toolchain components:
+1. IPFS Node:
+   - Install [IPFS Desktop](https://github.com/ipfs/ipfs-desktop)
+   - Make sure the IPFS daemon is running before proceeding
 
-1. Rust toolchain:
+2. Rust toolchain:
    ```bash
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```
 
-2. Risc0 zkVM toolchain:
+3. Risc0 zkVM toolchain:
    ```bash
    curl -L https://risczero.com/install | bash
    rzup
    ```
 
-3. Dojo framework:
-   ```bash
-   curl -L https://install.dojoengine.org | bash
-   dojoup 
-   ```
-
-4. Foundry development framework:
-   ```bash
-   curl -L https://foundry.paradigm.xyz | bash
-   foundryup
-   ```
+### 1. Build Network Images
 
-### Manual Setup Instructions
+First, build the essential network images:
 
-#### Terminal 1: Anvil Ethereum Devnet Configuration
-
-1. Load environment configuration:
-   ```bash
-   source .env
-   ```
-
-2. Initialize Anvil instance with mainnet fork:
-   ```bash
-   anvil --fork-url $ETH_RPC_URL --block-time 12
-   ```
-
-> **Technical Note:** Configure `${ETH_RPC_URL}` in `anvil.env` with an RPC endpoint (Infura/Alchemy) for mainnet state replication.
-
-#### Terminal 2: Katana Starknet Devnet Initialization
+```bash
+# Make the build script executable
+chmod +x scripts/build-network.sh
 
-1. Source environment variables:
-   ```bash
-   source .env
-   ```
+# Build network images (anvil, katana, deploy)
+./scripts/build-network.sh
+```
 
-2. Configure `anvil.messaging.json` with fork block parameters from Anvil initialization output.
+### 2. Start Network Services
 
-3. Initialize Katana with L1 messaging bridge:
-   ```bash
-   katana --messaging $ANVIL_CONFIG --disable-fee --disable-validate
-   ```
+Start the core infrastructure and wait for deployments to complete:
 
-#### Terminal 3: Contract Deployment Pipeline
+```bash
+# Start network services
+docker-compose up -d
 
-1. Initialize environment:
-   ```bash
-   source .env
-   ```
+# Monitor deployment progress
+docker-compose logs -f
+```
 
-2. Execute deployment pipeline:
-   ```bash
-   ./scripts/deploy.sh
-   ```
+Wait until you see messages indicating that all deployments are complete and environment files are updated.
 
-#### Terminal 4: MMR Builder Options
+### 3. Build MMR (Small Test Set)
 
-The MMR builder supports several options for controlling how the MMR is built:
+In a new terminal, build a small MMR with 2 batches of 4 blocks each:
 
 ```bash
-# Build MMR with default settings (from latest finalized block)
-cargo run --bin build_mmr --release
-
-# Build from a specific start block
-cargo run --bin build_mmr --release -- --start-block <BLOCK_NUMBER>
+cargo run --bin build_mmr -- -b 4 -n 2 -e .env.local
+```
 
-# Build from the latest onchain MMR block
-cargo run --bin build_mmr --release -- --from-latest
+Monitor the output logs. You'll see information about the blocks being processed. Note the block range being processed - you'll need these numbers for step 5. The output will look similar to:
 
-# Control batch size
-cargo run --bin build_mmr --release -- --batch-size <SIZE>
+```
+Starting MMR build... start_block=7494088 end_block=7494095
+```
 
-# Process specific number of batches
-cargo run --bin build_mmr --release -- --num-batches <COUNT>
+### 4. Start State Proof API
 
-# Skip proof verification
-cargo run --bin build_mmr --release -- --skip-proof
+In a new terminal, start the state proof API service:
 
-# Combine options (examples)
-cargo run --bin build_mmr --release -- --from-latest --num-batches 10
-cargo run --bin build_mmr --release -- --start-block 1000 --batch-size 512
+```bash
+cargo run --bin state-proof-api -- -b 4 -e .env.local
 ```
 
-Available options:
-- `--start-block, -s`: Start building from this block number
-- `--from-latest, -l`: Start building from the latest onchain MMR block
-- `--batch-size`: Number of blocks per batch (default: 1024)
-- `--num-batches, -n`: Number of batches to process
-- `--skip-proof, -p`: Skip proof verification
-- `--env-file, -e`: Path to environment file (default: .env)
+Wait for the service to start up and begin listening for requests.
 
-Note: `--from-latest` and `--start-block` cannot be used together.
+### 5. Test Fee Proof Fetching
 
-#### Terminal 4: Light Client Process
+In a new terminal, run the fee proof fetcher using the block range from step 3:
 
-Execute client binary:
 ```bash
-cargo run --bin client --release
+cargo run --bin fetch-fees-proof -- --from-block <start_block> --to-block <end_block>
 ```
 
-The client supports the following options:
-
+For example, using the blocks from our example output:
 ```bash
-# Run with default settings (5 second polling interval)
-cargo run --bin client --release
+cargo run --bin fetch-fees-proof -- --from-block 7494088 --to-block 7494095
+```
 
-# Run with custom polling interval (in seconds)
-cargo run --bin client --release -- --polling-interval 10
+> **Note:** The block range should match the blocks that were added to the MMR in step 3. You can find these numbers in the build_mmr output logs.
 
-# Use a specific environment file
-cargo run --bin client --release -- --env-file .env.local
-```
+## Block Range Selection for Fee State Proofs
 
-Available options:
-- `--polling-interval`: Time between polls in seconds (default: 5)
-- `--env-file, -e`: Path to environment file (default: .env)
+When requesting state proofs for fees, you can specify any block range within the available processed blocks. The system processes blocks in batches, but proofs can be requested for any valid range within those batches.
 
-#### Terminal 5: Block Hash Relayer Process
+For example, if blocks 7494088-7494095 have been processed:
+- You can request proofs for block range 7494090-7494093
+- Or 7494088-7494095 (full range)
+- Or any other valid subset within these bounds
 
-Execute relayer process:
-```bash
-./scripts/run_relayer.sh
-```
+Note: While the MMR internally processes batches from higher to lower block numbers (e.g., batch 1: 7494092-7494095, batch 2: 7494088-7494091), this is an implementation detail. Your proof requests can span across these internal batch boundaries.

config/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=XXX

config/.env.local.example

@@ -0,0 +1,31 @@
+ETH_RPC_URL=http://localhost:8545
+FORK_URL=http://209.127.228.66:8545
+
+BONSAI_API_KEY=XXX
+BONSAI_API_URL=https://api.bonsai.xyz/
+
+DATABASE_URL=XXX
+
+ETH_ACCOUNT_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
+ACCOUNT_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+
+SN_MESSAGING=0x0c77a52c35601106993B684E6b20D68FF0a89493
+L1_MESSAGE_SENDER=0x77F83238fa5FFD7E031C2D1195AC5d0a8D1B3df5
+
+export FOUNDRY_EVM_VERSION=cancun
+
+ANVIL_CONFIG=config/anvil.messaging.json
+STARKNET_RPC_URL=http://localhost:5050
+STARKNET_PRIVATE_KEY=0xc5b2fcab997346f3ea1c00b002ecf6f382c5f9c9659a3894eb783c5320f912
+STARKNET_ACCOUNT_ADDRESS=0x127fd5f1fe78a71f8bcd1fec63e3fe2f0486b6ecd5c86a0466c3a21fa5cfcec
+
+L2_MSG_PROXY=0x01c0692f888adfb3dea3d4b4446afbfcd3a2456a64b113084af3549e8d6915e8
+FOSSIL_STORE=0x02d4eac88f8e9bbb0fd4ff2c35d385710bf3f8a6e4061266ac4de628dac11dd5
+
+STARKNET_VERIFIER=0x03848e3432559e5804d48e1a60faa59c9ab00f515bcf122e3865193277eb118a
+FOSSIL_VERIFIER=0x029d9eba080e8e7a6eed79f432b8d0cbe1e7ffe4187eda3cf2819cde8d700ff2
+
+STARKNET_ACCOUNT=katana-0
+
+DEPLOYMENT_VERSION=local
+CHAIN_ID=11155111

config/anvil.messaging.docker.json

@@ -1,9 +1,9 @@
 {
   "chain": "ethereum",
   "rpc_url": "http://anvil:8545",
-  "contract_address": "0x49Cf40BEe86Ab8bD080eE7918eD1d2D26DCF4c8b",
+  "contract_address": "0x35aD67435d437D781e210f3aC5bfC9818B034907",
   "sender_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
   "private_key": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
   "interval": 2,
-  "from_block": 7484849
+  "from_block": 7494164
 }

contracts/starknet/Scarb.lock

@@ -24,15 +24,15 @@ dependencies = [
 
 [[package]]
 name = "snforge_scarb_plugin"
-version = "0.34.0"
+version = "0.35.1"
 source = "registry+https://scarbs.xyz/"
-checksum = "sha256:56f2b06ff2f0d8bbdfb7fb6c211fba7e4da6e5334ea70ba849af329a739faf11"
+checksum = "sha256:1b6d50abc7f306a06abf90649bcd60a3bc1cdf6d0dc21a9725c71b014a334bab"
 
 [[package]]
 name = "snforge_std"
-version = "0.34.0"
+version = "0.35.1"
 source = "registry+https://scarbs.xyz/"
-checksum = "sha256:bd20964bde07e6fd0f7adb50d41216f05d66abd422ed82241030369333385876"
+checksum = "sha256:e25cbeb9cbed6da8e14ab19ad0e7c1d888055dfee62978a845ce669cfaba5d93"
 dependencies = [
  "snforge_scarb_plugin",
 ]

contracts/starknet/Scarb.toml

@@ -4,7 +4,7 @@ members = ["l1_message_proxy", "store", "verifier"]
 [workspace.dependencies]
 starknet = "2.9.1"
 assert_macros = "2.9.1"
-snforge_std = "0.34.0"
+snforge_std = "0.35.1"
 cairo_test = "2.9.1"
 
 [dev-dependencies]

scripts/build-network.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+set -e
+
+# Parse command line arguments
+VERBOSE=""
+if [[ " $* " =~ " --verbose " ]] || [[ " $* " =~ " -v " ]]; then
+    VERBOSE="--progress=plain"
+fi
+
+# Define colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Ensure we're using buildx
+docker buildx create --use --name fossil-builder || true
+
+echo -e "${BLUE}Building network Docker images...${NC}"
+
+# Build network images
+echo -e "${BLUE}Building anvil image...${NC}"
+docker buildx build --load -f docker/Dockerfile.anvil -t anvil:latest . $VERBOSE
+
+echo -e "${BLUE}Building katana image...${NC}"
+docker buildx build --load -f docker/Dockerfile.katana -t fossil-katana:latest . $VERBOSE
+
+echo -e "${BLUE}Building deploy image...${NC}"
+docker buildx build --load -f docker/Dockerfile.deploy -t fossil-deploy:latest . $VERBOSE
+
+# Clean up the builder
+echo -e "${BLUE}Cleaning up builder...${NC}"
+docker buildx rm fossil-builder
+
+echo -e "${GREEN}Network images built successfully!${NC}"