Cardano Proposal Anchoring Prototype

A minimal working Python prototype that anchors community proposals to the Cardano blockchain using Blockfrost and PyCardano. The system uploads proposals to Arweave for permanent storage, computes SHA256 hashes, and anchors them as metadata in Cardano transactions on the testnet.

📑 Table of Contents

• Key Features
• Architecture
• Quick Start
• Usage
• How It Works
• Troubleshooting
• Project Structure
• Useful Links

✨ Key Features

• 🔐 Immutable Anchoring - Proposals permanently stored on Cardano blockchain
• 🌐 Permanent Storage - Arweave integration for decentralized, permanent data storage
• 🔍 Verifiable Integrity - SHA256 hashing ensures data hasn't been tampered with
• ⚡ Simple CLI - Easy-to-use command-line interface for anchoring and verification
• 🔑 Secure Wallets - Built-in wallet generation and management
• 📊 Metadata Support - Rich metadata stored on-chain for easy retrieval
• 🌍 Testnet Ready - Works with Cardano preview and preprod testnets
• 🎯 Production Ready - Fully tested and operational with comprehensive error handling

🏗️ Architecture

Proposal JSON → Arweave Upload → Hash Computation → Cardano Transaction → Blockchain
     ↓              ↓              ↓                    ↓              ↓
   JSON File    Arweave TX ID   SHA256 Hash         Metadata         On-chain

🚀 Quick Start

💡 Tip: Always use the wrapper scripts (anchor_proposal.py, verify_proposal.py, wallet_utils.py) from the project root - they handle all paths automatically!

1. Installation

# Clone the repository
git clone <repository-url>
cd AI-Blockchain-Prototype

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run setup script to verify installation
python setup.py

2. Configuration

Copy the environment template and configure your API keys:

cp env.example .env

Edit .env with your credentials:

# Blockfrost API Configuration
BLOCKFROST_API_KEY=your_blockfrost_api_key_here
BLOCKFROST_NETWORK=preview

# Arweave Configuration
ARWEAVE_GATEWAY_URL=https://arweave.net
ARWEAVE_KEY_FILE=your_arweave_wallet_key.json
ARWEAVE_NETWORK=mainnet

# Cardano Network Configuration
CARDANO_NETWORK=preview
METADATA_LABEL=1337

3. Get API Keys

Blockfrost API Key

1. Visit Blockfrost.io
2. Sign up for a free account
3. Create a new project for Cardano (choose mainnet, preview, or preprod)
4. Copy your API key to .env
5. Set BLOCKFROST_NETWORK to match your project (mainnet/preview/preprod)

Arweave Wallet

1. Visit Arweave.org
2. Download the Arweave wallet or use ArConnect
3. Create a new wallet and download the key file (e.g., your_arweave_wallet_key.json)
4. Save the key file in your project directory
5. Update .env with your key file name:

   ARWEAVE_KEY_FILE=your_arweave_wallet_key.json
   

6. Fund your wallet with AR tokens (see funding instructions below)

📘 For detailed Arweave setup, see ARWEAVE_SETUP.md

4. Generate Wallet

# Generate a new testnet wallet
python wallet_utils.py --generate

This will create:

• wallet.json - Wallet keys (keep secure!)
• wallet_mnemonic.txt - Recovery phrase (keep secure!)

5. Fund Your Wallets

Cardano Wallet (for transaction fees)

1. Copy the payment address from the wallet generation output
2. For preview/preprod networks: Visit the Cardano Testnets Faucet
3. For mainnet: Transfer ADA from an exchange or wallet
4. Request testnet ADA for your address (preview/preprod only)
5. Wait for the transaction to confirm

Arweave Wallet (for permanent storage)

1. Get AR tokens from exchanges like KuCoin, Gate.io, or Binance
2. Transfer AR to your Arweave wallet address
3. You need approximately 0.1-0.5 AR for each upload (cost varies with data size)

📖 Usage

Anchor a Proposal

Using Example Proposal

python anchor_proposal.py --example

Using a JSON File

# Create a proposal file
cat > my_proposal.json << EOF
{
  "title": "Community Garden Initiative",
  "description": "Proposal to establish a community garden in the local park",
  "proposer": "Alice Johnson",
  "timestamp": 1703001600,
  "category": "community_development",
  "budget": 5000,
  "duration_months": 12
}
EOF

# Anchor the proposal
python anchor_proposal.py --file my_proposal.json

Using stdin

echo '{"title": "Test Proposal", "description": "A test proposal", "proposer": "Test User"}' | python anchor_proposal.py --stdin

Verify a Proposal

# Verify using transaction ID
python verify_proposal.py <transaction_id>

# Show full proposal content
python verify_proposal.py <transaction_id> --show-proposal

# Save results to file
python verify_proposal.py <transaction_id> --output verification_results.json

📋 Proposal Schema

The system accepts proposals with the following structure:

{
  "title": "string (required)",
  "description": "string (required)", 
  "proposer": "string (required)",
  "timestamp": "number (optional)",
  "category": "string (optional)",
  "budget": "number (optional)",
  "duration_months": "number (optional)",
  "beneficiaries": "array (optional)"
}

🔧 API Reference

Wallet Management

