Dara DocsReferenceOperations
Reconciliation runbook
Reconciliation compares the financial ledger, the chain and the backing in one consistent read: one RPC node and
one closed ledger per run (recorded on the run). It runs every RECONCILE_EVERY (10 minutes in production) and on
demand (Admin → Reconciliation → Run now; roles PLATFORM_ADMIN, AUDITOR, RECONCILIATION_OPERATOR). A failing check
opens an incident; nothing is corrected automatically. A check is SKIPPED_IN_FLIGHT when an intent touching the
same balances is between submission and a closed ledger; the next run decides.
Checks
| Check | Compares | Usual causes | Action |
|---|---|---|---|
ledger_transactions_balanced | Every ledger transaction sums to zero | A bug or a manual database edit | Stop manual postings; engineering |
ledger_projection_matches_entries | Balance projections = sum of entries | Same | Same |
ledger_restricted_non_negative | No restricted account below zero | Same | Same |
balance_matches_ledger:COLD/HOT/CUSTOMER:<account> | Each account's on-chain trustline balance = its ledger position (available + held/reserved) | A movement outside the platform (also an indexer incident); an intent applied whose handler did not run (CHAIN_OPERATION_UNRESOLVED) | Find the movement in Dara Scan; follow its incident |
trustline_states_match | Authorization on-chain = what the platform believes (frozen customers revoked, others authorized) | A revoke/authorize applied outside the platform, or a failed authorization change | Re-apply through the console (freeze / unfreeze), investigate who changed it |
onchain_supply_matches_ledger | Sum of all holdings on-chain = ledger supply (+ in-flight) | Issuance or burn outside the platform; clawback without intent | Key-compromise playbook (INCIDENT_RESPONSE.md) |
ledger_supply_within_unexpired_backing | Ledger supply ≤ effective backing (attestations count 35 days) | Attestation expired; backing reduced | New approved reserve snapshot, or burn |
ledger_supply_equals_holders | Ledger supply = customers + HOT + COLD positions | A posting bug | Engineering |
indexer_current | The indexer is within MaxIndexerLag ledgers of the run's ledger (WARNING) | Worker or node problems | STELLAR_RPC_RUNBOOK.md; it clears by itself once the indexer catches up |
indexed_supply_matches_holdings | Supply by indexed movements (issued − burned − clawed back) = every holding the indexer has seen | A gap in indexing, or movements before the indexer start ledger | Check INDEXER_GAP; the start ledger must precede the ceremony |
no_supply_outside_known_trustlines | Nothing held outside trustlines of accounts the platform created | Unknown holder, claimable balance, pool, contract balance | Follow the matching indexer incident |
issuer_configuration | The issuer's signers, thresholds and flags = the ceremony layout | An unapproved SetOptions on the issuer | Key-compromise playbook |
After a fix
Run reconciliation manually. Resolve the incident only when the run passes, with a note naming the cause.