Merge pull request #43 from macalinao/igm/balance

Add helpers for ATA balance/token balance

Author: macalinao

.changeset/short-parrots-smash.md

@@ -0,0 +1,5 @@
+---
+"@macalinao/grill": patch
+---
+
+Add balance helpers

apps/example-dapp/src/components/layout/examples/index.tsx

@@ -4,6 +4,7 @@ import {
   Coins,
   Database,
   LayoutDashboard,
+  Wallet,
   Zap,
 } from "lucide-react";
 import type * as React from "react";
@@ -54,6 +55,11 @@ const exampleNavItems: ExampleNavItem[] = [
     href: "/examples/tokens",
     icon: Database,
   },
+  {
+    title: "Token Balances",
+    href: "/examples/token-balances",
+    icon: Wallet,
+  },
   {
     title: "Batch Accounts",
     href: "/examples/batch-accounts",

apps/example-dapp/src/routeTree.gen.ts

@@ -15,6 +15,7 @@ import { Route as ExamplesIndexRouteImport } from "./routes/examples/index.tsx"
 import { Route as ExamplesWrappedSolRouteImport } from "./routes/examples/wrapped-sol.tsx"
 import { Route as ExamplesTransferSolRouteImport } from "./routes/examples/transfer-sol.tsx"
 import { Route as ExamplesTokensRouteImport } from "./routes/examples/tokens.tsx"
+import { Route as ExamplesTokenBalancesRouteImport } from "./routes/examples/token-balances.tsx"
 import { Route as ExamplesDashboardRouteImport } from "./routes/examples/dashboard.tsx"
 import { Route as ExamplesBatchAccountsRouteImport } from "./routes/examples/batch-accounts.tsx"
 
@@ -48,6 +49,11 @@ const ExamplesTokensRoute = ExamplesTokensRouteImport.update({
   path: "/tokens",
   getParentRoute: () => ExamplesRoute,
 } as any)
+const ExamplesTokenBalancesRoute = ExamplesTokenBalancesRouteImport.update({
+  id: "/token-balances",
+  path: "/token-balances",
+  getParentRoute: () => ExamplesRoute,
+} as any)
 const ExamplesDashboardRoute = ExamplesDashboardRouteImport.update({
   id: "/dashboard",
   path: "/dashboard",
@@ -64,6 +70,7 @@ export interface FileRoutesByFullPath {
   "/examples": typeof ExamplesRouteWithChildren
   "/examples/batch-accounts": typeof ExamplesBatchAccountsRoute
   "/examples/dashboard": typeof ExamplesDashboardRoute
+  "/examples/token-balances": typeof ExamplesTokenBalancesRoute
   "/examples/tokens": typeof ExamplesTokensRoute
   "/examples/transfer-sol": typeof ExamplesTransferSolRoute
   "/examples/wrapped-sol": typeof ExamplesWrappedSolRoute
@@ -73,6 +80,7 @@ export interface FileRoutesByTo {
   "/": typeof IndexRoute
   "/examples/batch-accounts": typeof ExamplesBatchAccountsRoute
   "/examples/dashboard": typeof ExamplesDashboardRoute
+  "/examples/token-balances": typeof ExamplesTokenBalancesRoute
   "/examples/tokens": typeof ExamplesTokensRoute
   "/examples/transfer-sol": typeof ExamplesTransferSolRoute
   "/examples/wrapped-sol": typeof ExamplesWrappedSolRoute
@@ -84,6 +92,7 @@ export interface FileRoutesById {
   "/examples": typeof ExamplesRouteWithChildren
   "/examples/batch-accounts": typeof ExamplesBatchAccountsRoute
   "/examples/dashboard": typeof ExamplesDashboardRoute
+  "/examples/token-balances": typeof ExamplesTokenBalancesRoute
   "/examples/tokens": typeof ExamplesTokensRoute
   "/examples/transfer-sol": typeof ExamplesTransferSolRoute
   "/examples/wrapped-sol": typeof ExamplesWrappedSolRoute
@@ -96,6 +105,7 @@ export interface FileRouteTypes {
     | "/examples"
     | "/examples/batch-accounts"
     | "/examples/dashboard"
+    | "/examples/token-balances"
     | "/examples/tokens"
     | "/examples/transfer-sol"
     | "/examples/wrapped-sol"
@@ -105,6 +115,7 @@ export interface FileRouteTypes {
     | "/"
     | "/examples/batch-accounts"
     | "/examples/dashboard"
+    | "/examples/token-balances"
     | "/examples/tokens"
     | "/examples/transfer-sol"
     | "/examples/wrapped-sol"
@@ -115,6 +126,7 @@ export interface FileRouteTypes {
     | "/examples"
     | "/examples/batch-accounts"
     | "/examples/dashboard"
+    | "/examples/token-balances"
     | "/examples/tokens"
     | "/examples/transfer-sol"
     | "/examples/wrapped-sol"
@@ -170,6 +182,13 @@ declare module "@tanstack/react-router" {
       preLoaderRoute: typeof ExamplesTokensRouteImport
       parentRoute: typeof ExamplesRoute
     }
+    "/examples/token-balances": {
+      id: "/examples/token-balances"
+      path: "/token-balances"
+      fullPath: "/examples/token-balances"
+      preLoaderRoute: typeof ExamplesTokenBalancesRouteImport
+      parentRoute: typeof ExamplesRoute
+    }
     "/examples/dashboard": {
       id: "/examples/dashboard"
       path: "/dashboard"
@@ -190,6 +209,7 @@ declare module "@tanstack/react-router" {
 interface ExamplesRouteChildren {
   ExamplesBatchAccountsRoute: typeof ExamplesBatchAccountsRoute
   ExamplesDashboardRoute: typeof ExamplesDashboardRoute
+  ExamplesTokenBalancesRoute: typeof ExamplesTokenBalancesRoute
   ExamplesTokensRoute: typeof ExamplesTokensRoute
   ExamplesTransferSolRoute: typeof ExamplesTransferSolRoute
   ExamplesWrappedSolRoute: typeof ExamplesWrappedSolRoute
@@ -199,6 +219,7 @@ interface ExamplesRouteChildren {
 const ExamplesRouteChildren: ExamplesRouteChildren = {
   ExamplesBatchAccountsRoute: ExamplesBatchAccountsRoute,
   ExamplesDashboardRoute: ExamplesDashboardRoute,
+  ExamplesTokenBalancesRoute: ExamplesTokenBalancesRoute,
   ExamplesTokensRoute: ExamplesTokensRoute,
   ExamplesTransferSolRoute: ExamplesTransferSolRoute,
   ExamplesWrappedSolRoute: ExamplesWrappedSolRoute,

apps/example-dapp/src/routes/examples/token-balances.tsx

@@ -0,0 +1,136 @@
+import { useATABalance } from "@macalinao/grill";
+import { formatTokenAmount } from "@macalinao/token-utils";
+import { address } from "@solana/kit";
+import { useWallet } from "@solana/wallet-adapter-react";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/examples/token-balances")({
+  component: TokenBalances,
+});
+
+// Common token mints on mainnet
+const TOKENS = [
+  {
+    symbol: "USDC",
+    mint: address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
+    name: "USD Coin",
+  },
+  {
+    symbol: "JUP",
+    mint: address("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"),
+    name: "Jupiter",
+  },
+  {
+    symbol: "BONK",
+    mint: address("DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"),
+    name: "Bonk",
+  },
+  {
+    symbol: "WIF",
+    mint: address("EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm"),
+    name: "dogwifhat",
+  },
+  {
+    symbol: "PYTH",
+    mint: address("HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3"),
+    name: "Pyth Network",
+  },
+  {
+    symbol: "RENDER",
+    mint: address("rndrizKT3MK1iimdxRdWabcF7Zg7AR5T4nud4EkHBof"),
+    name: "Render Token",
+  },
+];
+
+function TokenBalanceRow({
+  token,
+  owner,
+}: {
+  token: (typeof TOKENS)[0];
+  owner: ReturnType<typeof address> | undefined;
+}) {
+  const balance = useATABalance({
+    mint: token.mint,
+    owner,
+  });
+
+  return (
+    <tr className="border-b">
+      <td className="px-4 py-2 font-medium">{token.symbol}</td>
+      <td className="px-4 py-2 text-sm text-gray-600">{token.name}</td>
+      <td className="px-4 py-2 text-right font-mono">
+        {balance ? formatTokenAmount(balance) : "0"}
+      </td>
+    </tr>
+  );
+}
+
+function TokenBalances() {
+  const { publicKey } = useWallet();
+  const owner = publicKey ? address(publicKey.toBase58()) : undefined;
+
+  return (
+    <div className="container mx-auto p-6">
+      <h1 className="text-3xl font-bold mb-6">Token Balances</h1>
+
+      {!owner ? (
+        <div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
+          <p className="text-yellow-800">
+            Please connect your wallet to view token balances.
+          </p>
+        </div>
+      ) : (
+        <>
+          <div className="mb-4">
+            <p className="text-sm text-gray-600">
+              Wallet: <span className="font-mono">{owner}</span>
+            </p>
+          </div>
+
+          <div className="bg-white rounded-lg shadow overflow-hidden">
+            <table className="w-full">
+              <thead className="bg-gray-50">
+                <tr>
+                  <th className="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
+                    Token
+                  </th>
+                  <th className="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
+                    Name
+                  </th>
+                  <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
+                    Balance
+                  </th>
+                </tr>
+              </thead>
+              <tbody className="bg-white divide-y divide-gray-200">
+                {TOKENS.map((token) => (
+                  <TokenBalanceRow
+                    key={token.mint}
+                    token={token}
+                    owner={owner}
+                  />
+                ))}
+              </tbody>
+            </table>
+          </div>
+
+          <div className="mt-6 text-sm text-gray-500">
+            <p>
+              This example demonstrates the <code>useATABalance</code> hook
+              which fetches token balances for Associated Token Accounts.
+            </p>
+            <p className="mt-2">
+              The hook automatically handles:
+              <ul className="list-disc list-inside mt-1 ml-4">
+                <li>Computing the ATA address for each token</li>
+                <li>Fetching token metadata and decimals</li>
+                <li>Returning zero balance if the ATA doesn't exist</li>
+                <li>Formatting the balance with proper decimal places</li>
+              </ul>
+            </p>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.2.2/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

packages/grill/src/hooks/index.ts

@@ -5,10 +5,12 @@ export * from "./use-account.js";
 export * from "./use-accounts.js";
 export * from "./use-associated-token-account.js";
 export * from "./use-associated-token-pda.js";
+export * from "./use-ata-balance.js";
 export { useConnectedWallet } from "./use-connected-wallet.js";
 export { useKitWallet } from "./use-kit-wallet.js";
 export * from "./use-mint-account.js";
 export * from "./use-send-tx.js";
 export * from "./use-token-account.js";
+export * from "./use-token-balance.js";
 export * from "./use-token-info.js";
 export * from "./use-token-metadata-account.js";

packages/grill/src/hooks/use-ata-balance.ts

@@ -0,0 +1,61 @@
+import type { TokenAmount } from "@macalinao/token-utils";
+import { createTokenAmount } from "@macalinao/token-utils";
+import type { Address } from "@solana/kit";
+import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { useMemo } from "react";
+import { useAssociatedTokenAccount } from "./use-associated-token-account.js";
+import { useTokenInfo } from "./use-token-info.js";
+
+export interface UseATABalanceOptions {
+  /** The mint address of the token */
+  mint: Address | null | undefined;
+  /** The owner address of the token account */
+  owner: Address | null | undefined;
+  /** The token program address (defaults to TOKEN_PROGRAM_ADDRESS) */
+  tokenProgram?: Address;
+}
+
+/**
+ * Hook that fetches an Associated Token Account balance as a TokenAmount.
+ * This combines useAssociatedTokenAccount and useTokenInfo to provide the complete balance information.
+ *
+ * @example
+ * ```typescript
+ * const balance = useATABalance({
+ *   mint: mintAddress,
+ *   owner: walletAddress,
+ * });
+ *
+ * if (balance) {
+ *   console.log("Balance:", formatTokenAmount(balance));
+ * }
+ * ```
+ */
+export function useATABalance(
+  options: UseATABalanceOptions,
+): TokenAmount | null {
+  const { mint, owner, tokenProgram = TOKEN_PROGRAM_ADDRESS } = options;
+
+  // Fetch the ATA and its data
+  const { data: ataAccount } = useAssociatedTokenAccount({
+    mint,
+    owner,
+    tokenProgram,
+  });
+
+  // Fetch the token info
+  const { data: tokenInfo } = useTokenInfo({ mint });
+
+  return useMemo(() => {
+    if (!tokenInfo) {
+      return null;
+    }
+
+    // If ATA doesn't exist, return zero balance
+    if (!ataAccount) {
+      return createTokenAmount(tokenInfo, 0n);
+    }
+
+    return createTokenAmount(tokenInfo, ataAccount.data.amount);
+  }, [ataAccount, tokenInfo]);
+}

packages/grill/src/hooks/use-token-balance.ts

@@ -0,0 +1,51 @@
+import type { TokenAmount } from "@macalinao/token-utils";
+import { createTokenAmount } from "@macalinao/token-utils";
+import type { Address } from "@solana/kit";
+import { useMemo } from "react";
+import { useTokenAccount } from "./use-token-account.js";
+import { useTokenInfo } from "./use-token-info.js";
+
+export interface UseTokenBalanceOptions {
+  /** The address of the token account */
+  address: Address | null | undefined;
+  /** The mint address of the token (optional, will be fetched from token account) */
+  mint?: Address | null | undefined;
+}
+
+/**
+ * Hook that fetches a token account and its token info to return a TokenAmount.
+ * This combines useTokenAccount and useTokenInfo to provide the complete balance information.
+ *
+ * @example
+ * ```typescript
+ * const balance = useTokenBalance({
+ *   address: tokenAccountAddress,
+ * });
+ *
+ * if (balance) {
+ *   console.log("Balance:", formatTokenAmount(balance));
+ * }
+ * ```
+ */
+export function useTokenBalance(
+  options: UseTokenBalanceOptions,
+): TokenAmount | null {
+  const { address, mint: providedMint } = options;
+
+  // Fetch the token account data
+  const { data: tokenAccount } = useTokenAccount({ address });
+
+  // Use provided mint or get it from the token account
+  const mint = providedMint ?? tokenAccount?.data.mint;
+
+  // Fetch the token info
+  const { data: tokenInfo } = useTokenInfo({ mint });
+
+  return useMemo(() => {
+    if (!(tokenAccount && tokenInfo)) {
+      return null;
+    }
+
+    return createTokenAmount(tokenInfo, tokenAccount.data.amount);
+  }, [tokenAccount, tokenInfo]);
+}