Flowzmith

AI-powered smart contract generation and deployment platform for Flow blockchain using Cadence programming language.

Features

• Multi-modal Input Processing: Accepts contracts via .cdc/.sol files or natural language descriptions
• AI-Powered Generation: Uses OpenAI/Groq LLMs to generate and optimize Cadence smart contracts
• Flow Blockchain Integration: Seamless deployment to Flow testnet/mainnet using Flow CLI
• Real-time Learning: Captures deployment logs to improve future contract generation
• Documentation Intelligence: Vector-powered documentation search for Cadence development
• User Privacy Controls: GDPR-compliant data management and export capabilities
• Real-time Updates: WebSocket-powered progress tracking and notifications
• Web Interface: Complete frontend for contract management and deployment
• Firecrawl Integration: Seamless documentation indexing and search using Firecrawl

Quick Start

Prerequisites

• Python 3.8+
• Flow CLI installed and configured
• OpenAI API key or Groq API key
• PostgreSQL (recommended) or SQLite for development

Installation

1. Clone the repository

   git clone <repository-url>
   cd flowzmith

2. Set up environment

   cp .env.example .env
   # Edit .env with your API keys and database settings

3. Install dependencies

   pip install -r requirements.txt

4. Initialize database

   alembic upgrade head

5. Start the application

   python src/main.py
   # Or use the start script
   ./start.sh

6. Access the web interface Open your browser and navigate to http://localhost:8000

API Documentation

Authentication

The API uses JWT tokens for authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Endpoints

User Management

Create User

POST /api/v1/users
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password",
  "persona_type": "DEVELOPER",
  "full_name": "John Doe"
}

User Login

POST /api/v1/users/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password"
}

Contract Generation

Generate Contract from Natural Language

POST /api/v1/contracts
Authorization: Bearer <token>
Content-Type: application/json

{
  "input_type": "NATURAL_LANGUAGE",
  "content": "Create a simple NFT contract with mint and transfer functions",
  "pre_conditions": {
    "accounts": {"user": "0x123"},
    "tokens": {"initial_supply": 1000}
  },
  "post_conditions": {
    "deployed_contracts": ["NFTContract"],
    "created_resources": ["NFT"]
  },
  "network": "testnet"
}

Upload Contract File

POST /api/v1/contracts/file
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <contract-file>.cdc

Deployment

Deploy Contract

POST /api/v1/contracts/{submission_id}/deploy
Authorization: Bearer <token>
Content-Type: application/json

{
  "network": "testnet",
  "config_id": "generated_config_id"
}

Get Deployment Status

GET /api/v1/contracts/{submission_id}/deployments/{deployment_id}
Authorization: Bearer <token>

Documentation

Search Documentation

POST /api/v1/documentation/search
Content-Type: application/json

{
  "query": "Cadence resources",
  "limit": 10,
  "use_semantic_search": true
}

Get Documentation Statistics

GET /api/v1/documentation/stats

Firecrawl Integration

Scrape URL

POST /api/v1/firecrawl/scrape
Content-Type: application/json

{
  "url": "https://developers.flow.com/cadence",
  "formats": ["markdown", "html"],
  "include_tags": ["main", "article"],
  "exclude_tags": ["nav", "footer"]
}

Crawl Website

POST /api/v1/firecrawl/crawl
Content-Type: application/json

{
  "url": "https://developers.flow.com",
  "limit": 100,
  "include_paths": ["/cadence/*"],
  "exclude_paths": ["/blog/*"]
}

Check Crawl Status

GET /api/v1/firecrawl/crawl/{crawl_id}/status

Learning & Analytics

Get Learning Insights

GET /api/v1/learning/insights
Authorization: Bearer <token>

Get System Statistics

GET /api/v1/statistics
Authorization: Bearer <token>

WebSocket Connections

Connect to WebSocket for real-time updates:

ws://localhost:8000/ws

Configuration

Environment Variables

Create a .env file in the project root:

# Application
APP_NAME=Flowzmith
DEBUG=false
HOST=0.0.0.0
PORT=8000

