core: add option to override blockIdentifier in useBalance (#429)

## Context

Now that the chain produces less blocks, it helps to request the balance
for pending blocks.

## Changes in this Pull Request

Add option to specify the `blockIdentifier`.

## Test Plan

.changeset/rich-elephants-marry.md

@@ -0,0 +1,5 @@
+---
+"@starknet-react/core": patch
+---
+
+Add option to useBalance to override block identifier

packages/core/src/hooks/useBalance.ts

@@ -1,6 +1,8 @@
 import { Chain } from "@starknet-react/chains";
 import { useMemo } from "react";
 import {
+  BlockNumber,
+  BlockTag,
   CallData,
   ContractInterface,
   num,
@@ -15,6 +17,8 @@ import { useContract } from "./useContract";
 import { useInvalidateOnBlock } from "./useInvalidateOnBlock";
 import { useNetwork } from "./useNetwork";
 
+const DEFAULT_FETCH_INTERVAL = 5_000;
+
 export type Balance = {
   decimals: number;
   symbol: string;
@@ -34,13 +38,17 @@ export type UseBalanceProps = UseQueryProps<
   address?: string;
   /** Whether to watch for changes. */
   watch?: boolean;
+  /** Block identifier used when performing call. */
+  blockIdentifier?: BlockNumber;
 };
 
 export type UseBalanceResult = UseQueryResult<Balance, Error>;
 
 export function useBalance({
   token,
   address,
+  blockIdentifier = BlockTag.latest,
+  refetchInterval: refetchInterval_,
   watch = false,
   enabled: enabled_ = true,
   ...props
@@ -52,23 +60,30 @@ export function useBalance({
   });
 
   const queryKey_ = useMemo(
-    () => queryKey({ chain, contract, token, address }),
-    [chain, contract, token, address],
+    () => queryKey({ chain, contract, token, address, blockIdentifier }),
+    [chain, contract, token, address, blockIdentifier],
   );
 
   const enabled = useMemo(
     () => Boolean(enabled_ && contract && address),
     [enabled_, contract, address],
   );
 
+  const refetchInterval =
+    refetchInterval_ ??
+    (blockIdentifier === BlockTag.pending && watch
+      ? DEFAULT_FETCH_INTERVAL
+      : undefined);
+
   useInvalidateOnBlock({
     enabled: Boolean(enabled && watch),
     queryKey: queryKey_,
   });
 
   return useQuery({
     queryKey: queryKey_,
-    queryFn: queryFn({ chain, contract, token, address }),
+    queryFn: queryFn({ chain, contract, token, address, blockIdentifier }),
+    refetchInterval,
     ...props,
   });
 }
@@ -78,11 +93,13 @@ function queryKey({
   contract,
   token,
   address,
+  blockIdentifier,
 }: {
   chain: Chain;
   contract?: ContractInterface;
   token?: string;
   address?: string;
+  blockIdentifier?: BlockNumber;
 }) {
   return [
     {
@@ -91,6 +108,7 @@ function queryKey({
       contract,
       token,
       address,
+      blockIdentifier,
     },
   ] as const;
 }
@@ -100,33 +118,39 @@ function queryFn({
   token,
   address,
   contract,
+  blockIdentifier,
 }: {
   chain: Chain;
   token?: string;
   address?: string;
   contract?: ContractInterface;
+  blockIdentifier?: BlockNumber;
 }) {
   return async function () {
     if (!address) throw new Error("address is required");
     if (!contract) throw new Error("contract is required");
 
+    const callArgs = { blockIdentifier };
+
     let symbolPromise = Promise.resolve(chain.nativeCurrency.symbol);
     if (token) {
-      symbolPromise = contract.call("symbol", []).then((result) => {
+      symbolPromise = contract.call("symbol", [], callArgs).then((result) => {
         const s = symbolSchema.parse(result).symbol;
         return shortString.decodeShortString(num.toHex(s));
       });
     }
 
     let decimalsPromise = Promise.resolve(chain.nativeCurrency.decimals);
     if (token) {
-      decimalsPromise = contract.call("decimals", []).then((result) => {
-        return Number(decimalsSchema.parse(result).decimals);
-      });
+      decimalsPromise = contract
+        .call("decimals", [], callArgs)
+        .then((result) => {
+          return Number(decimalsSchema.parse(result).decimals);
+        });
     }
 
     const balanceOfPromise = contract
-      .call("balanceOf", CallData.compile({ address }))
+      .call("balanceOf", CallData.compile({ address }), callArgs)
       .then((result) => {
         return uint256.uint256ToBN(balanceSchema.parse(result).balance);
       });

website/components/demos/balance.tsx

@@ -1,6 +1,7 @@
 "use client";
 import React from "react";
 
+import { BlockTag } from "starknet";
 import { useBalance, useNetwork } from "@starknet-react/core";
 import { AlertCircle } from "lucide-react";
 import { useState } from "react";
@@ -20,6 +21,7 @@ function TokenBalance() {
   const { data, error, isLoading } = useBalance({
     address,
     watch: false,
+    blockIdentifier: BlockTag.pending,
   });
 
   return (