Developer Guides

Token balances and fees

Why wallets show a placeholder balance on NVNM Chain, how fees are paid in nUSD, and how to read balances and send TIP-20 transfers from your dApp.

NVNM Chain NEXT is an L1 with no native gas token. You pay fees in a USD-denominated TIP-20 stablecoin, and on NVNM Chain the default fee token is nUSD. This guide explains what that means for balances, how the fee mechanism works, and how to read and transfer nUSD from a dApp.

Try it in the demo dApp

Open the NVNM demo dApp and use the Send nUSD card to see your nUSD balance and send a transfer. The TypeScript samples on this page come from the demo dApp's source (NVNM-Chain/nvnm-demo-dapp on GitHub).

Before you start:

  1. Add the network to your wallet. Enter the values from Network details, or open the NVNM demo dApp and connect your wallet. The dApp prompts your wallet to add the chain.
  2. Get nUSD from the faucet for Testnet or Devnet.

There is no native token

NVNM Chain has no native gas token. There is no ETH-like coin, and every amount you care about lives in a TIP-20 token.

Why your wallet shows a huge balance

Wallets still assume every chain has a native coin. To show it, they call the eth_getBalance RPC method and read the hex result as an 18-decimal number.

NVNM Chain has no native balance to report, so eth_getBalance returns a fixed, very large placeholder instead: 0x9612084f0316e0ebd5182f398e5195a51b5ca47667d4c9b26c9b26c9b26c9b2. In decimal, that is 4.242424242424242e+75.

That placeholder is why wallets show a number such as 4,242,424,2… next to nUSD:

Wallet asset list showing a balance of 4,242,424,2… next to nUSD on NVNM Devnet 1 and NVNM Testnet 1

This is not your balance

The number is a placeholder, not money you can spend. NVNM Chain has no native gas token, so the wallet has no real native balance to show. The symbol next to it (USD or nUSD) comes from the network settings in your wallet. Your real balance is your nUSD TIP-20 balance.

You can see the placeholder yourself. Any address returns the same value:

curl -s -X POST -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x000000000000000000000000000000000000dEaD","latest"]}' \
  https://rpc.nvnm.testnet.nvnmchain.io
# {"jsonrpc":"2.0","id":1,"result":"0x9612084f0316e0ebd5182f398e5195a51b5ca47667d4c9b26c9b26c9b26c9b2"}

The placeholder keeps wallets that are built around a native balance working. Without it, a wallet that checks the native balance before it sends a transaction could block the user with an error such as Insufficient balance. The curl call above queries the NVNM Chain Testnet RPC.

What we recommend

  • Don't check or show a native balance. If your app checks eth_getBalance, remove that check. Don't show any "native balance" in your UI.
  • Check the fee token balance instead. To confirm that a user can pay, read their fee token balance (nUSD by default) with TIP-20 balanceOf, not eth_getBalance.
  • Treat the currency symbol as cosmetic. Wallets ask for one when you add the network. USD and nUSD both work.

Inside NVNM Chain's EVM, native balances are always zero:

FeatureNVNM Chain behaviorWhat to do instead
BALANCE and SELFBALANCEAlways returns 0Read the token's TIP-20 balanceOf
CALLVALUEAlways returns 0Nothing replaces it. Contracts never receive a native value, so don't rely on msg.value

Add the network to a wallet

The demo dApp's chain config uses nUSD's 6 decimals as nativeCurrency (see Display the nUSD balance). MetaMask, however, rejects wallet_addEthereumChain unless nativeCurrency.decimals is 18. The demo dApp keeps a separate wallet-facing currency for that case:

apps/web/src/config/chains.ts
// The native currency as wallets are told it when a network is added. It only describes the chain to
// the wallet; amounts are always read from the 6-decimal TIP-20 token.
export const walletNativeCurrency = { name: nUSD.name, symbol: nUSD.symbol, decimals: 18 } as const;

View on GitHub: apps/web/src/config/chains.ts

The demo dApp and the wallet setup guides for Testnet and Devnet use nUSD, to match NVNM Chain's fee token name. Either way, the label is cosmetic.

