Skip to content

abdul-abdi/karibu

BranchesTags

Repository files navigation

Karibu

A Smart Contract Analyzer for EVM Chains

Karibu Logo

Smart Contract Analyzer for EVM-Compatible Testnets

📋 Overview

Karibu is an all-in-one platform for blockchain developers to build, analyze, deploy, and interact with smart contracts on EVM-compatible testnets. Our platform streamlines the development process with zero setup required - no wallet configuration needed. Karibu combines powerful development tools with an integrated AI assistant to help you write secure and efficient code.

�� Key Features

  • 🔍 Smart Contract Analysis - Instantly analyze Solidity code for insights and security considerations
  • 🚀 One-Click Deployment - Deploy to EVM testnets without wallet configuration or manual gas settings
  • 🔒 Security-First Approach - Automated security checks and best practice suggestions
  • ⚡ Universal Contract Interaction - Dynamically interact with any contract type using intelligent interface detection
  • 🔮 Advanced ABI Discovery - Accurate function detection through bytecode analysis for any smart contract
  • 📊 Live State Visualization - Real-time view of contract state variables and storage
  • 📚 Learning Resources - Comprehensive guides on smart contract development
  • 🧠 AI Assistant - Get instant answers about blockchain concepts, Solidity, and EVM development
  • 🔌 No External Dependencies - Everything runs in-browser with no wallet requirements
  • 📂 Multi-File IDE - Develop complex contract systems with multiple files and dependencies
  • 📦 External Library Support - Seamless integration with popular libraries like OpenZeppelin
  • 🔄 Dependency Management - Automatic resolution of imports and dependencies between files
  • 🏗️ Rich Template Library - Categorized, ready-to-use contract templates with detailed documentation

🚀 Getting Started

Prerequisites

  • Node.js 18+ and npm/yarn
  • A Gemini API key for the AI Assistant functionality (optional)

Installation

  1. Clone the repository

    git clone https://github.com/abdul-abdi/karibu.git
cd karibu

  2. Install dependencies

    npm install
# or
yarn

  3. Set up environment variables

    cp .env.example .env.local

    Edit the .env.local file with your credentials:

    # AI Assistant (optional)
NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key_here

# API endpoints
HASHIO_API_ENDPOINT=https://testnet.hashio.io/api
MIRROR_NODE_TESTNET=https://testnet.mirrornode.hedera.com/api/v1

  4. Start the development server

    npm run dev
# or
yarn dev

  5. Open http://localhost:3000 in your browser

🔧 Application Workflow

Karibu provides an end-to-end workflow for smart contract development:

  1. Create or Upload - Write Solidity code in our editor or upload existing files
  2. Compile & Analyze - Automated compilation and security analysis
  3. Deploy to Testnet - One-click deployment to supported testnets
  4. Interact & Verify - Call functions and view results in real-time with our universal interface

📖 Usage Guide

Creating a Smart Contract

  1. Navigate to the "Create" page
  2. Choose between Simple Editor and Advanced IDE modes:
    • Simple Editor: Write a single Solidity file or choose from templates
    • Advanced IDE: Develop multi-file projects with dependencies
  3. Save your contract when finished

Using the Advanced Multi-File IDE

  1. Click "Switch to Advanced IDE" from the Create page
  2. Create files and folders with the "New" button
  3. Organize your project structure:
    • Create contract interfaces in separate files
    • Import libraries and dependencies
    • Manage project organization with folders
  4. External libraries like OpenZeppelin are automatically detected and linked
  5. Files with dependencies are compiled together

Using Contract Templates

  1. Navigate to the "Templates" page
  2. Browse templates by category (Tokens, NFTs, DeFi, Governance, Utility)
  3. Click on a template card to:
    • View detailed description
    • See use cases and technical specifications
    • Examine the implementation code
  4. Use the "View Details" button to access comprehensive information about any template
  5. Click "Use Template" to load it directly into the editor
  6. Templates are loaded into the custom contract editor for immediate customization

Analyzing a Contract

  1. On the contract creation page, click "Analyze"
  2. Review security insights and optimization suggestions
  3. Make any necessary modifications based on recommendations

Deploying a Contract

  1. From the editor, click "Deploy"
  2. Enter any constructor arguments if required
  3. Click "Deploy to Testnet"
  4. View deployment status and contract address when complete

Interacting with Contracts

  1. Navigate to the "Interact" page and enter your contract address
  2. Our system automatically detects available functions through bytecode analysis
  3. View live contract state and storage values through our dynamic interface
  4. Select functions to call from the interface
  5. For read functions, results will display immediately
  6. For write functions, transaction details will be shown

