Phase 1 completion

.github/workflows/rust.yml

@@ -0,0 +1,22 @@
+name: Rust
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build
+      run: cargo build --verbose
+    - name: Run tests
+      run: cargo test --verbose

.gitignore

@@ -0,0 +1,28 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+tmp/
+test-ledger/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+/.idea/.gitignore
+/.idea/modules.xml
+/.idea/trollup.iml
+/.idea/vcs.xml

Cargo.toml

@@ -0,0 +1,6 @@
+[workspace]
+resolver = "2"
+
+members = ["state", "state_commitment", "execution", "example", "state_management", "zk", "api", "validator"]
+
+exclude = ["trollup-initialize-programs"]

Dockerfile-api

@@ -0,0 +1,95 @@
+# syntax=docker/dockerfile:1
+
+# Comments are provided throughout this file to help you get started.
+# If you need more help, visit the Dockerfile reference guide at
+# https://docs.docker.com/engine/reference/builder/
+
+################################################################################
+# Create a stage for building the application.
+
+ARG RUST_VERSION=1.77.2
+ARG APP_NAME=trollup-api
+FROM debian:trixie-slim AS build
+ARG APP_NAME
+WORKDIR /app
+
+RUN apt update && apt install -y pkg-config && apt install -y libssl-dev && apt install -y openssl && apt install -y ca-certificates && apt install -y protobuf-compiler
+
+# Install Rust and other necessary tools
+RUN apt-get update && apt-get install -y \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Rust
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Build the application.
+# Leverage a cache mount to /usr/local/cargo/registry/
+# for downloaded dependencies and a cache mount to /app/target/ for
+# compiled dependencies which will speed up subsequent builds.
+# Leverage a bind mount to the src directory to avoid having to copy the
+# source code into the container. Once built, copy the executable to an
+# output directory before the cache mounted /app/target is unmounted.
+RUN --mount=type=bind,source=api,target=api \
+    --mount=type=bind,source=validator,target=validator \
+    --mount=type=bind,source=execution,target=execution \
+    --mount=type=bind,source=state,target=state \
+    --mount=type=bind,source=state_commitment,target=state_commitment \
+    --mount=type=bind,source=state_management,target=state_management \
+    --mount=type=bind,source=zk,target=zk \
+    --mount=type=bind,source=example,target=example \
+    --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
+    --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
+    --mount=type=bind,source=api/config/docker,target=config/ \
+    --mount=type=cache,target=/app/target/ \
+    --mount=type=cache,target=/usr/local/cargo/registry/ \
+    <<EOF
+set -e
+cargo build --release
+cp -r ./config /config
+cp ./target/release/$APP_NAME /bin/server
+EOF
+
+################################################################################
+# Create a new stage for running the application that contains the minimal
+# runtime dependencies for the application. This often uses a different base
+# image from the build stage where the necessary files are copied from the build
+# stage.
+#
+# The example below uses the debian bullseye image as the foundation for running the app.
+# By specifying the "bullseye-slim" tag, it will also use whatever happens to be the
+# most recent version of that tag when you build your Dockerfile. If
+# reproducability is important, consider using a digest
+# (e.g., debian@sha256:ac707220fbd7b67fc19b112cee8170b41a9e97f703f588b2cdbbcdcecdd8af57).
+FROM debian:trixie-slim AS final
+
+# Install necessary runtime dependencies
+RUN apt update && apt install -y pkg-config && apt install -y libssl-dev && apt install -y openssl && apt install -y ca-certificates && apt install -y protobuf-compiler && apt install -y libssl3
+
+
+# Create a non-privileged user that the app will run under.
+# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
+RUN useradd -ms /bin/bash appusuer
+
+#ARG UID=10001
+#RUN adduser \
+#    --disabled-password \
+#    --gecos "" \
+#    --home "/nonexistent" \
+#    --shell "/sbin/nologin" \
+#    --no-create-home \
+#    --uid "${UID}" \
+#    appuser
+#USER appuser
+
+ENV TROLLUP_API_PATH=/config/trollup-api-config.json
+
+# Copy the executable from the "build" stage.
+COPY --from=build /bin/server /bin/
+# Copy over blank configurations files for mounting or editing in place
+COPY --from=build /config /config/
+
+# What the container should run when it is started.
+CMD ["/bin/server"]

Dockerfile-validator

