每次 ADA 质押奖励都会触发两次税务事件。协议会在每个纪元边界将奖励记入质押地址。用户则会通过单独的链上提现交易将奖励提取到支付地址。不同的司法管辖区可能将其中一次或两次都视为应税时刻。无论采用哪种方式，您的税务引擎导入的 CSV 文件都需要包含每个时间戳以及对应的 ADA 价格。本文是现有 Cardano 托管系列文章的税务和会计补充。配套指南《大规模轮询 Cardano 质押和奖励余额》（/blog/polling-cardano-stake-and-reward-balances-at-scale）涵盖了底层 Cardano 质押查询（](https://docs.bitquery.io/v1/docs/Examples/cardano/address?utm_source=blog&utm_campaign=cardano_tax) 以及使重复读取免费的缓存经济机制。关于如何在不运行完整节点的情况下检测 Cardano 存款的配套指南涵盖了用于观察链上提款交易的区块范围遍历器。本文面向构建用户奖励报表的工程师，该报表用于向加密税务平台（Koinly、CoinTracker、Cryptio、ZenLedger）或生成年终报表的托管后台提供数据。相同的五列数据可以满足两类用户的需求。本文将详细介绍生成这些报表的两个查询、epoch 数学运算、法币转换步骤、CSV 格式以及与税务报告相关的具体操作注意事项。## 每个奖励的两个税务事件 Cardano 上有两个奖励事件。大多数税务框架至少关注其中一个。许多框架关注两个。第一个事件是获得奖励。在每个周期边界，Shelley 奖励计算会将两个周期前的奖励计入质押地址。奖励无需用户操作即可到账。某些司法管辖区将此奖励视为普通收入。奖励到账时的 ADA 价格成为新 ADA 的成本基础。第二个事件是提现。用户签署一笔链上交易，将累积的奖励从奖励账户转移到支付地址。这是一个独立的事件，拥有自己的交易哈希和时间戳。其他司法管辖区将提现视为应税时刻。提现时的 ADA 价格成为已实现价值。一份可核实的每位用户奖励报表会记录这两项信息。收益流构成了收入确认的时间线。已提取数据流提供了提现时间表。接受这两种模型的税务平台都希望将它们作为单独的行。## Bitquery API 中的 Cardano 质押字段 Cardano address API 会为任何 Shelley 地址或质押地址（stake1...）返回一个 staking 区块。打开 Bitquery GraphQL IDE 中的 Cardano 质押快照查询 即可运行它。五个字段驱动税务导出。rewardsAmount 是此质押密钥终身获得的 ADA 奖励总额。rewardsAvailable 是已获得但尚未提取的部分。withdrawnAmount 是终身从奖励账户中转出的总额。stakedAmount 是当前委托的本金，用于验证有效的委托期限。stakedAmountWithRewards 是合并后的持仓。 rewardsAmount 和 withdrawnAmount 都是单调递增的。今天拍摄一个快照，然后在下一个 epoch 边界再拍摄一个快照，两者的差值就是该窗口期内的活动量。正是这个特性使得下面的快照方法能够奏效。## 模式 1：使用缓存读取进行每个 epoch 的奖励快照 Cardano 协议在每个 epoch 边界发放奖励。主网 epoch 为五天。epoch N 的奖励在 epoch N+1 结束时计算，并在 epoch N+2 开始时发放。在每个 epoch 边界之后立即拍摄的快照会捕获新的奖励。该过程很简单。在每个 epoch 边界处，为每个质押密钥拍摄 rewardsAmount 快照。用新快照减去前一个快照。差值就是该 epoch 发放的奖励。用 epoch 开始时间标记每个差值，该时间将成为用户声明中的收入事件时间戳。Bitquery 缓存正是为此类读取密集型工作而设计的。重复的 (stake_address, snapshot_time) 读取操作从缓存中获取，不会消耗 API 点数。Bitquery 上生产托管商的轮询模式证实了这一点：在多个 epoch 中轮询的数千个权益密钥在第一次轮询后几乎全部从缓存中解析。对于税务工作流程而言，这一点至关重要。年度报告运行成本很低。几个月后，为了审计或修改报表而重新运行同一时期，可以零成本地重现完全相同的快照。## 模式 2：链上提现事件 提现是显式交易。Cardano 的 transactions API 在交易级别公开了 withdrawalValue 和 withdrawalCount。打开 Bitquery GraphQL IDE 中的 Cardano 提现交易查询 即可运行。要将提现与特定的质押密钥关联起来，请使用交易提现证书中使用的质押地址进行连接。实际上，托管方已经知道哪个质押密钥属于哪个用户，因此连接操作会在您的应用程序代码中根据交易哈希和已存档的质押密钥完成。加密货币税务平台通常会在用户注册时收到质押地址，并运行相同的连接操作。输出结果为每笔提现一行：质押密钥、时间戳、ADA 金额和交易哈希。加上时间戳对应的 ADA/USD 价格，即可得到税务引擎所需的提现事件。## 模式 3：附加 ADA 价格以进行法币转换 有两种方法可以获取价格。最经济的方法是使用交易 API 的 inputValue(in: USD) 或 outputValue(in: USD)。Bitquery 会在同一查询中返回交易时间戳对应的美元转换值。无需二次 API 调用，也无需维护单独的价格数据源。如果审计要求使用固定的价格来源（例如特定交易所、每日结算价或内部预言机），则需要维护一个以 Unix 时间戳为索引的价格表。使用快照或提现交易的时间戳进行连接。审计人员通常更倾向于使用可验证的、有据可查的价格来源，而不是无法验证的嵌入式转换。## 税务导出的 CSV 格式 大多数税务平台都接受以下格式的通用 CSV 文件。各列直接对应于模式 1 和模式 2 生成的字段。event_type 用于分隔两个数据流，以便税务引擎能够为每一行应用正确的规则。提现行的 epoch 为空，因为提现并非 Unix 时间戳对齐的事件。在已赚取的行中，tx_hash 为空，因为已赚取的事件是协议级别的积分，在纪元边界处发放，本身没有交易哈希。Koinly 和 Cryptio 都通过其通用 CSV 导入器接受这种格式。CoinTracker 在重命名列后也能接受。同一个文件在 Excel 中可以正常打开，供首席财务官审核。## 纪元 N+2 的延迟和报表时间奖励不会在纪元 N 结束时发放，而是在纪元 N+2 开始时发放，大约晚十天。用户报表上的收入时间戳是发放时间，而不是工作时间。这会产生两个值得在您的报告策略中记录的后果。对于在周期中途取消质押的用户，最后一笔奖励会在他们停止委托后的两个周期到达。大多数税务平台都要求将入账时间戳作为收入日期。请坚持这样做，并记录原因。对于年终报表，12 月份最后一个周期的奖励会在 1 月初到账。请提前制定您的策略。美国国税局 (IRS) 的做法是，收入事件即为入账时间，这会将奖励计入下一个纳税年度。请与用户的会计师确认。Bitquery 的快照方法使得这两种策略都易于实现，因为快照时间戳在每一行中都是明确的。## Bitquery 与自托管 cardano-db-sync 用于奖励报告 另一种自然的选择是针对 Cardano 节点运行 cardano-db-sync，并直接在 Postgres 中查询奖励模式。对于某些团队来说，这是一个合理的选择。但对于大多数税务和会计用例来说，这不是一个好的选择。db-sync 的优势在于私有查询的延迟低于 50 毫秒，以及对 Postgres 模式的完全控制。反对使用数据库同步进行税务报告的理由是，工作流程主要由重复运行（审计修订、修改后的报表、期间重述）构成，而 Bitquery 缓存可以将这些重复运行转化为免费读取。## 将其集成到税务或会计后端 典型的奖励报告流程包含四个组件。快照调度器在每个 epoch 边界为每个质押密钥触发质押查询，并将结果写入以 (stake_address, epoch) 为索引的快照表。增量计算机读取每个质押密钥的连续快照，并为每个非零增量生成一条收益事件记录。提款监视器在滚动窗口中查询交易 API 中 withdrawalCount: {gt: 0} 的记录，将每个结果连接到内部质押密钥到用户的映射，并为每笔关联的提款生成一条提款事件记录。CSV 生成器读取请求报表期间的收益和提款记录，附加 ADA/USD 价格列，并生成 CSV 文件。这四个组件彼此独立。快照调度器运行在纪元时钟上。提现监视器运行在链时钟上。增量计算器和 CSV 生成器运行在报告时钟上。其中一个组件的故障不会影响其他组件，而且由于底层 API 读取操作已被缓存，因此重新运行任何组件的成本都很低。## 总结 托管型 Cardano 产品或加密货币税务平台在报告每个用户的 ADA 质押奖励时，无论受众是谁，都会面临相同的数据问题。CSV 文件需要包含事件时间戳、ADA 数量、事件发生时的 ADA 价格以及质押密钥归属信息，分别对应赚取和提取时刻。两个 GraphQL 查询涵盖这两个时刻。Cardano 地址 API 上的质押快照提供赚取时间线。Cardano 交易 API 提供提取时间线。(in: USD) 聚合器提供法币转换信息。缓存将审计重运行和修改后的语句转换为零点读取。[Bitquery]