Module shuffler 

Stack shuffler for optimal stack layout transitions.

This module implements a greedy shuffler algorithm similar to solc’s approach. The shuffler converts a source stack layout to a target layout using minimal DUP, SWAP, and POP operations.

Algorithm Overview

The shuffler uses a greedy approach with multiplicity tracking:

1. Count how many copies of each value are needed in the target
2. DUP values that need multiple copies
3. SWAP values to correct positions
4. POP excess values

Key insight: Values that can be “freely generated” (literals, function labels) don’t need to be in the source stack - they can be pushed when needed.

Structs

BlockStackLayout

Represents a stack layout for a block - the values that should be on the stack when entering or exiting a block, from top to bottom.

LayoutAnalysis

Computes the ideal entry layout for an instruction given the desired exit layout.

ShuffleResult

Result of a shuffle operation.

StackShuffler

The stack shuffler transforms a source stack layout to a target layout.

Enums

FreelyGenerable

Represents a “freely generable” value that can be pushed without being on the stack. These values don’t need to be in the source layout when shuffling.

TargetSlot

Represents a slot in the target layout.

Functions

combine_stack_layouts

Computes a common stack layout for multiple incoming edges at a merge point.

estimate_shuffle_cost

Computes the shuffle cost from a source layout to a target layout. This estimates the number of DUP/SWAP/POP operations needed.

ideal_binary_op_entry

Computes the ideal pre-layout for a binary operation.

ideal_operand_layout

Creates an ideal layout for preparing multiple operands.

ideal_unary_op_entry

Computes the ideal pre-layout for a unary operation.

is_freely_generable

Checks if a value can be freely generated (doesn’t need to be on stack).