@@ -0,0 +1,95 @@
+# syntax=docker/dockerfile:1
+
+# Comments are provided throughout this file to help you get started.
+# If you need more help, visit the Dockerfile reference guide at
+# https://docs.docker.com/engine/reference/builder/
+
+################################################################################
+# Create a stage for building the application.
+
+ARG RUST_VERSION=1.77.2
+ARG APP_NAME=trollup-validator
+FROM debian:trixie-slim AS build
+ARG APP_NAME
+WORKDIR /app
+
+RUN apt update && apt install -y pkg-config && apt install -y libssl-dev && apt install -y openssl && apt install -y ca-certificates && apt install -y protobuf-compiler
+
+# Install Rust and other necessary tools
+RUN apt-get update && apt-get install -y \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Rust
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Build the application.
+# Leverage a cache mount to /usr/local/cargo/registry/
+# for downloaded dependencies and a cache mount to /app/target/ for
+# compiled dependencies which will speed up subsequent builds.
+# Leverage a bind mount to the src directory to avoid having to copy the
+# source code into the container. Once built, copy the executable to an
+# output directory before the cache mounted /app/target is unmounted.
+RUN --mount=type=bind,source=api,target=api \
+    --mount=type=bind,source=validator,target=validator \
+    --mount=type=bind,source=execution,target=execution \
+    --mount=type=bind,source=state,target=state \
+    --mount=type=bind,source=state_commitment,target=state_commitment \
+    --mount=type=bind,source=state_management,target=state_management \
+    --mount=type=bind,source=zk,target=zk \
+    --mount=type=bind,source=example,target=example \
+    --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
+    --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
+    --mount=type=bind,source=api/config/docker,target=config/ \
+    --mount=type=cache,target=/app/target/ \
+    --mount=type=cache,target=/usr/local/cargo/registry/ \
+    <<EOF
+set -e
+cargo build --release
+cp -r ./config /config
+cp ./target/release/$APP_NAME /bin/server
+EOF
+
+################################################################################
+# Create a new stage for running the application that contains the minimal
+# runtime dependencies for the application. This often uses a different base
+# image from the build stage where the necessary files are copied from the build
+# stage.
+#
+# The example below uses the debian bullseye image as the foundation for running the app.
+# By specifying the "bullseye-slim" tag, it will also use whatever happens to be the
+# most recent version of that tag when you build your Dockerfile. If
+# reproducability is important, consider using a digest
+# (e.g., debian@sha256:ac707220fbd7b67fc19b112cee8170b41a9e97f703f588b2cdbbcdcecdd8af57).
+FROM debian:trixie-slim AS final
+
+# Install necessary runtime dependencies
+RUN apt update && apt install -y pkg-config && apt install -y libssl-dev && apt install -y openssl && apt install -y ca-certificates && apt install -y protobuf-compiler && apt install -y libssl3
+
+
+# Create a non-privileged user that the app will run under.
+# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
+RUN useradd -ms /bin/bash appusuer
+
+#ARG UID=10001
+#RUN adduser \
+#    --disabled-password \
+#    --gecos "" \
+#    --home "/nonexistent" \
+#    --shell "/sbin/nologin" \
+#    --no-create-home \
+#    --uid "${UID}" \
+#    appuser
+#USER appuser
+
+ENV TROLLUP_API_PATH=/config/trollup-api-config.json
+
+# Copy the executable from the "build" stage.
+COPY --from=build /bin/server /bin/
+# Copy over blank configurations files for mounting or editing in place
+COPY --from=build /config /config/
+
+# What the container should run when it is started.
+CMD ["/bin/server"]

README.md

