Introduce new backend

.github/workflows/docker-rewards-backend.yml

@@ -0,0 +1,32 @@
+name: docker-rewards-backend
+on:
+  workflow_dispatch: # manually run
+    inputs:
+      tag:
+        description: image tag
+        required: true
+
+env:
+  CI: true
+
+jobs:
+  publish:
+    name: Build & publish docker image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Docker login
+        uses: docker/login-action@v1
+        with:
+          username: ${{ secrets.DOCKER_LOGIN }}
+          password: ${{ secrets.DOCKER_TOKEN }}
+
+      - name: Build & publish subsquid-rewards-backend image
+        uses: docker/build-push-action@v3
+        with:
+          push: true
+          context: .
+          file: packages/subsquid-rewards-backend/Dockerfile
+          tags: subsquid/rewards-backend:${{ inputs.tag }}

.gitignore

@@ -1,5 +1,10 @@
+cache/
+out/
+!/broadcast
+/broadcast/*/31337/
+/broadcast/**/dry-run/
 node_modules
 .idea
-.env
+.env*
 .turbo
 .lockb

Readme.md

@@ -6,6 +6,62 @@
 
 This is a monorepo that contains contracts and utils that enable [Subsquid](https://subsquid.io/) decentralised network
 
+-----------
+
+### 🔍 What Is a Merkle Mountain Range (MMR) 
+
+A Merkle Mountain Range is like a “forest” of perfect Merkle trees (the “mountains”), each one packed as tightly as possible, side by side. 
+Instead of rebuilding one giant Merkle tree every time we append new data:
+* Append a new leaf
+  * Find the rightmost “mountain” whose height matches our new leaf count (a perfect power-of-two subtree)
+  * Hash the new leaf with its immediate sibling(s) to climb up that mountain, creating new parent nodes as needed
+
+* “Bag the peaks”
+  * After we’ve added all the leaves, we take the root of each perfect subtree (each “mountain peak”)
+    then we hash those peaks pairwise—left to right—until we collapse them into a single, final MMR root
+  * Those two steps let us grow the data set one leaf at a time (append-only) without ever touching old leaves, yet still end up with a single 32-byte root that cryptographically commits to     
+     every leaf ever added
+
+### 🛠 How This Powers DistributedRewardsDistribution
+
+Our rewards pipeline leverages MMR to securely batch-and-release thousands of worker payouts with minimal on-chain footprint:
+
+1. **Off-chain: Collect & Batch thousands of per-worker rewards**  
+   - Pull each worker’s reward slice from ClickHouse.  
+   - Group them into fixed-size batches (e.g. 200 workers per batch).  
+   - For each batch, compute a “batch leaf hash”:
+     ```ts
+     keccak256(abi.encode(recipients[], workerRewards[], stakerRewards[]))
+     ```
+   - Assemble a list of `BatchInput = { batchId, recipients[], workerRewards[], stakerRewards[], leafHash }`.
+
+2. **Off-chain: Build the MMR**  
+   - **Append** each `leafHash` into our in-memory MMR structure, creating only the minimal new parent hashes.  
+   - **Compute peaks** via bit-twiddling on the leaf count to isolate perfect subtrees.  
+   - **Bag peaks** into one final MMR root and record each leaf’s inclusion proof (an array of sibling hashes + cross-peak bag-hashes).
+
+3. **On-chain: Commit & Approve the MMR Root**  
+- We only store a single bytes32 finalRoot and a 64-bit totalLeaves on-chain per block-range key
+
+4. **On-chain: Distribute Each Batch**
+ ```
+rewardsContract.distributeBatch(
+  [fromBlock, toBlock],
+  kIndex,        // “mountain k-index” inside its peak
+  leafIndex,     // sequential batch ID
+  recipients[],  // worker IDs
+  workerRewards[],
+  stakerRewards[],
+  merkleProof[]  // sibling-hash proof + bagged peaks
+);
+ ```
+- The contract recomputes the batch’s leaf hash, then calls:
+`MerkleMountainRange.VerifyProof(finalRoot, merkleProof, [MmrLeaf(kIndex, leafIndex, leafHash)], totalLeaves)`
+
+On success, it marks the batch as processed, updates each worker’s accumulatedRewards, and triggers `router.staking().distribute(…)`
+
+-------------
+
 Subsquid uses [pnpm](https://pnpm.io/) as a package and monorepo manager.
 To install `pnpm`, run `npm install -g pnpm` or consult with [pnpm installation guide](https://pnpm.io/installation).
 

package.json

@@ -3,7 +3,8 @@
     "build": "turbo build",
     "lint": "turbo lint",
     "test": "turbo test",
-    "build-reward-image": "docker build -f packages/rewards-calculator/Dockerfile -t rewards-simulation ."
+    "build-reward-image": "docker build -f packages/rewards-calculator/Dockerfile -t rewards-simulation .",
+    "generate": "node packages/contracts/generate_merkle.mjs"
   },
   "devDependencies": {
     "turbo": "^1.9.9"

packages/contract-admin-state/src/config/contracts.ts

@@ -1,5 +1,5 @@
 import Deployments from "../../../contracts/deployments/42161.json";
-import rewardsDistributionAbi from "../../../contracts/artifacts/DistributedRewardDistribution.sol/DistributedRewardsDistribution";
+import rewardsDistributionAbi from "../../../contracts/artifacts/DistributedRewardsDistribution.sol/DistributedRewardsDistribution";
 import stakingAbi from "../../../contracts/artifacts/Staking.sol/Staking";
 import networkControllerAbi from "../../../contracts/artifacts/NetworkController.sol/NetworkController";
 import gatewayRegistryAbi from "../../../contracts/artifacts/GatewayRegistry.sol/GatewayRegistry";

packages/contracts/Dockerfile.arbitrum-fork

@@ -0,0 +1,61 @@
+
+FROM ubuntu:22.04
+
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    build-essential \
+    jq \
+    python3 \
+    python3-pip \
+    bash \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs
+
+RUN pip3 install base58
+
+RUN npm install -g pnpm@latest
+
+RUN curl -L https://foundry.paradigm.xyz | bash
+ENV PATH="/root/.foundry/bin:${PATH}"
+RUN foundryup
+
+WORKDIR /usr/src/app
+
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY packages/contracts/package.json ./packages/contracts/
+COPY packages/rewards-calculator/package.json ./packages/rewards-calculator/
+
+RUN pnpm install
+
+COPY packages/contracts/foundry.toml ./packages/contracts/foundry.toml
+
+WORKDIR /usr/src/app/packages/contracts
+RUN forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts@v5.0.1 OpenZeppelin/openzeppelin-contracts-upgradeable@v5.0.2 PaulRBerg/prb-math@release-v4 --no-git
+
+COPY packages/contracts/src ./src
+COPY packages/contracts/script/DeployDistributedRewards.s.sol ./script/DeployDistributedRewards.s.sol
+#COPY packages/contracts/test ./test
+COPY packages/contracts/lib ./lib
+COPY packages/contracts/generate_merkle.mjs ./generate_merkle.mjs
+COPY packages/contracts/b58.py ./b58.py
+
+RUN forge build
+
+COPY packages/contracts/deploy ./deploy
+COPY packages/contracts/deployments ./deployments
+
+RUN mkdir -p /usr/src/app/packages/contracts/docker-scripts
+
+COPY packages/contracts/docker-scripts/ ./docker-scripts/
+
+RUN chmod +x docker-scripts/*.sh
+
+EXPOSE 8545
+
+WORKDIR /usr/src/app/packages/contracts
+
+CMD ["./docker-scripts/run_arbitrum_fork.sh"] 

packages/contracts/docker-compose.arbitrum-fork.yml

@@ -0,0 +1,35 @@
+version: '3.8'
+
+services:
+  arbitrum-fork:
+    build:
+      context: ../../
+      dockerfile: packages/contracts/Dockerfile.arbitrum-fork
+    ports:
+      - "8545:8545"
+    environment:
+      - ADMIN_KEY=${ADMIN_KEY:-}
+      - DISTRIBUTOR1_KEY=${DISTRIBUTOR1_KEY:-}
+      - DISTRIBUTOR2_KEY=${DISTRIBUTOR2_KEY:-}
+
+      - NUM_WORKERS=${NUM_WORKERS:-500}
+      - BATCH_SIZE=${BATCH_SIZE:-100}
+      - IPFS_LINK=${IPFS_LINK:-ipfs://test}
+
+      - SKIP_COMMIT=${SKIP_COMMIT:-false}
+      - SKIP_APPROVE=${SKIP_APPROVE:-false}
+      - SKIP_DISTRIBUTE=${SKIP_DISTRIBUTE:-false}
+
+      - FORK_URL=${FORK_URL:-https://arb1.arbitrum.io/rpc}
+      - FORK_BLOCK_NUMBER=${FORK_BLOCK_NUMBER:-latest}
+    volumes:
+      - ./broadcast:/usr/src/app/packages/contracts/broadcast
+      - ./cache:/usr/src/app/packages/contracts/cache
+      - ./out:/usr/src/app/packages/contracts/out
+    networks:
+      - arbitrum-fork-network
+    command: ["./docker-scripts/run_arbitrum_fork.sh"]
+
+networks:
+  arbitrum-fork-network:
+    driver: bridge