SWAP2 (0x91)

[..., valueN, item1, ..., item1, top]

[..., top, item1, ..., item1, valueN]

temp = stack[top]
stack[top] = stack[top - 3]
stack[top - 3] = temp

import { handler_0x91_SWAP2 } from '@tevm/voltaire/evm/stack/handlers';
import { createFrame } from '@tevm/voltaire/evm/Frame';

// Swap top with 3rd item
const frame = createFrame({
  stack: [300n, 200n, 100n],
  gasRemaining: 1000n
});

const err = handler_0x91_SWAP2(frame);

console.log(frame.stack); // [100n, 200n, 300n] - positions 0 and 2 swapped
console.log(frame.gasRemaining); // 997n (3 gas consumed)

contract Example {
    function reorder() public pure {
        assembly {
            push1 0x01
            push1 0x02
            push1 0x03
            // Stack: [1, 2, 3]
            swap2
            // Stack: [3, 2, 1]
        }
    }
}

assembly {
    push1 0xa
    push1 0xb
    push1 0xc
    // Stack: ['a', 'b', 'c']

    swap2
    // Stack: ['c', 'b', 'a'] - 'a' and 'c' swapped
}

assembly {
    let a := 1
    let b := 2
    let c := 3
    // Stack: [a, b, c]
    swap2
    // Stack: [c, b, a]
}```

### Efficient Reordering

```solidity
// Reorder for function call
assembly {
    // Have: [value, to, token]
    // Need: [token, to, value]
    swap2  // [token, to, value]

    // Call transfer(token, to, value)
    call(gas(), target, 0, 0, 100, 0, 0)
}

assembly {
    let slot := 0
    let value := 42
    // Stack: [slot, value]

    // SSTORE needs (slot, value) but we have them reversed
    // No swap needed in this case, but if we did:
    swap1
    // Stack: [value, slot]
    sstore
}

// SWAP2 requires 3 items
assembly {
    push1 0x01
    push1 0x02
    // Only 2 items - SWAP2 will fail!
    swap2  // StackUnderflow
}

assembly {
    push1 0x01
    push1 0x02
    push1 0x03
    // Exactly 3 items - safe
    swap2  // Success
}

// Insufficient stack depth
const frame = createFrame({
  stack: [100n, 100n]  // Only 2 items, need 3
});

const err = handler_0x91_SWAP2(frame);
console.log(err); // { type: "StackUnderflow" }

// Insufficient gas
const frame = createFrame({
  stack: [100n, 100n, 100n],
  gasRemaining: 2n  // Need 3
});

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

// Swap same values
const frame = createFrame({
  stack: new Array(3).fill(42n)
});

handler_0x91_SWAP2(frame);
console.log(frame.stack); // All still 42n

// Swap with max uint256
const MAX = (1n << 256n) - 1n;
const frame = createFrame({
  stack: [0n, 0n, MAX, 1n]
});

handler_0x91_SWAP2(frame);
console.log(frame.stack[0]); // 1n (was at top)
console.log(frame.stack[2]); // MAX (was at bottom)