> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# PUSH32 (0x7F)

> Push 32-byte immediate value onto stack

<Warning>
  **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.
</Warning>

## Overview

**Opcode:** `0x7F`
**Introduced:** Frontier (EVM genesis)

PUSH32 pushes a 32-byte immediate value from the bytecode onto the stack. The 32 bytes immediately following the opcode are read and zero-padded to 256 bits.

## Specification

**Stack Input:**

```
[]
```

**Stack Output:**

```
value (uint256, 32 bytes from bytecode)
```

**Gas Cost:** 3 (GasFastestStep)

**Bytecode:** 1 byte opcode + 32 bytes immediate data

**Operation:**

```
value = read_bytes(pc + 1, 32)  // Big-endian
stack.push(value)
pc += 33
```

## Behavior

PUSH32 reads 32 bytes from bytecode starting at position `pc + 1`, interprets them as a big-endian unsigned integer, and pushes the result onto the stack.

Key characteristics:

* Reads exactly 32 bytes following opcode
* Big-endian byte order (most significant byte first)
* Zero-padded to 256 bits if less than 32 bytes
* InvalidOpcode if insufficient bytecode remaining
* PC advances by 33 (opcode + data)

## Examples

### Basic Usage

```typescript theme={null}
import { handler_0x7F_PUSH32 } from '@tevm/voltaire/evm/stack/handlers';
import { createFrame } from '@tevm/voltaire/evm/Frame';

// Bytecode with PUSH32
const bytecode = new Uint8Array([
  0x7F,  // PUSH32
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20   // 32 bytes: 0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
]);

const frame = createFrame({
  bytecode,
  pc: 0,
  stack: [],
  gasRemaining: 1000n
});

const err = handler_0x7F_PUSH32(frame);

console.log(frame.stack); // [0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20n]
console.log(frame.pc); // 33
console.log(frame.gasRemaining); // 997n (3 gas consumed)
```

### Solidity Compilation

```solidity theme={null}
contract Example {
    // Large constants use PUSH32
    uint256 constant MAX = type(uint256).max;
    // PUSH32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
}
```

### Assembly Usage

```solidity theme={null}
assembly {
    // Push 32-byte value
    push32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
    
}
```

## Gas Cost

**Cost:** 3 gas (GasFastestStep)

All PUSH1-32 instructions cost the same despite different data sizes. Bytecode size impact:

* PUSH32: 33 bytes (1 opcode + 32 data)

**Comparison:**

| Opcode | Gas | Bytes | Use Case                  |
| ------ | --- | ----- | ------------------------- |
| PUSH0  | 2   | 1     | Zero constant (Shanghai+) |
| PUSH1  | 3   | 2     | Small numbers (0-255)     |

\| PUSH32 | 3 | 33 | Large constants |

## Common Usage

### Maximum Values

```solidity theme={null}
contract Constants {
    uint256 constant MAX_UINT256 = type(uint256).max;

    // Compiled to:
    // PUSH32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
}
```

### Big-Endian Encoding

```typescript theme={null}
// Bytecode: PUSH32 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20
// Reads as: 0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20

// Most significant byte first
// Byte 0: 0x01 (highest significance)
// Byte 31: 0x20 (lowest significance)
```

## Implementation

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    /**
     * Read immediate data from bytecode for PUSH operations
     */
    function readImmediate(bytecode: Uint8Array, pc: number, size: number): bigint | null {
      if (pc + 1 + size > bytecode.length) {
        return null;
      }

      let result = 0n;
      for (let i = 0; i < size; i++) {
        result = (result << 8n) | BigInt(bytecode[pc + 1 + i]);
      }
      return result;
    }

    /**
     * PUSH32 opcode (0x7F) - Push 32 bytes onto stack
     *
     * Stack: [] => [value]
     * Gas: 3 (GasFastestStep)
     */
    export function handler_0x7F_PUSH32(frame: FrameType): EvmError | null {
      const gasErr = consumeGas(frame, FastestStep);
      if (gasErr) return gasErr;

      const value = readImmediate(frame.bytecode, frame.pc, 32);
      if (value === null) {
        return { type: "InvalidOpcode" };
      }

      const pushErr = pushStack(frame, value);
      if (pushErr) return pushErr;

      frame.pc += 33;
      return null;
    }
    ```
  </Tab>
</Tabs>

## Edge Cases

### Insufficient Bytecode

```typescript theme={null}
// Bytecode ends before 32 bytes read
const bytecode = new Uint8Array([0x7F, 0x01]); // Only 1 byte instead of 32
const frame = createFrame({ bytecode, pc: 0 });

const err = handler_0x7F_PUSH32(frame);
console.log(err); // { type: "InvalidOpcode" }
```

### Stack Overflow

```typescript theme={null}
// Stack at maximum capacity
const frame = createFrame({
  stack: new Array(1024).fill(0n),
  bytecode: new Uint8Array([0x7F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
});

const err = handler_0x7F_PUSH32(frame);
console.log(err); // { type: "StackOverflow" }
```

### Out of Gas

```typescript theme={null}
// Insufficient gas
const frame = createFrame({
  gasRemaining: 2n,  // Need 3 gas
  bytecode: new Uint8Array([0x7F, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
});

const err = handler_0x7F_PUSH32(frame);
console.log(err); // { type: "OutOfGas" }
```

### Maximum Value

```typescript theme={null}
// All bytes 0xFF
const bytecode = new Uint8Array([0x7F, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
const frame = createFrame({ bytecode, pc: 0 });

handler_0x7F_PUSH32(frame);
console.log(frame.stack[0]); // 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn
```

## References

* [Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf) - Section 9.4.1 (PUSH)
* [EVM Codes - PUSH32](https://www.evm.codes/#7f?fork=cancun)
* [Solidity Assembly - push32](https://docs.soliditylang.org/en/latest/yul.html#evm-opcodes)