Utility APIs

Helper functions for cryptography, address conversion, keylet computation, serialized-object (STO) inspection/editing, and debug tracing. These functions do not read or mutate ledger state directly (with the exception of util_keylet, which consults the active Rules/amendments to decide which keylet types are available). They are pure helpers you call to prepare data for the state, slot, emit, and transaction APIs documented elsewhere.

dice and util_random require the featureRNG amendment; a few util_keyletkeylet types are individually amendment-gated — see below. This page covers the util_* functions and the RNG functions; the STO helpers and the trace helpers that used to share this page now have their own pages: see STO APIs and Trace APIs.

A note on the calling convention: every *_ptr/*_len pair refers to a region of the hook's own linear WASM memory. Any pointer/length pair that is out of bounds of that memory returns OUT_OF_BOUNDS (-1). Pointer values are 32-bit offsets into WASM memory, not host pointers.

---

Return values and error codes

Utility functions follow the standard hook convention: a non-negative return is a result (a count of bytes written, a packed offset/length, a boolean 0/1, or a keylet length of 34), and a negative return is an error code. Always test result < 0 before using the value. Codes referenced above:

Code	Value	Code	Value
OUT_OF_BOUNDS	-1	INVALID_FIELD	-17
INTERNAL_ERROR	-2	PARSE_ERROR	-18
TOO_BIG	-3	NO_SUCH_KEYLET	-21
TOO_SMALL	-4	INVALID_KEY	-41
DOESNT_EXIST	-5	MEM_OVERLAP	-43
INVALID_ARGUMENT	-7	TOO_MANY_NONCES	-12
TOO_LITTLE_ENTROPY	-46

See error.h / the full error table for the complete list.

---

Index

Function	Purpose
util_raddr	20-byte AccountID → base58 r-address string.
util_accid	base58 r-address string → 20-byte AccountID.
util_verify	Verify a secp256k1/ed25519 signature over a payload.
util_sha512h	SHA-512Half (first 32 bytes of SHA-512) of a buffer.
util_keylet	Compute a ledger keylet of a given KEYLET_* type.
dice	Draw a uniform integer in [0, sides).
util_random	Write 1–512 random bytes to WASM memory.

See also the STO APIs index (sto_validate, sto_subfield, sto_subarray, sto_emplace, sto_erase) and the Trace APIs index (trace, trace_num, trace_float).

Related documents

• Hook API reference index
• Overview and Glossary
• Helper macros — SBUF, SUB_OFFSET/SUB_LENGTH, TRACE*, BUFFER_EQUAL_*, integer conversion helpers
• Ledger and slot APIs — slot_set, slot_subfield, ledger_keylet (keylet consumers)
• State APIs — state, state_foreign (namespace/keylet usage)
• Float and Amount APIs — XFL values used by trace_float, float_sto
• Emit and etxn APIs — assembling and emitting transactions built with sto_emplace
• Best practices