From fee53f1dbfe6c2eccbebfdfd4dab1072860364c3 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 8 Oct 2025 10:30:27 +0200 Subject: [PATCH 1/3] add makefile for tools to be built and installed --- Makefile | 1 + tools/tools.mk | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 tools/tools.mk diff --git a/Makefile b/Makefile index dd964f69e4..1b86d6f70b 100644 --- a/Makefile +++ b/Makefile @@ -3,6 +3,7 @@ include ./scripts/test.mk include ./scripts/proto.mk include ./scripts/utils.mk include ./scripts/run.mk +include ./tools/tools.mk # Sets the default make target to `build`. # Requires GNU Make >= v3.81. diff --git a/tools/tools.mk b/tools/tools.mk new file mode 100644 index 0000000000..2eefeec775 --- /dev/null +++ b/tools/tools.mk @@ -0,0 +1,90 @@ +# tools.mk - Build configuration for ev-node tools + +# Tool names +TOOLS := da-debug blob-decoder cache-analyzer + +# Build directory +TOOLS_BUILD_DIR := $(CURDIR)/build + +# Version information (inherited from main build.mk if available) +VERSION ?= $(shell git describe --tags --abbrev=0 2>/dev/null || echo "dev") +GITSHA ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown") +LDFLAGS ?= \ + -X main.Version=$(VERSION) \ + -X main.GitSHA=$(GITSHA) + +# Individual tool build targets +## build-tool-da-debug: Build da-debug tool +build-tool-da-debug: + @echo "--> Building da-debug tool" + @mkdir -p $(TOOLS_BUILD_DIR) + @cd tools/da-debug && go build -ldflags "$(LDFLAGS)" -o $(TOOLS_BUILD_DIR)/da-debug . + @echo "--> da-debug built: $(TOOLS_BUILD_DIR)/da-debug" +.PHONY: build-tool-da-debug + +## build-tool-blob-decoder: Build blob-decoder tool +build-tool-blob-decoder: + @echo "--> Building blob-decoder tool" + @mkdir -p $(TOOLS_BUILD_DIR) + @cd tools/blob-decoder && go build -ldflags "$(LDFLAGS)" -o $(TOOLS_BUILD_DIR)/blob-decoder . + @echo "--> blob-decoder built: $(TOOLS_BUILD_DIR)/blob-decoder" +.PHONY: build-tool-blob-decoder + +## build-tool-cache-analyzer: Build cache-analyzer tool +build-tool-cache-analyzer: + @echo "--> Building cache-analyzer tool" + @mkdir -p $(TOOLS_BUILD_DIR) + @cd tools/cache-analyzer && go build -ldflags "$(LDFLAGS)" -o $(TOOLS_BUILD_DIR)/cache-analyzer . + @echo "--> cache-analyzer built: $(TOOLS_BUILD_DIR)/cache-analyzer" +.PHONY: build-tool-cache-analyzer + +# Build all tools +## build-tools: Build all tools +build-tools: $(addprefix build-tool-, $(TOOLS)) + @echo "--> All tools built successfully!" +.PHONY: build-tools + +# Install individual tools +## install-tool-da-debug: Install da-debug tool to Go bin +install-tool-da-debug: + @echo "--> Installing da-debug tool" + @cd tools/da-debug && go install -ldflags "$(LDFLAGS)" . + @echo "--> da-debug installed to Go bin" +.PHONY: install-tool-da-debug + +## install-tool-blob-decoder: Install blob-decoder tool to Go bin +install-tool-blob-decoder: + @echo "--> Installing blob-decoder tool" + @cd tools/blob-decoder && go install -ldflags "$(LDFLAGS)" . + @echo "--> blob-decoder installed to Go bin" +.PHONY: install-tool-blob-decoder + +## install-tool-cache-analyzer: Install cache-analyzer tool to Go bin +install-tool-cache-analyzer: + @echo "--> Installing cache-analyzer tool" + @cd tools/cache-analyzer && go install -ldflags "$(LDFLAGS)" . + @echo "--> cache-analyzer installed to Go bin" +.PHONY: install-tool-cache-analyzer + +# Install all tools +## install-tools: Install all tools to Go bin +install-tools: $(addprefix install-tool-, $(TOOLS)) + @echo "--> All tools installed successfully!" +.PHONY: install-tools + +# Clean built tools +## clean-tools: Remove built tool binaries +clean-tools: + @echo "--> Cleaning built tools" + @rm -f $(addprefix $(TOOLS_BUILD_DIR)/, $(TOOLS)) + @echo "--> Tools cleaned" +.PHONY: clean-tools + +# List available tools +## list-tools: List all available tools +list-tools: + @echo "Available tools:" + @for tool in $(TOOLS); do \ + echo " - $$tool"; \ + done +.PHONY: list-tools \ No newline at end of file From a50a8504a87b04df9bf1c5c2c5ddd5a88bfd50b2 Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 8 Oct 2025 10:43:06 +0200 Subject: [PATCH 2/3] add install sections to readmes --- tools/blob-decoder/README.md | 120 +++++++++++++++++++++++++++++++++ tools/cache-analyzer/README.md | 19 +++++- tools/da-debug/README.md | 16 +++++ 3 files changed, 153 insertions(+), 2 deletions(-) create mode 100644 tools/blob-decoder/README.md diff --git a/tools/blob-decoder/README.md b/tools/blob-decoder/README.md new file mode 100644 index 0000000000..11f5d985ae --- /dev/null +++ b/tools/blob-decoder/README.md @@ -0,0 +1,120 @@ +# Blob Decoder + +A web-based tool for decoding and inspecting blob data from the ev-node Data Availability layer. + +## Overview + +The `blob-decoder` tool provides a web interface for decoding protobuf-encoded blobs used in ev-node. It can decode blocks and other data structures from both hex and base64 encoded inputs, making it useful for debugging and inspecting DA layer data. + +## Installation + +Install using `go install`: + +```bash +go install github.com/evstack/ev-node/tools/blob-decoder@latest +``` + +Or install a specific version: + +```bash +go install github.com/evstack/ev-node/tools/blob-decoder@v1.0.0-beta.6 +``` + +After installation, the `blob-decoder` binary will be available in your `$GOPATH/bin` directory. + +## Usage + +### Running the Server + +Start the blob decoder server: + +```bash +# Run on default port 8090 +blob-decoder + +# Run on custom port +blob-decoder 8080 +``` + +The server will start and display: + +``` +╔═══════════════════════════════════╗ +║ Evolve Blob Decoder ║ +║ by ev.xyz ║ +╚═══════════════════════════════════╝ + +🚀 Server running at: http://localhost:8090 +⚡ Using native Evolve protobuf decoding + +Press Ctrl+C to stop the server +``` + +### Web Interface + +Open your browser and navigate to `http://localhost:8090` to access the web interface. + +The interface allows you to: +- Paste blob data in either hex or base64 format +- Automatically detect and decode the blob type +- View decoded block headers, transactions, and other metadata +- Inspect raw hex data and blob size information + +### API Endpoint + +The decoder also provides a REST API endpoint: + +```bash +POST /api/decode +Content-Type: application/json + +{ + "data": "", + "encoding": "hex" | "base64" +} +``` + +Response: +```json +{ + "type": "Block", + "data": { + // Decoded block or data structure + }, + "rawHex": "", + "size": 1234, + "timestamp": "2024-01-01T00:00:00Z" +} +``` + +## Features + +- **Auto-detection**: Automatically detects blob type (blocks, commits, etc.) +- **Multiple Encodings**: Supports both hex and base64 encoded inputs +- **Protobuf Decoding**: Native decoding of ev-node protobuf structures +- **Web Interface**: User-friendly web interface for easy blob inspection +- **REST API**: Programmatic access for automation and integration +- **CORS Support**: Can be accessed from other web applications + +## Examples + +```bash +# Start server on default port +blob-decoder + +# Start server on port 3000 +blob-decoder 3000 + +# Use with curl to decode a hex-encoded blob +curl -X POST http://localhost:8090/api/decode \ + -H "Content-Type: application/json" \ + -d '{"data": "0x...", "encoding": "hex"}' +``` + +## Use Cases + +- Debug DA layer blob submissions +- Inspect block structure and content +- Validate blob encoding and decoding +- Troubleshoot sync issues related to blob data +- Educational tool for understanding ev-node data structures \ No newline at end of file diff --git a/tools/cache-analyzer/README.md b/tools/cache-analyzer/README.md index 149ffda1bb..c1de8d61ec 100644 --- a/tools/cache-analyzer/README.md +++ b/tools/cache-analyzer/README.md @@ -6,10 +6,25 @@ This small program is designed to analyze the cache of a sync node. It is useful to debug when the sync node is downloading from DA but not advancing. This usually means the `DA_START_HEIGHT` is too late. This tool allows clearly to identify the first height fetched from DA. +## Installation + +Install using `go install`: + +```bash +go install github.com/evstack/ev-node/tools/cache-analyzer@latest +``` + +Or install a specific version: + +```bash +go install github.com/evstack/ev-node/tools/cache-analyzer@v1.0.0-beta.6 +``` + +After installation, the `cache-analyzer` binary will be available in your `$GOPATH/bin` directory. + ## Usage -```sh -go install github.com/evstack/ev-node/tools/cache-analyzer@main +```bash cache-analyzer -data-dir ~/.appd/data/ -summary cache-analyzer -data-dir ~/.appd/data/ -limit 50 ``` diff --git a/tools/da-debug/README.md b/tools/da-debug/README.md index 429fc987ba..8ad25d1c35 100644 --- a/tools/da-debug/README.md +++ b/tools/da-debug/README.md @@ -6,6 +6,22 @@ A professional debugging tool for querying and inspecting Data Availability (DA) The `da-debug` tool provides a command-line interface to interact with DA layers for debugging purposes. It offers two main commands: `query` for inspecting specific DA heights and `search` for finding blobs containing specific blockchain heights. +## Installation + +Install using `go install`: + +```bash +go install github.com/evstack/ev-node/tools/da-debug@latest +``` + +Or install a specific version: + +```bash +go install github.com/evstack/ev-node/tools/da-debug@v1.0.0-beta.6 +``` + +After installation, the `da-debug` binary will be available in your `$GOPATH/bin` directory. + ## Commands ### Query Command From 882f535f8681225c712ab4396831d3f2859bd57d Mon Sep 17 00:00:00 2001 From: tac0turtle Date: Wed, 8 Oct 2025 10:46:00 +0200 Subject: [PATCH 3/3] change from main to latest --- tools/blob-decoder/README.md | 10 ++-------- tools/cache-analyzer/README.md | 8 +------- tools/da-debug/README.md | 8 +------- 3 files changed, 4 insertions(+), 22 deletions(-) diff --git a/tools/blob-decoder/README.md b/tools/blob-decoder/README.md index 11f5d985ae..c420b7ca58 100644 --- a/tools/blob-decoder/README.md +++ b/tools/blob-decoder/README.md @@ -11,13 +11,7 @@ The `blob-decoder` tool provides a web interface for decoding protobuf-encoded b Install using `go install`: ```bash -go install github.com/evstack/ev-node/tools/blob-decoder@latest -``` - -Or install a specific version: - -```bash -go install github.com/evstack/ev-node/tools/blob-decoder@v1.0.0-beta.6 +go install github.com/evstack/ev-node/tools/blob-decoder@main ``` After installation, the `blob-decoder` binary will be available in your `$GOPATH/bin` directory. @@ -117,4 +111,4 @@ curl -X POST http://localhost:8090/api/decode \ - Inspect block structure and content - Validate blob encoding and decoding - Troubleshoot sync issues related to blob data -- Educational tool for understanding ev-node data structures \ No newline at end of file +- Educational tool for understanding ev-node data structures diff --git a/tools/cache-analyzer/README.md b/tools/cache-analyzer/README.md index c1de8d61ec..69cd3c6056 100644 --- a/tools/cache-analyzer/README.md +++ b/tools/cache-analyzer/README.md @@ -11,13 +11,7 @@ This usually means the `DA_START_HEIGHT` is too late. This tool allows clearly t Install using `go install`: ```bash -go install github.com/evstack/ev-node/tools/cache-analyzer@latest -``` - -Or install a specific version: - -```bash -go install github.com/evstack/ev-node/tools/cache-analyzer@v1.0.0-beta.6 +go install github.com/evstack/ev-node/tools/cache-analyzer@main ``` After installation, the `cache-analyzer` binary will be available in your `$GOPATH/bin` directory. diff --git a/tools/da-debug/README.md b/tools/da-debug/README.md index 8ad25d1c35..957e44f424 100644 --- a/tools/da-debug/README.md +++ b/tools/da-debug/README.md @@ -11,13 +11,7 @@ The `da-debug` tool provides a command-line interface to interact with DA layers Install using `go install`: ```bash -go install github.com/evstack/ev-node/tools/da-debug@latest -``` - -Or install a specific version: - -```bash -go install github.com/evstack/ev-node/tools/da-debug@v1.0.0-beta.6 +go install github.com/evstack/ev-node/tools/da-debug@main ``` After installation, the `da-debug` binary will be available in your `$GOPATH/bin` directory.