DUP9 (0x88)

[..., value, item8, ..., item1]

[..., value, item8, ..., item1, value]

value = stack[depth - 9]
stack.push(value)

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

// Duplicate 9th item
const frame = createFrame({
  stack: [900n, 800n, 700n, 600n, 500n, 400n, 300n, 200n, 100n],
  gasRemaining: 1000n
});

const err = handler_0x88_DUP9(frame);

console.log(frame.stack); // [900n, 800n, 700n, 600n, 500n, 400n, 300n, 200n, 100n, 100n] - 9th item duplicated
console.log(frame.gasRemaining); // 997n (3 gas consumed)

contract Example {
    function deepAccess() public pure {
        // Access deep stack value
        assembly {
            // Stack has 9 items
            dup9  // Duplicate 9th item to top
        }
    }
}

assembly {
    push1 0x01
    push1 0x02
    push1 0x03
    push1 0x04
    push1 0x05
    push1 0x06
    push1 0x07
    push1 0x08
    push1 0x09
    // Stack: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09]

    dup9
    // Stack: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x01] - first item duplicated
}

function complex() public pure {
    assembly {
        // Build deep stack
        let v1 := 1
        let v2 := 2
        let v3 := 3
        let v4 := 4
        let v5 := 5
        let v6 := 6
        let v7 := 7
        let v8 := 8
        let v9 := 9

        // Access v1 from depth 9
        dup9
    }
}```

### Efficient Copies

```solidity
// Instead of multiple loads
assembly {
    let value := sload(slot)  // Expensive
    // Use value
    let value2 := sload(slot) // Wasteful!
}

// Use DUP to reuse
assembly {
    let value := sload(slot)  // Load once
    dup1                       // Copy
    // Use both copies
}

assembly {
    let condition := calldataload(0)
    dup1  // Keep condition for later
    iszero
    jumpi(skip)
    // Use condition again
    skip:
}

// DUP9 requires 9 items on stack
assembly {
    push1 0x01
    push1 0x02
    push1 0x03
    push1 0x04
    push1 0x05
    push1 0x06
    push1 0x07
    push1 0x08
    // Only 8 items - DUP9 will fail!
    dup9  // StackUnderflow
}

assembly {
    push1 0x01
    push1 0x02
    push1 0x03
    push1 0x04
    push1 0x05
    push1 0x06
    push1 0x07
    push1 0x08
    push1 0x09
    // Exactly 9 items - safe
    dup9  // Success
}

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

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

// Stack at maximum, can't add more
const frame = createFrame({
  stack: new Array(1024).fill(0n)
});

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

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

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

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

handler_0x88_DUP9(frame);
console.log(frame.stack[frame.stack.length - 1]); // MAX (duplicated)