Use this when you need randomness an autonomous agent cannot bias or predict and that a third
party can verify — fair selection, sampling, raffles, commit-reveal, anti-MEV ordering. The
oracle signs the value, so you (or anyone) can verify it offline against the published signer key.

Returns:
    The standard envelope (see server instructions). `result` contains:
      - `random_hex`: the random bytes, hex-encoded (`num_bytes` long).
      - `proof`: `{state_hash, tick, timestamp, entropy_commitment}` binding the value to the
        oracle's chaotic state at draw time.
      - `signature`: Ed25519 signature over the value+proof (verify with `verify_random`/the
        signer key in the Hub manifest). `verifiable.signed` will be true.
    Cost ~$0.004 USDC, charged per call.

Example:
    get_random(num_bytes=32, client_seed="0xdeadbeef")

Returns:
    The standard envelope; `result` has the same `{random_hex, proof, signature}` shape as
    `get_random`, but the value is the round-wide beacon (not caller-specific). Cost ~$0.004 USDC.

Example:
    get_randomness_beacon()

Use for lightweight oracle-mediated decisions (e.g. an unbiased pick among options). Read-only —
no side effects, no state change.

Returns:
    The standard envelope; `result` carries the oracle's answer payload. Cost ~$0.003 USDC.

Example:
    ask_oracle(question="Pick one at random: red, green, or blue?")

Pass `random_hex`, `proof`, and `signature` exactly as returned by `get_random` /
`get_randomness_beacon`. Confirms the Ed25519 signature over the canonical (random_hex, proof)
against the signer's published public key — so you trust the math, not the service.

Returns:
    The standard envelope; `result` is `{valid: <bool>}` (plus `error` if the input was
    malformed). Cost ~$0.001 USDC.

Example:
    verify_random(random_hex="0x9f2c…", proof={"scheme": "platon-chaos-vrf/v1", …},
                  signature={"algorithm": "ed25519", "public_key": "<b64>", "value": "<b64>"})

Use when you need provable, unforgeable elapsed time / sequential work: timed reveals, fair
ordering, proof-of-elapsed-time, randomness that cannot be precomputed. Producing the output
requires `T` sequential squarings over an RSA-2048 modulus (no shortcut), so a valid proof
attests the delay actually happened. Verify cheaply with `verify_vdf`.

Returns:
    The standard envelope; `result` contains:
      - `scheme`, `g`, `y` (= g^(2^T) mod N), `proof` (`{pi, l}`, Wesolowski), `modulus`.
    `verifiable.has_proof` will be true. Cost ~$0.01 USDC.

Example:
    compute_vdf(seed="0x1234abcd", difficulty=100000)

Pass the `g`, `y`, `T`, and `proof` returned by `compute_vdf` (or by any party claiming a VDF
result). Confirms `y = g^(2^T) mod N` without redoing the T squarings.

Returns:
    The standard envelope; `result` is `{valid: <bool>}`. Cost ~$0.001 USDC.

Example:
    verify_vdf(g="0x03", y="0x9f2a…", T=100000, proof={"pi": "0x1a2b…", "l": "0x65"})

Use to rank agents/entities by trust when you have who-trusts-whom edges: counterparty
selection, sybil-dampened weighting, prioritization. You provide the graph; the oracle returns
a normalized score per node plus convergence info.

Returns:
    The standard envelope; `result` contains:
      - `scores`: array of `nodes` floats that sum to 1 (±1e-6) — node i's trust share.
      - `iterations`, `converged`: power-iteration convergence info.
    Cost ~$0.005 USDC (scales with graph size).

Example:
    get_reputation_scores(nodes=3, edges=[[0,1,1.0],[1,2,0.5],[2,0,0.5]], damping=0.85)

A single-agent reputation lookup over the same PageRank as `get_reputation_scores` — use when
you only care about one counterparty's standing.

Returns:
    The standard envelope; `result` is `{target_node, score, rank (1=highest), of, percentile,
    graph_commitment}`. Cost ~$0.003 USDC.

Example:
    get_agent_trust(nodes=3, edges=[[0,1,1.0],[1,2,0.5],[2,0,0.5]], target_node=1)

Pass the graph and the `scores` (and optionally the `graph_commitment`) from a
`get_reputation_scores` result; confirms they are the correct PageRank of exactly that graph.

Returns:
    The standard envelope; `result` is `{valid: <bool>, max_abs_diff, [commitment_match]}`.
    Cost ~$0.002 USDC.

Example:
    verify_reputation(nodes=3, edges=[[0,1,1.0],[1,2,0.5],[2,0,0.5]], scores=[0.33,0.33,0.34])

Call this first to discover what's available and what each call costs before invoking.

Returns:
    A JSON array (string) of `{tool, capability_id, price_usd, summary}` — one entry per tool.

Example:
    list_oracle_capabilities()