chore: merge

.dockerignore

@@ -0,0 +1,4 @@
+.tmp
+build
+/target
+*.bin

.github/workflows/lint.yml

@@ -17,11 +17,6 @@ jobs:
           version: v1.61.0
           args: --timeout 10m
           github-token: ${{ secrets.github_token }}
-  # hadolint lints the Dockerfile
-  hadolint:
-    uses: celestiaorg/.github/.github/workflows/[email protected]
-    with:
-      dockerfile: "docker/Dockerfile"
 
   yamllint:
     runs-on: ubuntu-latest

Makefile

@@ -6,7 +6,8 @@ IMAGE := ghcr.io/tendermint/docker-build-proto:latest
 DOCKER_PROTO_BUILDER := docker run -v $(shell pwd):/workspace --workdir /workspace $(IMAGE)
 PROJECT_NAME=$(shell basename "$(PWD)")
 HTTPS_GIT := https://github.com/celestiaorg/celestia-zkevm-ibc-demo
-GHCR_REPO := ghcr.io/celestiaorg/simapp
+SIMAPP_GHCR_REPO := ghcr.io/celestiaorg/celestia-zkevm-ibc-demo/simapp
+CELESTIA_PROVER_GHCR_REPO := ghcr.io/celestiaorg/celestia-zkevm-ibc-demo/celestia-prover
 
 # process linker flags
 ldflags = -X github.com/cosmos/cosmos-sdk/version.Name=celestia-zkevm-ibc-demo \
@@ -29,6 +30,48 @@ install-dependencies:
 	@go run ./testing/demo/pkg/setup-env
 .PHONY: install-dependencies
 
+## check-dependencies: Check if all dependencies are installed.
+check-dependencies:
+	@echo "--> Checking if all dependencies are installed"
+	@if command -v cargo >/dev/null 2>&1; then \
+		echo "cargo is installed."; \
+	else \
+		echo "Error: cargo is not installed. Please install Rust."; \
+		exit 1; \
+	fi
+	@if command -v forge >/dev/null 2>&1; then \
+		echo "foundry is installed."; \
+	else \
+		echo "Error: forge is not installed. Please install Foundry."; \
+		exit 1; \
+	fi
+	@if command -v bun >/dev/null 2>&1; then \
+		echo "bun is installed."; \
+	else \
+		echo "Error: bun is not installed. Please install bun."; \
+		exit 1; \
+	fi
+	@if command -v just >/dev/null 2>&1; then \
+		echo "just is installed."; \
+	else \
+		echo "Error: just is not installed. Please install just."; \
+		exit 1; \
+	fi
+	@if command -v cargo prove >/dev/null 2>&1; then \
+		echo "cargo prove is installed."; \
+	else \
+		echo "Error: succinct is not installed. Please install SP1."; \
+		exit 1; \
+	fi
+	@if command -v operator >/dev/null 2>&1; then \
+		echo "operator is installed."; \
+	else \
+		echo "Error: operator is not installed. Please run install-dependencies."; \
+		exit 1; \
+	fi
+	@echo "All dependencies are installed."
+.PHONY: check-dependencies
+
 ## start: Start all processes needed for the demo.
 start: stop
 	@docker compose up -d
@@ -38,21 +81,22 @@ start: stop
 setup:
 	@echo "--> Deploying tendermint light client contract on the EVM roll-up"
 	@cd ./solidity-ibc-eureka/scripts && just deploy-sp1-ics07
-	@echo "--> Setting up IBC Clients and Channels"
+	@echo "--> Creating IBC light clients and channel"
 	@go run ./testing/demo/pkg/setup/
 .PHONY: setup
 
-## transfer: Transfer tokens from simapp network to the EVM rollup.
+## transfer: Transfer tokens from simapp to the EVM roll-up.
 transfer:
-	@echo "--> Transferring tokens"
+	@echo "--> Transferring tokens from simapp to the EVM roll-up"
+	@go run ./testing/demo/pkg/transfer/
 .PHONY: transfer
 
