Skip to content

Windows and macOS nodes load Linux checkpoints and sync mainnet with the same digests - #115

Merged
EnzinoBB merged 12 commits into
masterfrom
fix/platform-checkpoints
Oct 27, 2026
Merged

EnzinoBB merged 12 commits into
masterfrom
fix/platform-checkpoints

Conversation

@EnzinoBB

Copy link
Copy Markdown
Collaborator

Summary

A node on Windows or macOS now loads the quick-start checkpoint and the published snapshot that a Linux node wrote, and syncs mainnet with the same state digests as Linux. Found by running the packages of #114 on mainnet.

Checkpoint files (the part that touches the node's state loading)

  • Header of the binary archives. A Boost binary archive records sizeof(long) (8 on Linux and macOS, 4 on Windows) and refuses another size. No checkpoint field is a long (64-bit fields are int64_t/uint64_t), so only that header byte differs.
    • cs::ArchiveOutput writes 8 on every system: checkpoints and the snapshots made of them have the same bytes everywhere, and old Linux nodes read them.
    • cs::ArchiveInput rewrites 8 to 4 on Windows only. On Linux and macOS the input is passed through untouched (the plain read), so Boost keeps its own check there.
    • Used by the five binary serializers (api handler, blockchain incl. the pending file, smart contracts, round stat, wallet ids).
  • Text mode. Wallets cache and tokens are text archives, and every file that is hashed is now opened in binary mode: on Windows text mode wrote \r\n, so the hashes of the loaded state differed from the ones Linux wrote ("invalid hashes on load"). The two text archives hashed with no_codecvt also use the classic locale explicitly.
  • On Linux the bytes read, written and hashed are identical to before. Reviewed twice (Fable; Opus with experiments: byte comparison of written files, 11,000 partial-write cases, 6,000 header mutations, ASan/UBSan, timing).

macOS

  • Boost for macOS is built as C++17 (cxxstd=17). Apple clang compiles C++ as C++98 by default, so Boost.Log's Asio code had a run-time initialised static where the node's has a constant in __DATA_CONST; the linker kept one with the other and the node died with SIGBUS at its first UDP socket. Linux and Windows are not affected.

CI

  • platform-sync.yml: the Linux, Windows and macOS packages of one Release run each restore the published snapshot, sync mainnet to the head and log state digests; a job compares them block by block. It fails at once when a node ends, has no API after 4 minutes or syncs below 3000 blocks/min (Linux does 30000+); the snapshot import is kept out of the job log; the wait-head output, the exit status and macOS crash reports are saved.

Test plan

  • Build and tests: Linux, Windows (MSVC), macOS (Apple Silicon)
  • Mainnet from the published snapshot, Linux, Windows and macOS: 91 blocks with a digest from all three systems, 0 mismatches (186,600,000 to 186,690,000)
  • Robustness suite on Linux (all 69 scenarios) before the last hardening commit
  • This PR's CI

🤖 Generated with Claude Code

EnzinoBB and others added 12 commits October 27, 2026 03:58
…f a node that did not reach the head

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A boost binary archive header records sizeof(long), 8 on Linux and macOS and 4 on Windows, and
binary_iarchive refuses another size: a Windows node could not load the published snapshot's
checkpoint. No checkpoint field is a long (64-bit fields are int64_t/uint64_t, 8 bytes on every
system), so only that header byte differs:
- cs::ArchiveInput reads it as this system's value (4 or 8 only; anything else as before)
- cs::ArchiveOutput writes 8 on every system, so a checkpoint and a snapshot made of it have the
  same bytes everywhere and nodes without this change read them
The hashes of the caches are computed without a header and do not change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…as on Linux)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ash reports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…or syncs too slowly

Linux reaches the head in about 5 minutes at 30000+ blocks/min. wait-head now fails when the node
process ends (exit file), its API is not up after 4 minutes, or the speed over 2 minutes is below
3000 blocks/min while far from the head, and the workflow prints the end of the node's output.
The timeouts drop from 150/300 minutes to 30/90.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…orm check exit file

walletscache and tokens are text archives: in text mode Windows writes \r\n, so the hashes of the
loaded state differed from the ones written by Linux and the checkpoint was refused ("invalid
hashes on load"). All of them are binary now (the same bytes on Linux).
The platform check records the node's exit status (the subshell no longer ends at the failing
node under -e) and does not use pgrep on Windows.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Apple clang compiles C++ as C++98 unless told otherwise, so the Boost built by b2 held definitions
of header templates that differ from the node's C++17 ones: the Asio code in Boost.Log's syslog
backend has a run-time initialised static (boost::source_location in reactive_socket_service<udp>
::open) where the node's has a constant one in __DATA_CONST, and the linker kept the code of one
with the constant of the other. The node died with SIGBUS at the first UDP socket it opened.
A macOS build with cxxstd=17 starts and passes that point (debug run 40462211836).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nd saves the wait-head output

The import prints hundreds of thousands of debug lines to the console and the job log was cut
before the sync step. The wait-head lines and the download log go to the artifact instead.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…lassic locale for the hashed text; header test

From the impact review of the branch:
- ArchiveInput only changes the header where long is 4 bytes (Windows) and the archive says 8; on
  Linux and macOS the bytes are passed through, so boost keeps refusing a 32-bit archive and the
  read is exactly the plain one
- the two text archives whose hash is computed with no_codecvt (tokens, wallets cache) are written
  through a stream imbued with the classic locale, so a global locale could never change them
- tests: the 40-byte header the node writes is compared with the Boost 1.83 one, byte by byte; the
  input is checked to behave as the plain reader where long is 8 bytes

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…struction

p2p's Network singleton keeps a shared_ptr to the host's routing table
(Host::Run). It kept the routing table alive after net::Host and its
io_context were destroyed; ~Network at static destruction then destroyed the
routing table's UDP socket against the io_context's freed reactor: SIGSEGV in
kqueue_reactor::deregister_descriptor at exit on macOS (status 139), undefined
behaviour elsewhere. ~Transport now clears that reference before host_ (its
last member) is destroyed, so the routing table, its socket and its pinger and
explorer threads end within ~Host, while the io_context still exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The node closes an API connection idle for server_receive_timeout (30 s), the interval of the
wait-head polls. The kept connection raced that close: on macOS the node's close won every time, so
every other poll failed with 'TSocket read 0 bytes' and reset the 3 minutes at the head the check
waits for; Windows lost it now and then. A connection per poll, closed after it, has no such race.
The node's API was never at fault.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant