func New
New returns a Limiter replenishing `rate` tokens per tick, each bucket capped at `burst`. rate is clamped to >= 0, burst to >= 1.
v0 source pure
Package ratelimit is a deterministic token-bucket rate limiter — a port of golang.org/x/time/rate with the wall clock...
View source
gno.land/p/moul/x/daily/ratelimit/v0
Deterministic token-bucket rate limiter — a port of golang.org/x/time/rate
with the wall clock replaced by a caller-supplied monotonic tick (on-chain, the
block height).
A Limiter owns a set of per-key token buckets sharing one rate/burst
config. Each bucket refills at rate tokens per tick up to burst; the caller
picks what a key is (typically an address) and passes the current tick on every
call. Pure integer/float math over persistent avl state — no chain imports, no
ambient state, fully replayable.
1import "gno.land/p/moul/x/daily/ratelimit/v0"
2
3l := ratelimit.New(0.5, 5.0) // 0.5 tokens/tick, capacity 5
4l.Allow("g1caller", height) // consume one token; false if empty
5l.AllowN("g1caller", height, 3) // consume 3 atomically; false if <3
6l.Tokens("g1caller", height) // read-only balance (whole tokens)
Live demo: r/moul/x/daily/ratelimitdemo
· render it at /r/moul/x/daily/ratelimitdemo/v0.
Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.
Dependency graph:
🧪 Highly experimental — potentially vibe-coded. Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: DISCLAIMER.
Package ratelimit is a deterministic token-bucket rate limiter — a port of golang.org/x/time/rate with the wall clock replaced by a caller-supplied monotonic tick (on-chain, that tick is the block height).
It is a pure library: it imports no chain APIs and reads no ambient state. A Limiter owns a set of per-key token buckets sharing one rate/burst config; the caller decides what a key is (typically an address string) and supplies the current tick on every call. Between two observations at ticks `last` and `now`, a bucket gains (now-last)*rate tokens, capped at `burst`. Everything is integer/float arithmetic over persistent avl state, hence deterministic and replayable.
A realm wires it up by holding a *Limiter in a package-level var and feeding it runtime.ChainHeight() as the tick. For a complete, live example see the demo realm r/moul/x/daily/ratelimitdemo(/r/moul/x/daily/ratelimitdemo/v0).
1
1
type Limiter
structLimiter is a set of per-key token buckets sharing one rate/burst config. The zero value is not usable; construct one with New.
Methods on Limiter
func Allow
method on LimiterAllow consumes one token for `key` at tick `now` and reports whether the request is permitted. When the bucket is empty it returns false and consumes nothing. Equivalent to AllowN(key, now, 1).
func AllowN
method on LimiterAllowN consumes `n` tokens for `key` at tick `now` and reports whether the request is permitted. When fewer than `n` tokens are available it returns false and consumes nothing. A key is seen for the first time with a full bucket of `burst` tokens.
func Config
method on LimiterConfig returns the current rate (tokens/tick) and burst (capacity).
func Iterate
method on LimiterIterate calls fn for every known key in ascending order, passing the whole tokens available at tick `now` and the last tick the key was observed. Returning true from fn stops the iteration early; Iterate reports whether it was stopped that way.
func Len
method on LimiterLen returns the number of keys the limiter has seen.
func SetConfig
method on LimiterSetConfig updates the shared rate and burst. rate is clamped to >= 0, burst to >= 1. Existing buckets keep their stored tokens; the new config applies from the next refill.
func Tokens
method on LimiterTokens is a read-only view of how many whole tokens `key` has available at tick `now`, without mutating any state.