Pass it when you switch networks. This excerpt is from the network picker. switchChain comes from wagmi's useSwitchChain, and c is the chain the user clicked, one of the chains from wagmi's useChains:

apps/web/src/components/account-dialog.tsx
// ...
const switchChain = useSwitchChain();
// ...
switchChain.mutate({
  chainId: c.id,
  addEthereumChainParameter: { nativeCurrency: walletNativeCurrency },
});
// ...

View on GitHub: apps/web/src/components/account-dialog.tsx

The wallet then labels the placeholder from eth_getBalance as nUSD. Always read amounts from the TIP-20 token.

How fees work

Because NVNM Chain has no native token, you pay every transaction fee in a stablecoin. That covers both the gas fee and the priority fee. A stablecoin can pay fees only if it meets three conditions: it is denominated in USD, it is a native TIP-20 token, and the Fee AMM holds enough liquidity for it.

On NVNM Chain, the default fee token is nUSD, a TIP-20 at 0x20C0000000000000000000000000000000000000 with 6 decimals. The demo dApp calls it "the default fee token". Your nUSD balance covers both what you send and the fee.

Note

SDK and library examples may use other token names, such as pathUSD, USDG or AlphaUSD. On NVNM Chain, use nUSD at 0x20C0000000000000000000000000000000000000. It is the same token at the same address on Testnet and Devnet.

Fee units

NVNM Chain uses a dynamic base fee with an upper cap. The base fee can decrease while blocks stay under their gas target, and it increases again, up to the cap, as demand grows. The validator who proposes a block receives all of its fees.

Fees are priced in attodollars (10^-18 USD) per gas. This unit applies to the max_base_fee_per_gas and max_fee_per_gas transaction fields, and to the block's base_fee_per_gas field. TIP-20 tokens have 6 decimals, so one token base unit is one microdollar (10^-6 USD). To get a transaction's fee in token base units, compute ceil(base_fee * gas_used / 10^12).

Creating state costs more than on Ethereum. Budget about 300k gas when you send tokens to an address that has never held a balance. Expect contract deployments to cost 5-10x the gas they would on Ethereum. Set your gas limits with that in mind.

Which token pays the fee

NVNM Chain picks the fee token for each transaction by checking five levels, in this order:

  1. Transaction: the fee_token field of NVNM Chain's native transaction type (0x76). It takes precedence over any account, contract or validator preference.
  2. Account: a default the fee payer sets by calling setUserToken on the FeeManager precompile (0xfeec000000000000000000000000000000000000).
  3. TIP-20 contract: if the top-level call is transfer, transferWithMemo or startReward on a USD TIP-20 token, that token pays the fee. A batched 0x76 transaction qualifies only when every top-level call targets that same TIP-20 token with one of these functions and the sender pays its own fee.
  4. Stablecoin DEX: for certain swap calls, the tokenIn argument pays the fee.
  5. nUSD: the fallback, the predeployed TIP-20 at 0x20C0000000000000000000000000000000000000. SDK examples may call this fallback token pathUSD.

Only the first level that names a token counts. The chain then rejects the transaction as invalid unless the token is a USD TIP-20, the fee payer's balance covers the gas limit times the gas price, and the Fee AMM has the liquidity to convert it.

In practice:

  • A nUSD transfer pays its fee in nUSD through the TIP-20 contract rule.
  • A call to any other contract, such as your own smart contract, uses the fallback unless the transaction sets fee_token or the fee payer has set an account fee token with setUserToken. The demo dApp sets neither. Its chain config notes that, unset, "the chain charges nUSD."

The full amount reaches the recipient

When you transfer the token that also pays the fee, the recipient gets the full amount. The fee comes out of your remaining balance, on top of the amount you send. So keep a little nUSD back for the fee.

Fee lifecycle

The FeeManager precompile collects and settles every fee:

Submit the transaction

You send the transaction. Its fee token is the one the preference order above selects.

Reserve the maximum fee

