How to make multicalls more type safe?

[cursedId0l]

const vestingSplitterABI = [
  {
    stateMutability: 'view',
    type: 'function',
    name: 'balanceOf',
    inputs: [{ name: 'user', type: 'address' }],
    outputs: [{ name: '', type: 'uint256' }],
  },
  {
    stateMutability: 'view',
    type: 'function',
    name: 'TOKEN',
    inputs: [],
    outputs: [{ name: '', type: 'address' }],
  },
] as const;

  const ownerAddress = getAddress(owner);
  const client = getEvmClient(NetworkId.ethereum);

  const multicallContracts = vestingSplitterContracts.flatMap<
    ContractFunctionConfig<typeof vestingSplitterABI>
  >((address) => [
    {
      address,
      abi: vestingSplitterABI,
      functionName: 'balanceOf',
      args: [ownerAddress],
    },
    {
      address,
      abi: vestingSplitterABI,
      functionName: 'TOKEN',
    },
  ]);

  const responses = await client.multicall({ contracts: multicallContracts });

  const numContracts = vestingSplitterContracts.length;

  for (let i = 0; i < numContracts; i++) {
    const balanceResp = responses[i * 2];
    const tokenResp = responses[i * 2 + 1];

    if (balanceResp.error || tokenResp.error) continue;

    const rawBalance = balanceResp.result as bigint;
    const token = getAddress(tokenResp.result as Address);
    
    // Do something here

  }

I find myself using this pattern all the time. The problem is that balanceResp.result and tokenResp.result both have the same type - result: bigint | 0x${string}. This makes sense considering the ABI, but is there a way I can make the types stricter such that typescript can infer balanceResp.result is of type bigint and tokenResp.result is of type Address

[christianalberto]

Hello @cursedId0l the issue you're running into happens because TypeScript collapses the types of all objects inside the multicallContracts array into a single broad union type when you construct the array using .flatMap().

When Viem receives a broad array type like (ContractFunctionConfig | ContractFunctionConfig)[], it infers the return type as a union of all possible result types (bigint | Address).

Here are two primary ways to fix this and get strict, automatic type inference for each response without resorting to as bigint or as Address type assertions.

Solution 1: Use as const Tuple Mapping (Recommended)
Instead of using .flatMap(), construct the contracts array as a const tuple or map over your contracts array using direct array expressions with as const. TypeScript will preserve the exact sequence and type of each individual call.

import { ContractFunctionParameters } from 'viem';

// Map each contract into a fixed 2-tuple, then flatten with .flat()
const multicallContracts = vestingSplitterContracts.flatMap((address) => [
  {
    address,
    abi: vestingSplitterABI,
    functionName: 'balanceOf',
    args: [ownerAddress],
  },
  {
    address,
    abi: vestingSplitterABI,
    functionName: 'TOKEN',
  },
] as const); // <-- Crucial: prevents type widening

const responses = await client.multicall({ 
  contracts: multicallContracts 
});

When Viem reads multicallContracts as a readonly tuple instead of ContractFunctionConfig[], TypeScript evaluates the returned array as a tuple of precise response types.

Solution 2: Group Calls Per Contract (Promise.all)
If you want strong types at compile time and cleaner array iteration, structure the multicall requests per contract address using Promise.all or a mapped tuple.

// Map over contracts to execute structured multicalls per item
const contractData = await Promise.all(
  vestingSplitterContracts.map(async (address) => {
    // Passing a fixed tuple of 2 elements allows Viem to return a fixed 2-tuple result
    const [balanceResp, tokenResp] = await client.multicall({
      contracts: [
        {
          address,
          abi: vestingSplitterABI,
          functionName: 'balanceOf',
          args: [ownerAddress],
        },
        {
          address,
          abi: vestingSplitterABI,
          functionName: 'TOKEN',
        },
      ] as const,
    });

    return { address, balanceResp, tokenResp };
  })
);

for (const { balanceResp, tokenResp } filter in contractData) {
  if (balanceResp.status === 'success' && tokenResp.status === 'success') {
    // TypeScript automatically infers:
    // balanceResp.result -> bigint
    // tokenResp.result   -> `0x${string}`
    const rawBalance = balanceResp.result; 
    const token = getAddress(tokenResp.result);
  }
}

Why this works
Broad Array Inference: Typing your array explicitly with flatMap<ContractFunctionConfig<...>> strips individual function signatures (balanceOf vs TOKEN) and turns contracts into Array<ConfigA ConfigB |>.

Tuple Preservation: By applying as const to the call array or passing inline arrays, TypeScript treats the contracts as [CallBalance, CallToken, CallBalance, CallToken, ...] as a fixed tuple. Viem's conditional types can then map input tuple elements directly to output tuple types.