diff --git a/apps/block_scout_web/lib/block_scout_web/chain.ex b/apps/block_scout_web/lib/block_scout_web/chain.ex index 415b42cc1b..cebe723571 100644 --- a/apps/block_scout_web/lib/block_scout_web/chain.ex +++ b/apps/block_scout_web/lib/block_scout_web/chain.ex @@ -125,6 +125,10 @@ defmodule BlockScoutWeb.Chain do Map.put(next_page_params, "items_count", items_count) end + @doc """ + Makes Explorer.PagingOptions map. Overloaded by different params in the input map + for different modules using this function. + """ @spec paging_options(any) :: [{:paging_options, Explorer.PagingOptions.t()}, ...] | Explorer.PagingOptions.t() def paging_options(%{"hash" => hash_string, "fetched_coin_balance" => fetched_coin_balance_string}) diff --git a/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/transaction_controller.ex b/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/transaction_controller.ex index 635451c9bc..e8794f5842 100644 --- a/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/transaction_controller.ex +++ b/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/transaction_controller.ex @@ -63,7 +63,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do @api_true [api?: true] - @spec transaction(Plug.Conn.t(), map()) :: Plug.Conn.t() + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param` endpoint. + """ + @spec transaction(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def transaction(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do necessity_by_association = @transaction_necessity_by_association @@ -90,6 +93,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end + @doc """ + Function to handle GET requests to `/api/v2/transactions` endpoint. + """ @spec transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() def transactions(conn, params) do filter_options = filter_options(params, :validated) @@ -114,6 +120,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do |> render(:transactions, %{transactions: transactions, next_page_params: next_page_params}) end + @doc """ + Function to handle GET requests to `/api/v2/transactions/zkevm-batch/:batch_number` endpoint. + It renders the list of L2 transactions bound to the specified batch. + """ @spec zkevm_batch(Plug.Conn.t(), map()) :: Plug.Conn.t() def zkevm_batch(conn, %{"batch_number" => batch_number} = _params) do transactions = @@ -127,7 +137,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do |> render(:transactions, %{transactions: transactions}) end - @spec raw_trace(Plug.Conn.t(), map()) :: Plug.Conn.t() + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/raw-trace` endpoint. + """ + @spec raw_trace(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def raw_trace(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)}, {:not_found, {:ok, transaction}} <- @@ -157,6 +170,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/token-transfers` endpoint. + """ @spec token_transfers(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def token_transfers(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)}, @@ -190,6 +206,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/internal-transactions` endpoint. + """ @spec internal_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def internal_transactions(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)}, @@ -219,6 +238,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/logs` endpoint. + """ @spec logs(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def logs(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)}, @@ -255,6 +277,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end + @doc """ + Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/state-changes` endpoint. + """ @spec state_changes(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} def state_changes(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)}, @@ -282,7 +307,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do end end - @spec watchlist_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()} + @doc """ + Function to handle GET requests to `/api/v2/transactions/watchlist` endpoint. + """ + @spec watchlist_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {:auth, any()} def watchlist_transactions(conn, params) do with {:auth, %{watchlist_id: watchlist_id}} <- {:auth, current_user(conn)} do full_options = diff --git a/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/zkevm_controller.ex b/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/zkevm_controller.ex index 5aee41db88..a92589e029 100644 --- a/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/zkevm_controller.ex +++ b/apps/block_scout_web/lib/block_scout_web/controllers/api/v2/zkevm_controller.ex @@ -23,6 +23,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do :verify_transaction => :optional } + @doc """ + Function to handle GET requests to `/api/v2/zkevm/batches/:batch_number` endpoint. + """ @spec batch(Plug.Conn.t(), map()) :: Plug.Conn.t() def batch(conn, %{"batch_number" => batch_number} = _params) do {:ok, batch} = @@ -37,6 +40,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do |> render(:zkevm_batch, %{batch: batch}) end + @doc """ + Function to handle GET requests to `/api/v2/main-page/zkevm/batches/latest-number` endpoint. + """ @spec batch_latest_number(Plug.Conn.t(), map()) :: Plug.Conn.t() def batch_latest_number(conn, _params) do conn @@ -44,6 +50,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do |> render(:zkevm_batch_latest_number, %{number: batch_latest_number()}) end + @doc """ + Function to handle GET requests to `/api/v2/zkevm/batches` endpoint. + """ @spec batches(Plug.Conn.t(), map()) :: Plug.Conn.t() def batches(conn, params) do {batches, next_page} = @@ -64,6 +73,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do }) end + @doc """ + Function to handle GET requests to `/api/v2/zkevm/batches/count` endpoint. + """ @spec batches_count(Plug.Conn.t(), map()) :: Plug.Conn.t() def batches_count(conn, _params) do conn @@ -71,6 +83,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do |> render(:zkevm_batches_count, %{count: batch_latest_number()}) end + @doc """ + Function to handle GET requests to `/api/v2/main-page/zkevm/batches/confirmed` endpoint. + """ @spec batches_confirmed(Plug.Conn.t(), map()) :: Plug.Conn.t() def batches_confirmed(conn, _params) do batches = diff --git a/apps/block_scout_web/lib/block_scout_web/views/api/v2/zkevm_view.ex b/apps/block_scout_web/lib/block_scout_web/views/api/v2/zkevm_view.ex index db49265880..9a71ef647b 100644 --- a/apps/block_scout_web/lib/block_scout_web/views/api/v2/zkevm_view.ex +++ b/apps/block_scout_web/lib/block_scout_web/views/api/v2/zkevm_view.ex @@ -1,6 +1,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmView do use BlockScoutWeb, :view + @doc """ + Function to render GET requests to `/api/v2/zkevm/batches/:batch_number` endpoint. + """ @spec render(binary(), map()) :: map() | non_neg_integer() def render("zkevm_batch.json", %{batch: batch}) do sequence_tx_hash = @@ -26,6 +29,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmView do } end + @doc """ + Function to render GET requests to `/api/v2/zkevm/batches` endpoint. + """ def render("zkevm_batches.json", %{ batches: batches, next_page_params: next_page_params @@ -36,14 +42,23 @@ defmodule BlockScoutWeb.API.V2.ZkevmView do } end + @doc """ + Function to render GET requests to `/api/v2/main-page/zkevm/batches/confirmed` endpoint. + """ def render("zkevm_batches.json", %{batches: batches}) do %{items: render_zkevm_batches(batches)} end + @doc """ + Function to render GET requests to `/api/v2/zkevm/batches/count` endpoint. + """ def render("zkevm_batches_count.json", %{count: count}) do count end + @doc """ + Function to render GET requests to `/api/v2/main-page/zkevm/batches/latest-number` endpoint. + """ def render("zkevm_batch_latest_number.json", %{number: number}) do number end diff --git a/apps/explorer/lib/explorer/chain/zkevm/batch_transaction.ex b/apps/explorer/lib/explorer/chain/zkevm/batch_transaction.ex index 64993ad2bf..74f5fb9b9f 100644 --- a/apps/explorer/lib/explorer/chain/zkevm/batch_transaction.ex +++ b/apps/explorer/lib/explorer/chain/zkevm/batch_transaction.ex @@ -23,6 +23,9 @@ defmodule Explorer.Chain.Zkevm.BatchTransaction do timestamps() end + @doc """ + Validates that the `attrs` are valid. + """ @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t() def changeset(%__MODULE__{} = transactions, attrs \\ %{}) do transactions diff --git a/apps/explorer/lib/explorer/chain/zkevm/lifecycle_transaction.ex b/apps/explorer/lib/explorer/chain/zkevm/lifecycle_transaction.ex index 83ddcfa296..480b0c0c80 100644 --- a/apps/explorer/lib/explorer/chain/zkevm/lifecycle_transaction.ex +++ b/apps/explorer/lib/explorer/chain/zkevm/lifecycle_transaction.ex @@ -24,6 +24,9 @@ defmodule Explorer.Chain.Zkevm.LifecycleTransaction do timestamps() end + @doc """ + Validates that the `attrs` are valid. + """ @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t() def changeset(%__MODULE__{} = txn, attrs \\ %{}) do txn diff --git a/apps/explorer/lib/explorer/chain/zkevm/reader.ex b/apps/explorer/lib/explorer/chain/zkevm/reader.ex index 436ae787e8..49f69eaa0d 100644 --- a/apps/explorer/lib/explorer/chain/zkevm/reader.ex +++ b/apps/explorer/lib/explorer/chain/zkevm/reader.ex @@ -15,6 +15,11 @@ defmodule Explorer.Chain.Zkevm.Reader do alias Explorer.Chain.Zkevm.{BatchTransaction, LifecycleTransaction, TransactionBatch} alias Explorer.{Chain, PagingOptions, Repo} + @doc """ + Reads a batch by its number from database. + If the number is :latest, gets the latest batch from `zkevm_transaction_batches` table. + Returns {:error, :not_found} in case the batch is not found. + """ @spec batch(non_neg_integer() | :latest, list()) :: {:ok, map()} | {:error, :not_found} def batch(number, options \\ []) @@ -42,6 +47,10 @@ defmodule Explorer.Chain.Zkevm.Reader do end end + @doc """ + Reads a list of batches from `zkevm_transaction_batches` table. + """ + @spec batches(list()) :: list() def batches(options \\ []) do necessity_by_association = Keyword.get(options, :necessity_by_association, %{}) @@ -68,12 +77,21 @@ defmodule Explorer.Chain.Zkevm.Reader do select_repo(options).all(query) end + @doc """ + Reads a list of L2 transaction hashes from `zkevm_batch_l2_transactions` table. + """ + @spec batch_transactions(non_neg_integer(), list()) :: list() def batch_transactions(batch_number, options \\ []) do query = from(bts in BatchTransaction, where: bts.batch_number == ^batch_number) select_repo(options).all(query) end + @doc """ + Gets the number of the latest batch with defined verify_id from `zkevm_transaction_batches` table. + Returns 0 if not found. + """ + @spec last_verified_batch_number() :: non_neg_integer() def last_verified_batch_number do query = from(tb in TransactionBatch, @@ -88,6 +106,10 @@ defmodule Explorer.Chain.Zkevm.Reader do |> Kernel.||(0) end + @doc """ + Reads a list of L1 transactions by their hashes from `zkevm_lifecycle_l1_transactions` table. + """ + @spec lifecycle_transactions(list()) :: list() def lifecycle_transactions(l1_tx_hashes) do query = from( @@ -99,6 +121,10 @@ defmodule Explorer.Chain.Zkevm.Reader do Repo.all(query, timeout: :infinity) end + @doc """ + Determines ID of the future lifecycle transaction by reading `zkevm_lifecycle_l1_transactions` table. + """ + @spec next_id() :: non_neg_integer() def next_id do query = from(lt in LifecycleTransaction, diff --git a/apps/explorer/lib/explorer/chain/zkevm/transaction_batch.ex b/apps/explorer/lib/explorer/chain/zkevm/transaction_batch.ex index 1b4aa046dc..eda97e1d40 100644 --- a/apps/explorer/lib/explorer/chain/zkevm/transaction_batch.ex +++ b/apps/explorer/lib/explorer/chain/zkevm/transaction_batch.ex @@ -45,6 +45,9 @@ defmodule Explorer.Chain.Zkevm.TransactionBatch do timestamps() end + @doc """ + Validates that the `attrs` are valid. + """ @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t() def changeset(%__MODULE__{} = batches, attrs \\ %{}) do batches