BALANCE (0x31)

address (uint160 as uint256)

balance (uint256)

address = stack.pop()
balance = state.getBalance(address)
stack.push(balance)

import { balance } from '@tevm/voltaire/evm/context';
import { createFrame } from '@tevm/voltaire/evm/Frame';
import * as Address from '@tevm/voltaire/primitives/Address';

// Check balance of an address
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
const addrU256 = BigInt(addr); // Convert to u256

const frame = createFrame({ stack: [addrU256] });
const host = {
  getBalance: (addr) => 1000000000000000000n // 1 ETH
};

const err = balance(frame, host);

console.log(frame.stack[0]); // 1000000000000000000n (1 ETH in wei)

contract BalanceChecker {
    function getBalance(address account) public view returns (uint256) {
        return account.balance;  // Uses BALANCE opcode
    }

    function getSelfBalance() public view returns (uint256) {
        return address(this).balance;
    }

    function hasMinimumBalance(address account, uint256 min) public view returns (bool) {
        return account.balance >= min;
    }
}

contract PaymentProcessor {
    function processPayment(address payer, uint256 amount) public {
        // Verify payer has sufficient balance
        require(payer.balance >= amount, "Insufficient balance");

        // Process payment...
    }
}

// First access: cold (2600 gas)
let bal1 = address(0x123).balance;

// Second access: warm (100 gas)
let bal2 = address(0x123).balance;

// Different address: cold again (2600 gas)
let bal3 = address(0x456).balance;

// Pre-warm addresses in transaction
{
  accessList: [
    {
      address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      storageKeys: []
    }
  ]
}
// BALANCE now costs only 100 gas

contract MinimumBalance {
    uint256 public constant MINIMUM = 1 ether;

    modifier hasMinimum(address account) {
        require(account.balance >= MINIMUM, "Insufficient balance");
        _;
    }

    function restricted() public hasMinimum(msg.sender) {
        // Only callable if sender has >= 1 ETH
    }
}

contract BalanceTracker {
    mapping(address => uint256) public lastKnownBalance;

    function updateBalance(address account) public {
        lastKnownBalance[account] = account.balance;
    }

    function balanceChanged(address account) public view returns (bool) {
        return account.balance != lastKnownBalance[account];
    }
}

contract Withdrawable {
    mapping(address => uint256) public balances;

    function withdraw() public {
        uint256 amount = balances[msg.sender];
        require(amount > 0, "No balance");

        // Check contract has sufficient balance
        require(address(this).balance >= amount, "Insufficient contract balance");

        balances[msg.sender] = 0;
        payable(msg.sender).transfer(amount);
    }
}

contract PaymentRouter {
    function routePayment(address[] memory recipients, uint256 amount) public payable {
        require(msg.value >= amount * recipients.length);

        for (uint i = 0; i < recipients.length; i++) {
            // Check if recipient can receive (not always reliable)
            if (recipients[i].balance + amount <= type(uint256).max) {
                payable(recipients[i]).transfer(amount);
            }
        }
    }
}

// VULNERABLE: Balance can change between checks
function withdraw(uint256 amount) public {
    require(address(this).balance >= amount);  // Check
    // ... other operations ...
    payable(msg.sender).transfer(amount);      // Use
    // Balance may have changed in between!
}

function withdraw(uint256 amount) public {
    uint256 balance = address(this).balance;
    require(balance >= amount);
    payable(msg.sender).transfer(amount);
}

contract Vulnerable {
    function doSomething() public {
        require(address(this).balance == 0, "Must be empty");
        // DANGEROUS: Attacker can selfdestruct and force-send ETH
    }
}

contract Attacker {
    function attack(address target) public payable {
        selfdestruct(payable(target));  // Force-send ETH
        // Now target.balance > 0, breaking the invariant
    }
}

contract Safe {
    uint256 public accountedBalance;

    receive() external payable {
        accountedBalance += msg.value;
    }

    function doSomething() public {
        // Use accounting, not balance
        require(accountedBalance == 0);
    }
}

// Pre-Solidity 0.8.0: VULNERABLE
function totalBalance(address[] memory accounts) public view returns (uint256) {
    uint256 total = 0;
    for (uint i = 0; i < accounts.length; i++) {
        total += accounts[i].balance;  // Can overflow!
    }
    return total;
}

function totalBalance(address[] memory accounts) public view returns (uint256) {
    uint256 total = 0;
    for (uint i = 0; i < accounts.length; i++) {
        total += accounts[i].balance;  // Reverts on overflow
    }
    return total;
}

// Zero address may have balance
const frame = createFrame({ stack: [0n] });
balance(frame, host);

// Returns actual balance, not necessarily 0

// Non-existent accounts have balance 0
const randomAddr = 0x999999n;
const frame = createFrame({ stack: [randomAddr] });
balance(frame, { getBalance: () => 0n });

console.log(frame.stack[0]); // 0n

// Theoretically possible (though impractical)
const MAX_U256 = (1n << 256n) - 1n;
const frame = createFrame({ stack: [0x123n] });
balance(frame, { getBalance: () => MAX_U256 });

console.log(frame.stack[0]); // MAX_U256

// No address on stack
const frame = createFrame({ stack: [] });
const err = balance(frame, host);

console.log(err); // { type: "StackUnderflow" }