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:
- 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.
- 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:

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, noteth_getBalance. - Treat the currency symbol as cosmetic. Wallets ask for one when you add the network.
USDandnUSDboth work.
Inside NVNM Chain's EVM, native balances are always zero:
| Feature | NVNM Chain behavior | What to do instead |
|---|---|---|
BALANCE and SELFBALANCE | Always returns 0 | Read the token's TIP-20 balanceOf |
CALLVALUE | Always returns 0 | Nothing 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:
// 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:
// ...
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:
- Transaction: the
fee_tokenfield of NVNM Chain's native transaction type (0x76). It takes precedence over any account, contract or validator preference. - Account: a default the fee payer sets by calling
setUserTokenon the FeeManager precompile (0xfeec000000000000000000000000000000000000). - TIP-20 contract: if the top-level call is
transfer,transferWithMemoorstartRewardon a USD TIP-20 token, that token pays the fee. A batched0x76transaction 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. - Stablecoin DEX: for certain swap calls, the
tokenInargument pays the fee. - 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_tokenor the fee payer has set an account fee token withsetUserToken. 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:
| Goal | How to do it |
|---|---|
| Choose the fee token for one transaction | Pass feeToken |
| Set an account's persistent default fee token | Call setUserToken on the FeeManager |
| Have another account pay the fee | Pass 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:
| Function | Notes |
|---|---|
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.
// 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.
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.
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.
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.
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:
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:
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