Leveraging Knowledge Integration for Smart Contract Enhancement

Prerequisites

This project runs on Linux (developed and tested on Linux Mint 20.3 / Ubuntu 20.04 base).
All components run locally except for the LLMs, which uses the Google Gemini API (Gemini 2.5 Flash).

---

Required Software

Node.js and npm

Used for n8n and the gas measurement server.

# Install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Tested with:

• Node.js v20.20.0
• npm 10.8.2

Python

Used for the Etherscan contract fetcher.

The project uses Anaconda to manage Python environments, but a regular Python 3.10+ install works too.

# Check your version
python3 --version
# Python 3.13.5

To install Anaconda: https://www.anaconda.com/download

Docker

Used to run Qdrant.

# Install on Ubuntu/Mint
sudo apt-get update
sudo apt-get install docker.io
sudo systemctl enable --now docker

# Allow running Docker without sudo (log out and back in after this)
sudo usermod -aG docker $USER

Tested with Docker 26.1.3.

---

Components

1. n8n (workflow automation)

npm install -g n8n

Start it with:

n8n start

Runs on http://localhost:5678

Tested with n8n 2.3.6.

The workflows use Google Gemini 2.5 Flash for both the LLM and embeddings. In n8n, add a "Google Gemini (PaLM) API" credential with your API key. Get one at https://aistudio.google.com/app/apikey

---

2. Qdrant (vector database)

Pull the Docker image once:

docker pull qdrant/qdrant:latest

Start it:

docker run -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest

To stop it:

docker ps                   # find the container ID
docker stop <container-id>

Runs on http://localhost:6333

Tested with qdrant/qdrant:latest (image from 02.2026).

In n8n, configure a Qdrant credential with:

• URL: http://localhost:6333
• API key: leave empty (no auth needed for local instance)

The n8n RAG workflow expects a collection named knowledge-database. Create it via the Qdrant dashboard at http://localhost:6333/dashboard before running the workflow for the first time.

---

3. Ollama (embeddings for LightRAG only)

Ollama is only required for LightRAG. The n8n RAG pipeline uses Google Gemini embeddings (gemini-embedding-001) directly and does not need Ollama.

Install:

curl -fsSL https://ollama.com/install.sh | sh

Pull the embedding model used by LightRAG:

ollama pull nomic-embed-text

Ollama runs automatically as a background service after installation.
It listens on http://localhost:11434

Tested with Ollama 0.14.2 and nomic-embed-text:latest (274 MB).

---

4. LightRAG

Install the Python package:

pip install lightrag-hku==1.4.9.11

Or install the latest version:

pip install lightrag-hku

LightRAG also requires these dependencies (installed automatically via pip):

aiohttp, google-genai, networkx, numpy, pandas, pydantic,
python-dotenv, tenacity, tiktoken, nano-vectordb

Create a .env file in your LightRAG directory with the following content:

# LLM - Google Gemini
LLM_MODEL=gemini-2.5-flash
LLM_BINDING_HOST=https://generativelanguage.googleapis.com
LLM_BINDING_API_KEY=your_google_api_key
LLM_SLEEP_INTERVAL=5

# Free tier throttling
MAX_ASYNC=1
MAX_ASYNC_REQUESTS=1
MAX_PARALLEL_INSERT=1
CHUNK_SIZE=1200

# Embeddings - local via Ollama
EMBEDDING_BINDING=ollama
EMBEDDING_BINDING_HOST=http://localhost:11434
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_DIM=768
EMBEDDING_SEND_DIM=false
EMBEDDING_TIMEOUT=600
WORKER_TIMEOUT=600

# Reranking - Jina AI
RERANK_BINDING=jina
RERANK_MODEL=jina-reranker-v3
RERANK_BINDING_API_KEY=your_jina_api_key

# Server
HOST=0.0.0.0
PORT=9621

Start LightRAG:

cd lightrag
./start_lightrag.sh (copy the file into the lightrag folder)

Runs on http://localhost:9621

---

5. Gas Measurement Server

