Utilities

Utility helpers shared across CTF challenge services.

These utilities are intentionally tiny and dependency free so that every challenge server can import them without pulling in a heavy runtime. They encapsulate a few recurring patterns:

• launching coroutines from sync contexts in a safe, fire-and-forget manner,
• formatting addresses/entities for human readable log lines,
• normalising timestamps and annotations returned by the Arkiv SDK.

anns_to_dict(anns)

Convert Arkiv annotation lists into a plain dict.

The Arkiv SDK represents annotations as objects with key and value attributes. Challenge servers frequently want to look up annotations by key, so this helper collapses both the string and numeric annotation lists into a regular dictionary. Missing or malformed annotations result in an empty mapping.

asyncio_run_safely(coro)

Schedule an awaitable from a synchronous context.

If an event loop is already running (for instance inside an async web framework) the coroutine is scheduled on that loop. Otherwise a short-lived loop is created solely to execute the awaitable. Any exceptions raised by the coroutine are suppressed because the helper is intended for background tasks such as sending webhooks or metrics where failure should not bring the service down.

Parameters:

Name	Type	Description	Default
coro	Awaitable[Any]	The coroutine or awaitable that should eventually run.	required

decode_json_bytes(b)

Decode a best-effort JSON payload from bytes produced on-chain.

now_iso()

Return the current UTC time in ISO-8601 YYYY-MM-DDTHH:MM:SSZ form.

parse_private_key_hex(raw)

Return a 32-byte private key from a hex string with optional 0x prefix.

Uses eth_account.Account.from_key(bytes.fromhex(...)) so behavior matches the canonical Web3.py example.

short_hex(x)

Return a shortened hexadecimal representation for logging.

The helper keeps the 0x prefix (if present) and renders the first six and last four characters separated by an ellipsis. Non-hex inputs are returned unchanged which keeps it safe to call with any object that renders to string.