SUB (0x03)

a (top)
b

(a - b) mod 2^256

result = (a - b) & ((1 << 256) - 1)

import { sub } from '@tevm/voltaire/evm/arithmetic';
import { createFrame } from '@tevm/voltaire/evm/Frame';

// 10 - 5 = 5
const frame = createFrame({ stack: [10n, 5n] });
const err = sub(frame);

console.log(frame.stack); // [5n]
console.log(frame.gasRemaining); // Original - 3

// 0 - 1 wraps to maximum value
const frame = createFrame({ stack: [0n, 1n] });
const err = sub(frame);

const MAX = (1n << 256n) - 1n;
console.log(frame.stack); // [MAX]

// 5 - 10 wraps around
const frame = createFrame({ stack: [5n, 10n] });
const err = sub(frame);

// Result: 2^256 - 5 = MAX - 4
const MAX = (1n << 256n) - 1n;
console.log(frame.stack); // [MAX - 4n]

// Subtracting zero
const frame = createFrame({ stack: [42n, 0n] });
const err = sub(frame);

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

// x - x = 0
const frame = createFrame({ stack: [42n, 42n] });
const err = sub(frame);

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

// Smallest underflow: 0 - MAX
const MAX = (1n << 256n) - 1n;
const frame = createFrame({ stack: [0n, MAX] });
sub(frame);

console.log(frame.stack); // [1n]
// Because: (0 - MAX) mod 2^256 = 1

// 0 - 0 = 0
const frame = createFrame({ stack: [0n, 0n] });
sub(frame);

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

// SUB is NOT commutative: a - b ≠ b - a
const frame1 = createFrame({ stack: [10n, 5n] });
sub(frame1);  // 10 - 5 = 5

const frame2 = createFrame({ stack: [5n, 10n] });
sub(frame2);  // 5 - 10 = wraps

console.log(frame1.stack[0] === frame2.stack[0]); // false

// Not enough stack items
const frame = createFrame({ stack: [5n] });
const err = sub(frame);

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

// Decrease balance
function withdraw(uint256 amount) public {
    require(balances[msg.sender] >= amount, "insufficient balance");
    balances[msg.sender] -= amount;  // SUB opcode
    payable(msg.sender).transfer(amount);
}

// Countdown loop
for (uint i = n; i > 0; i--) {
    // Compiler generates: SUB i, 1
}

// Time elapsed
function elapsed(uint256 startTime) view returns (uint256) {
    return block.timestamp - startTime;
}

// Price difference
function priceGap(uint256 buyPrice, uint256 sellPrice)
    pure returns (uint256) {
    require(sellPrice >= buyPrice, "invalid prices");
    return sellPrice - buyPrice;
}

// Check if value is in range [min, max]
function inRange(uint256 value, uint256 min, uint256 max)
    pure returns (bool) {
    return (value - min) <= (max - min);
    // Uses wrapping: if value < min, underflows to large number
}

// Default: checked arithmetic (adds underflow checks)
uint256 result = a - b;  // Reverts on underflow

// Explicit wrapping (uses raw SUB)
unchecked {
    uint256 result = a - b;  // Wraps on underflow
}

import { describe, it, expect } from 'vitest';
import { sub } from './0x03_SUB.js';

describe('SUB (0x03)', () => {
  it('subtracts two numbers', () => {
    const frame = createFrame([10n, 5n]);
    expect(sub(frame)).toBeNull();
    expect(frame.stack).toEqual([5n]);
  });

  it('handles underflow wrapping', () => {
    const frame = createFrame([0n, 1n]);
    expect(sub(frame)).toBeNull();
    const MAX = (1n << 256n) - 1n;
    expect(frame.stack).toEqual([MAX]);
  });

  it('handles large underflow', () => {
    const frame = createFrame([5n, 10n]);
    expect(sub(frame)).toBeNull();
    const MAX = (1n << 256n) - 1n;
    expect(frame.stack).toEqual([MAX - 4n]);
  });

  it('handles zero subtraction', () => {
    const frame = createFrame([42n, 0n]);
    expect(sub(frame)).toBeNull();
    expect(frame.stack).toEqual([42n]);
  });

  it('handles self-subtraction', () => {
    const frame = createFrame([42n, 42n]);
    expect(sub(frame)).toBeNull();
    expect(frame.stack).toEqual([0n]);
  });

  it('returns StackUnderflow with insufficient stack', () => {
    const frame = createFrame([5n]);
    expect(sub(frame)).toEqual({ type: 'StackUnderflow' });
  });

  it('consumes correct gas (3)', () => {
    const frame = createFrame([10n, 5n], 100n);
    expect(sub(frame)).toBeNull();
    expect(frame.gasRemaining).toBe(97n);
  });
});

// VULNERABLE: No underflow protection
function withdraw(uint256 amount) public {
    balances[msg.sender] -= amount;  // Can underflow!
    payable(msg.sender).transfer(amount);
}

// User with balance 5 withdraws 10
// balances[msg.sender] = 5 - 10 = wraps to MAX_UINT256
// Attacker now has infinite balance

// Beauty Chain (BEC) token vulnerability
function batchTransfer(address[] recipients, uint256 value) {
    uint256 amount = recipients.length * value;  // Can overflow!
    require(balances[msg.sender] >= amount);    // Check bypassed

    balances[msg.sender] -= amount;  // Underflow if amount wrapped
    for (uint i = 0; i < recipients.length; i++) {
        balances[recipients[i]] += value;
    }
}

// Attack: batchTransfer([addr1, addr2], 2^255)
// amount = 2 * 2^255 = wraps to 0
// Check passes, sender balance unchanged, recipients get tokens

// SafeMath library
function safeSub(uint256 a, uint256 b) internal pure returns (uint256) {
    require(b <= a, "subtraction underflow");
    return a - b;
}

function withdraw(uint256 amount) public {
    balances[msg.sender] = safeSub(balances[msg.sender], amount);
    payable(msg.sender).transfer(amount);
}

// Automatic underflow checks
function withdraw(uint256 amount) public {
    balances[msg.sender] -= amount;  // Reverts on underflow
    payable(msg.sender).transfer(amount);
}

// Explicit wrapping when needed
function decrementWrapping(uint256 counter) pure returns (uint256) {
    unchecked {
        return counter - 1;  // Uses raw SUB, wraps on underflow
    }
}

// Check difference without underflow risk
function isGreater(uint256 a, uint256 b) pure returns (bool) {
    // WRONG: Can underflow
    // return (a - b) > 0;

    // RIGHT: Direct comparison
    return a > b;
}

// Safe difference with minimum value
function safeDifference(uint256 a, uint256 b) pure returns (uint256) {
    return a > b ? a - b : 0;
}

// These have identical gas costs:
uint256 result1 = a - b;  // 3 gas
uint256 result2 = a + (~b + 1);  // More expensive (NOT + ADD + ADD)

// Prefer SUB for clarity and efficiency