Cartouche.RPC.DSL (Cartouche v0.5.0)

Copy Markdown View Source

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:

  1. the public function,
  2. its @spec (return type derived from :decode),
  3. its @doc (carrying the doctest), and
  4. the Descripex api/3 metadata block read by Cartouche.describe/2.

Two uniform shapes are covered, selected by whether :address_desc is given:

  • address-at-blockname(<<_::160>> = address, opts) -> send_rpc(method, [encode(address), block_number], decode: ...) (e.g. get_balance, get_code).
  • no-argname(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

defrpc(name, method, opts)

(macro)
@spec defrpc(atom(), String.t(), Keyword.t()) :: Macro.t()

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:

  • :decodesend_rpc/3 decode mode; also fixes the @spec return type (:hexbinary(), :hex_unsignednon_neg_integer()).
  • :summary — one-line Descripex description.
  • :returns_desc — Descripex description of the :ok return.
  • :doc — the @doc body (with doctest).

Shape selection / optional:

  • :address_desc — present ⇒ the address-at-block shape; its value is the Descripex description of the leading address param. Absent ⇒ no-arg shape.
  • :encode — address encoder for the address shape, :to_hex (default) or :big_hex. Ignored by the no-arg shape.