algo_ops
In producing distributed blockchain applications, we found a need for a shared high level interface to a blockchain (initially Algorand).
This crate is part of that interface - it provides the Algorand implementation of the blockchain_ops traits, over algonaut.
AlgoOps covers accounts, payments, Algorand Standard Assets, and the
Transaction Execution Approval Language (TEAL) application lifecycle, and
implements BlockChainOps and AssetOps. Construct it with
AlgoOps::new_for_algorand.
The consumer is expected to be blockchain-aware: the traits cover what reads
naturally on any chain, while Algorand-specific power is reached directly on
AlgoOps or via its native escape hatch (the algonaut client accessors).
Example: print an account balance
AlgoChainConfig::default() targets algokit localnet (algod on
localhost:4001). Start it with algokit localnet start, then:
use ;
The same program is a runnable example — cargo run -p algo_ops --example print_balance -- <ADDRESS>.
Outbound rate limiting
Every algod and indexer request funnels through one call path, so a single, optional outbound rate limit protects a metered endpoint from a busy caller (for example a consumer polling the current round on every tick). It is off by default, so unset it behaves exactly as before.
Set it at construction with with_rate_limit(max, per) — a token bucket, so up to max
requests may burst before the rate settles to max/per:
use Duration;
use ;
// At most 100 requests per minute to the node/indexer.
let ops = new_for_algorand
.with_rate_limit;
Or set it declaratively on the config (it round-trips through serialization) via
AlgoChainConfig::rate_limit = Some(RateLimitConfig { max_requests, per_millis, mode }). The
limiter is shared across clones of a client, so cloning does not multiply the allowance.
Block vs Reject mode
When the bucket is empty the limiter's mode decides what happens:
RateLimitMode::Block(the default) sleeps the calling thread until a token frees, then proceeds.with_rate_limit(max, per)uses this — behaviour is unchanged from before.RateLimitMode::Rejectnever sleeps: it fails fast withAlgoError::rate_limited { retry_after }, carrying the wait until the next token, and consumes no token. A latency-sensitive caller (e.g. a consensus loop that must not freeze) selects it and backs off — or serves cached state — on its own terms.
use Duration;
use ;
let ops = new_for_algorand
.with_rate_limit_mode;
match ops.round
A Reject rejection is distinct from a server-side 429 (a retryable transient failure) and
from a 403/quota stop: is_rate_limited() is true while is_quota()/is_forbidden() are
false. A rejected call makes no network request and does not consume an internal retry.
Daily request backstop
The rate limit above is a burst clip: it bounds the short-term rate, not the total over a day. To stay under a metered provider's per-IP daily request quota (which halts a node until the provider's start-of-day reset), enable the wall-clock daily budget — independent of the token bucket, so both may be set: the bucket clips bursts, the budget caps the daily total. It counts at the same shared per-request hook, so each page of a paged fetch and each retry counts as one request.
use Duration;
use ;
let ops = new_for_algorand
.with_rate_limit_mode // burst clip
.with_daily_budget; // 50k/day at 00:00 UTC
match ops.round
The start-of-day is a UTC seconds-of-day offset in [0, 86_400) (0 = 00:00 UTC); a consumer
parsing an HH:MM±TZ day-start resolves it to that offset first. Set it declaratively on the
config via AlgoChainConfig::daily_budget = Some(DailyBudgetConfig { max_requests_per_day, day_start_offset_secs }) (it round-trips through serialization). The daily count is checked
before the token bucket, so neither limiter is charged for a request the other blocks.
is_daily_budget_exceeded() is distinct from is_rate_limited() (a transient burst clip) and
from is_quota()/is_forbidden() (a server-side 403): all three are false here.
Persisting the count across restarts
A restart does not refill the provider's quota, so the running total must survive one — a counter internal to a client instance otherwise resets on both a config rebuild and a process restart, letting a crash-loop re-spend the budget. Both the cumulative request counter and the daily-window count are primeable at construction and readable for persistence:
// Boot: restore the persisted totals into a freshly built client.
let ops = new_for_algorand
.with_daily_budget
.with_daily_spent // resume mid-day rather than from zero
.with_initial_request_count; // resume the lifetime counter
// Periodically snapshot to disk.
let total = ops.requests_made; // monotonic lifetime total
let state = ops.daily_budget_state; // Some({ window_start_unix, spent, max })
requests_made() counts every outbound request (each page, each retry) and is always on,
independent of any rate limit. Both the counter and the daily budget are shared across clones,
so cloning a client neither multiplies the allowance nor splits the count.
Distinguishing a quota rejection from a transient failure
A failed call surfaces the underlying HTTP status as a typed AlgoError, so a caller can
tell a hard quota/forbidden rejection (do not retry) from a transient failure (retry)
without string-matching the message. Downcast the returned anyhow::Error:
use AlgoError;
// `ops.round()` returns `anyhow::Result<u64>`; downcast a failure to classify it.
match ops.round
A per-second server rate limit (HTTP 429) is retried with backoff internally and, if it
still fails, surfaces as AlgoErrorKind::TransientFailure; a daily-quota 403 surfaces as
AlgoErrorKind::HttpError with is_quota() / is_forbidden() true.
Part of the blockchain_ops_rust workspace — see the root README for the full
picture.