# Database
DATABASE_URL=postgresql://user:password@localhost/smart_contract_llm
# For development: sqlite:///./smart_contract_llm.db

# LLM Providers
OPENAI_API_KEY=your_openai_api_key
GROQ_API_KEY=your_groq_api_key
DEFAULT_LLM_PROVIDER=OPENAI

# Flow Blockchain
FLOW_NETWORK=testnet
FLOW_ACCOUNT_ADDRESS=your_flow_account_address
FLOW_PRIVATE_KEY=your_flow_private_key

# Security
JWT_SECRET_KEY=your_jwt_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Firecrawl Configuration
FIRECRAWL_API_KEY=your_firecrawl_api_key_here
FIRECRAWL_BASE_URL=https://api.firecrawl.dev
FIRECRAWL_TIMEOUT=30000
FIRECRAWL_MAX_RETRIES=3

# CORS
ALLOWED_ORIGINS=["http://localhost:3000", "http://localhost:8000"]

Database Configuration

For production deployment with PostgreSQL:

1. Create database

   CREATE DATABASE smart_contract_llm;
   CREATE USER smart_contract_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE smart_contract_llm TO smart_contract_user;

2. Run migrations

   alembic upgrade head

Flow CLI Configuration

1. Install Flow CLI

   sh -ci "$(curl -fsSL https://storage.googleapis.com/flow-cli/install.sh)"

2. Configure Flow project

   flow project init
   flow keys generate

Usage Examples

This one works (internal notes)

python cli.py generate-from-context --stream --requirements "Create a simple NFT contract"

Generate and Deploy a Simple NFT Contract

Via API:

import requests
import json

# Login
login_response = requests.post('http://localhost:8000/api/v1/users/login', json={
    'email': 'user@example.com',
    'password': 'secure_password'
})
token = login_response.json()['access_token']

# Generate contract
headers = {'Authorization': f'Bearer {token}'}
contract_data = {
    'input_type': 'NATURAL_LANGUAGE',
    'content': 'Create a simple NFT contract with mint function that allows users to mint NFTs with unique IDs',
    'network': 'testnet'
}

response = requests.post(
    'http://localhost:8000/api/v1/contracts',
    json=contract_data,
    headers=headers
)

submission = response.json()
submission_id = submission['submission_id']

# Deploy contract
deploy_response = requests.post(
    f'http://localhost:8000/api/v1/contracts/{submission_id}/deploy',
    json={'network': 'testnet'},
    headers=headers
)

deployment = deploy_response.json()
print(f"Contract deployed with transaction hash: {deployment['transaction_hash']}")

Via Web Interface:

1. Open http://localhost:8000 in your browser
2. Login or create a new account
3. Navigate to "Contract Generation"
4. Enter your contract requirements in natural language
5. Select the target network (testnet/mainnet)
6. Click "Generate Contract"
7. Review the generated contract and configuration
8. Click "Deploy" to deploy to Flow blockchain

Upload and Deploy Existing Contract

Via API:

import requests

# Upload contract file
with open('my_contract.cdc', 'rb') as f:
    files = {'file': f}
    response = requests.post(
        'http://localhost:8000/api/v1/contracts/file',
        files=files,
        headers={'Authorization': f'Bearer {token}'}
    )

submission = response.json()
submission_id = submission['submission_id']

# Deploy
deploy_response = requests.post(
    f'http://localhost:8000/api/v1/contracts/{submission_id}/deploy',
    json={'network': 'testnet'},
    headers=headers
)

Search Documentation

Via API:

import requests

# Search for documentation
search_data = {
    'query': 'How to create resources in Cadence',
    'limit': 5,
    'use_semantic_search': True
}

response = requests.post(
    'http://localhost:8000/api/v1/documentation/search',
    json=search_data
)

results = response.json()
for doc in results:
    print(f"{doc['title']}: {doc['content'][:100]}...")

Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_api.py

# Run tests with markers
pytest -m "not llm"  # Skip LLM tests
pytest -m integration  # Run only integration tests

Test Structure