-## stop: Stop all processes and removes the tmp directory.
+## stop: Stop all processes and remove the tmp directory.
 stop:
 	@echo "--> Stopping all processes"
 	@docker compose down
 	@docker compose rm
-	@echo "--> Clearing tmp directory"
+	@echo "--> Removing the tmp directory"
 	@rm -rf .tmp
 .PHONY: stop
 
@@ -63,6 +107,10 @@ build-simapp: mod
 	@go build $(BUILD_FLAGS) -o build/ ./simapp/simd/
 .PHONY: build-simapp
 
+## build: Build the simapp binary.
+build: build-simapp
+.PHONY: build
+
 ## install-simapp: Build and install the simapp binary into the $GOPATH/bin directory.
 install-simapp:
 	@echo "--> Installing simd"
@@ -106,24 +154,38 @@ proto-format:
 .PHONY: proto-format
 
 ## build-simapp-docker: Build the simapp docker image from the current branch. Requires docker.
-build-simapp-docker:
+build-simapp-docker: build-simapp
 	@echo "--> Building Docker image"
-	$(DOCKER) build -t $(GHCR_REPO) -f docker/Dockerfile .
+	$(DOCKER) build -t $(SIMAPP_GHCR_REPO) -f docker/simapp.Dockerfile .
 .PHONY: build-simapp-docker
 
+## docker: Build the simapp Docker image.
+docker: build-simapp-docker
+.PHONY: docker
+
 ## publish-simapp-docker: Publish the simapp docker image to GHCR. Requires Docker and authentication.
 publish-simapp-docker:
-	$(DOCKER) push $(GHCR_REPO)
+	$(DOCKER) push $(SIMAPP_GHCR_REPO)
 .PHONY: publish-simapp-docker
 
+## build-celestia-prover-docker: Build the celestia prover docker image from the current branch. Requires docker.
+build-celestia-prover-docker:
+	$(DOCKER) build -t $(CELESTIA_PROVER_GHCR_REPO) -f docker/celestia_prover.Dockerfile .
+.PHONY: build-celestia-prover-docker
+
+## publish-celestia-prover-docker: Publish the celestia prover docker image from the current branch. Requires docker.
+publish-celestia-prover-docker:
+	$(DOCKER) push $(CELESTIA_PROVER_GHCR_REPO)
+.PHONY: publish-celestia-prover-docker
+
 ## lint: Run all linters; golangci-lint, markdownlint, hadolint, yamllint.
 lint:
 	@echo "--> Running golangci-lint"
 	@golangci-lint run
 	@echo "--> Running markdownlint"
 	@markdownlint --config .markdownlint.yaml '**/*.md'
 	@echo "--> Running hadolint"