Using the AI Assistant

  1. Click the AI Assistant chat button in the bottom-right corner
  2. Ask questions about blockchain concepts, Solidity, or how to use Karibu
  3. Get instant, contextual help while you develop

📄 Documentation

Comprehensive documentation is available in the following files:

🏗️ Project Structure

karibu/
├── app/                  # Next.js app directory
│   ├── api/              # API routes for contract interactions
│   ├── create/           # Contract creation pages and Multi-File IDE
│   ├── interact/         # Contract interaction pages
│   ├── learn/            # Educational content
│   ├── templates/        # Contract templates library
│   ├── community/        # Community features (upcoming)
│   └── roadmap/          # Platform roadmap
├── components/           # Global components
│   ├── providers/        # Context providers including FileSystem
│   └── ui/               # UI components including AI Assistant
├── public/               # Static assets
└── lib/                  # Utility functions

🗺️ Roadmap

Karibu is in active development with the following roadmap:

Current Features

  • Smart Contract Creation and Analysis
  • Multi-File IDE with dependency management
  • External library support (OpenZeppelin, etc.)
  • Dynamic Contract Interaction (supports any contract type)
  • Advanced ABI Discovery through bytecode analysis
  • Live Contract State Visualization
  • EVM Testnet Support (Initial support via Hedera Testnet)
  • Learning Resources
  • Karibu AI Assistant
  • Comprehensive Template System with categories and detailed documentation
  • Community and Learning Pages with integrated navigation

In Progress (Q2 2025)

  • Enhanced Security Analysis with integration with security standards
  • Performance Optimization and AI-assisted code improvements
  • Community Features with code sharing and collaborative development

Future Plans (Q3 2025)

  • Cross-Chain Support (Ethereum integration Q3 2025)
  • Advanced Analytics with deeper insights into contract performance
  • Advanced AI Features with integration into workflow and personalized recommendations

🧠 AI Assistant Setup

The Karibu AI Assistant requires a Gemini API key to function:

  1. Get a Gemini API key from Google AI Studio
  2. Add it to your .env.local file: 
    NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key_here
  3. Restart your development server

🤝 Contributing

We welcome contributions to Karibu! Please see our Contributing Guidelines for details on how to get started.

📦 Building for Production

npm run build
# or
yarn build

To start the production server:

npm start
# or
yarn start

🚢 Deployment

For deployment instructions, please refer to our Deployment Guide.

The application is set up for easy deployment on Vercel:

Deploy with Vercel

📄 License

This project is licensed under the ISC License

📚 Additional Resources

�� Acknowledgements

Troubleshooting

WalletConnect Issues

If you encounter "Connection interrupted while trying to subscribe" or similar WalletConnect errors:

1. Get a Valid WalletConnect Project ID

  • Go to WalletConnect Cloud Dashboard
  • Create a new project
  • Copy your Project ID
  • Add to your .env.local file: 
    NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_actual_project_id_here

2. Common Solutions

  • Clear browser cache and localStorage - WalletConnect stores connection data locally
  • Check network connectivity - Ensure stable internet connection
  • Try a different browser - Some browsers may block WebSocket connections
  • Restart your wallet app - Close and reopen your mobile wallet
  • Switch networks and back - Sometimes changing networks resolves connection issues

3. Alternative Connection Methods

If WalletConnect continues to fail:

  • Use browser extension wallets (MetaMask, etc.) directly
  • Try different wallet apps that support WalletConnect
  • Use the wallet's built-in browser for dApp interactions

4. Development Mode

In development, you can check the browser console for detailed error messages and debugging information.

Network Configuration Issues

If you encounter errors like "Failed to initialize network hedera-testnet":

1. Hedera Networks

  • Hedera networks are handled separately from Ethereum networks
  • Missing Hedera credentials will show warnings but won't break the app
  • To enable full Hedera functionality, configure: 
    HEDERA_OPERATOR_ID=0.0.your_account_id
HEDERA_OPERATOR_KEY=your_private_key

2. Network Fallback

  • The app will automatically fallback to read-only mode if network initialization fails
  • You can still view contracts and interact with supported features
  • Check the browser console for specific network error messages

3. RPC Connection Issues

If you see "could not detect network" errors:

  • Automatic Fallbacks: The app uses multiple RPC endpoints per network
  • Retry Logic: Failed connections automatically try backup endpoints
  • Graceful Degradation: Networks continue in read-only mode if connections fail
  • No App Crashes: Network failures won't break the application

The app includes reliable endpoints for major networks like Ethereum, Polygon, Arbitrum, Optimism, and Base.

About

No description, website, or topics provided.

Resources

Readme

License

ISC license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages