SHL (0x1b)

shift (top) - number of bit positions to shift
value - 256-bit value to shift

value << shift (mod 2^256)

shift < 256: value << shift (wraps at 256 bits)
shift >= 256: 0 (all bits shifted out)

import { shl } from '@tevm/voltaire/evm/bitwise';
import { createFrame } from '@tevm/voltaire/evm/Frame';

// Shift 0xFF left by 8 bits (multiply by 256)
const frame = createFrame({ stack: [8n, 0xFFn] });
const err = shl(frame);

console.log(frame.stack[0].toString(16));  // 'ff00'

// Shift left by N = multiply by 2^N
// 5 << 3 = 5 * 8 = 40
const frame = createFrame({ stack: [3n, 5n] });
shl(frame);

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

// Shift by 0 positions = identity
const value = 0x123456n;
const frame = createFrame({ stack: [0n, value] });
shl(frame);

console.log(frame.stack[0] === value);  // true

// Shift >= 256 results in 0
const value = 0xFFFFFFFFn;
const frame = createFrame({ stack: [256n, value] });
shl(frame);

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

// High bits are discarded
const value = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFn;
const frame = createFrame({ stack: [4n, value] });
shl(frame);

// Result: lower 252 bits are all 1s, upper 4 bits are 0
const expected = ((1n << 256n) - 1n) - ((1n << 4n) - 1n);
console.log(frame.stack[0] === expected);  // true

// Shift address to upper bits (leave lower bits for flags)
const address = 0xdEaDbEeFcAfE1234567890ABCDEf1234567890ABn;
const frame = createFrame({ stack: [96n, address] });  // Shift left 96 bits
shl(frame);

// Address now in upper 160 bits, lower 96 bits available for data
console.log(frame.stack[0].toString(16));

// Before Constantinople: expensive!
result = value * (2 ** shift)  // MUL (5 gas) + EXP (10 + 50/byte gas)
// Total: 15-1615 gas

// After Constantinople: cheap!
assembly { result := shl(shift, value) }  // 3 gas

// Shifting zero always yields zero
const frame = createFrame({ stack: [100n, 0n] });
shl(frame);

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

// No shift = identity
const value = 0xDEADBEEFn;
const frame = createFrame({ stack: [0n, value] });
shl(frame);

console.log(frame.stack[0] === value);  // true

// Shift left by 1 = multiply by 2
const value = 42n;
const frame = createFrame({ stack: [1n, value] });
shl(frame);

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

// Shift to MSB position
const value = 1n;
const frame = createFrame({ stack: [255n, value] });
shl(frame);

const expected = 1n << 255n;  // 0x8000...0000
console.log(frame.stack[0] === expected);  // true

// Any shift >= 256 yields 0
for (const shift of [256n, 257n, 1000n, (1n << 200n)]) {
  const frame = createFrame({ stack: [shift, 0xFFFFn] });
  shl(frame);
  console.log(frame.stack[0]);  // 0n for all
}

// Shifting MAX - some bits overflow
const MAX = (1n << 256n) - 1n;
const frame = createFrame({ stack: [1n, MAX] });
shl(frame);

// Result: all bits set except LSB
const expected = MAX - 1n;
console.log(frame.stack[0] === expected);  // true

// SHL is invalid before Constantinople
const frame = createFrame({
  stack: [8n, 0xFFn],
  hardfork: 'byzantium'  // Before Constantinople
});
const err = shl(frame);

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

// Insufficient stack items
const frame = createFrame({ stack: [8n] });
const err = shl(frame);

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

// Insufficient gas
const frame = createFrame({ stack: [8n, 0xFFn], gasRemaining: 2n });
const err = shl(frame);

console.log(err);  // { type: "OutOfGas" }
console.log(frame.gasRemaining);  // 0n

// Efficient multiplication by 256
assembly {
    result := shl(8, value)  // 3 gas vs MUL (5 gas)
}

// Pack timestamp (40 bits) + amount (216 bits)
function pack(uint40 timestamp, uint216 amount) pure returns (uint256) {
    return (uint256(timestamp) << 216) | uint256(amount);
    // Or in assembly:
    // assembly {
    //     result := or(shl(216, timestamp), amount)
    // }
}

// Shift to align data to byte boundary
function alignToBytes(uint256 value, uint256 bytePos) pure returns (uint256) {
    assembly {
        result := shl(mul(8, bytePos), value)
    }
}

// Create mask with N consecutive ones at position P
function createMask(uint256 numBits, uint256 position) pure returns (uint256) {
    require(numBits + position <= 256, "overflow");
    uint256 mask = (1 << numBits) - 1;
    return mask << position;
    // assembly { result := shl(position, sub(shl(numBits, 1), 1)) }
}

