Investigate AdaPot deposit-pot semantics and API representation

[satran004]

Context

This was found while validating the mainnet sync and governance fix from #47 / #48.

For mainnet epochs 640–645:

• Yano treasury, reserves, and fees matched Koios exactly.
• The corrected epoch 643 treasury value matched Koios.
• Reward calculation completed successfully and produced the expected treasury/reserve results.
• Current and pending governance proposal lifecycle states matched Koios after normalizing Koios lifecycle epochs to Yano statuses.

The remaining discrepancy is the deposits field returned by the AdaPot API. This does not appear to affect reward calculation, but its intended accounting semantics and public representation need to be clarified.

Observation

Yano exposes one aggregate field:

{
  "deposits": "3483424000000"
}

Koios exposes separate deposit categories through /totals:

• deposits_stake
• deposits_drep
• deposits_proposal

For example, at epoch 645:

Source/category	Lovelace
Yano deposits	3,483,424,000,000
Koios deposits_stake	4,408,914,000,000
Koios deposits_drep	529,500,000,000
Koios deposits_proposal	1,800,000,000,000
Koios category total	6,738,414,000,000

The same type of difference exists for epochs 640–644. We should not assume the fields are intended to be equivalent until the Yano API contract is defined.

Initial source observations

EpochBoundaryProcessor stores snapshotCreator.getTotalDeposited() in the AdaPot snapshot. DefaultAccountStateStore updates that metadata for several certificate deposit/refund paths, including stake and DRep registration changes.

However, further investigation is needed around at least these categories:

• A new pool registration does not appear to contribute a depositDelta to the total-deposited metadata.
• Governance proposal deposits are tracked for governance distribution/refunds but do not appear to be included in the same AdaPot deposit aggregate.
• The AdaPot deposit value does not appear to feed calculateAndDistribute; reward calculation uses treasury, reserves, epoch fees, and protocol parameters. This is consistent with treasury/reserves and the reward result remaining correct despite the deposit-field difference.

Design questions

1. What should AdaPotDto.deposits represent?
   • the full ledger deposit pot;
   • only deposits relevant to reward calculation;
   • only deposits currently tracked by account state; or
   • a compatibility value matching another API?
2. Should the API expose a single full deposit pot or separate fields such as:
   • stake credential deposits;
   • pool deposits;
   • DRep deposits;
   • governance proposal deposits?
3. If the current value is intentionally scoped, should it be renamed or documented to avoid implying it is the complete ledger deposit pot?
4. If the full pot is required, how should existing chainstate be backfilled or migrated safely?

Suggested investigation / acceptance criteria

• Define and document the accounting semantics of the AdaPot deposits field.
• Reconcile each deposit category against ledger rules and Koios for several completed epochs.
• Confirm explicitly that changing the representation does not alter reward calculation results.
• Decide between a corrected aggregate, categorized fields, or both.
• Add epoch-boundary tests covering registration, deregistration/refund, pool retirement/reaping, DRep deposits, proposal submission, proposal enactment, and proposal expiry.
• Document any chainstate migration or resync requirement.

References

• Koios epoch totals: https://api.koios.rest/api/v1/totals?_epoch_no=645
• Governance fix validation: Mainnet treasury +5,100,781 ADA from epoch 643: ParameterChange wrongly treated as delaying action in RatificationEngine #47 and fix(governance): exclude parameter changes from delaying actions #48
• Related but distinct historical reward-drift investigation: AdaPot: preprod treasury/reserves drift from epoch 297 (~27.44 ADA over-distributed rewards, not governance) #34