From 2ff834911b0e07abbff978e30bf2a23512dafb09 Mon Sep 17 00:00:00 2001
From: Dario Gabriel Lipicar <dario@status.im>
Date: Wed, 26 Aug 2026 23:26:43 -0300
Subject: [PATCH] docs: Windows is blocked on Nim 2.2.4, not on the cross
 toolchain
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cross build gets much further than "unproven" suggested. The mingw stdenv,
the `ar` shim that --app:staticlib needs, the vendored nat-libs that branch on
$(OS) and silently take the POSIX path under cross, and Nim compiling most of
the tree all work. It dies in one place:

  state_transition_block.nim(1018,32) Error: invalid type:
  'typeof(SomeBeaconBlockBody)' in this context

USE_SYSTEM_NIM=1 substitutes the nixpkgs Nim for the one nimbus-build-system
pins, and logos-nix's nixpkgs-windows carries 2.2.4 for every spelling while
nimbus-eth2's sources need 2.2.10 — the version the native build gets, and
compiles cleanly with.

Records the three non-fixes as well, since each looks plausible: a Nim from
another nixpkgs loses the cross wrapper that carries the toolchain config;
dropping USE_SYSTEM_NIM makes nimbus fetch Nim over the network, which the
sandbox forbids and which is why upstream sets the flag; and overriding
nim-unwrapped-2_2 from here cannot work because wrapNim is not exposed.

The fix belongs in logos-nix. Doing it here by importing a second nixpkgs would
put two builds of libstdc++-6.dll in one directory, which resolves by filename.

No Windows CI caller yet, deliberately: adding one now would only add a red
gate that says what this README already says.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/README.md b/README.md
index c3f7592..08a78aa 100644
--- a/README.md
+++ b/README.md
@@ -265,6 +265,46 @@ which is why it is a separate workflow from CI.
 nix run github:logos-co/logos-doctest -- run doctests/verified-proxy-runtime.test.yaml --verbose
 ```
 
+## Windows: blocked on the Nim version, not on the cross toolchain
+
+`nix build .#packages.x86_64-windows.libverifproxy` gets a long way and then
+fails in the same place every time:
+
+```
+vendor/nimbus-eth2/beacon_chain/spec/state_transition_block.nim(1018, 32)
+Error: invalid type: 'typeof(SomeBeaconBlockBody)' in this context
+[using system Nim: …/x86_64-w64-mingw32-nim-wrapped-2.2.4]
+```
+
+Everything that was expected to be hard already works: the mingw cross stdenv,
+the `ar` shim that `--app:staticlib` needs, the vendored nat-libs (which branch
+on `$(OS)` and silently take the POSIX path under cross), and Nim itself
+compiling most of the tree.
+
+The blocker is a **compiler version**. `USE_SYSTEM_NIM=1` substitutes the
+nixpkgs Nim for the one nimbus-build-system pins, and the `nixpkgs-windows` pin
+inside `logos-nix` carries **2.2.4** for every spelling — `nim`, `nim-2_2` and
+`nim-unwrapped-2_2` alike — while nimbus-eth2's beacon-chain sources need
+**2.2.10**, which is what the native build gets and compiles cleanly with.
+
+Three things that do NOT fix it, checked so the next person does not repeat them:
+
+- Passing a Nim from another nixpkgs. The build-side compiler in a cross set is
+  a *wrapper* (`x86_64-w64-mingw32-nim-wrapper`) that carries the mingw
+  toolchain configuration; a plain `nixpkgs#nim` is a native compiler that knows
+  nothing about the target.
+- Dropping `USE_SYSTEM_NIM=1` so nimbus-build-system builds its own pinned
+  2.2.10. It fetches Nim over the network, which the Nix sandbox forbids —
+  which is exactly why upstream's own nix build sets the flag.
+- Overriding `nim-unwrapped-2_2` from this flake. `wrapNim` is not exposed, so
+  the wrapper cannot be rebuilt from an overridden compiler without an overlay
+  applied where the package set is constructed.
+
+The fix belongs in `logos-nix`: bump `nixpkgs-windows` far enough to carry Nim
+2.2.10, or apply an overlay inside `mkWindowsPkgs`. Doing it here by importing a
+second nixpkgs would put two builds of `libstdc++-6.dll` in one directory, which
+resolves by filename and would be a worse problem than the one it solves.
+
 ## Development
 
 ```bash