Add VerifyScriptBatchParallel for multi-threaded batch verification

[icellan]

Summary

• Adds VerifyScriptBatchParallel across all layers: C++ core, CGO C wrapper, Go CGO binding, and Go purego binding
• Uses std::thread with chunk-based work distribution — batch is divided evenly across N threads, last chunk runs on the calling thread to avoid an extra thread spawn
• Per-item exception handling so one malformed transaction returns SCRIPT_ERR_UNKNOWN_ERROR for that item without killing the rest of the batch
• numThreads parameter: 0 defaults to std::thread::hardware_concurrency(), automatically capped at batch size

Files changed

Layer	File	Change
C++ core	core/scriptengine.hpp	Declaration + #include <thread>
C++ core	core/scriptengine.cpp	Implementation with std::thread chunking
CGO C wrapper	bdkcgo/scriptengine_cgo.h	ScriptEngine_VerifyScriptBatchParallel declaration
CGO C wrapper	bdkcgo/src/scriptengine_cgo.cpp	Wrapper + refactored shared _helper_results_to_carray
Go CGO	script/scriptengine.go	VerifyScriptBatchParallel(batch, numThreads)
Go purego	script/scriptengine_purego.go	Same method via purego FFI

Usage

batch := script.NewVerifyBatch(1000)
// ... add items ...
results := se.VerifyScriptBatchParallel(batch, 0)  // use all cores
results := se.VerifyScriptBatchParallel(batch, 4)  // use 4 threads

Test plan

• Build C++ static library with the new code and verify it links
• Run existing BenchmarkVerifyScriptBatch tests to confirm no regression
• Run VerifyScriptBatchParallel with same test data and verify results match sequential VerifyScriptBatch
• Benchmark parallel vs sequential with batch sizes 10, 100, 1000, 10000
• Test edge cases: empty batch, batch size 1, numThreads > batch size, numThreads = 1

🤖 Generated with Claude Code

[ctnguyen]

Default result should be SCRIPT_ERR_UNKNOWN_ERROR, i.e in case something unknown happens, the error is relevant.

[ctnguyen]

I was trying hard to make the bdk core not depending to thread. The reason was to plan for wasm build, that don't like threading.

Threading implementation would be in client code, i.e module level (go module, py module ...), or at higher level (client code)

[ctnguyen]

Gemini analysis pros/cons of purego

CGO's overhead is its safety mechanism. By doing the heavy lifting of switching to a safe OS stack and notifying the Go scheduler, CGO ensures that unmanaged C code doesn't break Go's concurrency model or garbage collector.

Purego buys speed by discarding those safety nets. It performs a blind, unmanaged jump into C code without telling the Go runtime. You pay for that minimal overhead with three major safety risks:

• Scheduler Starvation: If your C function blocks (e.g., waiting for I/O) or simply takes too long, it completely freezes the underlying OS thread. Go has no way to preempt it or move other Goroutines off that thread.
• Garbage Collection Stalls: Go's Garbage Collector often needs all threads to reach a "safe point" to run. A long-running Purego call hides from the runtime, which can stall the entire GC process for the whole application.
• Stack Overflows: Purego executes C code directly on Go's small, dynamically-sized Goroutine stack. If the C function allocates too much local memory, it will overrun the stack and cause a catastrophic segmentation fault, bypassing Go's standard panic recovery.

In short: CGO is a managed, safe boundary. Purego is a raw, unsafe execution that assumes the C code will be nearly instantaneous and memory-light.