// Fixed-point arithmetic: shift to scale by 10^18
uint256 constant SCALE = 1e18;

function toFixedPoint(uint256 value) pure returns (uint256) {
    // In practice, use MUL for non-power-of-2 scaling
    // But for powers of 2 (e.g., binary fixed-point):
    return value << 64;  // Q64.64 fixed-point
}

// Calculate array slot offset (element size * index)
// For 32-byte elements: index << 5 (multiply by 32)
function getArraySlot(uint256 baseSlot, uint256 index) pure returns (uint256) {
    assembly {
        let offset := shl(5, index)  // index * 32
        mstore(0, add(baseSlot, offset))
        return(0, 32)
    }
}

import { describe, it, expect } from 'vitest';
import { shl } from './shl.js';

describe('SHL (0x1b)', () => {
  it('shifts left by 8 bits', () => {
    const frame = createFrame({ stack: [8n, 0xFFn] });
    expect(shl(frame)).toBeNull();
    expect(frame.stack[0]).toBe(0xFF00n);
  });

  it('multiplies by power of 2', () => {
    const frame = createFrame({ stack: [3n, 5n] });
    expect(shl(frame)).toBeNull();
    expect(frame.stack[0]).toBe(40n);  // 5 * 2^3
  });

  it('handles zero shift (identity)', () => {
    const value = 0x123456n;
    const frame = createFrame({ stack: [0n, value] });
    expect(shl(frame)).toBeNull();
    expect(frame.stack[0]).toBe(value);
  });

  it('returns 0 for shift >= 256', () => {
    const frame = createFrame({ stack: [256n, 0xFFFFFFFFn] });
    expect(shl(frame)).toBeNull();
    expect(frame.stack[0]).toBe(0n);
  });

  it('handles partial overflow', () => {
    const value = 0xFFn;
    const frame = createFrame({ stack: [252n, value] });
    expect(shl(frame)).toBeNull();

    // 0xFF << 252 = 0xFF00...0000 (252 zeros)
    const expected = 0xFFn << 252n;
    expect(frame.stack[0]).toBe(expected);
  });

  it('shifts MAX value by 1', () => {
    const MAX = (1n << 256n) - 1n;
    const frame = createFrame({ stack: [1n, MAX] });
    expect(shl(frame)).toBeNull();

    // All bits except LSB
    expect(frame.stack[0]).toBe(MAX - 1n);
  });

  it('shifts 1 to MSB position', () => {
    const frame = createFrame({ stack: [255n, 1n] });
    expect(shl(frame)).toBeNull();
    expect(frame.stack[0]).toBe(1n << 255n);
  });

  it('returns InvalidOpcode before Constantinople', () => {
    const frame = createFrame({
      stack: [8n, 0xFFn],
      hardfork: 'byzantium'
    });
    expect(shl(frame)).toEqual({ type: 'InvalidOpcode' });
  });

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

  it('returns OutOfGas when insufficient gas', () => {
    const frame = createFrame({ stack: [8n, 0xFFn], gasRemaining: 2n });
    expect(shl(frame)).toEqual({ type: 'OutOfGas' });
  });
});

// RISKY: User-controlled shift without bounds
function shiftLeft(uint256 value, uint256 shift) pure returns (uint256) {
    return value << shift;  // shift >= 256 → 0 (may not be intended)
}

// SAFER: Validate shift range
function shiftLeft(uint256 value, uint256 shift) pure returns (uint256) {
    require(shift < 256, "shift overflow");
    return value << shift;
}

// WRONG: Assuming shifted value is always larger
function packData(uint96 flags, uint160 addr) pure returns (uint256) {
    uint256 packed = (uint256(flags) << 160) | uint256(addr);
    require(packed > addr, "packing failed");  // FALSE if flags = 0!
    return packed;
}

// CORRECT: Proper validation
function packData(uint96 flags, uint160 addr) pure returns (uint256) {
    return (uint256(flags) << 160) | uint256(addr);
    // No assumption about relative magnitude
}

// DANGEROUS: High bits silently discarded
function encode(uint128 high, uint128 low) pure returns (uint256) {
    // If high > type(uint128).max, upper bits are lost!
    return (uint256(high) << 128) | uint256(low);
}

// SAFER: Validate inputs
function encode(uint128 high, uint128 low) pure returns (uint256) {
    // Type system enforces high <= type(uint128).max
    return (uint256(high) << 128) | uint256(low);
}

// Use SHL only for powers of 2
function multiply(uint256 a, uint256 b) pure returns (uint256) {
    // WRONG: Only works if b is a power of 2
    return a << b;  // Treats b as exponent, not multiplicand!
}

// CORRECT: Use MUL for general multiplication
function multiply(uint256 a, uint256 b) pure returns (uint256) {
    return a * b;
}