Rewritten. This PR predated #1016 and originally shipped a parallel weighting mechanism (weighted: true + methodCosts + a per-descriptor HitsAddend). Now that vendor credit accounting is merged, that design duplicated its vocabulary, its resolution logic and its addend for no gain. This is a rebuild on top of it.

Stacked on #1058 → #1059. Review those first; this branch contains both commits. They are independent bugfixes and stand on their own.

Problem

Credit-weighted rate limiting only exists at upstream scope, where an upstream on rateLimitCountMode: credit prices each call from its vendor's credit-unit table.

A project-, network- or auth-scoped budget has no vendor, so it can only count requests — a range scan and a chain-ID lookup cost the same. The operator is then forced to size a per-IP cap for the worst case, which throttles cheap traffic in order to guard against expensive traffic. There is no way to say "this client may spend N units of work per minute, however they choose to spend it".

Change

Let a budget price its own methods.

rateLimiters:
  budgets:
    - id: frontend
      creditUnits:
        "*": 20
        eth_chainId: 0        # exempt
        eth_call: 26
        eth_getLogs: 60
      rules:
        - method: "*"
          countMode: credit   # the wallet: one pool shared by all methods
          maxCount: 20000
          period: minute
          perIP: true
        - method: eth_chainId # exempt from the wallet, still capped
          countMode: request
          maxCount: 100
          period: second
          perIP: true

rules[].countMode: credit charges the method's cost from the budget's creditUnits table instead of a flat 1, turning maxCount into a compute allowance. Resolution reuses ResolveCreditUnits, so precedence is the one operators already know from upstream.creditUnits: exact method, then "*", then 1. A method priced 0 is exempt.

countMode is per rule, not per budget. That is what makes exemption usable: price a method 0 to keep it out of the wallet, and cover it with a countMode: request rule so it still has a ceiling. A rule that states its mode keeps it even when the caller counts credits; only an unset mode inherits, so existing upstream credit budgets behave exactly as before.

Design decisions

No built-in cost table. The original version shipped DefaultRateLimitMethodCosts merged in SetDefaults. Dropping it is what allows ResolveCreditUnits to be reused unchanged: with defaults == nil the precedence collapses to override[method] → override["*"] → 1. With a defaults table it does not, because ResolveCreditUnits ranks defaults[method] above the operator's own "*" catch-all — so creditUnits: {"*": 1, eth_getLogs: 50} would have its global policy silently defeated by a table the operator never wrote and cannot see. A built-in table is also an unpinnable behaviour surface: a patch release adjusting it would change every budget's effective capacity with nothing visible in the marshalled config. The docs carry a starting table to copy instead.

This is also the weaker hypothesis in the sense of CLAUDE.md's razor — pricing is operator data, not something eRPC should commit to on their behalf.

The two cost sources never mix. An upstream on rateLimitCountMode: credit prices from its vendor; pointing it at a budget that also defines creditUnits or rule-level countMode is rejected at validation rather than resolved by silent precedence. Two plausible cost sources for one counter is the kind of ambiguity that surfaces six months later as "why is my wallet draining faster than my table says".

Exempt methods skip the rule rather than sending a 0 addend. Worth flagging, because the original version of this PR justified the same behaviour with the wrong reason. Check-only-at-zero is a property of the per-descriptor addend, which this rebuild no longer uses; the request-level addend coerces 0 to 1 (GetHitsAddends), so a 0 there would charge a full hit. The consequence is documented as a footgun: a 0-priced method keeps being served after the pool is empty, which is why the exemption pattern above pairs it with a flat rule.

countMode joins the rule identity and the metric labels (rate_limiter_budget_max_count), so rules differing only in mode cannot share a counter or overwrite each other's gauge. Today they cannot collide anyway — a credit rule drops the method entry a request rule keeps — but that non-collision is incidental and holds only while method-omission is the sole descriptor difference between the modes.

Testing

Nine behaviour tests covering: pricing from the budget table with pooling, zero-cost exemption with a flat rule still enforcing, an explicit countMode: request rule surviving a credit caller, nested wildcard pools, #1016 inheritance compatibility, vendor weight winning over the budget table, no-table behaviour as a cross-method request cap, and "*": 0 exemption. Plus config round-trip and rejection cases.

The regression guards were checked for teeth rather than assumed. Restoring the naive permit.Mode || rule.CountMode resolution fails the mixed-budget test immediately:

--- FAIL: TestCreditRule_ExplicitRequestModeSurvivesCreditCaller
    request 1 is within the flat ceiling of 2

That is the whole failure mode in one line: a credit-mode upstream attaching to the budget would force every rule credit, so the flat per-method caps silently stop being flat.

Verified green: upstream, common, auth, erpc. gofmt and go vet clean. Benchmarks show identical allocation counts against the #1059 baseline.

Notes

• Regenerated typescript/config/src/generated.ts with tygo@v0.2.21; esbuild + tsc verified.
• Added RateLimitCountModeRequest / RateLimitCountModeCredit to typescript/config/src/index.ts. They were never exported when feat(cost): unified vendor credit-unit accounting, metrics, headers & rate limiting #1016 landed; rule-level countMode makes that gap user-visible.
• Docs: schema rows, a worked per-IP-wallet example, and three footguns.

One item deliberately not in this PR: the auto-tuner is enabled by default for any upstream with a budget and clamps maxCount to maxBudget (default 100000), so on main today a rateLimitCountMode: credit upstream with a 300M CU plan is reduced to 100k on the first healthy adjustment tick. That is a pre-existing issue with the merged feature rather than anything this PR introduces, so it belongs in its own fix.