OR (0x17) - Voltaire

This page is a placeholder. All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.

Overview

Opcode: 0x17 Introduced: Frontier (EVM genesis) OR performs bitwise OR on two 256-bit unsigned integers. Each bit in the result is 1 if either (or both) corresponding bits in the operands are 1. This operation is fundamental for combining flags, setting specific bits, and data packing. Primary uses: enabling multiple flags, setting bits in bitmaps, combining packed data fields.

Specification

Stack Input:

a (top)
b

Stack Output:

a | b

Gas Cost: 3 (GasFastestStep) Truth Table (per bit):

a | b | a | b
--|---|------
0 | 0 |   0
0 | 1 |   1
1 | 0 |   1
1 | 1 |   1

Behavior

OR pops two values from the stack, performs bitwise OR on each corresponding bit pair, and pushes the result. The operation is:

Commutative: a | b = b | a
Associative: (a | b) | c = a | (b | c)
Identity element: a | 0 = a
Null element: a | MAX_UINT256 = MAX_UINT256

Examples

Set Multiple Flags

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

// Enable flags at bits 0 and 2
const existing = 0b0000n;
const flags = 0b0101n;  // Bits 0 and 2
const frame = createFrame({ stack: [existing, flags] });
const err = or(frame);

console.log(frame.stack[0].toString(2));  // '101' (0b0101)

Combine Two Bitmaps

// Merge two permission sets
const userPerms = 0b00001111n;   // Permissions 0-3
const groupPerms = 0b11110000n;  // Permissions 4-7
const frame = createFrame({ stack: [userPerms, groupPerms] });
or(frame);

console.log(frame.stack[0].toString(2));  // '11111111'

Pack Data Fields

// Pack address (160 bits) + flags (96 bits) into uint256
const address = 0xdeadbeefcafe1234567890abcdef1234567890ABn;
const flags = 0x123456789ABCn << 160n;  // Shift flags to upper bits
const frame = createFrame({ stack: [address, flags] });
or(frame);

// Result: lower 160 bits = address, upper 96 bits = flags
console.log(frame.stack[0].toString(16));

Set Specific Bit

// Set bit 5 in existing value
const value = 0b00001000n;  // Bit 3 is set
const setBit5 = 0b00100000n;  // Bit 5 mask
const frame = createFrame({ stack: [value, setBit5] });
or(frame);

console.log(frame.stack[0].toString(2));  // '101000' (bits 3 and 5)

Commutative Property

// a | b = b | a
const a = 0b1100n;
const b = 0b1010n;

const frame1 = createFrame({ stack: [a, b] });
or(frame1);

const frame2 = createFrame({ stack: [b, a] });
or(frame2);

console.log(frame1.stack[0] === frame2.stack[0]);  // true (both 0b1110)

Gas Cost

Cost: 3 gas (GasFastestStep) OR shares the lowest gas tier with:

AND (0x16), XOR (0x18), NOT (0x19)
BYTE (0x1a)
SHL (0x1b), SHR (0x1c), SAR (0x1d)
ADD (0x01), SUB (0x03)
Comparison operations

Edge Cases

Identity Element

// OR with zero
const value = 0x123456n;
const frame = createFrame({ stack: [value, 0n] });
or(frame);

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

Null Element

// OR with all ones
const MAX = (1n << 256n) - 1n;
const value = 0x123456n;
const frame = createFrame({ stack: [value, MAX] });
or(frame);

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

Self OR

// a | a = a (idempotent)
const value = 0x123456n;
const frame = createFrame({ stack: [value, value] });
or(frame);

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

Alternating Bits

// Complementary patterns OR to all ones
const pattern1 = 0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAn;
const pattern2 = 0x5555555555555555555555555555555555555555555555555555555555555555n;
const frame = createFrame({ stack: [pattern1, pattern2] });
or(frame);

const MAX = (1n << 256n) - 1n;
console.log(frame.stack[0] === MAX);  // true (all bits set)

Stack Underflow

// Insufficient stack items
const frame = createFrame({ stack: [0x123n] });
const err = or(frame);

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

Out of Gas

