feat(congestion): congestion-pricing native contract

[adamkrellenstein]

Summary

Adds a congestion native contract implementing the block-utilization fee multiplier β(t) from the economics spec (§Congestion Pricing). β evolves deterministically per block as a function of utilization u:

Region	Condition	Update
Uncongested	u < u_low	multiplicative decay β·λ_decay toward 0
Transition	u_low ≤ u < u_high	smoothstep ramp S(x), floored by the decay term
Congested	u ≥ u_high	compounding growth max(β,1)·(1 + κ·(u − u_high))

Fee = φ_base · β.

Parameters (u_low=20%, u_high=80%, λ_decay=0.95, κ=2.0, φ_base=2.5e-7) match Documentation/modeling/kontor_v1/congestion.py and specs/params.typ.

What's included

• New native-contracts/congestion/ workspace member (contract + WIT + built congestion.wasm.br).
• Registered as native contract ID 6 (append-only) in NATIVE_CONTRACTS.
• Runtime api module runtime/congestion.rs + two lite tests validating the β recurrence against the reference model (1.2 → 1.44 → 1.368; smoothstep midpoint 0.5; decay floor 0.475).

Deferred (intentionally out of scope)

The runtime gas-application hook — wiring β into call.rs fee charging — is deferred per the agreed split: this PR lands the deterministic state machine + contract only, keeping changes additive and low-risk while the indexer fee path is in flux.

CI note

The repo's cargo audit gate is currently red on the default branch from pre-existing upstream advisories (hickory-proto, rustls-webpki via libp2p/malachite/libsql/rustls; one has no fix available yet). This PR does not touch core/Cargo.lock and its own native-contracts audit is clean — the audit failures are unrelated and pre-existing.

---

Note

Medium Risk
Appending a genesis native contract is a protocol-level ID/order decision and affects all nodes at genesis; fee application is deferred, so economic impact is limited until a follow-up wires β into charging.

Overview
Introduces a congestion native contract that implements the economics-spec β(t) fee multiplier from block utilization u, with fee = φ_base · β. The contract stores default thresholds and rates (20%/80% bands, decay, κ, φ_base) and exposes core update_beta, views for β and fee_multiplier, and optional set_congestion_params with basic validation.

The change wires it into the stack like other natives: new native-contracts/congestion WASM crate + WIT, append to NATIVE_CONTRACTS (genesis ID 6), embedded congestion.wasm.br, and indexer runtime/congestion API bindings. Lite tests assert β recurrence, smoothstep mid-band, edge continuity, and invariants against the reference Python model.

Runtime gas charging is not hooked up in this PR—the contract and deterministic state machine land first; applying β in procedure fee paths is explicitly deferred.

^{Reviewed by Cursor Bugbot for commit dfd632b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 016164d. Configure here.}

[cursor]

set_congestion_params missing validation on decay/growth parameters

Medium Severity

set_congestion_params validates u_low_bps and u_high_bps but accepts any value for lambda_decay_bps, kappa_cong_bps, and phi_base without checks. Setting lambda_decay_bps above BPS_DENOM (10 000) turns the decay factor into a growth multiplier (>1.0), causing β to compound upward even in Region 1 (the "uncongested" region), completely inverting the economic model. The existing partial validation suggests guarding against bad parameter values was intended but incomplete.

 

^{Reviewed by Cursor Bugbot for commit 016164d. Configure here.}