# Account state & rollback

Account state, rewards, governance, and rollback behavior.

Canonical URL: https://getyano.dev/reference/account-state/

Yano's RocksDB account store is the authoritative implementation for stake
accounts, stake-pool and DRep delegations, pool lifecycle state, rewards and
epoch snapshots. The in-memory implementation exists only for deterministic
unit tests; startup never falls back to it when a persistent store is
incompatible or cannot be opened.

## Pool retirement at an epoch boundary

The boundary order is rewards, SNAP, POOLREAP and governance. SNAP therefore
captures the end-of-previous-epoch delegation state before an effective pool
retirement changes live state.

POOLREAP uses the exact deposit stored when the pool's current lifecycle was
created. It credits a registered reward account once, or accounts for an
unclaimed refund in the monetary result, and then removes the live pool,
retirement, lifecycle-slot and stake-pool-delegation rows. Stake accounts,
DRep delegations, pool-parameter history and certificate history remain.

Large delegation scans and writes are split into bounded rollback-v1 chunks. A
durable progress marker prevents a partial transition from being reported as a
complete boundary or a ready chain tip. Startup finishes a valid interrupted
transition before UTXO/account reconciliation and sync.

## Chainstate compatibility

An empty account store atomically records the current epoch-boundary indexes
and the `pool-lifecycle-state-v1` readiness marker. A populated store without
that marker, or with an unknown marker value, is rejected without modification
using `IncompatibleChainStateException`.

There is intentionally no automatic repair or v2 promotion. Incorrect
same-block certificate ordering in an older preview chainstate cannot be
reconstructed exactly from its live rows. Keep the old directory as a backup
if needed and sync into a new chainstate directory.

## Marker inventory

These are the format/readiness guards and transient recovery cursors an
operator may encounter for account-state lifecycle and its required UTXO
index. A permanent marker says that stored data has a known semantic contract;
a transient cursor says that a journaled operation must be resumed.

| Key | Kind | Written when | If absent, malformed or incompatible |
| --- | --- | --- | --- |
| `meta.epoch_boundary_state_version` | Format version | Atomically when an empty account store is initialized | A populated pre-marker or unknown version is rejected without writes; retain a backup and resync. |
| `meta.snapshot_dereg_index_version` | Permanent semantic-readiness guard | In the same empty-store initialization batch | Missing or incompatible means the credential-major SNAP deregistration input is not trustworthy; startup rejects the store and requires resync. |
| `meta.reward_event_index_version` | Permanent semantic-readiness guard | In the same empty-store initialization batch | Missing or incompatible means bounded reward event input is not trustworthy; startup rejects the store and requires resync. |
| `meta.pool_lifecycle_state_version` (`pool-lifecycle-state-v1`) | Permanent semantic-readiness guard | In the same empty-store initialization batch as the epoch-boundary markers | Missing on a populated store or any value other than v1 is rejected without writes; retain a backup and resync. |
| `meta.utxo_pointer.ready.v1` | Permanent, coordinate-pinned UTXO pointer-index completeness marker | Updated atomically with pointer-index changes after the full index is available | When the pointer index is applicable, a missing, malformed, stale or wrong-coordinate marker makes it not ready and startup fails closed with resync guidance. |
| `meta.genesis_staking_bootstrap` | Permanent idempotence and genesis-identity guard | Atomically with Shelley genesis pools, delegations, deposits and initial derived facts | Absence permits the one-time bootstrap. A marker for a different genesis identity fails closed; verify genesis configuration rather than overwriting it. |
| `meta.rollback.v1.target-slot` | Transient crash-recovery cursor | Before the first bounded account rollback chunk; removed after all phases are reversed | Absence is normal. Presence makes startup resume rollback-v1. A malformed value fails startup and requires restoring a sound checkpoint or resyncing. |
| `meta.reward.progress.v1` | Transient epoch-boundary crash cursor | With each committed bounded streaming-reward chunk; deleted by the final reward commit | Absence is normal. Presence makes reward processing resume after the last durable pool and prevents POOLREAP from starting. An epoch mismatch or malformed value fails the boundary closed. |
| `meta.pool.reap.progress.v1` | Transient epoch-boundary crash cursor | Before the first POOLREAP chunk, advanced with each chunk and deleted by the final pool/refund commit | Absence is normal. Presence keeps the boundary and application unready; startup resumes a matching boundary or fails closed if its epoch, slot or step is inconsistent. |

## Manual debugging rollback

A one-shot startup rollback can be requested with exactly one command-line
system property:

```text
-Dyano.debug.rollback-to-slot=<slot>
-Dyano.debug.rollback-to-epoch=<epoch>
```

Do not put these properties in `application.yml`; remove them from the next
start so the rollback is not requested again.

The runtime resolves a canonical stored block at or before the target and
rolls back account state, UTXO state and chain state in dependency-safe order.
For a rollback across an epoch boundary, account rollback includes every
POOLREAP chunk: live pool lifecycle rows and pool delegations are restored, and
the exact deposit refund and accumulated reward state are reversed. Replay of
the boundary then applies the same retirement and refund once.

The target must be at or above the common retained rollback floor. If required
reward inputs or journals have been pruned, Yano fails closed; restore a suitable
checkpoint or resync with a larger retention setting instead of forcing the
rollback.

POOLREAP uses the existing rollback-v1 boundary journal and progress marker.
There is no rollback-v2 format.