• Unit Tests: Test individual components and functions
• Integration Tests: Test service interactions and database operations
• API Tests: Test REST endpoints and WebSocket connections
• Performance Tests: Test system performance under load

Deployment

Docker Deployment

1. Build Docker image

   docker build -t flowzmith .

2. Run with Docker Compose

   docker-compose up -d

Manual Deployment

1. Install dependencies

   pip install -r requirements.txt

2. Set up database

   alembic upgrade head

3. Start application

   gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker

Environment Setup

Production Environment:

DEBUG=false
DATABASE_URL=postgresql://user:password@prod-db/smart_contract_llm
ALLOWED_ORIGINS=["https://yourdomain.com"]

Security Considerations

API Security

• JWT-based authentication
• Rate limiting on all endpoints
• Input validation and sanitization
• CORS configuration for cross-origin requests
• Secure password hashing with bcrypt

Data Privacy

• GDPR-compliant data handling
• User data export functionality
• Configurable data retention periods
• Anonymization of learning data
• Secure storage of sensitive information

Blockchain Security

• Flow account key management
• Transaction validation
• Gas estimation and optimization
• Network-specific deployment configurations
• Audit logging for all blockchain operations

Development

Code Structure

src/
├── main.py                 # FastAPI application entry point
├── config.py              # Configuration management
├── models/                # Database models
│   ├── database.py        # Database connection and session management
│   ├── user.py            # User and data control models
│   ├── contract.py        # Contract and configuration models
│   └── learning.py        # Learning and documentation models
├── services/              # Business logic layer
│   ├── llm_service.py     # LLM provider integration
│   ├── flow_service.py    # Flow blockchain operations
│   ├── user_service.py    # User management
│   └── learning_service.py # Learning and documentation
├── api/                   # API layer
│   ├── routes.py          # REST API endpoints
│   ├── websocket.py       # WebSocket handlers
│   ├── auth.py            # Authentication middleware
│   └── middleware.py      # Request processing middleware
└── utils/                 # Utility functions
    ├── validators.py      # Input validation
    ├── security.py        # Security functions
    └── helpers.py         # Helper functions

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pre-commit install

# Run linting
flake8 src/
black src/
isort src/

# Run type checking
mypy src/

Troubleshooting

Common Issues

Flow CLI not found:

# Ensure Flow CLI is installed and in PATH
flow version

# Add to PATH if needed
export PATH=$PATH:/path/to/flow/cli

Database connection issues:

# Check database service status
sudo systemctl status postgresql

# Verify connection string
psql $DATABASE_URL -c "SELECT 1"

LLM API errors:

# Verify API keys are set
echo $OPENAI_API_KEY
echo $GROQ_API_KEY

# Test API connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

Performance Optimization

• Database indexing on frequently queried fields
• Connection pooling for database connections
• Caching for documentation search results
• Background job processing for long-running operations
• Efficient WebSocket connection management

Command Line Interface (CLI)

Flowzmith includes a comprehensive CLI for developers who prefer command-line workflows. The CLI provides:

• Interactive Contract Creation: Step-by-step guided contract generation
• Real-time Documentation Search: Search and browse Cadence documentation
• Firecrawl Integration: Crawl and index external documentation sources
• Contract Deployment: Deploy contracts directly from the command line
• System Monitoring: Check system status and view statistics

Quick CLI Usage

# Setup environment
python cli.py setup

# Create a contract interactively
python cli.py create-contract

# Search documentation
python cli.py search-docs

# Crawl external documentation with Firecrawl
python cli.py crawl-docs

# Interactive Firecrawl documentation search
python cli.py firecrawl-search

# Deploy a contract
python cli.py deploy-contract

# Run the complete wizard
python cli.py wizard

For detailed CLI documentation, see CLI_README.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information
4. Join our community discussions

Roadmap

• Support for additional blockchain platforms
• Advanced contract optimization features
• Multi-signature contract deployment
• Contract verification and auditing tools
• Mobile application development
• Enhanced learning algorithms
• Enterprise features and compliance tools