Add CUDA miner environment presets for various NVIDIA GPUs

Provide example .env files targeting typical block/thread configurations
for RTX 3060/3080/3090/4080/4090/5090 and A5000/A6000.

Include guidance on tuning iterations, pinned buffers, and kernel modes.
Document usage with systemd and manual export for ease of deployment.

crates/engine-gpu-cuda/readme.md

@@ -193,4 +193,20 @@ Build-time:
 - `CUDA_ARCH` = `sm_86|sm_89|sm_120|…` — SM target for device images (normalized internally).
 - `NVCC` or `CUDA_HOME` or `CUDA_PATH` — where to find the toolkit.
 - `MINER_CUDA_ALLOW_UNSUPPORTED_COMPILER` = `1` — add `-allow-unsupported-compiler`.
-- `MINER_NVCC_CCBIN` = `/path/to/g++-14` — force a specific host compiler.
+- `MINER_NVCC_CCBIN` = `/path/to/g++-14` — force a specific host compiler.
+
+---
+
+## Example environment presets
+
+Presets are provided under `examples/.env` and follow a “lower” (≈1× SMs blocks) and “upper” (≈2× SMs blocks) pattern per GPU:
+- RTX 3060: `cuda-miner-3060-lower.env`, `cuda-miner-3060-upper.env`
+- RTX 3080: `cuda-miner-3080-lower.env`, `cuda-miner-3080-upper.env`
+- RTX 3090: `cuda-miner-3090-lower.env`, `cuda-miner-3090-upper.env`
+- RTX 4080: `cuda-miner-4080-lower.env`, `cuda-miner-4080-upper.env`
+- RTX 4090: `cuda-miner-4090-lower.env`, `cuda-miner-4090-upper.env`
+- RTX 5090: `cuda-miner-5090-lower.env`, `cuda-miner-5090-upper.env`
+- RTX A5000: `cuda-miner-a5000-lower.env`, `cuda-miner-a5000-upper.env`
+- RTX A6000: `cuda-miner-a6000-lower.env`, `cuda-miner-a6000-upper.env`
+
+Each preset uses `MINER_CUDA_MODE=g2` (device SHA3 + early-exit) and `MINER_CUDA_BLOCK_DIM=256`, and sizes `MINER_CUDA_THREADS` as `blocks × 256`. Adjust `MINER_CUDA_ITERS` to tune kernel dwell time vs early-exit responsiveness. If a G2 kernel image isn’t embedded for your device, the engine falls back to G1 automatically.

examples/.env/README.md

