papers/lux-evm-precompile-engineering/sections/05-determinism-requirements.tex

\section{Determinism Requirements}


\subsection{Why Determinism Is Non-Negotiable}

Every validator must compute identical state transitions. If a precompile produces
different outputs on different hardware, validators disagree on the state root, causing
a consensus split.

\subsection{Sources of Non-Determinism}

\begin{enumerate}[nosep]
  \item \textbf{Floating-point arithmetic}: Never use floating point in precompiles.
    All arithmetic is integer or modular.
  \item \textbf{Map iteration order}: Go map iteration is randomized. Never iterate over
    maps in precompile code.
  \item \textbf{Goroutines}: Concurrent execution with shared state is non-deterministic.
    Precompiles must be single-threaded.
  \item \textbf{System calls}: Time, random number generation, file I/O. Never use these.
  \item \textbf{Compiler optimizations}: Different Go compiler versions may produce
    different results for certain edge cases. Pin the Go version and test across platforms.
\end{enumerate}

\subsection{Determinism Testing}

We run every precompile test on three platforms (AMD64, ARM64, WASM) and verify identical
outputs. Any divergence is a critical bug.

\begin{lstlisting}[language=Go,caption={Determinism test}]
func TestDeterminism(t *testing.T) {
    // Golden outputs computed on reference platform
    for _, tc := range goldenTestCases {
        output, err := precompile.Run(tc.Input)
        if err != nil {
            t.Fatalf("unexpected error: %v", err)
        }
        if !bytes.Equal(output, tc.ExpectedOutput) {
            t.Fatalf("determinism violation:\n"+
                "input:    %x\n"+
                "got:      %x\n"+
                "expected: %x",
                tc.Input, output, tc.ExpectedOutput)
        }
    }
}
\end{lstlisting}

%% ============================================================