Skip to content

TEST_REAL_TRANSACTIONS.md

Latest commit

 

History

History
330 lines (273 loc) · 9.23 KB

TEST_REAL_TRANSACTIONS.md

File metadata and controls

330 lines (273 loc) · 9.23 KB
Raw

🔥 Test Real Cardano Blockchain Transactions

✅ Status: NO SIMULATIONS - 100% Real Blockchain

All simulated transaction fallbacks have been removed. Every transaction now goes directly to the Cardano blockchain.

🚀 Quick Test (5 Minutes)

Prerequisites Checklist:

  • ✅ Blockfrost API key configured in frontend/.env
  • ✅ Cardano wallet installed (Nami/Lace/Eternl/Flint)
  • ✅ Wallet has testnet ADA (get from faucet)
  • ✅ Development servers running (npm run dev)
  • ✅ Freelancer needs: 1.2 ADA minimum (1 ADA + fees for completion)
  • ✅ Client needs: Milestone amount + 0.2 ADA (for payment + fees)

Step 1: Get Testnet ADA (2 minutes)

# 1. Open your Cardano wallet
# 2. Copy your wallet address
# 3. Visit: https://docs.cardano.org/cardano-testnet/tools/faucet/
# 4. Paste your address and request ADA
# 5. Wait ~20 seconds for confirmation

You need:

  • Freelancer wallet: Minimum 2 ADA (1 ADA for completion proof + fees)
  • Client wallet: Minimum 3 ADA (2 ADA milestone payment + fees)
  • Total for full test: 5 ADA across both wallets

Step 2: Connect Wallet

  1. Open http://localhost:3000
  2. Click "Connect Wallet" (top right)
  3. Select your wallet (Nami/Lace/etc)
  4. Approve the connection
  5. Verify your address and balance display

Step 3: Create Test Project

  1. Click "Create Project"
  2. Fill in: 
    Title: Real Blockchain Test
Description: Testing real Cardano transactions
Freelancer Address: [paste another address or same for testing]

Milestone 1:
- Description: Test milestone
- Amount: 2000000 (2 ADA)
- Deadline: [any future date]
  3. Click "Create Project"
  4. Note the project ID

Step 4: Complete Milestone (Freelancer) 🔥

This is a REAL blockchain transaction!

  1. Navigate to the project detail page
  2. As freelancer, click "Mark Complete"
  3. Wallet popup appears - Review transaction: 
    Sending: 1 ADA (proof of completion)
To: [client address]
Fee: ~0.17 ADA
Metadata: Completion proof with milestone details
  4. Click "Confirm" in wallet
  5. Wait 5-10 seconds
  6. Success! Completion transaction hash displayed
  7. Status changes to "Completed"

Why 1 ADA? This creates an immutable on-chain record that the freelancer has completed the work and is requesting approval. The client receives 1 ADA as proof.

Step 5: Approve & Release Funds (Client) 🔥

This is the REAL blockchain transaction!

  1. As client, click "Approve & Release Funds"
  2. Wallet popup appears - Review transaction: 
    Sending: 2 ADA
To: [freelancer address]
Fee: ~0.17 ADA
Metadata: Project and milestone info
  3. Click "Confirm" in wallet
  4. Wait 5-10 seconds
  5. Success! Transaction hash displayed

Step 6: Verify on Blockchain Explorer

  1. Copy the transaction hash from the success message
  2. Visit: https://preprod.cardanoscan.io/
  3. Paste the transaction hash
  4. See your real transaction!
    • ✅ Amount: 2 ADA
    • ✅ Sender: Your address
    • ✅ Recipient: Freelancer address
    • ✅ Metadata: Project details
    • ✅ Status: Confirmed
    • ✅ Block number
    • ✅ Timestamp

🎯 What Happens Behind the Scenes

Transaction 1: Mark Complete (Freelancer)

1. Freelancer clicks "Mark Complete"
2. Lucid builds transaction: 1 ADA → Client
3. Metadata: Completion proof + milestone details
4. Wallet signs transaction locally
5. Lucid submits to Blockfrost API
6. Blockfrost submits to Cardano network
7. Transaction hash returned
8. Backend updated with completion tx hash

Transaction 2: Approve & Release Funds (Client)

1. Client clicks "Approve & Release Funds"
2. Lucid builds transaction: Full amount → Freelancer
3. Metadata: Payment proof + milestone details
4. Wallet signs transaction locally
5. Lucid submits to Blockfrost API
6. Blockfrost submits to Cardano network
7. Transaction hash returned
8. Backend updated with payment tx hash

Backend (Node.js):

1. Receives transaction hash from frontend
2. Validates and stores in database
3. Returns success with explorer URL
4. NO simulation fallbacks

Blockchain (Cardano):

1. Transaction enters mempool
2. Validators pick up transaction
3. Transaction included in block
4. Block confirmed (~20 seconds)
5. Funds transferred on-chain
6. Permanent immutable record

🔍 Transaction Details