// Insufficient gas
const frame = createFrame({ stack: [0x123n, 0x456n], gasRemaining: 2n });
const err = or(frame);

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

Common Usage

Enable Multiple Permissions

// Grant READ and WRITE permissions
uint256 constant READ = 1 << 0;
uint256 constant WRITE = 1 << 1;
uint256 constant EXECUTE = 1 << 2;

function grantPermissions(uint256 current) pure returns (uint256) {
    return current | READ | WRITE;  // Enable both flags
}

Set Bits in Bitmap

// Mark slots as occupied in storage bitmap
mapping(uint256 => uint256) public bitmap;

function markOccupied(uint256 index) internal {
    uint256 bucket = index / 256;
    uint256 bit = index % 256;
    bitmap[bucket] |= (1 << bit);  // Set bit
}

Pack Multiple Values

// Pack timestamp (40 bits) + amount (216 bits)
function pack(uint40 timestamp, uint216 amount) pure returns (uint256) {
    return (uint256(timestamp) << 216) | uint256(amount);
}

Combine Selectors

// Create function selector mask for multiple functions
bytes4 constant FUNC_A = 0x12345678;
bytes4 constant FUNC_B = 0x9ABCDEF0;

function getSelectorMask() pure returns (uint256) {
    return (uint256(uint32(FUNC_A)) << 224) |
           (uint256(uint32(FUNC_B)) << 192);
}

Set Color Channels

// Combine RGB channels into packed uint24 (0xRRGGBB)
function packRGB(uint8 r, uint8 g, uint8 b) pure returns (uint24) {
    return uint24(r) << 16 | uint24(g) << 8 | uint24(b);
}

Implementation

TypeScript

/**
 * OR opcode (0x17) - Bitwise OR operation
 */
export function op_or(frame: FrameType): EvmError | null {
  // Consume gas (GasFastestStep = 3)
  frame.gasRemaining -= 3n;
  if (frame.gasRemaining < 0n) {
    frame.gasRemaining = 0n;
    return { type: "OutOfGas" };
  }

  // Pop operands
  if (frame.stack.length < 2) return { type: "StackUnderflow" };
  const a = frame.stack.pop();
  const b = frame.stack.pop();

  // Compute bitwise OR
  const result = a | b;

  // Push result
  if (frame.stack.length >= 1024) return { type: "StackOverflow" };
  frame.stack.push(result);

  // Increment PC
  frame.pc += 1;

  return null;
}

Testing

Test Coverage

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

