Monad Token Transfer Test

A simple test suite that simulates and verifies basic token transfer transactions in a Monad-style blockchain execution environment.

Overview

This test demonstrates fundamental blockchain transaction processing including:

• Token transfers between accounts
• Balance state management
• Gas cost calculation and deduction
• Transaction nonce handling
• Edge case validation

Goal

Verify that a Monad node correctly processes basic token transfers by checking that account balances, gas fees, and nonces are updated properly in the blockchain state.

Files

• token_transfer_test.cpp - Main test suite with 6 comprehensive test cases
• run_test.sh - Build and execution script

Prerequisites

• G++ compiler with C++17 support
• Linux/Unix environment (or WSL on Windows)
• No external dependencies required

Installation

1. Clone or download the repository
2. Ensure you have g++ installed:

   g++ --version

Usage

Quick Start

Run the test suite with a single command:

chmod +x run_test.sh
./run_test.sh

Manual Build and Run

Alternatively, compile and run manually:

# Compile
g++ -std=c++17 -o token_transfer_test token_transfer_test.cpp

# Run
./token_transfer_test

Test Cases

Test 1: Successful Token Transfer

• Transfers 50,000 tokens from sender to receiver
• Verifies balance updates
• Confirms gas cost deduction (21,000 gas × 20 gas price)
• Checks nonce increment

Test 2: Insufficient Balance Failure

• Attempts transfer exceeding available balance
• Verifies transaction rejection
• Ensures state remains unchanged

Test 3: Multiple Transaction Processing

• Processes 3 sequential transfers
• Validates cumulative balance changes
• Confirms proper nonce progression

Test 4: Gas Cost Calculation

• Tests with high gas price (100)
• Verifies accurate gas cost computation
• Ensures correct fee deduction

Test 5: Exact Balance Transfer

• Edge case: transfer maximum possible amount
• Tests precision in balance calculations
• Confirms sender ends with zero balance

Test 6: Edge Cases

• Zero amount transfers
• Gas deduction verification for edge cases

Expected Output

========================================
Monad Token Transfer Test Suite
========================================
Testing basic transaction processing and state changes

Test 1: Successful Token Transfer
  [PASS] Transfer should succeed
  [PASS] Sender balance correct
  [PASS] Receiver balance correct
  [PASS] Nonce incremented

Test 2: Insufficient Balance Failure
  [PASS] Transfer should fail
  [PASS] Sender balance unchanged
  [PASS] Receiver balance unchanged

Test 3: Multiple Transaction Processing
  [PASS] Transaction 1 succeeds
  [PASS] Transaction 2 succeeds
  [PASS] Transaction 3 succeeds
  [PASS] Sender final balance correct
  [PASS] Receiver final balance correct
  [PASS] Nonce updated for all transactions

Test 4: Gas Cost Calculation
  [PASS] Transfer succeeds
  [PASS] Gas cost calculated correctly

Test 5: Exact Balance Transfer (Edge Case)
  [PASS] Max transfer succeeds
  [PASS] Sender has zero balance
  [PASS] Receiver gets max amount

Test 6: Edge Cases
  [PASS] Zero amount transfer allowed
  [PASS] Gas deducted even for zero transfer

========================================
Test Summary:
  Passed: 20
  Failed: 0
  Total:  20
========================================

All tests passed!

Architecture

StateManager Class

Manages blockchain state including:

• Account balances (map of address → balance)
• Account nonces (map of address → nonce)
• Transfer logic with gas cost calculation

Transaction Structure

Represents a basic blockchain transaction:

struct Transaction {
    string from;        // Sender address
    string to;          // Recipient address
    uint64_t value;     // Amount to transfer
    uint64_t gasLimit;  // Maximum gas allowed
    uint64_t gasPrice;  // Price per gas unit
    uint64_t nonce;     // Transaction sequence number
}

TestRunner Class

Custom test framework providing:

• Assertion methods (assert_equal, assert_true, assert_false)
• Test result tracking
• Summary reporting

Implementation Details

Gas Cost Calculation

Total Cost = Transfer Amount + (Gas Limit × Gas Price)

Standard transfer gas limit: 21,000 units

Balance Update Formula

Sender Balance After = Initial Balance - Transfer Amount - Gas Cost
Receiver Balance After = Initial Balance + Transfer Amount

Nonce Management

• Increments by 1 for each successful transaction
• Used to prevent replay attacks
• Ensures transaction ordering

Integration with Monad

This test uses mock/simulated classes for standalone operation. To integrate with the actual Monad blockchain:

1. Replace StateManager with Monad's actual state management system
2. Use Monad's transaction structures from execution/transaction.h
3. Link against Monad execution libraries
4. Update gas cost calculations to match Monad's implementation

Troubleshooting

Compilation Errors

• Ensure g++ supports C++17: g++ -std=c++17 --version
• Check file permissions: ls -la token_transfer_test.cpp

Permission Denied

chmod +x run_test.sh

File Not Found

• Verify files are in current directory: ls -la
• Check you're in the correct directory: pwd

Contributing

To extend the test suite:

1. Add new test functions following the pattern: void test_name(TestRunner& runner)
2. Call your test in main()
3. Use runner.assert_* methods for validation
4. Document the test case in this README

License

This test suite is provided as-is for educational and testing purposes within the Monad blockchain project.

Author

Created as a demonstration of basic transaction processing and state management in blockchain execution environments.

Related Documentation

• Monad Architecture
• Monad Execution Component
• EVM Transaction Processing

Version History

• v1.0 - Initial release with 6 core test cases
  • Basic transfer validation
  • Gas cost verification
  • Edge case handling
  • Standalone operation without external dependencies