Before anything runs, the FeeManager confirms that your fee token balance is high enough and, when a conversion is needed, that the Fee AMM has liquidity for it. If either check fails, the chain rejects the transaction without running it. Otherwise, the FeeManager takes the maximum fee, gas_limit * gas_price, up front.

Run the transaction

Execution proceeds as usual. The transaction can finish with gas to spare.

Refund unused gas

After execution, the FeeManager works out the real fee from the gas used. It returns the difference, (gas_limit - gas_used) * gas_price, to the fee payer.

Convert and settle the fee

When your fee token and the validator's preferred token are the same, the fee needs no conversion. When they differ, the Fee AMM converts it at a fixed rate of 0.9970: for each 1.0 of your token, the validator gets 0.9970 of theirs. The FeeManager holds the collected fees until validators claim them with distributeFees().

The Fee AMM is a protocol-run market for converting fees between stablecoins. When your fee token differs from the validator's, it swaps the fee at a fixed rate. You can't trade on it directly. Only fee conversions and the arbitrage trades that rebalance its pools use its liquidity. Liquidity providers earn the 0.3% difference.

Choosing a fee token and sponsoring fees

You have these options for fee setup:

GoalHow to do it
Choose the fee token for one transactionPass feeToken
Set an account's persistent default fee tokenCall setUserToken on the FeeManager
Have another account pay the feePass the account as feePayer

Fee sponsorship uses the fee_payer_signature field of 0x76 transactions. The sender signs with the fee token field left empty, so the fee payer chooses the fee token. A transaction with no fee_payer_signature has the sender pay its own fee. Contracts have no way to pick the fee token. You choose it when you build and sign the transaction, usually through your SDK's feeToken option.

Browser wallets and feeToken

The demo dApp leaves feeToken unset on purpose. Its chain config explains: "A fee token in a request makes viem send browser wallets a 0x76 transaction, which MetaMask can't sign." Leave feeToken unset when your users sign with MetaMask or similar wallets. The demo dApp doesn't use setUserToken or fee sponsorship.

TIP-20 basics

TIP-20 is the chain's token standard. Each TIP-20 token runs as a precompile, an optimized token implementation built into the core protocol, rather than as deployed contract code. It supports the ERC-20 interface and adds features ERC-20 lacks, such as transfer memos and transfer policies. Only TIP-20 tokens can pay fees, and only those whose currency is "USD".

You need these functions to show balances and send tokens:

FunctionNotes
balanceOf(address account) returns (uint256)The account's balance in base units
decimals() returns (uint8)Always returns 6 for TIP-20 tokens
transfer(address to, uint256 amount) returns (bool)Same as ERC-20
transferWithMemo(address to, uint256 amount, bytes32 memo)Like transfer, plus a fixed 32-byte memo emitted in a dedicated event

Note

TIP-20 tokens reject some recipients. A transfer to the zero address or to any TIP-20 token address (prefix 0x20c000000000000000000000) reverts with InvalidRecipient. That includes nUSD's own address.

Display the nUSD balance

The demo dApp never reads eth_getBalance. It reads nUSD's balanceOf and formats it with 6 decimals.

Define the fee token

Keep nUSD's address, symbol and decimals in one place. Later in the same file, each chain definition sets nativeCurrency: nUSD, so the chain's native currency also has 6 decimals.

apps/web/src/config/chains.ts
// The default fee token: a TIP-20 precompile, read and transferred like an ERC-20 (see `src/lib/tip20.ts`).
export const nUSD = {
  name: "NVNM USD",
  symbol: "nUSD",
  decimals: 6,
  address: "0x20C0000000000000000000000000000000000000",
} as const;

View on GitHub: apps/web/src/config/chains.ts

Declare a minimal TIP-20 ABI

TIP-20 is ERC-20 compatible for these calls. The two revert errors let viem decode a failed transfer.

apps/web/src/lib/tip20.ts
import { parseAbi } from "viem";

