From c63a4e093413bc37fd2c3008bfff826a85eece68 Mon Sep 17 00:00:00 2001 From: signature18632 Date: Thu, 7 Aug 2025 11:23:02 +0700 Subject: [PATCH 1/5] update modules --- .github/workflows/ci.yml | 2 +- docker/Dockerfile | 4 +- package.json | 6 +- packages/block-sync-monitor/package.json | 4 +- packages/deposit-analyzer/package.json | 4 +- packages/indexer-cache-validator/package.json | 4 +- packages/indexer-event-watcher/package.json | 4 +- packages/indexer-monitor/package.json | 4 +- packages/indexer/package.json | 6 +- packages/messenger-relayer/package.json | 4 +- packages/mint-executor/package.json | 4 +- packages/mock-l1-to-l2-relayer/package.json | 4 +- packages/mock-l2-to-l1-relayer/package.json | 4 +- packages/predicate/package.json | 6 +- packages/shared/package.json | 14 +- packages/token-map-register/package.json | 4 +- packages/token-metadata-sync/package.json | 4 +- packages/token/package.json | 6 +- packages/tx-map-cleaner/package.json | 2 +- packages/tx-map/package.json | 6 +- packages/wallet-observer/package.json | 4 +- yarn.lock | 270 +++++++++--------- 22 files changed, 185 insertions(+), 185 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2d7e7a4..1ac06fd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,7 +25,7 @@ jobs: - name: Use Node.js uses: actions/setup-node@v4 with: - node-version: 24.4.1 + node-version: 24.5.0 - name: Enable Corepack run: corepack enable diff --git a/docker/Dockerfile b/docker/Dockerfile index e855ecd..a16a84a 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -1,4 +1,4 @@ -FROM node:24.4.1-bookworm-slim AS builder +FROM node:24.5.0-bookworm-slim AS builder RUN corepack enable && \ corepack prepare yarn@4.9.2 --activate && \ @@ -36,7 +36,7 @@ RUN mkdir -p /tmp/packages && \ find /tmp/packages/$pkg_name -type d -empty -delete; \ done -FROM node:24.4.1-bookworm-slim AS production +FROM node:24.5.0-bookworm-slim AS production ENV NODE_ENV=production ENV NODE_OPTIONS="\ diff --git a/package.json b/package.json index d6ceac3..2364f78 100644 --- a/package.json +++ b/package.json @@ -38,14 +38,14 @@ "coverage": "vitest run --coverage" }, "devDependencies": { - "@biomejs/biome": "2.1.2", + "@biomejs/biome": "2.1.3", "@vitest/coverage-v8": "^3.2.4", - "typescript": "^5.8.3", + "typescript": "^5.9.2", "vitest": "^3.2.4" }, "packageManager": "yarn@4.9.2", "volta": { - "node": "24.4.1", + "node": "24.5.0", "yarn": "4.9.2" } } diff --git a/packages/block-sync-monitor/package.json b/packages/block-sync-monitor/package.json index b3cd6d2..c5d09de 100644 --- a/packages/block-sync-monitor/package.json +++ b/packages/block-sync-monitor/package.json @@ -4,7 +4,7 @@ "dependencies": { "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -15,7 +15,7 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3", + "typescript": "^5.9.2", "vitest": "^3.2.4" } } diff --git a/packages/deposit-analyzer/package.json b/packages/deposit-analyzer/package.json index 6c05122..ba11bcd 100644 --- a/packages/deposit-analyzer/package.json +++ b/packages/deposit-analyzer/package.json @@ -4,7 +4,7 @@ "dependencies": { "@intmax2-function/shared": "workspace:*", "ethers": "^6.15.0", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -15,7 +15,7 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3", + "typescript": "^5.9.2", "vitest": "^3.2.4" } } diff --git a/packages/indexer-cache-validator/package.json b/packages/indexer-cache-validator/package.json index b61989d..b84ff9f 100644 --- a/packages/indexer-cache-validator/package.json +++ b/packages/indexer-cache-validator/package.json @@ -5,7 +5,7 @@ "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", "semver": "^7.7.2", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -16,6 +16,6 @@ "devDependencies": { "@types/semver": "^7", "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/indexer-event-watcher/package.json b/packages/indexer-event-watcher/package.json index 3e803e1..7f4dfef 100644 --- a/packages/indexer-event-watcher/package.json +++ b/packages/indexer-event-watcher/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "dependencies": { "@intmax2-function/shared": "workspace:*", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -13,6 +13,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/indexer-monitor/package.json b/packages/indexer-monitor/package.json index 1a881f0..229322e 100644 --- a/packages/indexer-monitor/package.json +++ b/packages/indexer-monitor/package.json @@ -5,7 +5,7 @@ "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", "semver": "^7.7.2", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -16,6 +16,6 @@ "devDependencies": { "@types/semver": "^7", "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/indexer/package.json b/packages/indexer/package.json index 8883d69..e9d3e11 100644 --- a/packages/indexer/package.json +++ b/packages/indexer/package.json @@ -2,9 +2,9 @@ "name": "indexer", "version": "1.0.0", "dependencies": { - "@hono/node-server": "^1.17.1", + "@hono/node-server": "^1.18.1", "@intmax2-function/shared": "workspace:*", - "hono": "^4.8.9" + "hono": "^4.8.12" }, "scripts": { "start": "node dist/index.js", @@ -14,6 +14,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/messenger-relayer/package.json b/packages/messenger-relayer/package.json index 45f5218..e1c4c2e 100644 --- a/packages/messenger-relayer/package.json +++ b/packages/messenger-relayer/package.json @@ -5,7 +5,7 @@ "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", "ethers": "^6.15.0", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start:withdrawal": "node dist/index.js withdrawal", @@ -17,6 +17,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/mint-executor/package.json b/packages/mint-executor/package.json index 81849ae..bd586a2 100644 --- a/packages/mint-executor/package.json +++ b/packages/mint-executor/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "dependencies": { "@intmax2-function/shared": "workspace:*", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -13,6 +13,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/mock-l1-to-l2-relayer/package.json b/packages/mock-l1-to-l2-relayer/package.json index 381ff50..89a3f81 100644 --- a/packages/mock-l1-to-l2-relayer/package.json +++ b/packages/mock-l1-to-l2-relayer/package.json @@ -4,7 +4,7 @@ "dependencies": { "@intmax2-function/shared": "workspace:*", "ethers": "^6.15.0", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -15,7 +15,7 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3", + "typescript": "^5.9.2", "vitest": "^3.2.4" } } diff --git a/packages/mock-l2-to-l1-relayer/package.json b/packages/mock-l2-to-l1-relayer/package.json index 7c5b1d7..d069d2c 100644 --- a/packages/mock-l2-to-l1-relayer/package.json +++ b/packages/mock-l2-to-l1-relayer/package.json @@ -4,7 +4,7 @@ "dependencies": { "@intmax2-function/shared": "workspace:*", "ethers": "^6.15.0", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -14,6 +14,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/predicate/package.json b/packages/predicate/package.json index 452a862..e07c49c 100644 --- a/packages/predicate/package.json +++ b/packages/predicate/package.json @@ -2,10 +2,10 @@ "name": "predicate", "version": "1.0.0", "dependencies": { - "@hono/node-server": "^1.17.1", + "@hono/node-server": "^1.18.1", "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", - "hono": "^4.8.9" + "hono": "^4.8.12" }, "scripts": { "start": "node dist/index.js", @@ -15,6 +15,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/shared/package.json b/packages/shared/package.json index beafd25..c248b22 100644 --- a/packages/shared/package.json +++ b/packages/shared/package.json @@ -5,22 +5,22 @@ "dependencies": { "@google-cloud/firestore": "^7.11.3", "@google-cloud/storage": "^7.16.0", - "@hono/node-server": "^1.17.1", + "@hono/node-server": "^1.18.1", "abitype": "^1.0.8", "alchemy-sdk": "^3.6.2", "axios": "^1.11.0", "discord.js": "^14.21.0", "envalid": "^8.1.0", "ethers": "^6.15.0", - "hono": "^4.8.9", + "hono": "^4.8.12", "hono-rate-limiter": "^0.4.2", "http-status": "2.1.0", - "ioredis": "^5.6.1", + "ioredis": "^5.7.0", "node-cache": "^5.1.2", "pino": "^9.7.0", - "pino-pretty": "^13.0.0", - "viem": "^2.33.1", - "zod": "4.0.10" + "pino-pretty": "^13.1.1", + "viem": "^2.33.2", + "zod": "4.0.15" }, "scripts": { "start": "node dist/index.js", @@ -30,6 +30,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/token-map-register/package.json b/packages/token-map-register/package.json index 7262bad..a14f4fd 100644 --- a/packages/token-map-register/package.json +++ b/packages/token-map-register/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "dependencies": { "@intmax2-function/shared": "workspace:*", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -13,6 +13,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/token-metadata-sync/package.json b/packages/token-metadata-sync/package.json index b08b4e9..96672f4 100644 --- a/packages/token-metadata-sync/package.json +++ b/packages/token-metadata-sync/package.json @@ -5,7 +5,7 @@ "@intmax2-function/shared": "workspace:*", "axios": "^1.11.0", "coingecko-api-v3": "^0.0.31", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -15,6 +15,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/token/package.json b/packages/token/package.json index 74ef468..9779aa5 100644 --- a/packages/token/package.json +++ b/packages/token/package.json @@ -2,9 +2,9 @@ "name": "token", "version": "1.0.0", "dependencies": { - "@hono/node-server": "^1.17.1", + "@hono/node-server": "^1.18.1", "@intmax2-function/shared": "workspace:*", - "hono": "^4.8.9" + "hono": "^4.8.12" }, "scripts": { "start": "node dist/index.js", @@ -14,6 +14,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/tx-map-cleaner/package.json b/packages/tx-map-cleaner/package.json index 738302d..bc56f3f 100644 --- a/packages/tx-map-cleaner/package.json +++ b/packages/tx-map-cleaner/package.json @@ -12,6 +12,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/tx-map/package.json b/packages/tx-map/package.json index a74a062..54f5b94 100644 --- a/packages/tx-map/package.json +++ b/packages/tx-map/package.json @@ -2,9 +2,9 @@ "name": "tx-map", "version": "1.0.0", "dependencies": { - "@hono/node-server": "^1.17.1", + "@hono/node-server": "^1.18.1", "@intmax2-function/shared": "workspace:*", - "hono": "^4.8.9" + "hono": "^4.8.12" }, "scripts": { "start": "node dist/index.js", @@ -14,6 +14,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/packages/wallet-observer/package.json b/packages/wallet-observer/package.json index a177c9e..cfd1929 100644 --- a/packages/wallet-observer/package.json +++ b/packages/wallet-observer/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "dependencies": { "@intmax2-function/shared": "workspace:*", - "viem": "^2.33.1" + "viem": "^2.33.2" }, "scripts": { "start": "node dist/index.js", @@ -13,6 +13,6 @@ }, "devDependencies": { "tsx": "^4.20.3", - "typescript": "^5.8.3" + "typescript": "^5.9.2" } } diff --git a/yarn.lock b/yarn.lock index dc21dbe..ae92af5 100644 --- a/yarn.lock +++ b/yarn.lock @@ -78,18 +78,18 @@ __metadata: languageName: node linkType: hard -"@biomejs/biome@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/biome@npm:2.1.2" - dependencies: - "@biomejs/cli-darwin-arm64": "npm:2.1.2" - "@biomejs/cli-darwin-x64": "npm:2.1.2" - "@biomejs/cli-linux-arm64": "npm:2.1.2" - "@biomejs/cli-linux-arm64-musl": "npm:2.1.2" - "@biomejs/cli-linux-x64": "npm:2.1.2" - "@biomejs/cli-linux-x64-musl": "npm:2.1.2" - "@biomejs/cli-win32-arm64": "npm:2.1.2" - "@biomejs/cli-win32-x64": "npm:2.1.2" +"@biomejs/biome@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/biome@npm:2.1.3" + dependencies: + "@biomejs/cli-darwin-arm64": "npm:2.1.3" + "@biomejs/cli-darwin-x64": "npm:2.1.3" + "@biomejs/cli-linux-arm64": "npm:2.1.3" + "@biomejs/cli-linux-arm64-musl": "npm:2.1.3" + "@biomejs/cli-linux-x64": "npm:2.1.3" + "@biomejs/cli-linux-x64-musl": "npm:2.1.3" + "@biomejs/cli-win32-arm64": "npm:2.1.3" + "@biomejs/cli-win32-x64": "npm:2.1.3" dependenciesMeta: "@biomejs/cli-darwin-arm64": optional: true @@ -109,62 +109,62 @@ __metadata: optional: true bin: biome: bin/biome - checksum: 10c0/4863a5d64ff7e47c1f535aca3c0d59769fd1e59868b178798bf1f10de94f41188f235accddb852778743b16239dd890a520266dd2f93ecbcd147ad339caa8e23 + checksum: 10c0/0393412e965e41b1d6278208d895db0b030a465a4e6a7913d2165d61280c192ad3c95c1d0597e319b5980cee75a3ddf787a7e83698ddbfcc9b520734c407ef20 languageName: node linkType: hard -"@biomejs/cli-darwin-arm64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-darwin-arm64@npm:2.1.2" +"@biomejs/cli-darwin-arm64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-darwin-arm64@npm:2.1.3" conditions: os=darwin & cpu=arm64 languageName: node linkType: hard -"@biomejs/cli-darwin-x64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-darwin-x64@npm:2.1.2" +"@biomejs/cli-darwin-x64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-darwin-x64@npm:2.1.3" conditions: os=darwin & cpu=x64 languageName: node linkType: hard -"@biomejs/cli-linux-arm64-musl@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-linux-arm64-musl@npm:2.1.2" +"@biomejs/cli-linux-arm64-musl@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-linux-arm64-musl@npm:2.1.3" conditions: os=linux & cpu=arm64 & libc=musl languageName: node linkType: hard -"@biomejs/cli-linux-arm64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-linux-arm64@npm:2.1.2" +"@biomejs/cli-linux-arm64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-linux-arm64@npm:2.1.3" conditions: os=linux & cpu=arm64 & libc=glibc languageName: node linkType: hard -"@biomejs/cli-linux-x64-musl@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-linux-x64-musl@npm:2.1.2" +"@biomejs/cli-linux-x64-musl@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-linux-x64-musl@npm:2.1.3" conditions: os=linux & cpu=x64 & libc=musl languageName: node linkType: hard -"@biomejs/cli-linux-x64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-linux-x64@npm:2.1.2" +"@biomejs/cli-linux-x64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-linux-x64@npm:2.1.3" conditions: os=linux & cpu=x64 & libc=glibc languageName: node linkType: hard -"@biomejs/cli-win32-arm64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-win32-arm64@npm:2.1.2" +"@biomejs/cli-win32-arm64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-win32-arm64@npm:2.1.3" conditions: os=win32 & cpu=arm64 languageName: node linkType: hard -"@biomejs/cli-win32-x64@npm:2.1.2": - version: 2.1.2 - resolution: "@biomejs/cli-win32-x64@npm:2.1.2" +"@biomejs/cli-win32-x64@npm:2.1.3": + version: 2.1.3 + resolution: "@biomejs/cli-win32-x64@npm:2.1.3" conditions: os=win32 & cpu=x64 languageName: node linkType: hard @@ -895,12 +895,12 @@ __metadata: languageName: node linkType: hard -"@hono/node-server@npm:^1.17.1": - version: 1.17.1 - resolution: "@hono/node-server@npm:1.17.1" +"@hono/node-server@npm:^1.18.1": + version: 1.18.1 + resolution: "@hono/node-server@npm:1.18.1" peerDependencies: hono: ^4 - checksum: 10c0/a313e389a34782dbf310fc180dbd62bc3b32f41eeb5810718b560416122cdf81cd1bec1c31a3117e7fae26b596f9d8ffb2f7ac37a3a0194e2db89d4d4126998d + checksum: 10c0/5deee5f465eaab242146702ae599503d3444c4d88d734ab090d6a8f2ab4957b402649e07c785e07ed2f8cb0d79824fd29a71ae8cbcf83fa7c3075011e1d85020 languageName: node linkType: hard @@ -910,31 +910,31 @@ __metadata: dependencies: "@google-cloud/firestore": "npm:^7.11.3" "@google-cloud/storage": "npm:^7.16.0" - "@hono/node-server": "npm:^1.17.1" + "@hono/node-server": "npm:^1.18.1" abitype: "npm:^1.0.8" alchemy-sdk: "npm:^3.6.2" axios: "npm:^1.11.0" discord.js: "npm:^14.21.0" envalid: "npm:^8.1.0" ethers: "npm:^6.15.0" - hono: "npm:^4.8.9" + hono: "npm:^4.8.12" hono-rate-limiter: "npm:^0.4.2" http-status: "npm:2.1.0" - ioredis: "npm:^5.6.1" + ioredis: "npm:^5.7.0" node-cache: "npm:^5.1.2" pino: "npm:^9.7.0" - pino-pretty: "npm:^13.0.0" + pino-pretty: "npm:^13.1.1" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" - zod: "npm:4.0.10" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" + zod: "npm:4.0.15" languageName: unknown linkType: soft -"@ioredis/commands@npm:^1.1.1": - version: 1.2.0 - resolution: "@ioredis/commands@npm:1.2.0" - checksum: 10c0/a5d3c29dd84d8a28b7c67a441ac1715cbd7337a7b88649c0f17c345d89aa218578d2b360760017c48149ef8a70f44b051af9ac0921a0622c2b479614c4f65b36 +"@ioredis/commands@npm:^1.3.0": + version: 1.3.0 + resolution: "@ioredis/commands@npm:1.3.0" + checksum: 10c0/5ab990a8f69c20daf3d7d64307aa9f13ee727c92ab4c7664a6943bb500227667a0c368892e9c4913f06416377db47dba78d58627fe723da476d25f2c04a6d5aa languageName: node linkType: hard @@ -1934,8 +1934,8 @@ __metadata: "@intmax2-function/shared": "workspace:*" axios: "npm:^1.11.0" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" vitest: "npm:^3.2.4" languageName: unknown linkType: soft @@ -2271,8 +2271,8 @@ __metadata: "@intmax2-function/shared": "workspace:*" ethers: "npm:^6.15.0" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" vitest: "npm:^3.2.4" languageName: unknown linkType: soft @@ -3095,10 +3095,10 @@ __metadata: languageName: node linkType: hard -"hono@npm:^4.8.9": - version: 4.8.9 - resolution: "hono@npm:4.8.9" - checksum: 10c0/385539d1787fdc747bc869ef0e5ccc9f39cbe40289b94f23eecfc82c6ca440f059704647cd6381a5066d2cf7baa43ab25184c78d44af4c5c98a5c5b07670059e +"hono@npm:^4.8.12": + version: 4.8.12 + resolution: "hono@npm:4.8.12" + checksum: 10c0/09b4742ce86fa807dfeb37e5d83dba728d00963a497bfb8638085ddf4c20182e565cb9cb2d3e7341598d3e99b0adb2d049d86d89b5876c169098862704327a9e languageName: node linkType: hard @@ -3219,8 +3219,8 @@ __metadata: axios: "npm:^1.11.0" semver: "npm:^7.7.2" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3230,8 +3230,8 @@ __metadata: dependencies: "@intmax2-function/shared": "workspace:*" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3244,8 +3244,8 @@ __metadata: axios: "npm:^1.11.0" semver: "npm:^7.7.2" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3253,11 +3253,11 @@ __metadata: version: 0.0.0-use.local resolution: "indexer@workspace:packages/indexer" dependencies: - "@hono/node-server": "npm:^1.17.1" + "@hono/node-server": "npm:^1.18.1" "@intmax2-function/shared": "workspace:*" - hono: "npm:^4.8.9" + hono: "npm:^4.8.12" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" languageName: unknown linkType: soft @@ -3272,18 +3272,18 @@ __metadata: version: 0.0.0-use.local resolution: "intmax2-function@workspace:." dependencies: - "@biomejs/biome": "npm:2.1.2" + "@biomejs/biome": "npm:2.1.3" "@vitest/coverage-v8": "npm:^3.2.4" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" vitest: "npm:^3.2.4" languageName: unknown linkType: soft -"ioredis@npm:^5.6.1": - version: 5.6.1 - resolution: "ioredis@npm:5.6.1" +"ioredis@npm:^5.7.0": + version: 5.7.0 + resolution: "ioredis@npm:5.7.0" dependencies: - "@ioredis/commands": "npm:^1.1.1" + "@ioredis/commands": "npm:^1.3.0" cluster-key-slot: "npm:^1.1.0" debug: "npm:^4.3.4" denque: "npm:^2.1.0" @@ -3292,7 +3292,7 @@ __metadata: redis-errors: "npm:^1.2.0" redis-parser: "npm:^3.0.0" standard-as-callback: "npm:^2.1.0" - checksum: 10c0/26ae49cf448e807e454a9bdea5a9dfdcf669e2fdbf2df341900a0fb693c5662fea7e39db3227ce8972d1bda0ba7da9b7410e5163b12d8878a579548d847220ac + checksum: 10c0/c63c521a953bfaf29f8c8871b122af38e439328336fa238f83bfbb066556f64daf69ed7a4ec01fc7b9ee1f0862059dd188b8c684150125d362d36642399b30ee languageName: node linkType: hard @@ -3631,8 +3631,8 @@ __metadata: axios: "npm:^1.11.0" ethers: "npm:^6.15.0" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3773,8 +3773,8 @@ __metadata: dependencies: "@intmax2-function/shared": "workspace:*" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3794,8 +3794,8 @@ __metadata: "@intmax2-function/shared": "workspace:*" ethers: "npm:^6.15.0" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" vitest: "npm:^3.2.4" languageName: unknown linkType: soft @@ -3807,8 +3807,8 @@ __metadata: "@intmax2-function/shared": "workspace:*" ethers: "npm:^6.15.0" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -3937,9 +3937,9 @@ __metadata: languageName: node linkType: hard -"ox@npm:0.8.1": - version: 0.8.1 - resolution: "ox@npm:0.8.1" +"ox@npm:0.8.6": + version: 0.8.6 + resolution: "ox@npm:0.8.6" dependencies: "@adraffy/ens-normalize": "npm:^1.11.0" "@noble/ciphers": "npm:^1.3.0" @@ -3954,7 +3954,7 @@ __metadata: peerDependenciesMeta: typescript: optional: true - checksum: 10c0/3d04df384a35c94b21a29d867ee3735acf9a975d46ffb0a26cc438b92f1e4952b2b3cddb74b4213e88d2988e82687db9b85c1018c5d4b24737b1c3d7cb7c809e + checksum: 10c0/025c638966c6e569bb38a78a6f9f84bbeb9f5b0a594ef011ab3f81414edcaf5b20d9ea7d8f90471ddafdcb3f21c61f7a2255d35d2032e8daafbc8b20d98d27cf languageName: node linkType: hard @@ -4035,9 +4035,9 @@ __metadata: languageName: node linkType: hard -"pino-pretty@npm:^13.0.0": - version: 13.0.0 - resolution: "pino-pretty@npm:13.0.0" +"pino-pretty@npm:^13.1.1": + version: 13.1.1 + resolution: "pino-pretty@npm:13.1.1" dependencies: colorette: "npm:^2.0.7" dateformat: "npm:^4.6.3" @@ -4049,12 +4049,12 @@ __metadata: on-exit-leak-free: "npm:^2.1.0" pino-abstract-transport: "npm:^2.0.0" pump: "npm:^3.0.0" - secure-json-parse: "npm:^2.4.0" + secure-json-parse: "npm:^4.0.0" sonic-boom: "npm:^4.0.1" - strip-json-comments: "npm:^3.1.1" + strip-json-comments: "npm:^5.0.2" bin: pino-pretty: bin.js - checksum: 10c0/015dac25006c1b9820b9e01fccb8a392a019e12b30e6bfc3f3f61ecca8dbabcd000a8f3f64410b620b7f5d08579ba85e6ef137f7fbeaad70d46397a97a5f75ea + checksum: 10c0/845c07afd3d73cb96ad2049cfa7fca12b8280a51e30d6db8b490857690637556bb8e7f05b2fa640b3e4a7edd9b1369110042d670fda743ef98fe3be29876c8c7 languageName: node linkType: hard @@ -4101,12 +4101,12 @@ __metadata: version: 0.0.0-use.local resolution: "predicate@workspace:packages/predicate" dependencies: - "@hono/node-server": "npm:^1.17.1" + "@hono/node-server": "npm:^1.18.1" "@intmax2-function/shared": "workspace:*" axios: "npm:^1.11.0" - hono: "npm:^4.8.9" + hono: "npm:^4.8.12" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" languageName: unknown linkType: soft @@ -4385,10 +4385,10 @@ __metadata: languageName: node linkType: hard -"secure-json-parse@npm:^2.4.0": - version: 2.7.0 - resolution: "secure-json-parse@npm:2.7.0" - checksum: 10c0/f57eb6a44a38a3eeaf3548228585d769d788f59007454214fab9ed7f01fbf2e0f1929111da6db28cf0bcc1a2e89db5219a59e83eeaec3a54e413a0197ce879e4 +"secure-json-parse@npm:^4.0.0": + version: 4.0.0 + resolution: "secure-json-parse@npm:4.0.0" + checksum: 10c0/1a298cf00e1de91e833cee5eb406d6e77fb2f7eca9bef3902047d49e7f5d3e6c21b5de61ff73466c831e716430bfe87d732a6e645a7dabb5f1e8a8e4d3e15eb4 languageName: node linkType: hard @@ -4609,10 +4609,10 @@ __metadata: languageName: node linkType: hard -"strip-json-comments@npm:^3.1.1": - version: 3.1.1 - resolution: "strip-json-comments@npm:3.1.1" - checksum: 10c0/9681a6257b925a7fa0f285851c0e613cc934a50661fa7bb41ca9cbbff89686bb4a0ee366e6ecedc4daafd01e83eee0720111ab294366fe7c185e935475ebcecd +"strip-json-comments@npm:^5.0.2": + version: 5.0.2 + resolution: "strip-json-comments@npm:5.0.2" + checksum: 10c0/e9841b8face78a01b0eb66f81e0a3419186a96f1d26817a5e1f5260b0631c10e0a7f711dddc5988edf599e5c079e4dd6e91defd21523e556636ba5679786f5ac languageName: node linkType: hard @@ -4777,8 +4777,8 @@ __metadata: dependencies: "@intmax2-function/shared": "workspace:*" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -4790,8 +4790,8 @@ __metadata: axios: "npm:^1.11.0" coingecko-api-v3: "npm:^0.0.31" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -4799,11 +4799,11 @@ __metadata: version: 0.0.0-use.local resolution: "token@workspace:packages/token" dependencies: - "@hono/node-server": "npm:^1.17.1" + "@hono/node-server": "npm:^1.18.1" "@intmax2-function/shared": "workspace:*" - hono: "npm:^4.8.9" + hono: "npm:^4.8.12" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" languageName: unknown linkType: soft @@ -4857,7 +4857,7 @@ __metadata: dependencies: "@intmax2-function/shared": "workspace:*" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" languageName: unknown linkType: soft @@ -4865,11 +4865,11 @@ __metadata: version: 0.0.0-use.local resolution: "tx-map@workspace:packages/tx-map" dependencies: - "@hono/node-server": "npm:^1.17.1" + "@hono/node-server": "npm:^1.18.1" "@intmax2-function/shared": "workspace:*" - hono: "npm:^4.8.9" + hono: "npm:^4.8.12" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" + typescript: "npm:^5.9.2" languageName: unknown linkType: soft @@ -4889,23 +4889,23 @@ __metadata: languageName: node linkType: hard -"typescript@npm:^5.8.3": - version: 5.8.3 - resolution: "typescript@npm:5.8.3" +"typescript@npm:^5.9.2": + version: 5.9.2 + resolution: "typescript@npm:5.9.2" bin: tsc: bin/tsc tsserver: bin/tsserver - checksum: 10c0/5f8bb01196e542e64d44db3d16ee0e4063ce4f3e3966df6005f2588e86d91c03e1fb131c2581baf0fb65ee79669eea6e161cd448178986587e9f6844446dbb48 + checksum: 10c0/cd635d50f02d6cf98ed42de2f76289701c1ec587a363369255f01ed15aaf22be0813226bff3c53e99d971f9b540e0b3cc7583dbe05faded49b1b0bed2f638a18 languageName: node linkType: hard -"typescript@patch:typescript@npm%3A^5.8.3#optional!builtin": - version: 5.8.3 - resolution: "typescript@patch:typescript@npm%3A5.8.3#optional!builtin::version=5.8.3&hash=5786d5" +"typescript@patch:typescript@npm%3A^5.9.2#optional!builtin": + version: 5.9.2 + resolution: "typescript@patch:typescript@npm%3A5.9.2#optional!builtin::version=5.9.2&hash=5786d5" bin: tsc: bin/tsc tsserver: bin/tsserver - checksum: 10c0/39117e346ff8ebd87ae1510b3a77d5d92dae5a89bde588c747d25da5c146603a99c8ee588c7ef80faaf123d89ed46f6dbd918d534d641083177d5fac38b8a1cb + checksum: 10c0/34d2a8e23eb8e0d1875072064d5e1d9c102e0bdce56a10a25c0b917b8aa9001a9cf5c225df12497e99da107dc379360bc138163c66b55b95f5b105b50578067e languageName: node linkType: hard @@ -4983,9 +4983,9 @@ __metadata: languageName: node linkType: hard -"viem@npm:^2.33.1": - version: 2.33.1 - resolution: "viem@npm:2.33.1" +"viem@npm:^2.33.2": + version: 2.33.2 + resolution: "viem@npm:2.33.2" dependencies: "@noble/curves": "npm:1.9.2" "@noble/hashes": "npm:1.8.0" @@ -4993,14 +4993,14 @@ __metadata: "@scure/bip39": "npm:1.6.0" abitype: "npm:1.0.8" isows: "npm:1.0.7" - ox: "npm:0.8.1" + ox: "npm:0.8.6" ws: "npm:8.18.2" peerDependencies: typescript: ">=5.0.4" peerDependenciesMeta: typescript: optional: true - checksum: 10c0/3f6cb3f43492a6a6e8849bca57e08b798eb8e61346abb83010a67f11e910ff2f97fbca4c0614f76cd000e7929d93acdaa4d93e3f8ded922c9bb68664bf2f6781 + checksum: 10c0/4b0cdbb322617897f71f6ffa9efc90f8cfad202f9a90d2275181db79e806a962f5d458e3d8b5f861a81e628c05b9a4ebf7853ebce26283291aec3f54a03a4df3 languageName: node linkType: hard @@ -5136,8 +5136,8 @@ __metadata: dependencies: "@intmax2-function/shared": "workspace:*" tsx: "npm:^4.20.3" - typescript: "npm:^5.8.3" - viem: "npm:^2.33.1" + typescript: "npm:^5.9.2" + viem: "npm:^2.33.2" languageName: unknown linkType: soft @@ -5367,9 +5367,9 @@ __metadata: languageName: node linkType: hard -"zod@npm:4.0.10": - version: 4.0.10 - resolution: "zod@npm:4.0.10" - checksum: 10c0/8d1145e767c22b571a7967c198632f69ef15ce571b5021cdba84cf31d9af2ca40b033ea2fcbe5797cfd2da9c67b3a6ebe435938eabfbb1d1f3ab2f17f00f443b +"zod@npm:4.0.15": + version: 4.0.15 + resolution: "zod@npm:4.0.15" + checksum: 10c0/c4d5b0c6668fe32fb6040d713d75dbf65e2e46cb68c77755b7b66426e8583d5dacf49a44f90beb6b12aa1aa2545cc0d3c186e368711021e11dd3c1f0addb9100 languageName: node linkType: hard From f49594861ec267a341f1283c41326e2132ce8454 Mon Sep 17 00:00:00 2001 From: signature18632 Date: Thu, 7 Aug 2025 12:17:04 +0700 Subject: [PATCH 2/5] rate config --- README.md | 56 +++++++++++-------- biome.json | 2 +- packages/shared/src/config/index.ts | 9 ++- .../shared/src/middlewares/rate.middleware.ts | 2 +- 4 files changed, 42 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 1ac5622..6106c27 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,22 @@ This document provides instructions for setting up, running, building with Docker, and deploying the `intmax2-function` project. -## Installing Dependencies +## Setup -First, install the project dependencies, build the project, and set up the environment. +Before running any service, make sure to: -```bash -# install +```sh +# Install dependencies yarn -# build:shared -yarn build:shared - -# build -yarn build - -# setup env +# Copy environment variables cp .env.example .env + +# Build shared packages +yarn build:shared ``` -## Running the Project +## Development To start the development mode for each workspace, use the following commands: @@ -74,6 +71,9 @@ If your development workflow involves Firestore, you can start a local emulator: ```sh gcloud emulators firestore start + +# Set the FIRESTORE_EMULATOR_HOST variable in the same terminal where you will run your application. +export FIRESTORE_EMULATOR_HOST="HOST:PORT" export FIRESTORE_EMULATOR_HOST="HOST:PORT" # We will use what is displayed in the console. ``` @@ -86,6 +86,17 @@ docker build -f docker/Dockerfile -t intmax2-function . docker run --rm -p 3000:3000 --env-file .env intmax2-function workspace token start ``` +## Redis + +Run Redis in a Docker container with data persistence enabled. + +```sh +docker run -d --rm \ + --name redis \ + -p 6379:6379 \ + -v redis-data:/data \ + redis redis-server --appendonly yes +``` ## Testing @@ -102,22 +113,21 @@ yarn test --watch yarn coverage ``` -## Redis - -```sh -docker run -d --rm \ - --name redis \ - -p 6379:6379 \ - -v redis-data:/data \ - redis redis-server --appendonly yes -``` - ## Bootstrap Tasks +Run the following commands to initialize the token map configuration. + ```sh # Bootstrap token map configuration yarn token-map-bootstrap # Bootstrap token image assets yarn token-image-bootstrap -``` \ No newline at end of file +``` + +## Docs + +This document explains the overall system design of intmax2-function. It covers the architectural components, interactions between modules, data flow, and the process of generating and verifying ZKPs (Zero-Knowledge Proofs). It is intended to help developers and infrastructure engineers understand the technical foundation of the system. + +- [SYSTEM Design](./docs/SYSTEM_DESIGN.md) +- [API Usage](./docs/API.md) \ No newline at end of file diff --git a/biome.json b/biome.json index 8c8f82e..926844b 100644 --- a/biome.json +++ b/biome.json @@ -1,5 +1,5 @@ { - "$schema": "https://biomejs.dev/schemas/2.1.2/schema.json", + "$schema": "https://biomejs.dev/schemas/2.1.3/schema.json", "formatter": { "enabled": true, "formatWithErrors": false, diff --git a/packages/shared/src/config/index.ts b/packages/shared/src/config/index.ts index c089d40..a0f69f2 100644 --- a/packages/shared/src/config/index.ts +++ b/packages/shared/src/config/index.ts @@ -17,6 +17,9 @@ export const config = cleanEnv(process.env, { // auth ALLOWED_ORIGINS: str({ default: "http://localhost:3000,http://localhost:5173" }), AUTH_IP_ALLOW_LIST: str({ devDefault: "127.0.0.1,::1" }), + RATE_LIMIT_WINDOW_MS: num({ + default: 10 * 60 * 1000, // 10 minutes + }), RATE_LIMIT: num({ default: 1000, }), @@ -35,16 +38,18 @@ export const config = cleanEnv(process.env, { BLOCK_BUILDER_URL: url({ devDefault: "http://localhost:3001" }), // proxy BLOCK_BUILDER_VERSION: str({ default: "0.0.0" }), - PROXY_DOMAIN: str({ default: "localhost" }), - PROXY_FRP_TOKEN: str({ default: "dummy" }), + PROXY_DOMAIN: str({ default: "localhost", desc: "" }), + PROXY_FRP_TOKEN: str({ default: "dummy", desc: "" }), // network NETWORK_TYPE: str({ choices: ["ethereum", "scroll"], default: "ethereum", + desc: "The type of blockchain network to connect to", }), NETWORK_ENVIRONMENT: str({ choices: ["mainnet", "sepolia"], default: "sepolia", + desc: "The environment of the blockchain network to connect to", }), // blockchain ALCHEMY_API_KEY: str({ devDefault: "dummy" }), diff --git a/packages/shared/src/middlewares/rate.middleware.ts b/packages/shared/src/middlewares/rate.middleware.ts index dc8e9e1..aef2b01 100644 --- a/packages/shared/src/middlewares/rate.middleware.ts +++ b/packages/shared/src/middlewares/rate.middleware.ts @@ -12,7 +12,7 @@ const getClientIP = (c: Context): string => { }; export const limiter = rateLimiter({ - windowMs: 15 * 60 * 1000, // 15 minutes + windowMs: config.RATE_LIMIT_WINDOW_MS, // 15 minutes limit: config.RATE_LIMIT, // 1000 requests per windowMs standardHeaders: "draft-7", keyGenerator: (c) => { From be40f9ad963c10d4fd3709eb618420c1a1c77db4 Mon Sep 17 00:00:00 2001 From: signature18632 Date: Thu, 7 Aug 2025 12:18:39 +0700 Subject: [PATCH 3/5] added API.md doc --- docs/API.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/API.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..abdf6b2 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,92 @@ +# API + +Here are example commands for accessing the INTMAX2 Function APIs using curl. +These services provide various functionalities including indexer services, token management, predicate evaluation, and transaction mapping. + +## Services Overview + +- **Indexer**: Provides block builder node information and proxy metadata +- **Token**: Manages token prices and token mappings +- **Predicate**: Evaluates anti-money laundering (AML) policies +- **TX-Map**: Temporarily stores and retrieves transaction-related key-value mappings + +## API Usage + +### Indexer Service + +```sh +export INDEXER_ENDPOINT='http://localhost:3000' + +# health check +curl "$INDEXER_ENDPOINT/v1/health" | jq + +# fetch block builder nodes +curl "$INDEXER_ENDPOINT/v1/indexer/builders" | jq + +# fetch block builder metadata +curl "$INDEXER_ENDPOINT/v1/indexer/builders/meta" | jq + +# check indexer registration for specific address +curl "$INDEXER_ENDPOINT/v1/indexer/builders/registration/0x..." | jq + +# fetch proxy metadata +curl "$INDEXER_ENDPOINT/v1/proxy/meta" | jq +``` + +### Token Service + +```sh +export TOKEN_ENDPOINT='http://localhost:3000' + +# health check +curl "$TOKEN_ENDPOINT/v1/health" | jq + +# fetch token prices +curl "$TOKEN_ENDPOINT/v1/token-prices/list" | jq + +# fetch token prices with filters +curl "$TOKEN_ENDPOINT/v1/token-prices/list?contractAddresses=0x92d6c1e31e14520e676a687f0a93788b716beff5&contractAddresses=0x6e2a43be0b1d33b726f0ca3b8de60b3482b8b050&perPage=2" | jq + +# fetch token maps +curl "$TOKEN_ENDPOINT/v1/token-maps/list" | jq + +# fetch token maps with filters +curl "$TOKEN_ENDPOINT/v1/token-maps/list?tokenIndexes=1&tokenIndexes=2&perPage=2" | jq +``` + +### Predicate Service + +```sh +export PREDICATE_ENDPOINT='http://localhost:3000' + +# health check +curl "$PREDICATE_ENDPOINT/v1/health" | jq + +# evaluate policy (AML) +curl -X POST "$PREDICATE_ENDPOINT/v1/predicate/evaluate-policy" \ + -H "Content-Type: application/json" \ + -d '{ + "policy": "sample_policy_data" + }' | jq +``` + +### TX-Map Service + +```sh +export TX_MAP_ENDPOINT='http://localhost:3000' + +# health check +curl "$TX_MAP_ENDPOINT/v1/health" | jq + +# store a mapping +curl -X POST "$TX_MAP_ENDPOINT/v1/map" \ + -H "Content-Type: application/json" \ + -d '{ + "digest": "sampledigest123", + "data": "sampledata456", + "expiresIn": 300 + }' | jq + +# retrieve a mapping +curl "$TX_MAP_ENDPOINT/v1/map/sampledigest123" | jq +``` From 1a51924f33fe56521e9fa9fa4328cb189bdac3ca Mon Sep 17 00:00:00 2001 From: signature18632 Date: Thu, 7 Aug 2025 12:23:33 +0700 Subject: [PATCH 4/5] update system design --- docs/SYSTEM_DESIGN.md | 571 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 571 insertions(+) create mode 100644 docs/SYSTEM_DESIGN.md diff --git a/docs/SYSTEM_DESIGN.md b/docs/SYSTEM_DESIGN.md new file mode 100644 index 0000000..aac1507 --- /dev/null +++ b/docs/SYSTEM_DESIGN.md @@ -0,0 +1,571 @@ +# INTMAX2 Function Services - System Design + +## 1. Overview + +The INTMAX2 Function Services is a comprehensive suite of blockchain infrastructure services that support the INTMAX2 ecosystem. It comprises modular services for indexing, token management, deposit analysis, message relaying, monitoring, and various specialized functions to ensure efficient and secure blockchain operations. + +### 1.1 Project Structure + +```txt +packages/ +├── block-sync-monitor/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── deposit-analyzer/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── indexer/ +│ ├── src/ +│ │ ├── controllers/ +│ │ ├── routes/ +│ │ └── lib/ +│ └── package.json +├── indexer-cache-validator/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── indexer-event-watcher/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── indexer-monitor/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── messenger-relayer/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── mint-executor/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── mock-l1-to-l2-relayer/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── mock-l2-to-l1-relayer/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── predicate/ +│ ├── src/ +│ │ ├── controllers/ +│ │ ├── routes/ +│ │ └── services/ +│ └── package.json +├── shared/ +│ ├── src/ +│ │ ├── api/ +│ │ ├── blockchain/ +│ │ ├── bootstrap/ +│ │ ├── config/ +│ │ ├── constants/ +│ │ ├── controllers/ +│ │ ├── db/ +│ │ ├── lib/ +│ │ ├── middlewares/ +│ │ ├── monitor/ +│ │ ├── routes/ +│ │ ├── services/ +│ │ ├── typeChainTypes/ +│ │ ├── types/ +│ │ └── validations/ +│ └── package.json +├── token/ +│ ├── src/ +│ │ ├── controllers/ +│ │ └── routes/ +│ └── package.json +├── token-map-register/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── token-metadata-sync/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +├── tx-map/ +│ ├── src/ +│ │ ├── controllers/ +│ │ └── routes/ +│ └── package.json +├── tx-map-cleaner/ +│ ├── src/ +│ │ └── service/ +│ └── package.json +└── wallet-observer/ + ├── src/ + │ └── service/ + └── package.json +``` + +This mono-repo is organized under the `packages/` directory, with each package focusing on a distinct role: + +**API Services:** +- **indexer**: Provides block builder node information and proxy metadata via REST API +- **token**: Manages token prices and token mappings through REST endpoints +- **predicate**: Evaluates anti-money laundering (AML) policies via API +- **tx-map**: Temporarily stores and retrieves transaction-related key-value mappings + +**Background Services:** +- **deposit-analyzer**: Analyzes and processes deposit transactions on blockchain networks +- **messenger-relayer**: Relays messages using Scroll API for cross-layer communication +- **block-sync-monitor**: Monitors and validates block synchronization between validity prover and rollup contract +- **indexer-event-watcher**: Retrieves and processes information from blockchain nodes +- **indexer-monitor**: Monitors indexer service health and performance +- **indexer-cache-validator**: Validates and maintains indexer cache integrity +- **mint-executor**: Executes minting operations +- **wallet-observer**: Monitors wallet balances and sends notifications +- **token-map-register**: Registers and manages token mappings +- **token-metadata-sync**: Synchronizes token metadata across networks +- **tx-map-cleaner**: Periodically cleans up expired entries in tx-map storage + +**Development Tools:** +- **mock-l1-to-l2-relayer**: Development-only service for L1 to L2 message relay simulation +- **mock-l2-to-l1-relayer**: Development-only service for L2 to L1 message relay simulation + +**Shared Infrastructure:** +- **shared**: Common constants, types, utilities, blockchain interfaces, and configuration shared across all packages + +## 2. High-Level Architecture + +### 2.1 Service Architecture Overview + +```txt +┌─────────────────────────────────────────────────────────────────────────┐ +│ API Layer │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Indexer │ │ Token │ │ Predicate │ │ TX-Map │ │ +│ │ Service │ │ Service │ │ Service │ │ Service │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────┐ +│ Background Services │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Deposit │ │ Messenger │ │ Block Sync │ │ Indexer │ │ +│ │ Analyzer │ │ Relayer │ │ Monitor │ │ Event │ │ +│ │ │ │ │ │ │ │ Watcher │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Wallet │ │ Token │ │ TX-Map │ │ Mint │ │ +│ │ Observer │ │ Metadata │ │ Cleaner │ │ Executor │ │ +│ │ │ │ Sync │ │ │ │ │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────┐ +│ Infrastructure Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ FireStore │ │ Redis │ │ RPC Provider │ │ +│ │ Database │ │ Cache │ │ (Ethereum/Scroll) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The INTMAX2 Function Services architecture is organized into three main layers: + +1. **API Layer**: HTTP REST services that provide external interfaces for indexing, token management, AML evaluation, and transaction mapping +2. **Background Services**: Worker services that handle blockchain monitoring, data processing, cross-layer communication, and maintenance tasks +3. **Infrastructure Layer**: Shared data storage, caching, and blockchain connectivity components + +### 2.2 Data Flow Patterns + +#### API Service Flow + +```txt +Client Request → API Service → Shared Components → Database/Cache → Response +``` + +#### Background Service Flow + +```txt +Blockchain Events → Event Watcher → Data Processing → Database Update → Notifications +``` + +#### Cross-Service Communication + +```txt +Service A → Shared Database/Cache → Service B +Service A → Direct API Call → Service B (where needed) +``` + +## 3. Service Components + +### 3.1 API Services + +#### Indexer Service + +- **Purpose**: Provides block builder node information and proxy metadata +- **Endpoints**: + - `/v1/indexer/builders` - List all block builder nodes + - `/v1/indexer/builders/meta` - Fetch block builder metadata + - `/v1/indexer/builders/registration/{address}` - Check indexer registration + - `/v1/proxy/meta` - Fetch proxy metadata +- **Caching**: Implements intelligent caching with configurable TTL for different endpoint types +- **Dependencies**: Blockchain RPC provider, Redis cache + +#### Token Service + +- **Purpose**: Manages token prices and token mappings +- **Endpoints**: + - `/v1/token-prices/list` - Fetch token prices with filtering capabilities + - `/v1/token-maps/list` - Fetch token mappings with filtering capabilities +- **Features**: Supports filtering by contract addresses, token indexes, and pagination +- **Dependencies**: External price feeds, database storage + +#### Predicate Service + +- **Purpose**: Evaluates anti-money laundering (AML) policies +- **Endpoints**: + - `/v1/predicate/evaluate-policy` - Evaluate AML policies for transactions +- **Security**: Implements strict input validation and policy verification +- **Dependencies**: AML policy engine, compliance databases + +#### TX-Map Service + +- **Purpose**: Temporarily stores and retrieves transaction-related key-value mappings +- **Endpoints**: + - `POST /v1/map` - Store a key-value mapping with expiration + - `GET /v1/map/{digest}` - Retrieve a mapping by digest +- **Features**: TTL-based expiration, digest-based key lookup +- **Dependencies**: Redis for temporary storage + +### 3.2 Background Services + +#### Deposit Analyzer + +- **Purpose**: Analyzes and processes deposit transactions on blockchain networks +- **Functions**: + - Monitors deposit events from smart contracts + - Batches deposits for efficient processing + - Calculates gas optimization strategies + - Manages deposit state transitions +- **Dependencies**: Blockchain RPC, PostgreSQL database + +#### Messenger Relayer + +- **Purpose**: Relays messages using Scroll API for cross-layer communication +- **Functions**: + - Handles L1 to L2 and L2 to L1 message relaying + - Manages message queue and retry logic + - Processes withdrawal and claimable transactions + - Integrates with Scroll Messenger contracts +- **Dependencies**: Scroll API, Ethereum/Scroll RPC providers + +#### Block Sync Monitor + +- **Purpose**: Monitors and validates block synchronization between validity prover and rollup contract +- **Functions**: + - Tracks block synchronization status + - Validates block consistency across layers + - Alerts on synchronization issues + - Maintains synchronization metrics +- **Dependencies**: Multiple RPC providers, monitoring systems + +#### Indexer Event Watcher + +- **Purpose**: Retrieves and processes information from blockchain nodes +- **Functions**: + - Continuously monitors blockchain events + - Filters and processes relevant events + - Updates indexer state and metadata + - Maintains event logs for audit trails +- **Dependencies**: Blockchain RPC providers, PostgreSQL + +#### Wallet Observer + +- **Purpose**: Monitors wallet balances and sends notifications +- **Functions**: + - Tracks wallet balance changes + - Sends notifications for significant changes + - Maintains balance history + - Supports multiple wallet types +- **Dependencies**: Blockchain RPC, notification services + +#### Token Metadata Sync + +- **Purpose**: Synchronizes token metadata across networks +- **Functions**: + - Fetches token metadata from various sources + - Synchronizes metadata across L1/L2 + - Validates metadata consistency + - Updates token registries +- **Dependencies**: Multiple blockchain networks, IPFS + +#### TX-Map Cleaner + +- **Purpose**: Periodically cleans up expired entries in tx-map storage +- **Functions**: + - Scans for expired mappings + - Removes outdated entries + - Optimizes storage usage + - Maintains cleanup logs +- **Dependencies**: Redis, scheduled job system + +### 3.3 Development and Testing Services + +#### Mock L1-to-L2 Relayer + +- **Purpose**: Development-only service for simulating L1 to L2 message relay +- **Scope**: Development environment only +- **Functions**: Simulates cross-layer message relay for testing + +#### Mock L2-to-L1 Relayer + +- **Purpose**: Development-only service for simulating L2 to L1 message relay +- **Scope**: Development environment only +- **Functions**: Simulates reverse cross-layer message relay for testing + +### 3.4 Monitoring and Maintenance Services + +#### Indexer Monitor + +- **Purpose**: Monitors indexer service health and performance +- **Functions**: + - Health checks for indexer services + - Performance metrics collection + - Alert generation for service issues + - Service availability tracking + +#### Indexer Cache Validator + +- **Purpose**: Validates and maintains indexer cache integrity +- **Functions**: + - Cache consistency validation + - Cache refresh operations + - Performance optimization + - Cache health monitoring + +### 3.5 Shared Infrastructure + +#### Shared Library (`@intmax2-function/shared`) + +- **Components**: + - **Configuration Management**: Environment-based configuration with validation + - **Blockchain Interfaces**: Standardized blockchain interaction utilities + - **Database Schemas**: Shared data models and migration utilities + - **Logging**: Structured logging with centralized configuration + - **Middleware**: Common HTTP middleware for CORS, security, rate limiting + - **Utilities**: Helper functions for common operations + - **Type Definitions**: Shared TypeScript types and interfaces +- **Features**: + - Health check endpoints for all services + - Error handling and reporting utilities + - Caching abstractions with Redis integration + - Blockchain event processing utilities + +## 4. Data Flow and Integration Patterns + +### 4.1 API Service Data Flow + +```txt +1. Client Request → API Gateway/Load Balancer +2. API Service (Indexer/Token/Predicate/TX-Map) +3. Input Validation & Authentication +4. Business Logic Processing +5. Data Layer Access (PostgreSQL/Redis/External APIs) +6. Response Formatting & Caching +7. Client Response +``` + +### 4.2 Background Service Data Flow + +```txt +1. Event Detection (Blockchain/Timer/Queue) +2. Event Processing & Validation +3. Business Logic Execution +4. Database Operations (CRUD) +5. Inter-Service Communication (if needed) +6. Status Updates & Logging +7. Notification/Alert Generation (if needed) +``` + +### 4.3 Cross-Service Communication + +#### Database-Mediated Communication +- Services share data through PostgreSQL databases +- Event-driven updates through database triggers +- Shared caching layer using Redis + +#### Direct API Communication +- Service-to-service HTTP calls for real-time data +- Health check propagation between dependent services +- Configuration synchronization + +#### Message Queue Pattern +- Redis-based job queues for async processing +- Event broadcasting for status updates +- Background job scheduling and execution + +### 4.4 Monitoring and Observability Flow + +```txt +1. Service Metrics Collection → Structured Logging +2. Health Status Aggregation → Centralized Monitoring +3. Alert Generation → Notification Systems +4. Performance Analytics → Dashboard Updates +``` + +## 5. Data Storage and Persistence + +### 5.1 Database Architecture + +#### PostgreSQL Databases +- **Primary Database**: Core application data, user accounts, service configurations +- **Events Database**: Blockchain event logs, transaction histories, audit trails +- **Analytics Database**: Performance metrics, usage statistics, operational data + +#### Redis Cache & Queues +- **Application Cache**: API response caching, session data, temporary computations +- **Job Queues**: Background task queues, message relay queues, cleanup jobs +- **Rate Limiting**: API rate limiting counters, abuse prevention + +### 5.2 Data Models + +#### Core Entities +- **Tokens**: Token metadata, pricing data, contract addresses +- **Transactions**: Deposit/withdrawal records, cross-layer messages +- **Users/Wallets**: Wallet addresses, balance histories, notification preferences +- **Indexer Data**: Block builder information, node metadata, registration status + +#### Event Logs +- **Blockchain Events**: Contract events, transaction logs, block data +- **Service Events**: Internal service events, error logs, performance metrics +- **Audit Trails**: User actions, administrative operations, system changes + +### 5.3 Data Synchronization + +#### Cross-Layer Synchronization +- L1 ↔ L2 state synchronization via message relayers +- Token metadata consistency across networks +- Balance reconciliation and validation + +#### Cache Invalidation +- TTL-based cache expiration +- Event-driven cache invalidation +- Manual cache refresh for critical data + +## 6. Scalability & Reliability + +### 6.1 Horizontal Scaling + +- **Stateless API Services**: All API services (indexer, token, predicate, tx-map) can scale horizontally +- **Load Balancing**: Services support multiple instances behind load balancers +- **Database Sharding**: PostgreSQL databases can be sharded by service domain +- **Cache Distribution**: Redis clustering for distributed caching across instances + +### 6.2 Reliability Patterns + +- **Idempotent Operations**: All background services support safe operation retries +- **Circuit Breakers**: API services implement circuit breakers for external dependencies +- **Graceful Degradation**: Services continue operating with reduced functionality during outages +- **Database Replication**: Master-slave PostgreSQL setup for read scaling and failover + +### 6.3 Performance Optimization + +- **Intelligent Caching**: Multi-level caching with different TTL strategies per service +- **Connection Pooling**: Efficient database connection management +- **Background Processing**: Async processing for non-critical operations +- **Rate Limiting**: API rate limiting to prevent abuse and ensure fair usage + +### 6.4 Health Monitoring + +- **Health Endpoints**: All services expose standardized health check endpoints +- **Dependency Checks**: Health checks validate external service connectivity +- **Metrics Collection**: Structured logging and metrics for monitoring and alerting +- **Alert Systems**: Automated alerts for service failures and performance degradation + +## 7. Security + +### 7.1 API Security + +- **Input Validation**: Strict validation for all API inputs and parameters +- **Rate Limiting**: Protection against DDoS and abuse attacks +- **CORS Configuration**: Proper cross-origin resource sharing controls +- **Security Headers**: Implementation of security headers (HSTS, CSP, etc.) + +### 7.2 Blockchain Security + +- **Contract Validation**: Smart contract interaction validation and verification +- **Transaction Security**: Secure transaction signing and submission processes +- **Event Verification**: Blockchain event authenticity verification +- **Private Key Management**: Secure storage and handling of cryptographic keys + +### 7.3 Infrastructure Security + +- **Database Access Control**: Role-based PostgreSQL access with minimal privileges +- **Environment Isolation**: Secure separation between development, staging, and production +- **Configuration Management**: Secure handling of sensitive configuration via environment variables +- **Network Security**: VPC isolation and secure inter-service communication + +### 7.4 Data Protection + +- **Data Encryption**: Encryption at rest for sensitive data +- **Audit Logging**: Comprehensive audit trails for all operations +- **Data Retention**: Policies for data lifecycle management and cleanup +- **Privacy Compliance**: GDPR and privacy regulation compliance measures + +## 8. Development & Operations + +### 8.1 Development Environment + +- **Monorepo Structure**: Yarn workspaces for unified dependency management +- **Package Management**: Individual package configurations with shared dependencies +- **Development Servers**: Hot-reload development servers for each service +- **Mock Services**: L1/L2 relayer mocks for local development and testing + +### 8.2 Testing Strategy + +- **Unit Testing**: Vitest-based unit tests for individual service components +- **Integration Testing**: Service-to-service integration test suites +- **API Testing**: REST API endpoint testing with various scenarios +- **E2E Testing**: End-to-end workflow testing across multiple services + +### 8.3 Build & Deployment + +- **Build System**: TypeScript compilation with optimized production builds +- **Containerization**: Docker containers for consistent deployment environments +- **CI/CD Pipeline**: Automated testing, building, and deployment workflows +- **Environment Management**: Environment-specific configuration and secrets management + +### 8.4 Database Management + +- **Schema Migrations**: Version-controlled database schema migrations +- **Data Seeding**: Automated data seeding for development and testing +- **Backup & Recovery**: Automated database backup and recovery procedures +- **Performance Monitoring**: Database performance monitoring and optimization + +## 9. Observability & Monitoring + +### 9.1 Logging + +- **Structured Logging**: JSON-formatted logs with consistent schema across all services +- **Log Aggregation**: Centralized log collection and analysis +- **Log Retention**: Configurable log retention policies by service and environment +- **Error Tracking**: Automatic error detection and alerting + +### 9.2 Metrics & Analytics + +- **Performance Metrics**: Service response times, throughput, and error rates +- **Business Metrics**: Transaction volumes, user activity, and service usage +- **Infrastructure Metrics**: System resource usage, database performance +- **Custom Dashboards**: Service-specific monitoring dashboards + +### 9.3 Alerting + +- **Health Monitoring**: Automated health checks with configurable thresholds +- **Performance Alerts**: Alerts for response time degradation and error spikes +- **Business Logic Alerts**: Domain-specific alerts for unusual patterns +- **Escalation Procedures**: Automated escalation for critical system failures + +### 9.4 Debugging & Troubleshooting + +- **Distributed Tracing**: Request tracing across multiple services +- **Debug Endpoints**: Development-only endpoints for service introspection +- **Log Correlation**: Request ID tracking across service boundaries +- **Performance Profiling**: Application performance profiling and optimization tools \ No newline at end of file From c78157865a4ef860d9152be38d05b34fa3fd3058 Mon Sep 17 00:00:00 2001 From: signature18632 Date: Thu, 7 Aug 2025 13:05:00 +0700 Subject: [PATCH 5/5] update system design --- docs/SYSTEM_DESIGN.md | 471 +++++++++++++++++----------- packages/shared/src/config/index.ts | 73 ++++- 2 files changed, 342 insertions(+), 202 deletions(-) diff --git a/docs/SYSTEM_DESIGN.md b/docs/SYSTEM_DESIGN.md index aac1507..e6015b4 100644 --- a/docs/SYSTEM_DESIGN.md +++ b/docs/SYSTEM_DESIGN.md @@ -178,20 +178,13 @@ The INTMAX2 Function Services architecture is organized into three main layers: #### API Service Flow ```txt -Client Request → API Service → Shared Components → Database/Cache → Response +Client Request → API Service → Database/Cache → Response ``` #### Background Service Flow ```txt -Blockchain Events → Event Watcher → Data Processing → Database Update → Notifications -``` - -#### Cross-Service Communication - -```txt -Service A → Shared Database/Cache → Service B -Service A → Direct API Call → Service B (where needed) +Start Background Service → Process Data → (Submit Transaction / Send Notification / Update Database) ``` ## 3. Service Components @@ -211,12 +204,16 @@ Service A → Direct API Call → Service B (where needed) #### Token Service -- **Purpose**: Manages token prices and token mappings +- **Purpose**: Provides comprehensive token information including prices and mappings for INTMAX2 network - **Endpoints**: - `/v1/token-prices/list` - Fetch token prices with filtering capabilities - `/v1/token-maps/list` - Fetch token mappings with filtering capabilities -- **Features**: Supports filtering by contract addresses, token indexes, and pagination -- **Dependencies**: External price feeds, database storage +- **Features**: + - Supports filtering by contract addresses, token indexes, and pagination + - Returns token metadata including prices, symbols, decimals, and INTMAX2 tokenIndex mappings + - Provides real-time token information for bridged assets +- **Data Sources**: FireStore database containing token mappings and metadata synchronized by background services +- **Dependencies**: FireStore database, token-metadata-sync service, token-map-register service #### Predicate Service @@ -239,23 +236,39 @@ Service A → Direct API Call → Service B (where needed) #### Deposit Analyzer -- **Purpose**: Analyzes and processes deposit transactions on blockchain networks +- **Purpose**: Analyzes and processes deposit transactions on blockchain networks with gas optimization through intelligent batching - **Functions**: - - Monitors deposit events from smart contracts - - Batches deposits for efficient processing - - Calculates gas optimization strategies - - Manages deposit state transitions -- **Dependencies**: Blockchain RPC, PostgreSQL database + - Monitors deposit events from Liquidity smart contracts + - Collects and analyzes deposit transaction data from blockchain events + - Implements intelligent batching mechanism to optimize gas costs for relay operations + - Groups multiple deposits together for efficient batch processing and relay to reduce per-transaction gas fees + - Calculates optimal batch sizes based on gas limits and transaction costs + - Manages deposit state transitions and relay scheduling + - Ensures reliable delivery of batched deposit data to target networks +- **Gas Optimization Strategy**: + - Batches multiple deposit events into single relay transactions + - Reduces overall gas consumption compared to individual deposit relays + - Implements configurable thresholds for batch size and timing optimization +- **Dependencies**: Blockchain RPC, Liquidity contract events, FireStore database #### Messenger Relayer -- **Purpose**: Relays messages using Scroll API for cross-layer communication +- **Purpose**: Facilitates cross-layer communication by relaying messages from L2 to L1 using Scroll API and Messenger contracts - **Functions**: - - Handles L1 to L2 and L2 to L1 message relaying - - Manages message queue and retry logic - - Processes withdrawal and claimable transactions - - Integrates with Scroll Messenger contracts -- **Dependencies**: Scroll API, Ethereum/Scroll RPC providers + - Monitors withdrawal and claim contract events for `submitWithdrawalProof` transactions + - Retrieves L2-to-L1 message data from Scroll Messenger API when proof submissions are detected + - Processes and formats message data for L1 submission + - Submits `relayMessageWithProof` transactions to L1 Scroll Messenger contract + - Triggers Liquidity contract state changes on L1 based on relayed message data + - Implements retry logic with gas optimization for failed transactions + - Handles message verification and proof validation +- **Message Flow**: + 1. **Event Detection**: Monitors L2 withdrawal/claim contracts for `submitWithdrawalProof` events + 2. **Data Retrieval**: Fetches corresponding message data from L2 Scroll Messenger API + 3. **Message Relay**: Submits `relayMessageWithProof` to L1 Scroll Messenger contract + 4. **Contract Update**: L1 Scroll Messenger triggers Liquidity contract state changes +- **Error Handling**: Comprehensive retry mechanism with exponential backoff and gas fee adjustment +- **Dependencies**: Scroll API, Ethereum/Scroll RPC providers, L1/L2 Scroll Messenger contracts, Liquidity contract #### Block Sync Monitor @@ -269,13 +282,15 @@ Service A → Direct API Call → Service B (where needed) #### Indexer Event Watcher -- **Purpose**: Retrieves and processes information from blockchain nodes +- **Purpose**: Monitors block builder activity and maintains registry information through blockchain event processing - **Functions**: - - Continuously monitors blockchain events - - Filters and processes relevant events - - Updates indexer state and metadata - - Maintains event logs for audit trails -- **Dependencies**: Blockchain RPC providers, PostgreSQL + - Continuously monitors Block Builder Registry contract for `blockBuilderHeartbeatEvent` events + - Processes heartbeat events from active block builders to track their operational status + - Updates FireStore database with latest block builder information and activity timestamps + - Maintains event logs and audit trails for block builder activities + - Implements automatic inactive status assignment for builders without 24-hour heartbeat updates +- **Activity Monitoring**: Tracks block builder heartbeats and marks inactive builders (>24h without updates) as `active: false` +- **Dependencies**: Blockchain RPC providers (Scroll), Block Builder Registry contract, FireStore database #### Wallet Observer @@ -289,13 +304,28 @@ Service A → Direct API Call → Service B (where needed) #### Token Metadata Sync -- **Purpose**: Synchronizes token metadata across networks +- **Purpose**: Periodically synchronizes token metadata and pricing information across networks +- **Functions**: + - Fetches up-to-date token metadata from multiple blockchain networks (L1/L2) + - Retrieves real-time pricing information from external price feeds and market data providers + - Validates and normalizes token metadata (name, symbol, decimals, contract addresses) + - Updates FireStore database with the latest token information + - Ensures data consistency across different network environments +- **Schedule**: Runs periodically to maintain current token information +- **Dependencies**: Multiple blockchain networks (Ethereum, Scroll), external price APIs, FireStore database + +#### Token Map Register + +- **Purpose**: Monitors blockchain events and registers new token mappings for INTMAX2 network bridged assets - **Functions**: - - Fetches token metadata from various sources - - Synchronizes metadata across L1/L2 - - Validates metadata consistency - - Updates token registries -- **Dependencies**: Multiple blockchain networks, IPFS + - Continuously monitors Liquidity contract events for newly bridged tokens + - Detects bridge deposit events when tokens are first introduced to INTMAX2 network + - Creates tokenIndex mappings for newly bridged assets in INTMAX2 system + - Associates L1/L2 token contract addresses with their corresponding INTMAX2 tokenIndex + - Updates FireStore database with new token mapping relationships + - Maintains the authoritative registry of all supported tokens in the INTMAX2 ecosystem +- **Event Sources**: Liquidity contract bridge events, token registration events +- **Dependencies**: Blockchain RPC providers, Liquidity contract, FireStore database #### TX-Map Cleaner @@ -315,7 +345,7 @@ Service A → Direct API Call → Service B (where needed) - **Scope**: Development environment only - **Functions**: Simulates cross-layer message relay for testing -#### Mock L2-to-L1 Relayer +#### Mock L2-to-L1 Relayer - **Purpose**: Development-only service for simulating L2 to L1 message relay - **Scope**: Development environment only @@ -325,21 +355,29 @@ Service A → Direct API Call → Service B (where needed) #### Indexer Monitor -- **Purpose**: Monitors indexer service health and performance +- **Purpose**: Validates and monitors active block builders to ensure service quality and availability - **Functions**: - - Health checks for indexer services - - Performance metrics collection - - Alert generation for service issues - - Service availability tracking + - Periodically performs health checks on block builders with recent data updates + - Validates ETH balance sufficiency for continued block builder operations + - Verifies block builder service availability and response times + - Updates block builder status to `active: true` for validated builders + - Monitors service degradation and performance issues + - Maintains operational metrics for block builder performance analysis +- **Validation Criteria**: Health check success, sufficient ETH balance, service responsiveness +- **Dependencies**: Block builder endpoints, blockchain RPC providers, FireStore database #### Indexer Cache Validator -- **Purpose**: Validates and maintains indexer cache integrity +- **Purpose**: Continuously validates cached block builder information to ensure service reliability - **Functions**: - - Cache consistency validation - - Cache refresh operations - - Performance optimization - - Cache health monitoring + - Monitors health status of cached block builders during their cache lifetime + - Performs real-time validation of ETH balance for cached builders + - Conducts ongoing health checks to verify service availability + - Removes invalidated builders from cache when issues are detected + - Maintains cache integrity and prevents serving of unreliable block builders + - Implements automated cache refresh for validated builders +- **Monitoring Scope**: Cached block builders only, real-time validation during cache period +- **Dependencies**: Block builder endpoints, blockchain RPC providers, Redis cache, FireStore database ### 3.5 Shared Infrastructure @@ -368,7 +406,7 @@ Service A → Direct API Call → Service B (where needed) 2. API Service (Indexer/Token/Predicate/TX-Map) 3. Input Validation & Authentication 4. Business Logic Processing -5. Data Layer Access (PostgreSQL/Redis/External APIs) +5. Data Layer Access (FireStore/Redis/External APIs) 6. Response Formatting & Caching 7. Client Response ``` @@ -376,196 +414,255 @@ Service A → Direct API Call → Service B (where needed) ### 4.2 Background Service Data Flow ```txt -1. Event Detection (Blockchain/Timer/Queue) -2. Event Processing & Validation -3. Business Logic Execution -4. Database Operations (CRUD) -5. Inter-Service Communication (if needed) -6. Status Updates & Logging -7. Notification/Alert Generation (if needed) +Start Background Service + ↓ +Process Data + └─→ Event Detection + └─→ Processing & Validation + └─→ Business Logic Execution + └─→ Status Updates & Logging + ↓ +Trigger Action + └─→ Submit Transaction + └─→ Send Notification / Alert + └─→ Database Operations (CRUD) ``` -### 4.3 Cross-Service Communication +### 4.3 Deposit Processing System Data Flow -#### Database-Mediated Communication -- Services share data through PostgreSQL databases -- Event-driven updates through database triggers -- Shared caching layer using Redis +The deposit processing system optimizes gas costs through intelligent batching and relay operations: -#### Direct API Communication -- Service-to-service HTTP calls for real-time data -- Health check propagation between dependent services -- Configuration synchronization +```txt +┌─────────────────────────────────────────────────────────────────────────┐ +│ Deposit Processing System Flow │ +└─────────────────────────────────────────────────────────────────────────┘ -#### Message Queue Pattern -- Redis-based job queues for async processing -- Event broadcasting for status updates -- Background job scheduling and execution +1. Event Monitoring (Deposit Analyzer) + Liquidity Contract Events → Deposit Analyzer → Event Collection -### 4.4 Monitoring and Observability Flow +2. Batch Optimization (Deposit Analyzer) + Individual Deposits → Batching Algorithm → Optimized Batches -```txt -1. Service Metrics Collection → Structured Logging -2. Health Status Aggregation → Centralized Monitoring -3. Alert Generation → Notification Systems -4. Performance Analytics → Dashboard Updates +3. Relay Execution (Deposit Analyzer) + Batched Deposits → Gas-Optimized Relay → Target Network ``` -## 5. Data Storage and Persistence +#### Detailed Process Flow: -### 5.1 Database Architecture +1. **Event Detection and Collection**: + - Continuously monitors Liquidity contract for deposit events + - Captures deposit transaction details (amount, token, recipient, etc.) + - Validates and stores deposit event data in FireStore -#### PostgreSQL Databases -- **Primary Database**: Core application data, user accounts, service configurations -- **Events Database**: Blockchain event logs, transaction histories, audit trails -- **Analytics Database**: Performance metrics, usage statistics, operational data +2. **Intelligent Batching Algorithm**: + - Analyzes accumulated deposit events for batching opportunities + - Calculates optimal batch sizes based on gas limits and cost efficiency + - Groups compatible deposits together (same target network, token type, etc.) + - Implements configurable thresholds for batch timing and size -#### Redis Cache & Queues -- **Application Cache**: API response caching, session data, temporary computations -- **Job Queues**: Background task queues, message relay queues, cleanup jobs -- **Rate Limiting**: API rate limiting counters, abuse prevention +3. **Gas-Optimized Relay Execution**: + - Executes batched deposits as single relay transactions + - Significantly reduces gas costs compared to individual deposit processing + - Ensures reliable delivery and proper state management + - Updates deposit status and maintains audit trails -### 5.2 Data Models +### 4.4 Cross-Layer Message Relay System Data Flow -#### Core Entities -- **Tokens**: Token metadata, pricing data, contract addresses -- **Transactions**: Deposit/withdrawal records, cross-layer messages -- **Users/Wallets**: Wallet addresses, balance histories, notification preferences -- **Indexer Data**: Block builder information, node metadata, registration status +The cross-layer message relay system enables secure communication between L2 and L1 networks: -#### Event Logs -- **Blockchain Events**: Contract events, transaction logs, block data -- **Service Events**: Internal service events, error logs, performance metrics -- **Audit Trails**: User actions, administrative operations, system changes +```txt +┌────────────────────────────────────────────────────────────────────────────┐ +│ Cross-Layer Message Relay System Flow │ +└────────────────────────────────────────────────────────────────────────────┘ -### 5.3 Data Synchronization +1. Proof Submission Detection (Withdrawal / Claim Aggregator) + withdrawal aggregator / claim aggregator → submitWithdrawalProof / submitClaimProof → L2 Withdrawal / Claim Contracts -#### Cross-Layer Synchronization -- L1 ↔ L2 state synchronization via message relayers -- Token metadata consistency across networks -- Balance reconciliation and validation +2. Message Data Retrieval (Messenger Relayer) + L2 Scroll Messenger API → Message & Proof Data -#### Cache Invalidation -- TTL-based cache expiration -- Event-driven cache invalidation -- Manual cache refresh for critical data +3. L1 Message Relay (Messenger Relayer) + Message & Proof Data → relayMessageWithProof → L1 Scroll Messenger Contract -## 6. Scalability & Reliability +4. State Update Execution (L1 Scroll Messenger) + L1 Scroll Messenger Contract → Liquidity Contract → State Changes +``` -### 6.1 Horizontal Scaling +#### Detailed Process Flow: -- **Stateless API Services**: All API services (indexer, token, predicate, tx-map) can scale horizontally -- **Load Balancing**: Services support multiple instances behind load balancers -- **Database Sharding**: PostgreSQL databases can be sharded by service domain -- **Cache Distribution**: Redis clustering for distributed caching across instances +1. **Event Monitoring and Detection**: + - Continuously monitors L2 withdrawal and claim contracts + - Detects `submitWithdrawalProof` transaction events + - Extracts transaction details and proof submission information + - Validates event authenticity and completeness -### 6.2 Reliability Patterns +2. **Message Data Retrieval from L2**: + - Queries L2 Scroll Messenger API with detected event data + - Retrieves complete message payload including: + - Source and destination addresses (from, to) + - Transaction value and nonce + - Message data and proof information + - Merkle proof and batch index for verification + - Validates retrieved data integrity and format -- **Idempotent Operations**: All background services support safe operation retries -- **Circuit Breakers**: API services implement circuit breakers for external dependencies -- **Graceful Degradation**: Services continue operating with reduced functionality during outages -- **Database Replication**: Master-slave PostgreSQL setup for read scaling and failover +3. **L1 Message Relay Execution**: + - Formats retrieved data for L1 Scroll Messenger contract + - Submits `relayMessageWithProof` transaction to L1 network + - Implements retry logic with exponential gas fee increases + - Handles transaction failures and replacement scenarios + - Monitors transaction confirmation and finality -### 6.3 Performance Optimization +4. **Liquidity Contract State Updates**: + - L1 Scroll Messenger contract validates message proof + - Executes state changes on Liquidity contract based on message data + - Updates withdrawal/claim statuses and balances + - Maintains audit trail of cross-layer operations -- **Intelligent Caching**: Multi-level caching with different TTL strategies per service -- **Connection Pooling**: Efficient database connection management -- **Background Processing**: Async processing for non-critical operations -- **Rate Limiting**: API rate limiting to prevent abuse and ensure fair usage +### 4.5 Token Mapping System Data Flow -### 6.4 Health Monitoring +The token mapping system is a comprehensive pipeline that maintains accurate token information for the INTMAX2 network: -- **Health Endpoints**: All services expose standardized health check endpoints -- **Dependency Checks**: Health checks validate external service connectivity -- **Metrics Collection**: Structured logging and metrics for monitoring and alerting -- **Alert Systems**: Automated alerts for service failures and performance degradation +```txt +┌─────────────────────────────────────────────────────────────────────────┐ +│ Token Mapping System Flow │ +└─────────────────────────────────────────────────────────────────────────┘ -## 7. Security +1. Token Metadata Collection (Token Metadata Sync) + External Price APIs → Token Metadata Sync → FireStore Database -### 7.1 API Security +2. Bridge Event Monitoring (Token Map Register) + Liquidity Contract Events → Token Map Register → FireStore Database -- **Input Validation**: Strict validation for all API inputs and parameters -- **Rate Limiting**: Protection against DDoS and abuse attacks -- **CORS Configuration**: Proper cross-origin resource sharing controls -- **Security Headers**: Implementation of security headers (HSTS, CSP, etc.) +3. API Data Retrieval (Token Service) + Client Request → Token API → FireStore Database → Formatted Response +``` -### 7.2 Blockchain Security +#### Detailed Process Flow: -- **Contract Validation**: Smart contract interaction validation and verification -- **Transaction Security**: Secure transaction signing and submission processes -- **Event Verification**: Blockchain event authenticity verification -- **Private Key Management**: Secure storage and handling of cryptographic keys +1. **Token Metadata Sync Service**: + - Periodically fetches token pricing data from external APIs + - Retrieves token metadata (name, symbol, decimals) from blockchain networks + - Validates and normalizes token information + - Updates FireStore with the latest token data -### 7.3 Infrastructure Security +2. **Token Map Register Service**: + - Monitors Liquidity contract for new bridge deposit events + - Detects when tokens are first bridged to INTMAX2 network + - Creates tokenIndex mappings for newly bridged assets + - Associates L1/L2 contract addresses with INTMAX2 tokenIndex + - Stores complete token mapping relationships in FireStore -- **Database Access Control**: Role-based PostgreSQL access with minimal privileges -- **Environment Isolation**: Secure separation between development, staging, and production -- **Configuration Management**: Secure handling of sensitive configuration via environment variables -- **Network Security**: VPC isolation and secure inter-service communication +3. **Token API Service**: + - Receives client requests for token information + - Queries FireStore database for token mappings and metadata + - Returns comprehensive token data including prices, metadata, and tokenIndex mappings + - Supports filtering by contract addresses, token indexes, and pagination -### 7.4 Data Protection +### 4.6 Cross-Service Communication -- **Data Encryption**: Encryption at rest for sensitive data -- **Audit Logging**: Comprehensive audit trails for all operations -- **Data Retention**: Policies for data lifecycle management and cleanup -- **Privacy Compliance**: GDPR and privacy regulation compliance measures +#### Database-Mediated Communication -## 8. Development & Operations +- Services share data through FireStore databases +- Event-driven updates through database triggers +- Shared caching layer using Redis -### 8.1 Development Environment +#### Direct API Communication -- **Monorepo Structure**: Yarn workspaces for unified dependency management -- **Package Management**: Individual package configurations with shared dependencies -- **Development Servers**: Hot-reload development servers for each service -- **Mock Services**: L1/L2 relayer mocks for local development and testing +- Service-to-service HTTP calls for real-time data +- Health check propagation between dependent services +- Configuration synchronization -### 8.2 Testing Strategy +### 4.8 Block Builder Indexer System Data Flow -- **Unit Testing**: Vitest-based unit tests for individual service components -- **Integration Testing**: Service-to-service integration test suites -- **API Testing**: REST API endpoint testing with various scenarios -- **E2E Testing**: End-to-end workflow testing across multiple services +The block builder indexer system ensures reliable and validated block builder service discovery: -### 8.3 Build & Deployment +```txt +┌─────────────────────────────────────────────────────────────────────────┐ +│ Block Builder Indexer System Flow │ +└─────────────────────────────────────────────────────────────────────────┘ + +1. Heartbeat Monitoring (Indexer Event Watcher) + Block Builder Registry Contract → blockBuilderHeartbeatEvent → FireStore Update -- **Build System**: TypeScript compilation with optimized production builds -- **Containerization**: Docker containers for consistent deployment environments -- **CI/CD Pipeline**: Automated testing, building, and deployment workflows -- **Environment Management**: Environment-specific configuration and secrets management +2. Activity Validation (Indexer Event Watcher) + 24-Hour Activity Check → Inactive Builder Detection → Status Update (active: false) -### 8.4 Database Management +3. Health Validation (Indexer Monitor) + Updated Builders → Health Check + ETH Balance → Validation → Status Update (active: true) + +4. Client Response (Indexer Service) + Client Request → Active Builders Query → Random Selection → Cached Response + +5. Cache Validation (Indexer Cache Validator) + Cached Builders → Real-time Health Check → Cache Update/Invalidation +``` -- **Schema Migrations**: Version-controlled database schema migrations -- **Data Seeding**: Automated data seeding for development and testing -- **Backup & Recovery**: Automated database backup and recovery procedures -- **Performance Monitoring**: Database performance monitoring and optimization +#### Detailed Process Flow: + +1. **Heartbeat Event Monitoring (Indexer Event Watcher)**: + - Continuously monitors Block Builder Registry contract on Scroll network + - Detects `blockBuilderHeartbeatEvent` events from active block builders + - Extracts builder information and timestamp data from events + - Updates FireStore database with latest builder activity information + - Implements automatic marking of builders as inactive if no heartbeat received within 24 hours + +2. **Health and Resource Validation (Indexer Monitor)**: + - Periodically scans FireStore for block builders with recent data updates + - Performs comprehensive health checks on each builder endpoint + - Validates ETH balance sufficiency for continued operations + - Verifies service availability and response time metrics + - Updates builder status to `active: true` for successfully validated builders + - Maintains performance metrics and operational analytics + +3. **Client Service and Response (Indexer Service)**: + - Receives client requests for block builder information + - Queries FireStore for block builders with `active: true` status + - Implements random selection algorithm for load distribution + - Returns selected block builder information to clients + - Caches responses for configurable time periods to reduce database load + +4. **Cache Integrity Monitoring (Indexer Cache Validator)**: + - Monitors cached block builders during their cache lifetime + - Performs real-time health checks and ETH balance validation + - Detects service degradation or resource insufficiency + - Automatically removes invalidated builders from cache + - Ensures clients receive only reliable and operational builder information + +#### System Benefits: +- **High Availability**: Multiple validation layers ensure service reliability +- **Load Distribution**: Random selection provides balanced load across builders +- **Real-time Monitoring**: Continuous validation prevents serving of failed builders +- **Resource Efficiency**: Caching reduces database queries while maintaining data integrity + +### 4.9 Monitoring and Observability Flow -## 9. Observability & Monitoring +```txt +1. Service Metrics Collection → Structured Logging +2. Health Status Aggregation → Centralized Monitoring +3. Alert Generation → Notification Systems +``` -### 9.1 Logging +## 5. Scalability & Reliability -- **Structured Logging**: JSON-formatted logs with consistent schema across all services -- **Log Aggregation**: Centralized log collection and analysis -- **Log Retention**: Configurable log retention policies by service and environment -- **Error Tracking**: Automatic error detection and alerting +- **Stateless Services**: All services can scale horizontally behind a load balancer. +- **Eventual Consistency**: The jobs can be retried, idempotent. +- **Redis Caching**: Reduces read load on Firestore for popular queries. +- **Rate Limiting & API Keys**: Protects against abuse. +- **Health Checks & Monitoring**: `/health` endpoint and telemetry via structured logs. -### 9.2 Metrics & Analytics +## 6. Security -- **Performance Metrics**: Service response times, throughput, and error rates -- **Business Metrics**: Transaction volumes, user activity, and service usage -- **Infrastructure Metrics**: System resource usage, database performance -- **Custom Dashboards**: Service-specific monitoring dashboards +- **CORS**: Configurable whitelist of origins. +- **Input Validation**: Strict schema for query parameters; prevents injection. -### 9.3 Alerting +## 7. CI/CD & Testing -- **Health Monitoring**: Automated health checks with configurable thresholds -- **Performance Alerts**: Alerts for response time degradation and error spikes -- **Business Logic Alerts**: Domain-specific alerts for unusual patterns -- **Escalation Procedures**: Automated escalation for critical system failures +- **Vitest** unit and integration tests coverage for services and middleware. +- **Tasks**: `yarn test`, `yarn check`, `yarn build` in CI pipeline. +- **Docker**: Containerized deployment using provided Dockerfile. -### 9.4 Debugging & Troubleshooting +## 8. Observability -- **Distributed Tracing**: Request tracing across multiple services -- **Debug Endpoints**: Development-only endpoints for service introspection -- **Log Correlation**: Request ID tracking across service boundaries -- **Performance Profiling**: Application performance profiling and optimization tools \ No newline at end of file +- **Structured Logging**: Centralized logs via `logger` utility. +- **Error Notifications**: Critical failures automatically trigger alerts through cloud-based monitoring services. +- **Metrics**: Tracks block processing latency and API performance. Statistics are regularly analyzed to identify trends, and slow queries or underperforming API endpoints are investigated for optimization. \ No newline at end of file diff --git a/packages/shared/src/config/index.ts b/packages/shared/src/config/index.ts index a0f69f2..a82e9cb 100644 --- a/packages/shared/src/config/index.ts +++ b/packages/shared/src/config/index.ts @@ -54,12 +54,18 @@ export const config = cleanEnv(process.env, { // blockchain ALCHEMY_API_KEY: str({ devDefault: "dummy" }), TRANSACTION_WAIT_TRANSACTION_TIMEOUT: num({ default: 30_000 }), - TRANSACTION_INCREMENT_RATE: num({ default: 0.3 }), + TRANSACTION_INCREMENT_RATE: num({ + default: 0.3, + desc: "Rate at which the transaction wait time increases on each retry", + }), // mint - MINT_AVAILABLE_FROM: str({ devDefault: "2025-06-23T00:00:00Z" }), + MINT_AVAILABLE_FROM: str({ + devDefault: "2025-06-23T00:00:00Z", + desc: "The date and time when minting becomes available", + }), // predicate PREDICATE_API_URL: url({ devDefault: "http://localhost:3002" }), - PREDICATE_API_KEY: str({ devDefault: "dummy" }), + PREDICATE_API_KEY: str({ devDefault: "dummy", desc: "API key for the predicate service" }), // contract(must be lowercase for contract addresses) BUILDER_REGISTRY_CONTRACT_ADDRESS: str({ devDefault: "0x" }), BUILDER_REGISTRY_CONTRACT_DEPLOYED_BLOCK: num({ devDefault: 0 }), @@ -77,8 +83,11 @@ export const config = cleanEnv(process.env, { MOCK_L2_SCROLL_MESSENGER_CONTRACT_ADDRESS: str({ default: "0x" }), MOCK_L2_SCROLL_MESSENGER_CONTRACT_DEPLOYED_BLOCK: num({ default: 0 }), // private key - INTMAX2_OWNER_MNEMONIC: str({ devDefault: "" }), - MOCK_MESSENGER_PRIVATE_KEY: str({ default: "0x" }), + INTMAX2_OWNER_MNEMONIC: str({ devDefault: "", desc: "Owner mnemonic for Intmax2" }), + MOCK_MESSENGER_PRIVATE_KEY: str({ + default: "0x", + desc: "Private key for the mock messenger contract", + }), // discord DISCORD_BOT_TOKEN: str({ default: "dummy" }), DISCORD_BOT_INFO_CHANNEL_ID: str({ default: "dummy" }), @@ -86,17 +95,51 @@ export const config = cleanEnv(process.env, { // scroll SCROLL_GAS_MULTIPLIER: num({ default: 2 }), // indexer - BLOCK_BUILDER_ALLOWLIST: json({ default: ["0x"] }), - BLOCK_BUILDER_MIN_ETH_BALANCE: str({ default: "0.01" }), - BLOCK_BUILDER_REQUIRED_VERSION: str({ default: "0.1.0" }), - BLOCK_BUILDER_INDEXER_COUNT: num({ default: 3 }), - BLOCK_BUILDER_MIN_ALLOWLIST_COUNT: num({ default: 1 }), - ALLOWLIST_BLOCK_BUILDER_POSSIBILITIES: num({ default: 0.5 }), - BLOCK_BUILDER_ALLOWED_TOKEN_INDICES: str({ default: "0,1,2" }), - BLOCK_BUILDER_MAX_FEE_AMOUNT: str({ default: "2500000000000" }), - BUILDER_SELECTION_MODE: str({ default: "RANDOM" }), + BLOCK_BUILDER_ALLOWLIST: json({ + default: ["0x"], + desc: "List of allowed builder addresses. Only these addresses can participate in block building.", + }), + BLOCK_BUILDER_MIN_ETH_BALANCE: str({ + default: "0.01", + desc: "Minimum ETH balance required for a builder to be eligible for participation.", + }), + BLOCK_BUILDER_REQUIRED_VERSION: str({ + default: "0.1.0", + desc: "Required client version for a builder to be considered eligible.", + }), + BLOCK_BUILDER_INDEXER_COUNT: num({ + default: 3, + desc: "Number of indexers used by the builder to fetch and process transactions.", + }), + BLOCK_BUILDER_MIN_ALLOWLIST_COUNT: num({ + default: 1, + desc: "Minimum number of builders that must be in the allowlist for block building to proceed.", + }), + ALLOWLIST_BLOCK_BUILDER_POSSIBILITIES: num({ + default: 0.5, + desc: "Probability threshold (0.0–1.0) used to allow allowlisted builders to be selected.", + }), + BLOCK_BUILDER_ALLOWED_TOKEN_INDICES: str({ + default: "0,1,2", + desc: "Comma-separated indices of tokens that builders are allowed to include in blocks. Options may include 0 for ETH, 1 for ITX, 2 for WBTC and 3 for USDC.", + }), + BLOCK_BUILDER_MAX_FEE_AMOUNT: str({ + default: "2500000000000", + desc: "Maximum fee (in wei) a block builder can charge for including transactions in a block.", + }), + BUILDER_SELECTION_MODE: str({ + default: "RANDOM", + desc: `Strategy for selecting block builders: +- ALLOWLIST_ONLY: Use only allowlisted builders. +- ALLOWLIST_PRIORITY: Prefer allowlisted builders, fall back to others if needed. +- GUARANTEED_ALLOWLIST: Ensure at least one allowlisted builder is selected. +- RANDOM: Select randomly from all active builders, regardless of allowlist.`, + }), // validity prover - API_VALIDITY_PROVER_BASE_URL: str({ default: "http://localhost:3003" }), + API_VALIDITY_PROVER_BASE_URL: str({ + default: "http://localhost:3003", + desc: "Base URL for the validity prover API", + }), // wallet observer WALLET_REQUIRED_ETH_BALANCE: str({ default: "0.5" }), WALLET_REQUIRED_ETH_MIN_BALANCE: str({ default: "0.1" }),