-	@hadolint docker/Dockerfile
+	@hadolint docker/**
 	@echo "--> Running yamllint"
 	@yamllint --no-warnings . -c .yamllint.yml
 .PHONY: lint
@@ -154,3 +216,10 @@ run-simapp:
 # Warning this will remove all data in simapp home directory
 	./scripts/init-simapp.sh
 .PHONY: run-simapp
+
+## demo: Run the entire demo.
+demo:
+	@make start
+	@make setup
+	@make transfer
+.PHONY: demo

README.md

@@ -5,11 +5,11 @@
 
 This repo exists to showcase transferring tokens to and from a Cosmos SDK chain (representing Celestia) and a ZK proveable EVM using the [IBC-Eureka solidity contracts](https://github.com/cosmos/solidity-ibc-eureka/blob/main/README.md). The diagram below is meant to detail the components involved and, at a high level, how they interact with one another.
 
-![mvp-zk-accounts](./mvp-zk-accounts.png)
+![mvp-zk-accounts](./docs/images/mvp-zk-accounts.png)
 
 For more information refer to the [architecture document](./ARCHITECTURE.md). Note that the design is subject to change.
 
-## Local Development
+## Usage
 
 ### Prerequisites
 
@@ -18,7 +18,7 @@ For more information refer to the [architecture document](./ARCHITECTURE.md). No
 1. Install [Foundry](https://book.getfoundry.sh/getting-started/installation)
 1. Install [Bun](https://bun.sh/)
 1. Install [Just](https://just.systems/man/en/)
-1. Install [SP1](https://docs.succinct.xyz/docs/getting-started/install) (for end-to-end tests)
+1. Install [SP1](https://docs.succinct.xyz/docs/getting-started/install)
 
 ### Steps
 
@@ -45,34 +45,64 @@ For more information refer to the [architecture document](./ARCHITECTURE.md). No
 1. Set up IBC clients and channels:
 
     - Generate the `contracts/script/genesis.json` file which contains the initialization parameters for the `SP1ICS07Tendermint` light client contract.
-    - Initialize Groth16 light client on simapp.
-    - Create a channel on simapp.
+    - Initialize Groth16 light client on SimApp.
+    - Create a channel on SimApp.
     - Deploy IBC contracts on the Reth node.
     - Create a channel on the Reth node.
-    - Create a counterparty on the Reth node which points to the groth16 client ID on simapp.
-    - Create a counterparty on the simapp which points to the tendermint client ID on Reth.
+    - Create a counterparty on the Reth node which points to the groth16 client ID on SimApp.
+    - Create a counterparty on the SimApp which points to the tendermint client ID on Reth.
 
     ```shell
     make setup
     ```
 
-### Helpful commands
+1. Transfer tokens from SimApp to the EVM roll-up.
 
-```shell
-# See the running containers
-docker ps
+    ```shell
+    make transfer
+    ```
 
-# You can view the logs from a running container via Docker UI or:
-docker logs beacond
-docker logs celestia-network-bridge
-docker logs celestia-network-validator
-docker logs simapp-validator
-docker logs reth
+1. To stop and teardown the test environment (when you're finished)
 
-# State is persisted in the .tmp directory. Remove .tmp to start fresh:
-rm -rf .tmp
-```
+    ```shell
+    make stop
+    ```
+
+## A Breakdown of an IBC Transfer
+
+This section takes the diagram from above and breaks down each step during `make transfer` to help aid your understanding.
+
+![mvp-zk-accounts](./docs/images/mvp-zk-accounts-step-1.png)
+
+1a -> The user submits a transfer message. This is a `ICS20LibFungibleTokenPacketData` wrapped in a `SendPacket` message. As well as who it's sending the tokens to and how much it also specifies where this packet is going to and lets the eventual receiver know where the packet came from.
+
+1b -> The SimApp chain (mimicking Celestia) executes the transaction, checking the user's balance and then moving the funds to a locked acount. It stores a commitment to this execution in state. This is kind of like a verifiable receipt.
+
+![mvp-zk-accounts](./docs/images/mvp-zk-accounts-step-2.png)
+
+2a -> Now the relayer kicks in. It listens to events that SimApp has emitted that there are pending packets ready to be sent to other chains. It queries the chain for the receipt based on a predetermined location.
+
+2b -> The relayer needs to prove to the EVM rollup that SimApp has actually successfully executed the first part of the transfer: locking up the tokens. Proving this requires two steps: First the relayer queries a state transition proof from the prover process. This will prove the latest state root from the last trusted state root stored in the state of the ICS07 Tendermint smart contract on the EVM. Now the EVM has an up to date record of SimApp's current state (which includes the receipt). Second, the relayer asks the prover for a proof that the receipt is a merkle leaf of the state root i.e. it's part of state
+
+2c -> The prover has a zk circuit for generating both proofs. One takes tendermint headers and uses the `SkippingVerification` algorithm to assert the latest header. The other takes IAVL merkle proofs and proves some leaf key as part of the root. These are both STARK proofs which can be processed by the smart contracts on the EVM.
 
+2d -> The last step of the relayer is to combine these proofs and packets and submit a `MsgUpdateClient` and `MsgRecvPacket` to the EVM rollup.
+
+![mvp-zk-accounts](./docs/images/mvp-zk-accounts-step-3.png)
+
+Step 3 mirrors step 2 in many ways but now in the opposite direction
+
+3a -> The EVM executes both messages. It verifies the STARK proofs and updates it's local record of SimApp's state. It then uses the updated state to verify that the receipt that the packet refers is indeed present in SimApp's state. Once all the verification checks are passed. It mints the tokens and adds them to the account of the recipient as specified in the packet. The rollup then writes it's own respective receipt that it processed the corresponding message.
+
+3b -> Similarly, the relayer listens for events emitted from the EVM rollup for any packets awaiting to be sent back. Upon receiving the packet to be returned, an acknowledgement of the transfer to be sent back to SimApp, it talks to the prover service to prepare the relevant proofs. While they are of different state machines and different state trees, the requests are universal: a proof of the state transition and a proof of membership. The EVM Prover Service here futher compresses the STARK proofs into groth16 proofs for SimApp's groth16 IBC Client.
+
+3c -> The relayer then sends a `MsgUpdateClient` with the state transition proof to update SimApp's record of the Rollup's state after the point that it processed the transfer packet and wrote the receipt. The relayer also sends a `MsgAcknowledgement` which contains the membership proof of the commitment, a.k.a. the receipt alongside the details of the receipt i.e. for what transfer message are we acknowledging.
+
+3d -> SimApp processes these two messages. It validates the proofs and if everything is in order, it removes the transfer receipt and keeps one final receipt of the acknowledgement (to prevent a later timeout message).
+
+In the case that the EVM decided these messages were not valid it would not write the acknowledgement receipt. The relayer, tracking the time when the transfer message was sent would submit a `MsgTimeout` instead of the acknowledgement with an absence proof. This is a proof that no acknowledgement was written where the predermined path says it should be written. When SimApp receives this timeout and the corresponding absence proof, it reverses the transfer, releaseing the locked funds and returning them to the sender. This process is atomic - funds can not be unlocked if they are minted on the other chain.
+
+If someone were to send tokens from the EVM rollup back to SimApp, the source chain of those tokens, the process would be very similar, however the actions wouldn't be to lock and mint but rather the EVM rollup would burn tokens and SimApp would unlock them.
 
 ## Contributing
 
@@ -82,5 +112,19 @@ This repo uses protobuf to define the interfaces between several services. To he
 repo relies on [buf](https://buf.build). If you modify the protos you can regenerate them using:
 
 ```
-buf generate
-```
+make proto-gen
+```
+
+### Helpful commands
+
+```shell
+# See the running containers
+docker ps
+
+# You can view the logs from a running container via Docker UI or:
+docker logs beacond
+docker logs celestia-network-bridge
+docker logs celestia-network-validator
+docker logs simapp-validator
+docker logs reth
+```

docker-compose.yml

@@ -2,9 +2,6 @@ services:
   beacond:
     image: ghcr.io/rollkit/beacon-kit:v0.1.3
     container_name: beacond
-    # environment:
-    #   - TESTAPP_FILES_DIR=/beacon-kit/testing/files  # Add the actual path
-    #   - JWT_SECRET_PATH=${TESTAPP_FILES_DIR}/jwt.hex
     volumes:
       - ./testing/files:/beacon-kit/testing/files
       - ./.tmp:/beacon-kit/.tmp
@@ -90,7 +87,7 @@ services:
       - beacon-network
 
   simapp-validator:
-    image: ghcr.io/celestiaorg/simapp:latest
+    image: ghcr.io/celestiaorg/celestia-zkevm-ibc-demo/simapp:latest
     container_name: simapp-validator
     volumes:
       - ./.tmp/simapp-validator:/home/celestia
@@ -102,6 +99,18 @@ services:
     networks:
       - beacon-network
 
+  celestia-prover:
+    image: ghcr.io/celestiaorg/celestia-zkevm-ibc-demo/celestia-prover:latest
+    container_name: celestia-prover
+    environment:
+      - TENDERMINT_RPC_URL=http://celestia-network-validator:26657
+      - RPC_URL=http://reth:8545
+    ports:
+      - "50051:50051"
+    depends_on:
+      beacond:
+        condition: service_started
+
 networks:
   beacon-network:
     driver: bridge