// TIP-20 tokens are ERC-20 compatible for these calls. The functions mirror the faucet's `lib/tip20.ts`
// (https://github.com/NVNM-Chain/nvnm-tempo-devnet-faucet). Token metadata lives in `src/config/chains.ts`.
export const tip20Abi = parseAbi([
  "function transfer(address to, uint256 amount) returns (bool)",
  "function balanceOf(address account) view returns (uint256)",
  // How a transfer reverts. Declared so viem decodes the revert data when a wallet passes on only that, not the node's
  // message; `src/lib/wallet-errors.ts` maps both by name.
  "error InsufficientBalance(uint256 available, uint256 required, address token)",
  "error InvalidRecipient()",
]);

View on GitHub: apps/web/src/lib/tip20.ts

Read the balance

Call balanceOf with wagmi's useReadContract. The hook polls every 4 seconds so faucet top-ups and incoming transfers show up.

apps/web/src/hooks/use-nusd-balance.ts
import type { Address } from "viem";
import { useReadContract } from "wagmi";

import { nUSD } from "@/config/chains";
import type { SupportedChainId } from "@/config/wagmi";
import { tip20Abi } from "@/lib/tip20";

// The account's spendable nUSD, in base units. `eth_getBalance` is a placeholder on NVNM Chain; the balance that pays for
// transfers and fees is the TIP-20 fee token's. Every caller passes the same query options, so wagmi runs one query
// per account and chain however many components show the balance. Render the result with `<NusdAmount>`.
export function useNusdBalance(account: Address, chainId: SupportedChainId) {
  return useReadContract({
    address: nUSD.address,
    abi: tip20Abi,
    functionName: "balanceOf",
    args: [account],
    chainId,
    // Poll (rather than `watch`) so faucet top-ups and incoming transfers show up; see network-status.tsx.
    query: { refetchInterval: 4_000, retry: 1 },
  });
}

View on GitHub: apps/web/src/hooks/use-nusd-balance.ts

Parse and format amounts

Always use the token's 6 decimals, never 18. parseTokenAmount rejects extra decimals instead of rounding, so you never send a different amount than the user typed.

apps/web/src/lib/token-amount.ts
import { formatUnits, parseUnits } from "viem";

const DECIMAL = /^(\d+\.?\d*|\.\d+)$/;

export type ParsedAmount = { value: bigint } | { error: string };

// Parse user input into base units. Rejects rather than rounds extra decimals: viem's `parseUnits` rounds,
// which would send an amount other than the one typed.
export function parseTokenAmount(input: string, decimals: number): ParsedAmount {
  const text = input.trim();
  if (!DECIMAL.test(text)) return { error: "Enter an amount like 10 or 0.5." };
  if ((text.split(".")[1] ?? "").length > decimals) {
    return { error: `Use at most ${decimals} decimal places.` };
  }

  const value = parseUnits(text, decimals);
  return value > 0n ? { value } : { error: "Enter an amount above 0." };
}

const grouped = new Intl.NumberFormat("en-US", { maximumFractionDigits: 20 });

// `Intl.NumberFormat` formats decimal strings exactly, so no precision is lost to `Number`.
export function formatTokenAmount(value: bigint, decimals: number): string {
  return grouped.format(formatUnits(value, decimals) as `${number}`);
}

View on GitHub: apps/web/src/lib/token-amount.ts

Render the balance

Check for errors first. A failed refetch keeps the last value, which would otherwise show a stale balance as current.

apps/web/src/components/nusd-amount.tsx
import { nUSD } from "@/config/chains";
import type { useNusdBalance } from "@/hooks/use-nusd-balance";
import { formatTokenAmount } from "@/lib/token-amount";

type NusdBalance = Pick<ReturnType<typeof useNusdBalance>, "data" | "isError">;

// A `useNusdBalance` result as text. Error first: a failed refetch keeps the last `data`, which would pass a stale
// balance off as current.
export function NusdAmount({ balance }: { balance: NusdBalance }) {
  if (balance.isError) return "Unavailable";
  if (balance.data === undefined) return "…";
  return (
    <>
      {formatTokenAmount(balance.data, nUSD.decimals)}{" "}
      <span className="text-base text-muted-foreground">{nUSD.symbol}</span>
    </>
  );
}

