Add configurable fee rate bounds with decoupled simulation layout

[laurenshareshian]

Summary

• Dropping the min fee rate from 1.0 to 0.1 sats/vbyte is a big change. If we want to decrease more slowly and monitor the effects, we need to make the min rate configurable. For symmetry, I make the max fee rate configurable as well.
• Introduces BucketLayout (internal simulation array layout) to replace the hardcoded BUCKET_MIN and BUCKET_MAX constants
• minFeeRate controls the simulation array lower bound — transactions below this threshold are excluded from the modeled state space
• maxFeeRate is a pure output filter — estimates whose fee rate exceeds this bound are returned as null, but the simulation always models the full fee rate space (buckets 0–1000) regardless of this value
• minFeeRate default is 1.0 sat/vB; users on Bitcoin Core 29.1+ can opt in to sub-1 sat/vB support with FeeEstimator(minFeeRate = 0.1)
• maxFeeRate default is 22027.0 sat/vB
• Removes duplicate minFeeRate validation (now centralized in BucketLayout) and unused MAX_SIMULATABLE_FEE_RATE
• Removes @InternalAugurApi opt-in annotation (redundant with Kotlin internal visibility)
• Bumps version to 0.3.0

Design

• BucketLayout is an internal-only class that takes only minFeeRate. bucketMax is fixed at 1000 (the legacy simulation ceiling). This ensures maxFeeRate never changes the modeled state space — no lossy bucket folding, no inflow distortion.
• FeeEstimatesCalculator takes maxFeeRate as a separate parameter and applies it in prepareResultArray as a reporting filter.
• MempoolSnapshot.fromMempoolTransactions is unchanged — it buckets all transactions regardless of fee rate bounds. The minFeeRate filtering happens later when snapshots are converted to the internal simulation array.
• minFeeRate validation is centralized in BucketLayout.init (positivity + simulation ceiling check).

API compatibility note

This release changes JVM binary signatures for FeeEstimator constructors and configure(). FeeEstimator gains minFeeRate and maxFeeRate parameters (with Kotlin defaults). These new defaults alter the synthetic JVM overloads. All changes are source-compatible — existing Kotlin and Java callers compile without modification — but callers compiled against 0.1.0 or 0.2.x must be recompiled; linking against old bytecode will produce NoSuchMethodError at runtime. The three known consumers (baywatch, bitcoin-augur-reference, bitcoin-augur-benchmarking) all recompile on dependency bump.

One subtle behavioral change: the fee rate ceiling filter changed from < exp(10) to <= 22027.0. An estimate at exactly bucket 1000 (~22026.47 sat/vB) was previously null, now passes. This is near-impossible to hit in practice.

Test plan

• All 60 tests pass
• BucketLayout ceil test: minFeeRate = 0.15 yields bucket -189 (>= 0.15), not -190 (< 0.15)
• BucketLayout has fixed bucketMax = 1000 regardless of construction
• BucketLayout rejects minFeeRate too high for simulation ceiling
• Custom minFeeRate accepts lower buckets in MempoolSnapshotF64Array
• maxFeeRate filters estimates as output-only (does not affect simulation arrays)
• Estimates at or below maxFeeRate are preserved
• Constructor rejects invalid bounds (zero, negative)
• minFeeRate and maxFeeRate are independent — no cross-validation required
• Manual verification with reference implementation

🤖 Generated with Claude Code

[sanket1729]

Fee rate bounds (minFeeRate/maxFeeRate) and bucket configuration (bucketMin/bucketMax/arraySize) serve different purposes and shouldn't be conflated in a single BucketConfig class.

• Fee rate bounds are policy parameters: "what's the lowest relay fee?" and "above what do we stop reporting estimates?" These are user-facing input/output concerns.
• Bucket bounds are internal implementation details: how the fee rate space is discretized into array slots for the mining simulation.

Right now BucketConfig derives bucket bounds directly from fee rate bounds, coupling the array layout to user-facing config. But they don't need to be the same:

1. Max side: "don't report above X" is an output filter on prepareResultArray. You don't need to shrink the array — folding above-max txs into the highest bucket is lossy and could affect simulation accuracy.
2. Min side: Dropping sub-relay-fee txs is input filtering, independent of array sizing.
3. Array size: Making it smaller with tighter bounds is a memory optimization, not a semantic requirement.

A cleaner separation would keep the internal bucket structure fixed (or separately configured) and apply fee rate bounds as input/output filters.

[sanket1729]

The docs now say estimates are nulled only when they exceed maxFeeRate, but this strict < check also drops values exactly equal to the bound. That leaves the implementation out of sync with the README/KDoc and misses the exact-bound edge case in tests. Either switch this to <= or tighten the wording everywhere to say the bound is exclusive.

[laurenshareshian]

Added a test. This change is intentional.

[sanket1729]

This still changes the published ABI for configure(): main exposed the 4-arg overload, but this PR only leaves the new 6-arg signature in lib.api. Existing compiled Kotlin/Java callers of the old method will hit NoSuchMethodError. If this release is meant to stay binary-compatible, it needs a delegating shim that preserves the old method shape.

[laurenshareshian]

Acknowledged — this is intentionally not binary-compatible, which is why it's a 0.2.x → 0.3.0 bump. None of the three known consumers call configure(), and all recompile on dependency bump (this is a statically linked library, not a shared runtime dependency). Adding a delegating shim would preserve a method signature nobody calls.

[sanket1729]

Approving per request. I left two inline comments for follow-up on the remaining ABI and maxFeeRate-boundary issues.

[laurenshareshian]

Fee rate bounds (minFeeRate/maxFeeRate) and bucket configuration (bucketMin/bucketMax/arraySize) serve different purposes and shouldn't be conflated in a single BucketConfig class.

• Fee rate bounds are policy parameters: "what's the lowest relay fee?" and "above what do we stop reporting estimates?" These are user-facing input/output concerns.
• Bucket bounds are internal implementation details: how the fee rate space is discretized into array slots for the mining simulation.

Right now BucketConfig derives bucket bounds directly from fee rate bounds, coupling the array layout to user-facing config. But they don't need to be the same:

1. Max side: "don't report above X" is an output filter on prepareResultArray. You don't need to shrink the array — folding above-max txs into the highest bucket is lossy and could affect simulation accuracy.
2. Min side: Dropping sub-relay-fee txs is input filtering, independent of array sizing.
3. Array size: Making it smaller with tighter bounds is a memory optimization, not a semantic requirement.

A cleaner separation would keep the internal bucket structure fixed (or separately configured) and apply fee rate bounds as input/output filters.

Addressed: maxFeeRate is now a pure output filter — it no longer affects the simulation array. bucketMax is fixed at 1000 regardless of maxFeeRate. The filter is applied in prepareResultArray via .takeIf { it <= maxFeeRate }. minFeeRate remains the only parameter that controls array layout (via BucketLayout).