Onchain.Block (onchain v0.5.4)

Ethereum block fetching and timestamp-based block search.

Provides parsed block data (native integers instead of hex strings) and a binary search algorithm for finding the block closest to a target timestamp.

Functions

Function	Purpose
`get_by_number/2`	Fetch and parse a block by number or tag
`get_by_number!/2`	Same, raises on error
`find_by_timestamp/2`	Binary search for block ≤ target timestamp
`find_by_timestamp!/2`	Same, raises on error

Return Shape

All functions return a plain map with native types:

%{number: 20_000_000, timestamp: 1_717_281_407, hash: "0xd24f..."}

Algorithm

find_by_timestamp/2 performs a binary search between a floor and ceiling block. It fetches the midpoint block, compares its timestamp to the target, and recurses into the appropriate half. Returns the highest block with timestamp <= target. Ported from blockwatch's BlockFromTimestamp.

API Functions

Function	Arity	Description	Param Kinds
`find_by_timestamp!`	2	Binary search for block ≤ target timestamp. Raises on error.	`target_timestamp: value`, `opts: value`
`find_by_timestamp`	2	Binary search for the highest block with timestamp ≤ target.	`target_timestamp: value`, `opts: value`
`get_by_number!`	2	Fetch and parse a block by number or tag. Raises on error.	`block_id: value`, `opts: value`
`get_by_number`	2	Fetch and parse a block by number or tag.	`block_id: value`, `opts: value`

Summary

Functions

find_by_timestamp(target_timestamp, opts \\ [])

Binary search for the highest block with timestamp ≤ target.

find_by_timestamp!(target_timestamp, opts \\ [])

Binary search for block ≤ target timestamp. Raises on error.

get_by_number(block_id, opts \\ [])

Fetch and parse a block by number or tag.

get_by_number!(block_id, opts \\ [])

Fetch and parse a block by number or tag. Raises on error.

Functions

find_by_timestamp(target_timestamp, opts \\ [])

@spec find_by_timestamp(
  non_neg_integer(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Binary search for the highest block with timestamp ≤ target.

Parameters

target_timestamp - Unix timestamp (seconds) to search for (value)
opts - Options: :rpc_url, :timeout, :floor (block number integer), :ceil (block number integer) (default: [], value)

Returns

Block with highest timestamp ≤ target ({:ok, map} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :floor (block number integer), :ceil (block number integer)",
      kind: :value
    },
    target_timestamp: %{
      description: "Unix timestamp (seconds) to search for",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, map} | {:error, term}",
    description: "Block with highest timestamp ≤ target",
    example: "%{number: 20_000_000, timestamp: 1_717_281_407, hash: \"0xd24f...\"}"
  }
}

find_by_timestamp!(target_timestamp, opts \\ [])

@spec find_by_timestamp!(
  non_neg_integer(),
  keyword()
) :: map()

Binary search for block ≤ target timestamp. Raises on error.

Parameters

target_timestamp - Unix timestamp (seconds) (value)
opts - Options: :rpc_url, :timeout, :floor, :ceil (default: [], value)

Returns

Parsed block map (map)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :floor, :ceil",
      kind: :value
    },
    target_timestamp: %{description: "Unix timestamp (seconds)", kind: :value}
  },
  returns: %{type: :map, description: "Parsed block map"}
}

get_by_number(block_id, opts \\ [])

@spec get_by_number(
  integer() | String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Fetch and parse a block by number or tag.

Parameters

block_id - Block number (integer) or tag string ("latest", "finalized", etc.) (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed block with native types ({:ok, map} | {:error, term})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    block_id: %{
      description: "Block number (integer) or tag string (\"latest\", \"finalized\", etc.)",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, map} | {:error, term}",
    description: "Parsed block with native types",
    example: "%{number: 20_000_000, timestamp: 1_717_281_407, hash: \"0xd24f...\"}"
  }
}

get_by_number!(block_id, opts \\ [])

@spec get_by_number!(
  integer() | String.t(),
  keyword()
) :: map()

Fetch and parse a block by number or tag. Raises on error.

Parameters

block_id - Block number (integer) or tag string (value)
opts - Options: :rpc_url, :timeout (default: [], value)

Returns

Parsed block map (map)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout",
      kind: :value
    },
    block_id: %{
      description: "Block number (integer) or tag string",
      kind: :value
    }
  },
  returns: %{type: :map, description: "Parsed block map"}
}