Completion Transaction (Freelancer → Client):

  • Amount: 1 ADA (proof of completion)
  • Sender: Freelancer wallet address
  • Recipient: Client wallet address
  • Fee: ~0.17 ADA (network fee)
  • Metadata (Label 674): 
    {
  "type": "milestone_completion",
  "projectId": "project_123",
  "milestoneId": 1,
  "projectTitle": "Real Blockchain Test",
  "milestoneDescription": "Test milestone",
  "completedBy": "addr_test1freelancer...",
  "timestamp": "2024-12-15T16:30:00Z",
  "message": "Freelancer has completed this milestone and is requesting approval"
}

Payment Transaction (Client → Freelancer):

  • Amount: Full milestone amount (e.g., 2 ADA)
  • Sender: Client wallet address
  • Recipient: Freelancer wallet address
  • Fee: ~0.17 ADA (network fee)
  • Metadata (Label 674): 
    {
  "type": "milestone_payment",
  "projectId": "project_123",
  "milestoneId": 1,
  "projectTitle": "Real Blockchain Test",
  "milestoneDescription": "Test milestone",
  "timestamp": "2024-12-15T16:30:00Z"
}

Transaction Properties:

  • ✅ Immutable: Cannot be reversed or modified
  • ✅ Transparent: Anyone can verify on blockchain
  • ✅ Permanent: Stored forever on Cardano
  • ✅ Trustless: No intermediary needed
  • ✅ Verifiable: Check on any Cardano explorer

⚠️ Important Notes

NO Simulations:

  • ❌ No fallback to mock transactions
  • ❌ No simulated transaction hashes
  • ❌ No demo mode for approvals
  • ✅ 100% real blockchain or error

Requirements:

  • ✅ Valid Blockfrost API key (free from blockfrost.io)
  • ✅ Wallet connected with sufficient ADA
  • ✅ Development mode (npm run dev)
  • ✅ Network connectivity

If Transaction Fails:

The app will show a detailed error message:

  • Wallet not connected → Connect wallet first
  • Insufficient funds → Get more testnet ADA
  • Invalid API key → Configure Blockfrost key
  • Network error → Check internet connection

🧪 Advanced Testing

Test Multiple Milestones:

Create project with 3 milestones:
- Milestone 1: 2 ADA
- Milestone 2: 3 ADA  
- Milestone 3: 5 ADA

Complete and approve each one separately.
Each creates a separate blockchain transaction.

Test Different Wallets:

1. Create project with Wallet A (client)
2. Set Wallet B as freelancer
3. Complete milestone with Wallet B
4. Approve with Wallet A
5. Verify funds arrive in Wallet B

Test Transaction Metadata:

1. Complete transaction
2. View on explorer
3. Click "Metadata" tab
4. See project and milestone details
5. Verify all information is correct

📊 Expected Results

Console Logs (Frontend):

💰 Approving milestone and releasing funds...
Amount: 2 ADA
Recipient: addr_test1...
🔨 Building real blockchain transaction...
✅ Transaction signed, submitting to blockchain...
📡 Submitting to Cardano network via Blockfrost...
✅ Transaction submitted successfully to Cardano blockchain!
Transaction hash: a1b2c3d4e5f6...
View on explorer: https://preprod.cardanoscan.io/transaction/a1b2c3d4e5f6...

Console Logs (Backend):

✅ Approving milestone 1 for project project_123
💰 Recording blockchain transaction...
Transaction hash: a1b2c3d4e5f6...
View on explorer: https://preprod.cardanoscan.io/transaction/a1b2c3d4e5f6...

User Experience:

  1. Click button
  2. Wallet popup (5 seconds)
  3. Confirm transaction
  4. Success message with tx hash (5 seconds)
  5. Funds transferred on blockchain (20 seconds)
  6. Verifiable on explorer (immediately)

🎉 Success Indicators

You'll know it's working when:

  • ✅ Wallet prompts for signature
  • ✅ Real transaction hash returned (64 characters)
  • ✅ Transaction visible on Cardano explorer
  • ✅ Funds actually transferred between wallets
  • ✅ Metadata visible on blockchain
  • ✅ Transaction confirmed in blocks

🔧 Troubleshooting

"Wallet not connected"

→ Click "Connect Wallet" and approve

"Insufficient funds"

→ Get more testnet ADA from faucet

"Invalid project token"

→ Check Blockfrost API key in frontend/.env

"Lucid library not available"

→ Make sure you're running npm run dev (not production build)

Transaction pending forever

→ Check Cardano network status → Verify on explorer → May take up to 2 minutes during high load

📈 Next Steps

After successful testing:

  1. ✅ Test with different amounts
  2. ✅ Test with multiple milestones
  3. ✅ Test with different wallets
  4. ✅ Verify all transactions on explorer
  5. ✅ Check metadata is correct
  6. ✅ Confirm funds arrive in recipient wallet

🌐 Mainnet Deployment

To use real ADA on mainnet:

  1. Change network to mainnet in .env
  2. Get mainnet Blockfrost API key
  3. Use real ADA (not testnet)
  4. Test thoroughly on testnet first!

Status: ✅ Real blockchain transactions only - No simulations Network: Cardano Preprod Testnet Last Updated: December 15, 2024