This is the local Node.js server that compiles and deploys Solidity contracts on a local Ganache chain to measure gas usage.

In the project folder:

npm install

This installs:

• solc ^0.8.34
• ethers ^6.16.0
• ganache (local EVM)

Start the server:

node ganache_gas_server.js

Runs on http://localhost:5695

---

6. Etherscan Contract Fetcher

Install the Python dependency:

pip install requests

The script requires a valid Etherscan API key. Set it in the script or via environment variable.
Get a free key at https://etherscan.io/myapikey

The gas server (step 5) must be running before you run the fetcher, because the fetcher sends each contract there to verify it compiles and deploys cleanly.

Run:

python fetcher.py

7. Static Baseline Tools

Two static analysis tools are used as a rule-based baseline. Each has a dedicated Python batch script that runs the tool across all contracts and writes per-contract JSON reports plus an overall summary.

Slither

Install Slither and solc-select:

pip install slither-analyzer
pip install solc-select

Run the batch analyzer:

python slither_batch_analyzer.py contracts/

Output is written to contracts/slither_reports/.

Tested with slither-analyzer 0.10.x and solc-select 0.x.

SGO (Solidity Gas Optimizer)

Install globally via npm:

npm install -g solidity-gas-optimizer

The SGO batch script expects the tool to be installed at ~/solidity-gas-optimizer. Clone and build it there if the global install does not place it at that path:

cd ~
git clone https://github.com/babyhome/solidity-gas-optimizer.git
cd solidity-gas-optimizer
npm install
npm run build

Run the batch analyzer:

python sgo_batch_analyzer.py contracts/

Output is written to contracts/sgo_reports/.

---

Knowledge Base Setup

Both RAG systems need to be populated with the source documents before the n8n workflows will return useful results. The documents live in ~/.n8n-files and include PDFs, Markdown files, Solidity source files, and plain text files covering gas optimization techniques, security patterns, and audit guidelines. Especially Qdrant needs the sources inside the .n8n-files folder

File types present in .n8n-files:

• .pdf : gas optimization guides, security best practices, audit standards
• .md : specific optimization patterns (storage packing, unchecked arithmetic, loop fusion, etc.)
• .sol and .sol.txt : annotated Solidity example contracts
• .txt : reference material and syntax guides

Uploading to Qdrant

The n8n workflow reads from ~/.n8n-files/ and embeds each document into the knowledge-database Qdrant collection using gemini-embedding-001.

Before ingesting, make sure:

• Qdrant is running at http://localhost:6333
• The knowledge-database collection exists — create it via the dashboard at http://localhost:6333/dashboard if not
• Your Google Gemini API credential is configured in n8n

Then trigger the ingestion workflow from the n8n UI. You can save time uploading files with *.file_type e.g. *.pdf.

Uploading to LightRAG

LightRAG is ingested via its HTTP API. It must be running on port 9621 before you start.

Bulk ingest all Markdown files with *.file_type (see above).

LightRAG persists its graph and vector data in ~/lightrag/rag_storage/. The user interface can be reached at http://localhost:9621.

---

Startup Order

Start the components in this order:

1. Docker -> Qdrant
2. Ollama -> runs automatically, just verify with: ollama list
3. node server.js -> gas server
4. n8n start -> n8n
5. cd lightrag && ./start_lightrag.sh -> LightRAG
6. python fetch_etherscan.py -> run on demand when you want to collect contracts

---

Port Overview

Component	Port
n8n	5678
Gas server	5695
Qdrant HTTP	6333
Qdrant gRPC	6334
Ollama	11434
LightRAG	9621

---

Notes

• The LightRAG throttling settings (MAX_ASYNC=1 etc.) are tuned for the Gemini free tier. If you are on a paid plan you can increase these values (due to time savings and capacity issues we switched to a paid plan).
• The gas server automatically downloads the correct solc version for each contract based on its pragma. The first request after startup may be slightly slower while it fetches the version list from soliditylang.org.
• Qdrant data is persisted in ~/qdrant_storage on the host machine, so your vectors survive container restarts. Same for LightRAG.