跳转到内容

读取链上数据

使用 polkadot-api 读取链上账户余额,并通过纯整数运算完成代币精度换算,避免浮点数精度丢失。

前置条件: 已安装 polkadot-api@3.3.0 并生成 d9 描述文件(参见 生成 PAPI 3 描述文件),以及一个已验证创世哈希的 RPC 地址。

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { d9, getMetadata } from "@polkadot-api/descriptors";
import { toChainAddress } from "@d9-network/dapp-connector/protocol";
export async function readFreeBalance(rpcUrl: string, userAddress: string) {
const client = createClient(getWsProvider(rpcUrl), { getMetadata });
try {
const api = client.getTypedApi(d9);
// 在最新最终确认区块上读取,保证状态一致
const finalized = await client.getFinalizedBlock();
const account = await api.query.System.Account.getValue(
toChainAddress(userAddress),
{ at: finalized.hash },
);
return {
blockNumber: finalized.number,
blockHash: finalized.hash,
freeBalance: account.data.free, // bigint,最小单位
};
} finally {
client.destroy();
}
}

验证: 返回的 freeBalance 为最小单位表示的 bigint,可使用第 2 步中的工具函数格式化展示。

代币 小数位
D9(原生代币) 12
USDT、Energy、Bandwidth(Pallet 资产) 6

新建 src/amount.ts,用于在可读十进制字符串与链上 bigint 最小单位之间转换。切勿使用浮点数处理链上金额。

export function parseAmount(text: string, decimals: number): bigint {
const trimmed = text.trim();
if (!/^\d+(\.\d+)?$/.test(trimmed)) {
throw new Error("金额必须是非负十进制数");
}
const [whole, fraction = ""] = trimmed.split(".");
if (fraction.length > decimals) {
throw new Error(`金额最多支持 ${decimals} 位小数`);
}
return BigInt(whole + fraction.padEnd(decimals, "0"));
}
export function formatAmount(raw: bigint, decimals: number): string {
const base = 10n ** BigInt(decimals);
const whole = raw / base;
const fraction = (raw % base).toString().padStart(decimals, "0").replace(/0+$/, "");
return fraction ? `${whole}.${fraction}` : whole.toString();
}

使用示例:

import { formatAmount, parseAmount } from "./amount";
parseAmount("1.25", 12); // D9: 1250000000000n
formatAmount(1250000000000n, 12); // D9: "1.25"
parseAmount("5.5", 6); // USDT: 5500000n

验证: formatAmount(parseAmount("1.25", 12), 12) 返回 "1.25"。

报错信息 处理方式
金额必须是非负十进制数 仅输入数字及最多一个小数点,例如 "1.25"。
金额最多支持 N 位小数 去除多余小数位(D9 最多 12 位,USDT 最多 6 位)。