Compile-time DSL for the uniform thin JSON-RPC wrappers in Cartouche.RPC.
defrpc/3 generates, from one declaration, the four artifacts these
wrappers otherwise hand-maintain in lockstep:
- the public function,
- its
@spec(return type derived from:decode), - its
@doc(carrying the doctest), and - the Descripex
api/3metadata block read byCartouche.describe/2.
Two uniform shapes are covered, selected by whether :address_desc is given:
- address-at-block —
name(<<_::160>> = address, opts) -> send_rpc(method, [encode(address), block_number], decode: ...)(e.g.get_balance,get_code). - no-arg —
name(opts) -> send_rpc(method, [], decode: ...)(e.g.eth_chain_id,gas_price).
Only the genuinely uniform shapes are covered. Wrappers with extra guards,
struct dispatch, multi-clause normalization, or per-method prose deviations
(e.g. get_nonce, whose param name, encoder, and opts description all differ)
stay hand-written — folding them in would grow more knobs than the
duplication it removes.
Prototype for ROADMAP Task 110 (defrpc), proving the api() introspection
stays byte-identical across the conversion.
Summary
Functions
Define a uniform thin JSON-RPC wrapper.
Functions
Define a uniform thin JSON-RPC wrapper.
name is the generated function (and api/3) name; method is the JSON-RPC
method string. Required opts:
:decode—send_rpc/3decode mode; also fixes the@specreturn type (:hex→binary(),:hex_unsigned→non_neg_integer()).:summary— one-line Descripex description.:returns_desc— Descripex description of the:okreturn.:doc— the@docbody (with doctest).
Shape selection / optional:
:address_desc— present ⇒ the address-at-block shape; its value is the Descripex description of the leadingaddressparam. Absent ⇒ no-arg shape.:encode— address encoder for the address shape,:to_hex(default) or:big_hex. Ignored by the no-arg shape.