@@ -0,0 +1,143 @@
+# Trollup - A Hybrid ZK-Optimistic Network Extension with Flexible Verification for Solana
+
+[![Rust](https://github.com/wkennedy/trollup/actions/workflows/rust.yml/badge.svg?branch=main)](https://github.com/wkennedy/trollup/actions/workflows/rust.yml)
+
+### **Overview:**
+
+The unique aspect of Trollup is its flexibility in handling transactions. It allows for quick finality through on-chain verification for optimistic transactions, while still maintaining the security of ZK proofs and the option for off-chain validation.
+This approach could potentially offer benefits such as:
+
+- Faster finality for certain transactions (the optimistic ones)
+- Reduced on-chain load by allowing off-chain validation
+- Strong security guarantees through ZK proofs
+- Flexibility in transaction processing to balance speed and security
+
+This approach aims at combining the strengths of different rollup types while mitigating their individual weaknesses.
+
+```mermaid
+flowchart TD
+    A[New Transaction] --> B{Optimistic?}
+    B -->|Yes| C[Mark as Optimistic]
+    B -->|No| D[Add to Regular Batch]
+    C --> E[Send to Solana Contract]
+    E --> F{Verified on-chain?}
+    F -->|Yes| G[Finalize account state]
+    F -->|No| H{Timeout?}
+    H -->|Yes| D
+    H -->|No| E
+    D --> I[Create ZK Proof for Batch]
+    I --> J[Send to Off-chain Validator]
+    J --> K{Proof Valid?}
+    K -->|Yes| L[Submit Commitment to Solana]
+    K -->|No| M[Reject Batch]
+    L --> N[Finalize account state]
+    G --> O[Transaction Completed]
+    N --> O
+    M --> P[Handle Rejected Transactions]
+```
+
+Optimistic Sequence
+
+```mermaid
+sequenceDiagram
+    participant User
+    box Trollup
+        participant Rollup as Trollup Execution Engine
+        participant Settlement as Trollup Settlement
+    end
+    participant Validator as Trollup Trusted Validator
+    participant MainChain as Main Chain (Solana)
+
+    User->>Rollup: Submit transaction
+    Rollup->>Rollup: Process transaction off-chain
+    Rollup->>Settlement: Batch transactions
+    Settlement->>Settlement: Compute state transition
+    Settlement->>Settlement: Generate proof
+    Settlement->>Settlement: Wait for on-chain verify or timeout
+    User->>MainChain: Submit proof package (proof + public inputs)
+    MainChain->>MainChain: Verify proof
+    alt Proof is valid
+        MainChain->>MainChain: Update state root
+        MainChain->>Settlement: Proof verification success
+        MainChain->>Settlement: Confirm settlement
+        Settlement->>Rollup: Update finalized state
+        Rollup->>User: Confirm transaction
+    else Proof is invalid
+        Settlement->>Settlement: Wait for timeout
+    end
+```
+
+Off-Chain Verification
+
+```mermaid
+sequenceDiagram
+    participant User
+    box Trollup
+        participant Rollup as Trollup Execution Engine
+        participant Settlement as Trollup Settlement
+    end
+    participant Validator as Trollup Trusted Validator
+    participant MainChain as Main Chain (Solana)
+
+    User->>Rollup: Submit transaction
+    Rollup->>Rollup: Process transaction off-chain
+    Rollup->>Settlement: Batch transactions
+    Settlement->>Settlement: Compute state transition
+    Settlement->>Settlement: Generate proof
+    Settlement->>Validator: Submit for validation
+    Validator->>Validator: Verify state transition
+    Validator->>Settlement: Return signed approval
+    Settlement->>MainChain: Submit new state root & signature
+    MainChain->>MainChain: Verify validator's signature
+    alt Signature is valid
+        MainChain->>MainChain: Update state root
+        MainChain->>Settlement: Confirm settlement
+        Settlement->>Rollup: Update finalized state
+        Rollup->>User: Confirm transaction
+    else Signature is invalid
+        MainChain->>Settlement: Reject update
+        Settlement->>Rollup: Report failure
+        Rollup->>User: Notify of failure
+    end
+```
+
+### **High level technical overview**
+
+- Proof: The proof is created using circuit creation provided by arkworks-rs. The proof is verified on chain by converting the proof, public inputs and verifying key data into pairs for use with Solanas alt_bn128_pairing function. This allows proof verification without using too much CU.
+
+- Validator commitment signature: The signature is created using libsecp256k1 and verified using Solanas secp256k1_recover function. This too helps keep it within the CU limit.
+
+### **Running this example**
+
+With command line:
+
+```shell
+cargo build
+```
+
+```shell
+cd api
+cargo run
+```
+
+```shell
+cd validator
+cargo run
+```
+
+With Docker:
+
+```shell
+docker-compose -f docker-compose.yml
+```
+
+```shell
+cd example
+cargo run
+```
+
+After running the example you see output in the console for the Trollup API and Trollup Validator showing details of the flow. If everything runs successfully then you'll see the transactions on the Solana chain. See the links below for the programs.
+
+[Proof Verify Program - Solana Explorer](https://explorer.solana.com/address/F68FK2Ai4vWVqFQpfx6RJjzpYieSzxWMqs179SBdcZVJ?cluster=devnet)
+
+[Commitment Signature Verify Program - Solana Explorer](https://explorer.solana.com/address/7xyXvzfXcBhc8Tbv5gJp7j3XKzPaS3xEXGfwuDJ6MgAo?cluster=devnet)