View on GitHub: apps/web/src/components/nusd-amount.tsx

Transfer nUSD

A nUSD transfer is a plain TIP-20 transfer call. Because the top-level call is transfer on a USD TIP-20, NVNM Chain's fee rules make nUSD pay the fee too.

Send the transfer

The demo dApp's Send nUSD card validates the recipient and amount, and rejects amounts above the balance. It calls transfer with wagmi's useWriteContract, then tracks the result with the dApp's useTxOutcome hook:

apps/web/src/components/token-transfer.tsx
function TransferForm({ account, chain }: { account: Address; chain: SupportedChain }) {
  // ...
  // Shares the query the account dialog runs for the same account and chain.
  const balance = useNusdBalance(account, chain.id);
  const transfer = useWriteContract();
  // Shares the queries TxResultDialog runs for the same hash.
  const outcome = useTxOutcome(transfer.data, chain.id);

  const recipientError =
    recipient && !isAddress(recipient)
      ? "Enter a valid 0x address. Mixed-case addresses must match their checksum."
      : undefined;
  const parsed = amountText ? parseTokenAmount(amountText, nUSD.decimals) : undefined;
  const amount = parsed && "value" in parsed ? parsed.value : undefined;
  const amountError =
    parsed && "error" in parsed
      ? parsed.error
      : amount !== undefined && balance.data !== undefined && amount > balance.data
        ? "That's more than your balance."
        : undefined;
  const ready = isAddress(recipient) && amount !== undefined && !amountError;

  function submit(event: SubmitEvent) {
    event.preventDefault();
    if (!isAddress(recipient) || amount === undefined || amountError) return;
    transfer.mutate(
      {
        address: nUSD.address,
        abi: tip20Abi,
        functionName: "transfer",
        args: [recipient, amount],
        chainId: chain.id,
      },
      { onSuccess: () => setResultOpen(true) },
    );
  }
  // ...
}

View on GitHub: apps/web/src/components/token-transfer.tsx

The card also tells users why the fee comes out of their nUSD. Under the amount field, it shows: "The fee comes out of your nUSD too, so keep a little back." Its info box reads:

NVNM Chain has no native coin like ETH. Network fees are paid in nUSD, a dollar stablecoin, so your nUSD balance covers both what you send and the fee. If your wallet shows a separate native balance, ignore it: it's a placeholder.

Note

wagmi's waitForTransactionReceipt throws when a transaction reverts, rather than returning a reverted receipt. To tell a revert from an RPC error, useTxOutcome fetches the receipt itself after a failed wait. Deploy and interact with smart contracts walks through the hook.

Map fee and transfer errors

Show users a clear message when they can't cover the amount plus the fee. The demo dApp maps wallet and TIP-20 errors by error name or by the text of the node's message. For TIP-20 reverts, revertedWith also matches the custom error name once viem decodes the revert data with tip20Abi. This excerpt shows the fee and transfer entries:

apps/web/src/lib/wallet-errors.ts
const known: [matches: (error: ErrorLike) => boolean, message: string][] = [
  // ...
  [
    (e) =>
      e.name === "InsufficientFundsError" || messageOf(e).includes("insufficient funds for gas"),
    `Not enough ${nUSD.symbol} to pay the network fee.`,
  ],
  // TIP-20 reverts, named in the node's message and, once viem decodes the revert data with `tip20Abi`, in viem's.
  [
    (e) => revertedWith(e, "InsufficientBalance") || messageOf(e).includes("InsufficientBalance"),
    `Not enough ${nUSD.symbol} for this amount plus the network fee.`,
  ],
  [
    // The zero address and TIP-20 token addresses (nUSD's own included) can't receive tokens.
    (e) => revertedWith(e, "InvalidRecipient") || messageOf(e).includes("InvalidRecipient"),
    `This address can't receive ${nUSD.symbol}. Check the recipient.`,
  ],
  // ...
];

View on GitHub: apps/web/src/lib/wallet-errors.ts

Next steps