# Generate new wallet
python wallet_utils.py --generate

# Show wallet info
python wallet_utils.py --info

Proposal Anchoring

# Anchor from file
python anchor_proposal.py --file proposal.json

# Anchor from stdin
python anchor_proposal.py --stdin

# Use example proposal
python anchor_proposal.py --example

# Save results to file
python anchor_proposal.py --file proposal.json --output results.json

Proposal Verification

# Basic verification
python verify_proposal.py <tx_id>

# Show proposal content
python verify_proposal.py <tx_id> --show-proposal

# Save results
python verify_proposal.py <tx_id> --output results.json

🔍 How It Works

Anchoring Process

1. Proposal Input: Accept JSON proposal via file, stdin, or example
2. Hash Computation: Compute SHA256 hash of normalized JSON
3. Arweave Upload: Upload proposal to Arweave for permanent storage
4. Transaction Building: Create Cardano transaction with metadata
5. Blockchain Submission: Submit transaction to Cardano testnet
6. Confirmation: Return transaction ID and Arweave permanent URL

Verification Process

1. Transaction Lookup: Fetch transaction metadata from Blockfrost
2. Arweave Retrieval: Download proposal using stored Arweave transaction ID
3. Hash Comparison: Compute hash of retrieved proposal
4. Verification: Compare computed hash with on-chain hash
5. Result: Report success/failure with details

🛡️ Security Considerations

• Testnet Only: This prototype is designed for Cardano testnet only
• Wallet Security: Keep your wallet files and mnemonics secure
• API Keys: Don't commit API keys to version control
• Environment Variables: Use .env file for sensitive configuration

🐛 Troubleshooting

Common Issues

"python: command not found"

# Use python3 instead of python
python3 wallet_utils.py --generate
python3 anchor_proposal.py --example
python3 verify_proposal.py <tx_id>

# Or create an alias in your shell
echo 'alias python=python3' >> ~/.zshrc
source ~/.zshrc

"No wallet found"

# Generate a wallet first
python wallet_utils.py --generate

"No UTxOs found"

# Fund your wallet with ADA
# Preview/Preprod: https://docs.cardano.org/cardano-testnets/tools/faucet
# Mainnet: Transfer ADA from exchange or wallet

"Arweave key file not found"

# Download your Arweave wallet key file from Arweave.org or ArConnect
# Save it in the project directory
# Update .env with the exact filename:
# ARWEAVE_KEY_FILE=your_arweave_wallet_key.json

# Check if the file exists
ls -la *.json

"Insufficient AR balance"

# Check your AR balance
python check_arweave_balance.py

# Or use arweave_utils directly
python arweave_utils.py --check-balance --key-file your_arweave_wallet_key.json

# Fund your Arweave wallet with AR tokens
# You need approximately 0.1-0.5 AR per upload

"Failed to submit transaction"

# Check your Blockfrost API key
# Ensure you have sufficient ADA in your wallet
# Verify network configuration (mainnet/preview/preprod)
# Ensure your API key matches the selected network

Debug Mode

Enable verbose logging by setting environment variable:

export PYTHONPATH=.
python -v anchor_proposal.py --example

📁 Project Structure

AI-Blockchain-Prototype/
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── setup.py                     # Package setup script
├── .env.example                 # Environment template
├── .gitignore                   # Git ignore rules
│
├── src/                         # 🔧 Source Code
│   ├── config.py               # Configuration management
│   ├── core/                   # Core functionality
│   │   ├── wallet_utils.py     # Cardano wallet operations
│   │   └── arweave_utils.py    # Arweave operations
│   └── commands/               # CLI commands
│       ├── anchor_proposal.py  # Proposal anchoring
│       └── verify_proposal.py  # Proposal verification
│
├── scripts/                     # 🔨 Helper Scripts
│   ├── check_status.py         # System status checker
│   ├── check_arweave_balance.py # Check Arweave balance
│   └── test_blockfrost.py      # Test Blockfrost API
│
├── docs/                        # 📚 Documentation
│   ├── ARWEAVE_SETUP.md        # Arweave wallet guide
│   ├── ARCHITECTURE.md         # System architecture
│   ├── API.md                  # API reference
│   └── TROUBLESHOOTING.md      # Troubleshooting guide
│
├── examples/                    # 📝 Usage Examples
│   ├── example_proposal.json   # Sample proposal
│   └── anchor_example.py       # Example script
│
├── tests/                       # 🧪 Tests
│   └── (test files here)
│
└── wallet/                      # 💼 Wallet Storage
    ├── wallet.json             # Generated wallet (keep secure!)
    ├── wallet_mnemonic.txt     # Recovery phrase (keep secure!)
    └── your_arweave_wallet_key.json # Arweave key (keep secure!)

Note: For backwards compatibility, wrapper scripts exist in the root directory that call the organized code in src/.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

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

⚠️ Disclaimer

This is a prototype for educational and testing purposes only. Do not use for production applications without proper security audits and testing.

🔗 Useful Links

• Cardano Documentation
• PyCardano Documentation
• Blockfrost API Documentation
• Arweave Documentation
• Arweave Wallet
• ArConnect Browser Extension
• Cardano Testnets Faucet
• AR Token Exchanges