CDK Dev Stack

🦀 A comprehensive Rust-based blockchain development stack for Polygon CDK (Chain Development Kit) networks, providing production-ready services for blockchain monitoring, indexing, testing, and Web3 infrastructure.

🏗️ Architecture Overview

┌────────────────────────────────────────────────────────────────────────┐
│ CDK Dev Stack │
├────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Events │ │ Blocks │ │ Mempool │ │
│ │ Monitor │ │ Monitor │ │ Monitor │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌────────────────────────────────┴────────────────────────────────┐ │
│ │ Core Infrastructure │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │
│ │ │ PostgreSQL │ │ NATS │ │ AWS RDS │ │ │
│ │ │ Database │ │ Messaging │ │ Cloud storage │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Application Services │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌─────────────┐ │ │
│ │ │ Airdrop │ │ Agentic │ │ Oracle │ │ │
│ │ │ Backend │ │ Payment │ │ Service │ │ │
│ │ └───────────────┘ └───────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Development Tools │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ TX Producer │ │ Load Tester │ │ Merkle Trie │ │ │
│ │ │ │ │ CLI │ │ CLI │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ ABI Fetcher │ │ ABI2Sol │ │ User ID │ │ │
│ │ └───────────────┘ └───────────────┘ │ Fetcher │ │ │
│ │ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘

📦 Components

🔍 Monitoring Services

Component	Description	Documentation
events-monitor	Real-time blockchain event monitoring and indexing service with WebSocket/HTTP subscriptions	README
blocks-monitor	Block tracking and indexing service for chain state monitoring	README
mempool-monitor	Pending transaction monitoring from the mempool	README

💰 Application Services

Component	Description	Documentation
airdrop-backend	Airdrop eligibility verification service with Merkle tree proof generation	README
agentic-payment-service	AI-agent payment processing with X-402 and AP2 protocol support	README
oracle-service	Blockchain oracle service (for on-chain data providing)	README

🛠️ Development & Testing Tools

Component	Description	Documentation
tx-producer	Transaction generation and broadcasting library	README
load-tester-cli	Blockchain load testing CLI benchmarking tool with support of multiple test scenarios, configurable rate limiting (TPS) for throughput and bandwidth testing, and detailed statistics output	README, Usage Guide
merkle-trie-cli	Merkle trie generation and proof verification CLI	README: MERKLE-TRIE-CLI VIEM COMPATIBLE, README: MERKLE-TRIE-CLI
abi-fetcher	Smart contract ABI fetching from block explorers	README
abi2sol	ABI to Solidity interface generator	README
user-id-fetcher	User identity resolution and fetching CLI tool	README

📁 Legacy Components

Located in ./legacy/:

• cdk-indexer.v1.ethers - Original ethers-rs based indexer
• cdk-indexer.v2.alloy - Alloy-based indexer (migration)
• cdk-indexer.v4.prototype - Improved Alloy-based indexer prototype
• merkle-trie-generator - Original Merkle trie implementation
• merkle-trie-cli.py - Python-based Viem compatible Merkle Tree generator CLI (deprecated, used for quick prototyping and compatibility check)

📦 Summary of Components

Category	Component	Purpose
Monitoring	events-monitor	Real-time blockchain event indexing
Monitoring	blocks-monitor	Block data tracking and storage
Monitoring	mempool-monitor	Pending transaction monitoring
Services	airdrop-backend	Token airdrop eligibility verification
Services	agentic-payment-service	AI agent payment processing
Services	oracle-service	Blockchain oracle service
Tools	tx-producer	Transaction generation library
Tools	load-tester-cli	Blockchain load testing
Tools	merkle-trie-cli	Merkle proof generation
Tools	abi-fetcher	ABI retrieval from explorers
Tools	abi2sol	ABI to Solidity conversion
Services	user-id-fetcher	User identity resolution

🚀 Quick Start

Prerequisites

• Rust stable toolchain (see rust-toolchain)
• PostgreSQL 17+
• NATS Server 2.x
• Docker & Docker Compose

Building

# Build all workspace members
cargo build --release
# Build specific component
cargo build --release -p events-monitor

Running with Docker

cd .docker
./build.run.sh
# or for rebuild
./rebuild.run.sh

Configuration

Each service uses YAML configuration files located in their .config directories:

# Example: Events Monitor
cp events-monitor/events_monitor.config.yaml.example events-monitor/events_monitor.config.yaml
# Edit configuration...
cargo run -p events-monitor

📚 Documentation

Comprehensive documentation is available in each corresponding component/service directory in respective REAMDE.md file.

• Monitoring Services

  • events-monitor
  • blocks-monitor
  • mempool-monitor

• Application Services

  • airdrop-backend
  • agentic-payment-service
  • oracle-service(./oracle-service/README.md)

• Development & Testing Tools

  • tx-producer
  • load-tester-cli: README, Usage Guide
  • merkle-trie-cli: README: MERKLE-TRIE-CLI VIEM COMPATIBLE, README: MERKLE-TRIE-CLI
  • abi-fetcher
  • abi2sol
  • user-id-fetcher

🔧 Tech Stack

• Language: Rust (stable)
• Blockchain:Alloy - Modern Ethereum library
• Async Runtime: Tokio
• Database: PostgreSQL with tokio-postgres
• Messaging: NATS
• Web Framework: Axum
• Serialization: Serde, JSON, YAML
• Cryptography: Keccak256, Merkle Trees

📁 Project Structure

cdk-dev-stack/
├── .cargo/ # Cargo configuration
├── .config/ # Global configuration
├── .docker/ # Docker build files
│ ├── docker-compose.yml
│ └── cdk-soa-backend.dockerfile
├── docs/ # Documentation artefacts
├── legacy/ # Deprecated/archived code
│
├── # Core Monitoring Services
├── events-monitor/ # Event indexing service
├── blocks-monitor/ # Block monitoring service
├── mempool-monitor/ # Mempool monitoring service
│
├── # Application Services
├── airdrop-backend/ # Airdrop eligibility API
├── agentic-payment-service/ # AI payment processing
├── oracle-service/ # Oracle service
│
├── # Development Tools
├── tx-producer/ # Transaction library
├── load-tester-cli/ # Load testing CLI
├── merkle-trie-cli/ # Merkle proof CLI
├── abi-fetcher/ # ABI fetching tool
├── abi2sol/ # ABI to Solidity converter
├── user-id-fetcher/ # User identity service
│
├── Cargo.toml # Workspace manifest
├── Cargo.lock # Dependency lock file
├── rust-toolchain # Rust version specification
└── LICENSE-APACHE # Apache 2.0 License

🗄️ Database Schema

The monitoring services use PostgreSQL. Initialize schemas:

# Events Monitor
psql -U postgres -d cdk_events -f events-monitor/init.sql
psql -U postgres -d cdk_events -f events-monitor/init_aws_rds_schema.sql
# Blocks Monitor
psql -U postgres -d cdk_blocks -f blocks-monitor/init.sql
psql -U postgres -d cdk_blocks -f blocks-monitor/init_aws_rds_schema.sql
# Mempool Monitor
psql -U postgres -d cdk_mempool -f mempool-monitor/init.sql
psql -U postgres -d cdk_mempool -f mempool-monitor/init_aws_rds_schema.sql
# Airdrop Backend
psql -U postgres -d airdrop -f airdrop-backend/initial_schema.sql

🧪 Testing

# Run all tests
cargo test# Run tests for specific component
cargo test -p tx-producer
# Run integration tests
cargo test --test '*' -p load-tester-cli

🔄 Load Testing

Use the load-tester-cli for performance testing:

cd load-tester-cli
# Run full benchmark suite
./scripts/run-benchmarks.sh

See USAGE_GUIDE.md for detailed options.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE-APACHE file for details.

🙏 Acknowledgments

• Polygon CDK - Chain Development Kit
• Alloy - Rust Ethereum library
• Tokio - Async runtime for Rust

---

Built with 🦀 by the Sentient Enclaves&CDK Dev Team

---