Fix silent key corruption above 125-bit intervals: widen distance field to 256 bits

[Dileep-Kumar-5]

The bug

ENTRY.d packs the travelled distance into 128 bits as b127=sign b126=kangaroo type, b125..b0 distance, leaving 126 bits of magnitude. Distances span the interval width, so anything wider than 125 bits overflows — hence the README's "This program is limited to a 125bit interval search."

The problem is what happens when you exceed it. Convert() masks the excess away with & 0x3FFFFFFFFFFFFFFF, stores a valid-looking entry, and on collision yields a wrong private key with no error, no warning and no crash.

Measured on puzzle #140's real range (2^139), current master vs this branch, same input, same machine:

	DPs stored	-wcheck
master	376,836	0.024% OK (376,747 corrupt)
this branch	408,118	100.000% OK

master reports normal progress throughout. Nothing indicates the run is worthless. Filed separately as #159.

The change

The wider field is opt-in, and the default build is byte-compatible with upstream.

DIST_WORDS selects the distance width: 2 by default, 4 with -DWIDE_DIST (or by uncommenting WIDE_DIST in Constants.h).

	default	-DWIDE_DIST
max interval	125 bits	253 bits
ENTRY	32 bytes	48 bytes
ITEM	56 bytes	72 bytes
KSIZE	10 words	12 words
DP packet	40 bytes	56 bytes
kangaroo transfer	16 bytes	32 bytes

The default column is exactly today's layout, including the original work-file and protocol magics, so a default build reads and writes upstream's files and talks to upstream peers unchanged.

Rather than #ifdef-ing every use site, a dist_t typedef plus DIST_WORDS lets one implementation serve both widths — the sign and type flags always sit in the top two bits of the top word, so Convert, CalcDistAndType, CreateEntry, sameDist and the four network checksum accumulations became loops. That also deleted the legacy 126-bit overloads and Widen(): at DIST_WORDS == 2, dist_t simply is int128_t. Only genuinely width-specific code stayed conditional.

Over-range distances now abort instead of truncating, and name the fix:

HashTable::Convert: travelled distance exceeds 126 bits.
Interval is too large for the DP entry format (max 125 bits).
Rebuild with -DWIDE_DIST for intervals up to 253 bits.
Aborting rather than storing a truncated distance.

Three other defects fixed along the way, all independent of the width work:

• Latent out-of-bounds write: ModNeg256Order(dist[g]) writes r[0..3] into a 2-word dist[g], clobbering the next kangaroo. Only dormant because USE_SYMMETRY ships commented out.
• CUDA 13 build break: cudaDeviceProp::computeMode was removed, so GPUEngine.cu no longer compiles at all against a current toolkit. Switched to cudaDeviceGetAttribute. This is why the branch builds today. Filed separately as GPUEngine.cu does not compile with CUDA 13: cudaDeviceProp::computeMode was removed #160.
• Stale SM table: _ConvertSMVer2Cores() stops at sm_75, so Ampere and newer return 0. Not just the (16x0 cores) banner — GetGridSize() does *y = 2 * _ConvertSMVer2Cores(...), gets 0, and falls back to *y = 128, so the default grid Y on an sm_86 card is 128 instead of the intended 256. Added sm_80/86/87/89/90 and Blackwell. Measured back to back with -g forced: 32x128 = 338.9 MK/s, 32x256 = 345.5 MK/s (+2.0%).

Verification

RTX 3050 Laptop, sm_86, CUDA 13.3.73, MSVC 14.44. Both widths built and run. All DP validity via -wcheck:

	default build	-DWIDE_DIST build