@@ -0,0 +1,119 @@
+# CUDA miner environment presets
+
+This directory contains example environment files for commonly deployed NVIDIA GPUs. Each file sets reasonable defaults for the Quantus miner GPU engine and can be used as-is or as a starting point for further tuning.
+
+Environment variables are read by the service via the systemd `EnvironmentFile` directive. You can point the service at any of these example files or copy one to your node’s standard location (for example, `/etc/resonance-miner.env`).
+
+Key variables
+- MINER_CUDA_BLOCK_DIM
+  - Threads per block. Keep this a multiple of 32 (warp size). 256 is a solid default.
+- MINER_CUDA_THREADS
+  - Total threads launched. This sets the grid size as blocks = ceil(threads / block_dim).
+  - Calculate threads = desired_blocks × block_dim.
+- MINER_CUDA_ITERS
+  - Iterations per thread.
+  - G2 (device SHA3 + early-exit): increase for longer kernel dwell time while keeping early-exit responsiveness acceptable.
+  - G1 (host SHA3): sets copy size and host hashing load. Try to keep threads × iters × 64 bytes ≈ 64–128 MB per launch.
+- MINER_CUDA_MODE
+  - Set to g2 to use the device SHA3 + early-exit kernel when available. If the G2 kernel is not embedded, the engine falls back to G1 automatically.
+- MINER_CUDA_PINNED
+  - Use pinned host buffers. Helpful in G1 to reduce D2H latency. Safe to leave enabled for G2 (doesn’t hurt).
+- MINER_CUDA_HASH_THREADS
+  - Only used by G1 (host SHA3). Defaults to available CPU parallelism.
+
+General tuning guidance
+- Target at least one block per SM for decent occupancy, and often 2× SMs is better for latency hiding.
+- Number of blocks = ceil(MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM).
+- For a given GPU:
+  - “Lower” preset ≈ 1× SMs blocks.
+  - “Upper” preset ≈ 2× SMs blocks.
+- Leave MINER_CUDA_BLOCK_DIM=256 unless you have a strong reason to change it; adjust blocks via MINER_CUDA_THREADS.
+- For G2, prefer higher MINER_CUDA_ITERS (e.g., 2048–4096) to increase kernel durations and reduce host round-trip overhead, while still allowing fast early-exit.
+
+Included presets
+
+RTX 3060 (28 SMs)
+- cuda-miner-3060-lower.env
+  - 28 blocks × 256 threads/block → MINER_CUDA_THREADS=7168
+  - “Lower” preset (≈1× SMs blocks)
+- cuda-miner-3060-upper.env
+  - 56 blocks × 256 threads/block → MINER_CUDA_THREADS=14336
+  - “Upper” preset (≈2× SMs blocks)
+
+RTX 3080 (68 SMs)
+- cuda-miner-3080-lower.env
+  - 68 blocks × 256 threads/block → MINER_CUDA_THREADS=17408
+  - “Lower” preset
+- cuda-miner-3080-upper.env
+  - 136 blocks × 256 threads/block → MINER_CUDA_THREADS=34816
+  - “Upper” preset
+
+RTX 3090 (82 SMs)
+- cuda-miner-3090-lower.env
+  - 82 blocks × 256 threads/block → MINER_CUDA_THREADS=20992
+  - “Lower” preset
+- cuda-miner-3090-upper.env
+  - 164 blocks × 256 threads/block → MINER_CUDA_THREADS=41984
+  - “Upper” preset
+
+RTX 4080 (76 SMs)
+- cuda-miner-4080-lower.env
+  - 76 blocks × 256 threads/block → MINER_CUDA_THREADS=19456
+  - “Lower” preset
+- cuda-miner-4080-upper.env
+  - 152 blocks × 256 threads/block → MINER_CUDA_THREADS=38912
+  - “Upper” preset
+
+RTX 4090 (128 SMs)
+- cuda-miner-4090-lower.env
+  - 128 blocks × 256 threads/block → MINER_CUDA_THREADS=32768
+  - “Lower” preset
+- cuda-miner-4090-upper.env
+  - 256 blocks × 256 threads/block → MINER_CUDA_THREADS=65536
+  - “Upper” preset
+
+RTX 5090 (est.)
+- cuda-miner-5090-lower.env
+  - Conservative starting point: 128 blocks × 256 threads/block → MINER_CUDA_THREADS=32768
+  - Adjust threads toward ≈ (#SMs × 256) for “lower”
+- cuda-miner-5090-upper.env
+  - 256 blocks × 256 threads/block → MINER_CUDA_THREADS=65536
+  - Adjust threads toward ≈ (2 × #SMs × 256) for “upper”
+
+RTX A5000 (64 SMs)
+- cuda-miner-a5000-lower.env
+  - 64 blocks × 256 threads/block → MINER_CUDA_THREADS=16384
+  - “Lower” preset
+- cuda-miner-a5000-upper.env
+  - 128 blocks × 256 threads/block → MINER_CUDA_THREADS=32768
+  - “Upper” preset
+
+RTX A6000 (84 SMs)
+- cuda-miner-a6000-lower.env
+  - 84 blocks × 256 threads/block → MINER_CUDA_THREADS=21504
+  - “Lower” preset
+- cuda-miner-a6000-upper.env
+  - 168 blocks × 256 threads/block → MINER_CUDA_THREADS=43008
+  - “Upper” preset
+
+Datacenter GPUs (A100/H100) — guidance
+- Build: use a matching CUDA_ARCH (e.g., sm_80 for A100, sm_90 for H100) to embed native CUBINs for your driver.
+- Start with:
+  - Lower: blocks ≈ #SMs, threads = blocks × 256
+  - Upper: blocks ≈ 2 × #SMs, threads = blocks × 256
+- Iterations (G2): start at 4096–8192; increase to reduce host round-trips; decrease if you need faster early-exit responsiveness.
+- Keep --workers 1 for single-GPU nodes.
+- If you want presets added to this directory, use the “lower/upper” naming convention: cuda-miner-a100-lower.env, cuda-miner-a100-upper.env, cuda-miner-h100-lower.env, cuda-miner-h100-upper.env.
+
+Usage
+- With systemd
+  - Point your service `EnvironmentFile=` at the selected file in this directory, or copy the file to `/etc/resonance-miner.env`.
+  - Example:
+    - EnvironmentFile=/path/to/quantus-miner/examples/.env/cuda-miner-4090-256.env
+- Manual testing
+  - Export the variables in your shell before starting `quantus-miner` with `--engine gpu-cuda`.
+
+Notes
+- These presets default to G2 mode (MINER_CUDA_MODE=g2) where applicable. If your binary doesn’t include the G2 kernel image for your device, the engine falls back to G1 automatically.
+- For G1-only deployments, consider smaller MINER_CUDA_ITERS so threads × iters × 64 stays within 64–128 MB per launch to keep PCIe and host SHA3 balanced.
+- Keep `--workers 1` for GPU runs to avoid contention on a single device.

examples/.env/cuda-miner-3060-lower.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3060 — G2 device path (lower-block example: 28 blocks)
+# Launch shape targets ~1× SMs (28 SMs → 28 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 28 blocks with 256 threads/block: 28 * 256 = 7168 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 28 * 256 = 7168 (28 blocks)
+MINER_CUDA_THREADS=7168
+
+# Iterations per thread
+# G2 guidance on Ampere 3060: start around 2048; increase for longer kernels while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=2048
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-3060-upper.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3060 — G2 device path (upper-block example: 56 blocks)
+# Launch shape targets ~2× SMs (28 SMs → 56 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 56 blocks with 256 threads/block: 56 * 256 = 14336 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 56 * 256 = 14336 (56 blocks)
+MINER_CUDA_THREADS=14336
+
+# Iterations per thread
+# G2 guidance on Ampere 3060: use a longer kernel dwell time here; start around 4096.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-3080-lower.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3080 — G2 device path (lower-block example: 68 blocks)
+# Launch shape targets ~1× SMs (68 SMs → 68 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 68 blocks with 256 threads/block: 68 * 256 = 17408 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 68 * 256 = 17408 (68 blocks)
+MINER_CUDA_THREADS=17408
+
+# Iterations per thread
+# G2 guidance on Ampere 3080: start around 3072; increase for longer kernels while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=3072
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-3080-upper.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3080 — G2 device path (upper-block example: 136 blocks)
+# Launch shape targets ~2× SMs (68 SMs → 136 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 136 blocks with 256 threads/block: 136 * 256 = 34816 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 136 * 256 = 34816 (136 blocks)
+MINER_CUDA_THREADS=34816
+
+# Iterations per thread
+# G2 guidance on Ampere 3080: use a longer kernel dwell time here; start around 4096.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-3090-lower.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3090 — G2 device path (lower-block example: 82 blocks)
+# Launch shape targets ~1× SMs (82 SMs → 82 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 82 blocks with 256 threads/block: 82 * 256 = 20992 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 82 * 256 = 20992 (82 blocks)
+MINER_CUDA_THREADS=20992
+
+# Iterations per thread
+# G2 guidance on Ampere 3090: start around 3072; increase for longer kernels while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=3072
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-3090-upper.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 3090 — G2 device path (upper-block example: 164 blocks)
+# Launch shape targets ~2× SMs (82 SMs → 164 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 164 blocks with 256 threads/block: 164 * 256 = 41984 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 164 * 256 = 41984 (164 blocks)
+MINER_CUDA_THREADS=41984
+
+# Iterations per thread
+# G2 guidance on Ampere 3090: use a longer kernel dwell time here; start around 4096.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-4080-lower.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 4080 — G2 device path (lower-block example: 76 blocks)
+# Launch shape targets ~1× SMs (76 SMs → 76 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 76 blocks with 256 threads/block: 76 * 256 = 19456 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 76 * 256 = 19456 (76 blocks)
+MINER_CUDA_THREADS=19456
+
+# Iterations per thread
+# G2 guidance on Ada 4080: start around 4096; increase for longer kernels while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-4080-upper.env

@@ -0,0 +1,39 @@
+# NVIDIA RTX 4080 — G2 device path (upper-block example: 152 blocks)
+# Launch shape targets ~2× SMs (76 SMs → 152 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 152 blocks with 256 threads/block: 152 * 256 = 38912 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 152 * 256 = 38912 (152 blocks)
+MINER_CUDA_THREADS=38912
+
+# Iterations per thread
+# G2 guidance on Ada 4080 (upper-block): use a longer kernel dwell time; start around 6144.
+# Reduce if you need faster early-exit responsiveness for highly variable workloads.
+MINER_CUDA_ITERS=6144
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-4090-lower.env

@@ -0,0 +1,38 @@
+# NVIDIA RTX 4090 — G2 device path (lower-block example: 128 blocks)
+# Launch shape targets ~1× SMs (128 SMs → 128 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 128 blocks with 256 threads/block: 128 * 256 = 32768 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 128 * 256 = 32768 (128 blocks)
+MINER_CUDA_THREADS=32768
+
+# Iterations per thread
+# G2 guidance on Ada 4090 (lower-block): start around 3072; increase for longer kernels while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=3072
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-4090-upper.env

@@ -0,0 +1,33 @@
+# NVIDIA RTX 4090 — G2 device path (upper-block example: 256 blocks)
+# Launch shape targets 2x SMs (128 SMs → 256 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+
+# Threads per block (warp multiple)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 256 * 256 = 65536 (256 blocks)
+MINER_CUDA_THREADS=65536
+
+# Iterations per thread (tune for your device; start with 4096 on Ada)
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging
+# RUST_LOG=info

examples/.env/cuda-miner-5090-lower.env

@@ -0,0 +1,52 @@
+# NVIDIA RTX 5090 — G2 device path (conservative lower-block example)
+# This preset intentionally uses a conservative block count to be safe across early/unknown
+# silicon revisions. Start here, validate stability/throughput, then scale blocks/iters up.
+#
+# Guidance:
+# - Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM.
+# - This file uses 128 blocks × 256 threads/block → MINER_CUDA_THREADS=32768.
+#   If your card reports substantially more SMs than 128, raise MINER_CUDA_THREADS
+#   to approximately (#SMs × 256) for the “lower” preset, and (~2 × #SMs × 256)
+#   for an “upper” preset.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+# - If the embedded G2 kernel isn’t available for your device image, the engine will
+#   fall back to G1 automatically (the rest of the variables are still safe).
+#
+# Build note:
+# - When building device images specifically for this GPU generation, set CUDA_ARCH=sm_120
+#   (or matching compute capability) at build time to embed a native CUBIN for your driver.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 128 * 256 = 32768 (128 blocks)
+MINER_CUDA_THREADS=32768
+
+# Iterations per thread
+# G2 guidance on high-end modern GPUs: start around 4096. Increase for longer kernel dwell time
+# (fewer host round-trips) while preserving early-exit responsiveness as needed.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info
+
+# Tuning checklist (post-deploy):
+# 1) Check per-launch timings in logs:
+#    - “CUDA G2 kernel and sync OK (kernel_ms=…)”
+# 2) If the device is underutilized (low occupancy), increase MINER_CUDA_THREADS
+#    so that blocks ≈ #SMs (lower preset) or ≈ 2 × #SMs (upper preset).
+# 3) If kernel_ms is very short and host round-trip dominates, increase MINER_CUDA_ITERS.
+# 4) Confirm that early-exit behavior meets your latency target; reduce ITERS if needed.

examples/.env/cuda-miner-5090-upper.env

@@ -0,0 +1,52 @@
+# NVIDIA RTX 5090 — G2 device path (upper-block example)
+# This preset targets a higher block count to better saturate the GPU on modern silicon.
+# Start here, validate stability/throughput, then tune blocks/iters for your specific card.
+#
+# Guidance:
+# - Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM.
+# - This file uses 256 blocks × 256 threads/block → MINER_CUDA_THREADS=65536.
+#   If your card reports substantially more or fewer SMs than 128, adjust:
+#     • “Lower” preset ≈ (#SMs × 256) threads  (≈ 1× SMs blocks)
+#     • “Upper” preset ≈ (2 × #SMs × 256)      (≈ 2× SMs blocks)
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+# - If the embedded G2 kernel isn’t available for your device image, the engine will
+#   fall back to G1 automatically (the rest of the variables remain safe).
+#
+# Build note:
+# - When building device images specifically for this GPU generation, set CUDA_ARCH=sm_120
+#   (or matching compute capability) at build time to embed a native CUBIN for your driver.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 256 * 256 = 65536 (256 blocks)
+MINER_CUDA_THREADS=65536
+
+# Iterations per thread
+# G2 guidance on high-end modern GPUs (upper-block): start around 8192 for longer kernel dwell time
+# (fewer host round-trips). Reduce if you need faster early-exit responsiveness.
+MINER_CUDA_ITERS=8192
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info
+
+# Tuning checklist (post-deploy):
+# 1) Check per-launch timings in logs:
+#    - “CUDA G2 kernel and sync OK (kernel_ms=…)”
+# 2) If the device is underutilized (low occupancy), increase MINER_CUDA_THREADS
+#    so that blocks ≈ #SMs (lower preset) or ≈ 2 × #SMs (upper preset).
+# 3) If kernel_ms is very short and host round-trip dominates, increase MINER_CUDA_ITERS.
+# 4) Confirm that early-exit behavior meets your latency target; reduce ITERS if needed.

examples/.env/cuda-miner-a5000-lower.env

@@ -0,0 +1,39 @@
+# NVIDIA RTX A5000 — G2 device path (lower-block example: 64 blocks)
+# Launch shape targets ~1× SMs (64 SMs → 64 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 64 blocks with 256 threads/block: 64 * 256 = 16384 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 64 * 256 = 16384 (64 blocks)
+MINER_CUDA_THREADS=16384
+
+# Iterations per thread
+# G2 guidance on Ampere A5000 (lower-block): start around 3072; increase for longer kernels
+# while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=3072
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-a5000-upper.env

@@ -0,0 +1,39 @@
+# NVIDIA RTX A5000 — G2 device path (upper-block example: 128 blocks)
+# Launch shape targets ~2× SMs (64 SMs → 128 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 128 blocks with 256 threads/block: 128 * 256 = 32768 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 128 * 256 = 32768 (128 blocks)
+MINER_CUDA_THREADS=32768
+
+# Iterations per thread
+# G2 guidance on Ampere A5000 (upper-block): use a longer kernel dwell time; start around 4096.
+# Reduce if you need faster early-exit responsiveness for highly variable workloads.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-a6000-lower.env

@@ -0,0 +1,39 @@
+# NVIDIA RTX A6000 — G2 device path (lower-block example: 84 blocks)
+# Launch shape targets ~1× SMs (84 SMs → 84 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 84 blocks with 256 threads/block: 84 * 256 = 21504 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 84 * 256 = 21504 (84 blocks)
+MINER_CUDA_THREADS=21504
+
+# Iterations per thread
+# G2 guidance on Ampere A6000 (lower-block): start around 3072; increase for longer kernels
+# while preserving early-exit responsiveness.
+MINER_CUDA_ITERS=3072
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info

examples/.env/cuda-miner-a6000-upper.env

@@ -0,0 +1,39 @@
+# NVIDIA RTX A6000 — G2 device path (upper-block example: 168 blocks)
+# Launch shape targets ~2× SMs (84 SMs → 168 blocks) with 256 threads/block.
+# This configuration uses the G2 kernel (device SHA3 + early-exit).
+#
+# Notes:
+# - Increase/decrease ITERS to balance kernel duration vs early-exit responsiveness.
+# - Pinned host buffers are harmless here (G2 doesn’t do large copy-backs) but left enabled.
+# - If the embedded G2 kernel isn’t available, the engine will fall back to G1 automatically.
+# - Keep your service at --workers 1 to avoid multiple concurrent launches on a single GPU.
+#
+# Blocks = MINER_CUDA_THREADS / MINER_CUDA_BLOCK_DIM
+# For 168 blocks with 256 threads/block: 168 * 256 = 43008 threads.
+
+# Threads per block (warp multiple; 256 is a solid default)
+MINER_CUDA_BLOCK_DIM=256
+
+# Total threads = blocks * threads_per_block → 168 * 256 = 43008 (168 blocks)
+MINER_CUDA_THREADS=43008
+
+# Iterations per thread
+# G2 guidance on Ampere A6000 (upper-block): use a longer kernel dwell time; start around 4096.
+# Reduce if you need faster early-exit responsiveness for highly variable workloads.
+MINER_CUDA_ITERS=4096
+
+# Use pinned (page-locked) host buffers (harmless in G2; helps if we fall back to G1)
+MINER_CUDA_PINNED=1
+
+# Select G2 kernel (device SHA3 + threshold + early-exit)
+MINER_CUDA_MODE=g2
+
+# Optional: force embedded image selection (default prefers cubin)
+# MINER_CUDA_IMAGE=cubin
+# MINER_CUDA_IMAGE=ptx
+
+# Optional: host SHA3 workers (only used if engine falls back to G1)
+# MINER_CUDA_HASH_THREADS=24
+
+# Optional: logging verbosity
+# RUST_LOG=info