了解您的代币如何在 Spark 中流动对于作为发行者运营至关重要。您可能需要知道谁持有代币，何时铸造、销毁或冻结代币，以及它如何在 Spark 中转移。 我们正在开发多种方式让发行者观察和理解代币行为。Spark 浏览器正在开发中，将提供更直观、更视觉化的体验，但我们也在 SDK 层面公开了这些洞察，为高级用户提供更高的精确度和灵活性。 作为起点，SDK 提供了两个核心函数 — queryTokenTransactions() 和 getIssuerTokenDistribution() — 让发行者可以查询他们控制的任何代币的完整历史和当前状态。

​
检索代币交易历史

使用 queryTokenTransactions() 可获取代币的详细、可筛选的历史记录。通过组合可选参数，您可以灵活地按需切片数据，例如：“所有来自此地址的转出交易”或“与我的发行者公钥相关的所有交易”。

​
参数

参数类型描述
ownerPublicKeysstring[]（可选）仅返回涉及任意给定所有者公钥的交易
issuerPublicKeysstring[]（可选）仅返回由任意给定发行者公钥创建的交易
tokenTransactionHashesstring[]（可选）仅返回指定哈希对应的交易
tokenIdentifiersstring[]（可选）按一个或多个代币标识符过滤
outputIdsstring[]（可选）仅返回引用给定输出 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(
  ["<ownerPublicKey>"],
  ["<issuerPublicKey>"],
  undefined,
  ["<tokenIdentifier>"],
);

console.log("代币交易:", transactions);

​
探索您的代币分析

此功能目前正在开发中，将在即将发布的 Spark 版本中提供。
使用 getIssuerTokenDistribution() 获取代币分布的快照。这包括诸如有多少钱包持有它、流通中有多少以及销毁了多少等指标。 当您想监控供应指标、评估采用情况或在发行逻辑之上构建自定义分析时，这很有帮助。 它将返回：
  • totalCirculatingSupply：代币的总流通供应量
  • totalIssued：曾经铸造的代币总数
  • totalBurned：累计销毁的代币
  • numHoldingAddress：唯一代币持有者
  • numConfirmedTransactions：涉及此代币的已确认交易
const distribution = await wallet.getIssuerTokenDistribution();

console.log("代币分布:" + distribution);