describe('OR (0x17)', () => {
  it('performs basic OR', () => {
    const frame = createFrame({ stack: [0b1100n, 0b1010n] });
    expect(op_or(frame)).toBeNull();
    expect(frame.stack[0]).toBe(0b1110n);
  });

  it('combines flags', () => {
    const flag1 = 0b0001n;
    const flag2 = 0b0100n;
    const frame = createFrame({ stack: [flag1, flag2] });
    expect(op_or(frame)).toBeNull();
    expect(frame.stack[0]).toBe(0b0101n);
  });

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

  it('handles null element (OR with MAX)', () => {
    const MAX = (1n << 256n) - 1n;
    const value = 0x123456n;
    const frame = createFrame({ stack: [value, MAX] });
    expect(op_or(frame)).toBeNull();
    expect(frame.stack[0]).toBe(MAX);
  });

  it('is idempotent (a | a = a)', () => {
    const value = 0x123456n;
    const frame = createFrame({ stack: [value, value] });
    expect(op_or(frame)).toBeNull();
    expect(frame.stack[0]).toBe(value);
  });

  it('is commutative', () => {
    const a = 0xAAAAn;
    const b = 0x5555n;
    const frame1 = createFrame({ stack: [a, b] });
    const frame2 = createFrame({ stack: [b, a] });
    op_or(frame1);
    op_or(frame2);
    expect(frame1.stack[0]).toBe(frame2.stack[0]);
  });

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

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

Edge Cases Tested

Basic OR operations (truth table)
Identity element (OR with 0)
Null element (OR with MAX_UINT256)
Flag combining
Idempotent property (a | a = a)
Commutative property
Complementary patterns (0xAAAA… | 0x5555… = MAX)
Stack underflow
Out of gas

Security

Flag Mismanagement

// WRONG: Using AND instead of OR to set flags
function addPermission(uint256 perms, uint256 flag) pure returns (uint256) {
    return perms & flag;  // Removes all other flags!
}

// CORRECT: Use OR to preserve existing flags
function addPermission(uint256 perms, uint256 flag) pure returns (uint256) {
    return perms | flag;
}

Overlapping Bit Positions

// DANGEROUS: Flag definitions overlap
uint256 constant FLAG_A = 1 << 0;  // Bit 0
uint256 constant FLAG_B = 1 << 0;  // Also bit 0! (collision)

// SAFE: Unique bit positions
uint256 constant FLAG_A = 1 << 0;  // Bit 0
uint256 constant FLAG_B = 1 << 1;  // Bit 1
uint256 constant FLAG_C = 1 << 2;  // Bit 2

Unintended Side Effects

// DANGEROUS: OR can never clear bits, only set them
function updateFlags(uint256 current, uint256 desired) pure returns (uint256) {
    return current | desired;  // Can't remove flags!
}

// BETTER: Explicit set/clear interface
function setFlags(uint256 current, uint256 flags) pure returns (uint256) {
    return current | flags;
}

function clearFlags(uint256 current, uint256 flags) pure returns (uint256) {
    return current & ~flags;
}

Packed Data Corruption

// VULNERABLE: OR can corrupt existing packed fields
struct Packed {
    uint160 addr;   // Bits 0-159
    uint96 value;   // Bits 160-255
}

// Wrong: OR overwrites existing address
function updateValue(uint256 packed, uint96 newValue) pure returns (uint256) {
    return packed | (uint256(newValue) << 160);  // Address corrupted if newValue has lower bits!
}

// Correct: Clear field first, then OR
function updateValue(uint256 packed, uint96 newValue) pure returns (uint256) {
    uint256 addrMask = (1 << 160) - 1;
    uint256 addr = packed & addrMask;  // Extract address
    return addr | (uint256(newValue) << 160);  // Recombine
}

Benchmarks

OR is one of the fastest EVM operations: Execution time (relative):

OR: 1.0x (baseline, fastest tier)
AND/XOR: 1.0x (same tier)
ADD: 1.0x (same tier)
MUL: 1.2x
DIV: 2.5x

Gas efficiency:

3 gas per 256-bit OR operation
~333,333 OR operations per million gas
Native hardware instruction on all platforms

References

Yellow Paper - Section 9.1 (Bitwise Logic Operations)
EVM Codes - OR
Solidity Docs - Bitwise Operators

AND (0x16) - Bitwise AND operation
XOR (0x18) - Bitwise XOR operation
NOT (0x19) - Bitwise NOT operation
BYTE (0x1a) - Extract byte operation

​Overview

​Specification

​Behavior

​Examples

​Set Multiple Flags

​Combine Two Bitmaps

​Pack Data Fields

​Set Specific Bit

​Commutative Property

​Gas Cost

​Edge Cases

​Identity Element

​Null Element

​Self OR

​Alternating Bits

​Stack Underflow

​Out of Gas

​Common Usage

​Enable Multiple Permissions

​Set Bits in Bitmap

​Pack Multiple Values

​Combine Selectors

​Set Color Channels

​Implementation

​Testing

​Test Coverage

​Edge Cases Tested

​Security

​Flag Mismanagement

​Overlapping Bit Positions

​Unintended Side Effects

​Packed Data Corruption

​Benchmarks

​References

​Related Documentation

Overview

Specification

Behavior

Examples

Set Multiple Flags

Combine Two Bitmaps

Pack Data Fields

Set Specific Bit

Commutative Property

Gas Cost

Edge Cases

Identity Element

Null Element

Self OR

Alternating Bits

Stack Underflow

Out of Gas

Common Usage

Enable Multiple Permissions

Set Bits in Bitmap

Pack Multiple Values

Combine Selectors

Set Color Channels

Implementation

Testing

Test Coverage

Edge Cases Tested

Security

Flag Mismanagement

Overlapping Bit Positions

Unintended Side Effects

Packed Data Corruption

Benchmarks

References

Related Documentation