Polkadot 开发教程：使用 SDK 查询链上状态（Dedot 完整指南）

原文作者：PaperMoon团队

简介（Introduction）

基于 Polkadot SDK 构建的区块链，其底层数据存储采用 Key-Value 键值数据库模型。
链上的所有信息（On-Chain State）本质上都保存在 Runtime 的 Storage 中，外部应用可以通过 RPC 接口进行读取。

链上状态通常包括：
    •    账户余额（Account Balances）
    •    资产信息（Assets Metadata）
    •    治理提案（Governance Proposals）
    •    Runtime 管理的任意业务数据

换句话说：区块链 ≈ 一个公开可读的状态数据库（State Machine），而 SDK 的作用就是提供读取这个数据库的“客户端工具”。

本文以 Dedot 为完整可运行示例，其它 SDK 原理一致。

在 Polkadot 中：
    •    Runtime → 管理状态
    •    Storage → 保存状态
    •    RPC → 提供读取入口
    •    SDK → 帮你调用 RPC

典型流程如下：

查询链上状态的逻辑：
    1.    SDK 连接节点 RPC
    2.    请求 Runtime Storage
    3.    节点读取数据库
    4.    返回编码后的数据
    5.    SDK 解码并输出

环境准备（Prerequisites）

需要安装：
    •    Node.js v18+
    •    npm / pnpm / yarn

1）创建项目

mkdir dedot-query-example && cd dedot-query-example && \
npm init -y && npm pkg set type=module

2）安装依赖

npm install dedot && \
npm install --save-dev @dedot/chaintypes @types/node tsx typescript

查询账户余额（System.Account）

该示例将读取 Runtime 中的：system.account

它是 Substrate 最核心的存储项，保存每个账户的原生代币余额。

新建文件

query-balance.ts

代码

import { DedotClient, WsProvider } from 'dedot';
import type { PolkadotAssetHubApi } from '@dedot/chaintypes';

const ASSET_HUB_RPC = 'INSERT_WS_ENDPOINT';

// 查询地址（Polkadot 地址）
const ADDRESS = 'INSERT_ADDRESS';

async function main() {
  // 连接节点
  const provider = new WsProvider(ASSET_HUB_RPC);
  const client = await DedotClient.new<PolkadotAssetHubApi>(provider);

  console.log('Connected to Polkadot Hub');
  console.log(`Querying balance for: ${ADDRESS}\n`);

  // 查询链上账户存储
  const accountInfo = await client.query.system.account(ADDRESS);

  // 解析返回数据
  const { nonce, data } = accountInfo;
  const { free, reserved, frozen } = data;

  console.log('Account Information:');
  console.log(`  Nonce: ${nonce}`);
  console.log(`  Free Balance: ${free}`);
  console.log(`  Reserved: ${reserved}`);
  console.log(`  Frozen: ${frozen}`);

  await client.disconnect();
}

main().catch(console.error);

参数说明

必须替换：

INSERT_WS_ENDPOINT

例如：

wss://polkadot-asset-hub-rpc.polkadot.io

INSERT_ADDRESS

替换为要查询的地址。

运行

npx tsx query-balance.ts

输出示例

Connected to Polkadot Hub
Querying balance for: 14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3

Account Information:
 Nonce: 0
 Free Balance: 0
 Reserved: 0
 Frozen: 0

字段解释

查询资产信息（Assets Pallet）

下面查询 USDT（资产 ID = 1984）。

我们会读取三类数据：
    1.    资产元数据
    2.    资产全局信息
    3.    指定账户持仓

新建文件

query-asset.ts

代码

import { DedotClient, WsProvider } from 'dedot';
import { hexToString } from 'dedot/utils';
import type { PolkadotAssetHubApi } from '@dedot/chaintypes';

const ASSET_HUB_RPC = 'INSERT_WS_ENDPOINT';

const USDT_ASSET_ID = 1984;
const ADDRESS = 'INSERT_ADDRESS';

async function main() {
  const provider = new WsProvider(ASSET_HUB_RPC);
  const client = await DedotClient.new<PolkadotAssetHubApi>(provider);

  console.log('Connected to Polkadot Hub');
  console.log(`Querying asset ID: ${USDT_ASSET_ID}\n`);

  // 元数据
  const assetMetadata = await client.query.assets.metadata(USDT_ASSET_ID);

  console.log('Asset Metadata:');
  console.log(`  Name: ${hexToString(assetMetadata.name)}`);
  console.log(`  Symbol: ${hexToString(assetMetadata.symbol)}`);
  console.log(`  Decimals: ${assetMetadata.decimals}`);

  // 资产详情
  const assetDetails = await client.query.assets.asset(USDT_ASSET_ID);

  if (assetDetails) {
    console.log('\nAsset Details:');
    console.log(`  Owner: ${assetDetails.owner.address()}`);
    console.log(`  Supply: ${assetDetails.supply}`);
    console.log(`  Accounts: ${assetDetails.accounts}`);
    console.log(`  Min Balance: ${assetDetails.minBalance}`);
    console.log(`  Status: ${JSON.stringify(assetDetails.status)}`);
  }

  // 查询账户持仓
  console.log(`\nQuerying asset balance for: ${ADDRESS}`);
  const assetAccount = await client.query.assets.account([
    USDT_ASSET_ID,
    ADDRESS,
  ]);

  if (assetAccount) {
    console.log('\nAsset Account:');
    console.log(`  Balance: ${assetAccount.balance}`);
    console.log(`  Status: ${JSON.stringify(assetAccount.status)}`);
  } else {
    console.log('\nNo asset balance found for this account');
  }

  await client.disconnect();
}

main().catch(console.error);

运行

npx tsx query-asset.ts

输出示例

Asset Metadata:
 Name: Tether USD
 Symbol: USDT
 Decimals: 6

Asset Details:
 Owner: 5Gy6UDPQNFG6vBL...
 Supply: 77998622834581
 Accounts: 13544
 Min Balance: 10000
 Status: "Live"

在 EVM 世界：
你只能通过区块浏览器（如 Etherscan）。

在 Polkadot：
你可以直接读取 Runtime Storage。

本质区别：

阅读原文：https://docs.polkadot.com/chain-interactions/query-data/query-sdks/#__tabbed_1_3