了解您的代币如何在 Spark 中流动对于作为发行者运营至关重要。您可能需要知道谁持有代币，何时铸造、销毁或冻结代币，以及它如何在 Spark 中转移。
我们正在开发多种方式让发行者观察和理解代币行为。Spark 浏览器正在开发中，将提供更直观、更视觉化的体验，但我们也在 SDK 层面公开了这些洞察，为高级用户提供更高的精确度和灵活性。
作为起点，SDK 提供了两个核心函数 — queryTokenTransactions() 和 getIssuerTokenDistribution() — 让发行者可以查询他们控制的任何代币的完整历史和当前状态。
检索代币交易历史
使用 queryTokenTransactions() 可获取代币的详细、可筛选的历史记录。该函数现在使用基于对象的参数结构，提供更灵活的过滤。通过组合可选参数，您可以灵活地按需切片数据，例如：“所有来自此地址的转出交易”或”与我的发行者公钥相关的所有交易”。
| 参数 | 类型 | 描述 |
|---|
ownerPublicKeys | string[] | （可选）仅返回涉及任意给定所有者公钥的交易 |
issuerPublicKeys | string[] | （可选）仅返回由任意给定发行者公钥创建的交易 |
tokenTransactionHashes | string[] | （可选）仅返回指定哈希对应的交易 |
tokenIdentifiers | string[] | （可选）按一个或多个 Bech32m 代币标识符 (btkn1…) 过滤 |
outputIds | string[] | （可选）仅返回引用给定输出 ID 的交易 |
返回值
函数返回 TokenTransactionWithStatus[]，每个元素包含：
tokenTransaction — 对应的 TokenTransaction 记录status — 该交易所处的生命周期阶段confirmationMetadata — 当交易最终确认后，包含链上确认的附加信息
状态枚举说明：
| 状态 | 含义 |
|---|
TOKEN_TRANSACTION_STARTED | 交易已创建，但尚未签名 |
TOKEN_TRANSACTION_SIGNED | 交易已由所有必需方签名 |
TOKEN_TRANSACTION_REVEALED | 交易已揭露到链上，等待最终确认 |
TOKEN_TRANSACTION_FINALIZED | 交易已确认并最终完成 |
TOKEN_TRANSACTION_STARTED_CANCELLED | 交易在签名前被取消 |
TOKEN_TRANSACTION_SIGNED_CANCELLED | 交易在签名后被取消 |
TOKEN_TRANSACTION_UNKNOWN | 未知或意外状态 |
const transactions = await wallet.queryTokenTransactions({
ownerPublicKeys: ["<ownerPublicKey>"],
issuerPublicKeys: ["<issuerPublicKey>"],
tokenIdentifiers: ["btkn1qwertyuiopasdfghjklzxcvbnm1234567890abcdef"],
});
console.log("代币交易:", transactions);
探索您的代币分析
此功能目前正在开发中，将在即将发布的 Spark 版本中提供。
getIssuerTokenDistribution() 获取代币分布的快照。这包括诸如有多少钱包持有它、流通中有多少以及销毁了多少等指标。
当您想监控供应指标、评估采用情况或在发行逻辑之上构建自定义分析时，这很有帮助。
它将返回：
totalCirculatingSupply：代币的总流通供应量totalIssued：曾经铸造的代币总数totalBurned：累计销毁的代币numHoldingAddress：唯一代币持有者numConfirmedTransactions：涉及此代币的已确认交易
const distribution = await wallet.getIssuerTokenDistribution();
console.log("代币分布:" + distribution);
