Cardano Blockchain Integration Guide

🎯 Overview

This guide explains how to enable live Cardano blockchain transactions in TrustlessTask.

📋 Current Status

✅ What's Implemented

Cardano wallet connection interface
Blockfrost API integration
Transaction building framework
Script interaction methods
Transaction status tracking

⏳ What's Needed for Live Transactions

Blockfrost API key (free tier available)
Cardano wallet browser extension
Test ADA from faucet
Deployed Plutus scripts

🚀 Quick Start: Enable Blockchain

Step 1: Get Blockfrost API Key

Go to https://blockfrost.io/
Sign up for free account
Create new project (select Preprod testnet)
Copy your project ID

Step 2: Configure Environment

Frontend (frontend/.env):

VITE_BLOCKFROST_PROJECT_ID=your_project_id_here
VITE_BLOCKFROST_URL=https://cardano-preprod.blockfrost.io/api/v0
VITE_NETWORK=Preprod

Backend (backend-api/.env):

BLOCKFROST_PROJECT_ID=your_project_id_here
CARDANO_NETWORK=preprod

Step 3: Install Cardano Wallet

Choose one:

Install browser extension and create wallet.

Step 4: Get Test ADA

Go to https://docs.cardano.org/cardano-testnet/tools/faucet/
Enter your testnet address
Receive 10,000 test ADA

Step 5: Enable Blockchain Mode

In frontend/src/hooks/useWallet.ts:

const USE_REAL_BLOCKCHAIN = true; // Change from false to true

Step 6: Restart Application

# Stop current processes (Ctrl+C)

# Restart backend
cd backend-api
npm run dev

# Restart frontend (new terminal)
cd frontend
npm run dev

🔧 How It Works

Wallet Connection Flow

User clicks "Connect Wallet"
    ↓
Frontend detects wallet extension
    ↓
Request wallet access
    ↓
User approves in wallet popup
    ↓
Get wallet address & balance
    ↓
Store connection state

Transaction Flow

User creates project
    ↓
Frontend builds transaction
    ↓
Attach project datum
    ↓
User signs in wallet
    ↓
Submit to Cardano network
    ↓
Wait for confirmation
    ↓
Update UI with tx hash

📝 Code Examples

Connect to Real Wallet

import { getCardanoService } from './services/cardano';

const cardano = getCardanoService();

// Connect wallet
const { address, balance } = await cardano.connectWallet('nami');
console.log('Connected:', address);
console.log('Balance:', balance / 1_000_000, 'ADA');

Lock Funds in Escrow

const txHash = await cardano.lockFundsInEscrow({
  amount: 1000_000_000, // 1000 ADA
  scriptAddress: 'addr_test1w...',
  datum: {
    projectId: 'proj_123',
    client: 'addr_test1...',
    freelancer: 'addr_test1...',
    milestones: [...]
  }
});

console.log('Funds locked! Tx:', txHash);

Release Funds

const txHash = await cardano.releaseFundsFromEscrow({
  scriptUtxo: 'utxo_ref',
  redeemer: {
    action: 'ReleaseFunds',
    milestoneId: 1
  },
  recipient: 'addr_test1...'
});

console.log('Funds released! Tx:', txHash);

Check Transaction Status

const status = await cardano.getTransactionStatus(txHash);

if (status.confirmed) {
  console.log('Confirmed at block:', status.blockHeight);
} else {
  console.log('Pending...');
}

🔐 Security Considerations

Private Keys

✅ Never stored in application
✅ Managed by wallet extension
✅ User signs each transaction

Transaction Validation

✅ Amount limits enforced
✅ Recipient addresses verified
✅ User confirms in wallet popup

Smart Contract Security

✅ Plutus validators enforce rules
✅ Funds locked until conditions met
✅ No centralized control

🧪 Testing on Testnet

Test Scenario 1: Create Project

Connect wallet (Nami/Eternl/Flint)
Create new project with milestones
Sign transaction in wallet
Wait for confirmation (~20 seconds)
View transaction on CardanoScan

Test Scenario 2: Complete Milestone

As freelancer, mark milestone complete
As client, approve milestone
Sign release transaction
Funds transferred to freelancer
Verify on blockchain explorer

Test Scenario 3: Dispute

Raise dispute
Arbiter reviews
Arbiter resolves
Funds distributed per outcome

📊 Monitoring Transactions

Blockchain Explorers

Preprod Testnet:

Mainnet:

Check Transaction

https://preprod.cardanoscan.io/transaction/{txHash}

🚨 Troubleshooting

Wallet Not Detected

Error: nami wallet not found

Solution: Install wallet extension and refresh page

Insufficient Funds

Error: Not enough ADA

Solution: Get test ADA from faucet

Transaction Failed

Error: Transaction submission failed

Solution:

Check network (preprod vs mainnet)
Verify script address
Ensure enough ADA for fees

Blockfrost Rate Limit

Error: 429 Too Many Requests