56-bit sample key	correct	correct
#120, 2^119	34,906 DPs, 100.000%	100.000%
#140, 2^139	aborts, exit 255	34,762 DPs, 100.000%
work-file magic	0xFA6A8001 (upstream's)	0xFA6A8011

Each build rejects the other's work file with "Not a work file" — a width mismatch is refused, never misparsed.

Also verified on the wide build: 2^134 (#135, which master cannot attempt at all) at 100.000%, and client/server on localhost — 196,231 DPs over TCP at 100.000%, kangaroo backup uploaded (536,576 x 32 bytes), downloaded (2^19.03 kangaroos loaded, 0 created), and DPs generated from the downloaded herd validating at 100.000%.

tools/check_layout.py and tools/test_distfield.py verify both widths in one run — producer/consumer agreement on every offset, the AddDist carry chain, the checksum truncation, the magics, and the bit-packing round-trip — and assert the default reproduces upstream's sizes. Neither needs a compiler or a GPU.

Costs

Only when -DWIDE_DIST is enabled: DP tables +50% RAM, device kangaroo memory +20%, DP packets +40%, kangaroo transfers +100%, and 4-7% throughput. ptxas: same 98 registers, zero spills either way, stack frame 18560 -> 20608 bytes.

A default build costs nothing and changes no format.

Splitting

The CUDA 13 fix (#160) and the SM table fix are each one self-contained commit with no bearing on the distance width, and are worth taking on their own even if the rest is rejected — without the first, nobody can build the GPU version against a current toolkit at all. Happy to open them separately if you prefer.

🤖 Generated with Claude Code

[Dileep-Kumar-5]

Updated in af9c5aa: the wider distance field is now opt-in, and a default build is byte-compatible with upstream. The description above has been rewritten accordingly.

I originally offered this as an option and it was the right call — it removes the main reason to reject the PR.

DIST_WORDS selects the width: 2 by default, 4 with -DWIDE_DIST (or by uncommenting WIDE_DIST in Constants.h).

	default	-DWIDE_DIST
max interval	125 bits	253 bits
ENTRY	32 bytes	48 bytes
ITEM	56 bytes	72 bytes
KSIZE	10 words	12 words
DP packet	40 bytes	56 bytes
kangaroo transfer	16 bytes	32 bytes

The default column is exactly today's layout, original work-file and protocol magics included. I verified that end to end rather than by inspection: a default build writes a work file whose magic reads back as 0xFA6A8001, i.e. upstream's HEADW. It reads and writes upstream's files and talks to upstream peers unchanged.

What this means for review: the format change is no longer something you have to accept to take the fix. On a default build the only behavioural difference is that an over-range interval now stops with an error instead of silently producing a wrong key.

The implementation also got smaller. Instead of #ifdef-ing every use site, a dist_t typedef plus DIST_WORDS lets one implementation serve both widths — the sign and type flags always occupy the top two bits of the top word, so Convert, CalcDistAndType, CreateEntry, sameDist and the four network checksum accumulations became loops over DIST_WORDS. That deleted the legacy 126-bit Add/Convert/CalcDistAndType overloads and Widen() outright: at DIST_WORDS == 2, dist_t is int128_t. Only genuinely width-specific code stayed conditional — the two extra device slots in Load/StoreKangaroos, the four extra uint32 in OutputDP, the Add128/Add256 choice behind AddDist, and the magics.

Both configurations built and run on an RTX 3050 Laptop (sm_86, CUDA 13.3.73, MSVC 14.44):

	default build	-DWIDE_DIST build
56-bit sample key	correct	correct
#120, 2^119	34,906 DPs, 100.000% -wcheck	100.000%
#140, 2^139	aborts, exit 255	34,762 DPs, 100.000%

Each build rejects the other's work file with "Not a work file", so a width mismatch is refused rather than misparsed.

tools/check_layout.py and tools/test_distfield.py now check both widths in a single run and assert the default reproduces upstream's sizes, so a future edit that quietly breaks compatibility fails the check. Neither needs a compiler or a GPU:

python tools/check_layout.py
python tools/test_distfield.py

The CUDA 13 fix (#160) and the sm_86 table fix remain independent single commits, still worth taking on their own even if the width work isn't wanted.

[Dileep-Kumar-5]

Additional verification on puzzle #135, which is the target that motivates the whole patch and the one case af9c5aa's commit message does not cover — I ran it after committing.

#135 is a 2^134 interval, so master cannot attempt it at all: it is above the 125-bit cap, and before this branch it would have run happily while corrupting every DP.

Target checked before spending GPU time on it, since a pubkey that does not belong to the address makes a run worthless and nothing in the solver would say so:

puzzle #135
  pubkey on curve   yes
  address expected  16RGFo6hjq9ym6Pj7N5H7L1NR1rVPJyw2v
  address derived   16RGFo6hjq9ym6Pj7N5H7L1NR1rVPJyw2v   MATCH
  range             2^134 .. 2^135-1   OK

Default build refuses it, which is the intended behaviour:

HashTable::Convert: travelled distance exceeds 126 bits.
Interval is too large for the DP entry format (max 125 bits).
Rebuild with -DWIDE_DIST for intervals up to 253 bits.
Aborting rather than storing a truncated distance.

-DWIDE_DIST build runs it correctly:

range	2^134
ops	10,808,848,384 in 28s = 386.0 MK/s
DPs	10,423
-wcheck	100.000% OK

Worth noting for the review: ptxas output is byte-identical to the hard-coded 256-bit version from before the refactor — 98 registers, 0 spill stores, 0 spill loads, 20608-byte stack frame. Making the width configurable via DIST_WORDS cost nothing in generated code; the #if blocks and loops all fold away at compile time.

So the full validated matrix across both builds is now:

interval	default build	-DWIDE_DIST
56-bit sample key	solves correctly	solves correctly
2^119 (#120)	100.000%	100.000%
2^134 (#135)	refuses, exit 255	100.000%
2^139 (#140)	refuses, exit 255	100.000%

For context on the scale rather than the correctness: #135 in one pass is ~3.07e20 operations, which on this RTX 3050 Laptop is roughly 25,200 GPU-years. The run above covered about 3.5e-9 percent of it. Nobody should read these numbers as progress on the puzzle — they only demonstrate that the DPs being produced are valid, which on master they would not be.