RapidChain - Vibe Coded Blockchain Implementation

A vibe coded feature-rich DEMO blockchain with CUSTOM smart contract support, multi-principal architecture (Wallet/User/App), and a complete wallet application (CLI + GUI).

Features

• Proof of Stake (PoS) consensus mechanism
• Smart Contracts with Solidity-like language
• Multi-Principal System: Wallet, User, and App principals with access control
• ERC20 Tokens and ERC721 NFTs
• Data Storage via DATA transactions
• Wallet Application with CLI and GUI interfaces
• gRPC-based node communication

Quick Start

1. Install Dependencies

pip install grpcio grpcio-tools ecdsa mnemonic customtkinter

2. Compile Proto Files (if modified)

python -m grpc_tools.protoc -I protos --python_out=. --grpc_python_out=. protos/miner.proto

3. Start a Blockchain Node

python start_node.py

The node will:

• Initialize blockchain storage (test_blockchain.db)
• Fund test wallet 0xc0e1a9546e05f6a4814b8d1264f73dbdd82f0536 with 1000 COIN
• Start gRPC server on localhost:50051
• Auto-mine blocks every 5 seconds if transactions are pending

4. Use the Wallet

GUI (Recommended):

python wallet_gui.py

CLI:

# Create wallet
python wallet_app.py create

# View balance
python wallet_app.py info

# Send coins
python wallet_app.py transfer <RECEIVER_ADDRESS> <AMOUNT>

# Deploy contract
python wallet_app.py deploy --code contracts/erc20.sol

# Deploy as app
python wallet_app.py deploy --code contracts/game_score.sol --as-app "game:v1"

Wallet GUI Guide

Tabs Overview

1. Home - View balance and address
2. Send - Transfer native COINs
3. Transactions - View transaction history (placeholder)
4. Tokens - Manage ERC20 tokens
5. NFTs - View NFT collections
6. Contracts - Interact with any contract
7. Deploy - Deploy smart contracts
8. Data - Store and retrieve data on-chain
9. Settings - Configure node address

Managing Tokens

1. Navigate to Tokens tab
2. Click "+ Add Token"
3. Enter token name and contract address
4. View balance and transfer tokens

Managing NFTs

1. Navigate to NFTs tab
2. Click "+ Add Collection"
3. Enter collection name and contract address
4. View owned NFTs

Deploying Contracts

As Wallet (User-owned):

1. Navigate to Deploy tab
2. Paste contract source code
3. Select "Wallet" radio button
4. Click "Deploy Contract"

As App (App-owned with isolation):

1. Select "App" radio button
2. Enter App ID (e.g., game:chess)
3. Click "Deploy Contract"
4. First deployment creates a new key for the app
5. Subsequent deployments reuse the same key

Storing Data

1. Navigate to Data tab
2. Enter a key (identifier)
3. Enter data (any text/JSON)
4. Click "Store Data"
5. Use "Retrieve Data" to view stored data

Understanding Principals

RapidChain supports three principal types:

1. Wallet Principal

• Traditional blockchain address (like Ethereum)
• Derived from ECDSA keypair
• Example: 0xc0e1a9546e05f6a4814b8d1264f73dbdd82f0536

2. User Principal

• Virtual identity within an app
• Format: user:alice within app:my-app
• Transactions signed by the app but attributed to the user

3. App Principal

• Application-level identity
• Format: app:my-awesome-app
• Can own contracts with app isolation (only owner app can call app modifier functions)

Smart Contract Examples

ERC20 Token

contract MyToken {
    public String name;
    public String symbol;
    public Integer totalSupply;
    public mapping(Address => Integer) balances;

    function initialize(String _name, String _symbol, Integer _supply) public {
        name = _name;
        symbol = _symbol;
        totalSupply = _supply;
        balances[msg.sender] = _supply;
    }

    function transfer(Address to, Integer amount) public {
        balances[msg.sender] = balances[msg.sender] - amount;
        balances[to] = balances[to] + amount;
    }

    function balanceOf(Address owner) public returns Integer {
        return balances[owner];
    }
}

App-Restricted Contract

contract GameScore {
    mapping(String => Integer) scores;

    // Only the owner app can call this
    function submitScore(String player, Integer score) app {
        scores[player] = score;
    }

    // Anyone can read
    function getScore(String player) public returns Integer {
        return scores[player];
    }
}

Transaction Types

TRANSFER

Send native COINs from one address to another.

python wallet_app.py transfer 0xBOB 50

DEPLOY

Deploy a smart contract.

python wallet_app.py deploy --code contracts/erc20.sol

CALL

Execute a smart contract method.

python wallet_app.py exec --contract 0xTOKEN --method transfer --args '["0xBOB", 100]'

DATA

Store arbitrary data on-chain.

# Via GUI: Data tab -> Enter key/value -> Store Data

Architecture

├── chain/
│   ├── blockchain.py    # Core blockchain logic
│   ├── node.py          # gRPC node server
│   ├── wallet.py        # Wallet/key management
│   ├── transaction.py   # Transaction types
│   ├── block.py         # Block structure
│   └── storage.py       # SQLite persistence
├── sol/
│   ├── lexer.py         # Contract lexer
│   ├── lang_ast.py      # AST parser
│   ├── compiler.py      # Bytecode compiler
│   └── bytecode.py      # Virtual machine
├── contracts/           # Sample contracts
│   ├── erc20.sol
│   ├── nft.sol
│   ├── game_score.sol
│   └── ...
├── protos/
│   └── miner.proto      # gRPC definitions
├── wallet_client.py     # Shared wallet logic
├── wallet_app.py        # CLI wallet
├── wallet_gui.py        # GUI wallet
└── start_node.py        # Node startup script

Testing

Run the comprehensive test suite:

python tests/test.py

Tests include:

• ERC20 operations
• NFT minting/transfers
• Multisig wallets
• Auction systems
• Staking with cross-contract calls
• User/App modifiers
• App isolation security

Node RPC API

The node exposes the following gRPC methods:

• SubmitTransaction - Submit a transaction to the mempool
• ProposeBlock - Propose a new block (PoS)
• SyncChain - Synchronize blockchain state
• GetState - Query account balance and nonce
• Call - Execute read-only contract call

Port Already in Use?

If you see "address already in use" error:

Windows:

netstat -ano | findstr :50051
taskkill /PID <PID> /F

Linux/Mac:

lsof -i :50051
kill -9 <PID>

Troubleshooting

Wallet not found

Run python wallet_app.py create first.

Node connection error

Ensure start_node.py is running and listening on localhost:50051.

Contract not found after deployment

Wait 5-10 seconds for the block to be mined, then check node.log for the contract address.

Transaction not mining

Blocks are mined every 5 seconds if there are pending transactions. Check node.log output.

⚠️ This is a demonstration blockchain.