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

---