Frequently Asked Questions (FAQ)

This page addresses common questions and provides solutions to help you get the most out of Yaci Store.

General Questions

Why does the utxo column in the adapot table always show 0?

Current workaround:

No action is required. The default value does not affect the accuracy of other ledger state calculations, including rewards, treasury, and reserves.

Troubleshooting

What’s the first thing I should do when encountering data discrepancy errors during synchronization?

Why rollback first?

Data discrepancies can occur for various reasons - network issues, interrupted synchronization, or edge cases in data processing. Rather than waiting for a fix or troubleshooting extensively, rolling back to a stable epoch allows you to:

• Quickly restore operations to a working state
• Isolate the problematic epoch to better understand the issue
• Continue synchronization from a clean checkpoint
• Provide better bug reports with specific epoch information

How to perform a rollback:

The Yaci Store Admin CLI provides a straightforward rollback feature:

1. Stop the Yaci Store application to prevent further synchronization

2. Identify the last known good epoch (check your logs or database state before the error occurred)

3. Run the rollback command:

   The command differs depending on your distribution type:

   For Docker Distribution

   Use the admin-cli.sh script in non-interactive mode by passing commands and arguments directly:

   ./admin-cli.sh rollback --epoch <EPOCH_NUMBER>

   Replace <EPOCH_NUMBER> with the epoch you want to roll back to.

   Example:

   ./admin-cli.sh rollback --epoch 450

   For ZIP (JAR) Distribution

   The ZIP distribution requires using the Admin CLI in interactive mode:

   1. Start the Admin CLI prompt:

      ./bin/admin-cli.sh

   2. Once in the Admin CLI prompt, run the rollback command:

      admin-cli> rollback --epoch <EPOCH_NUMBER>

   Example:

   ./bin/admin-cli.sh
   admin-cli> rollback --epoch 450

4. Verify the rollback by checking your database state

5. Restart Yaci Store and monitor the synchronization process

After rolling back:

• Monitor the logs carefully as synchronization resumes
• If the error persists at the same epoch, check the Known Issues page
• Report the issue with specific epoch and error details to help improve Yaci Store
• Consider enabling debug logging for more detailed diagnostics

Best practices:

• Maintain regular database backups
• Document the epoch where errors occur for future reference
• Test rollback procedures in non-production environments first
• Keep your Yaci Store version up to date to benefit from the latest fixes

How do I check if AdaPot calculation has errors?

Checking for errors:

Query the adapot_jobs table and look at the status and error_message columns:

SELECT epoch, status, error_message
FROM adapot_jobs
WHERE error_message IS NOT NULL

The status column can be: NOT_STARTED, STARTED, or COMPLETED. If a job has STARTED status with a non-null error_message, it means the calculation failed for that epoch.

How to retry failed calculations:

1. Stop the Yaci Store application

2. Rollback to the epoch before the failed one using the Admin CLI:

   First, try rollback-ledger-state-data — this rolls back only ledger state data (AdaPot, rewards, stake snapshots, DRep distribution) without affecting other indexed data (blocks, transactions, UTXOs):

   # Docker distribution
   ./admin-cli.sh rollback-ledger-state-data --epoch <FAILED_EPOCH>
    
   # ZIP distribution
   ./bin/admin-cli.sh
   admin-cli> rollback-ledger-state-data --epoch <FAILED_EPOCH>

   For example, if the AdaPot job failed at epoch 100, run rollback-ledger-state-data --epoch 100. The system will automatically find the last block of epoch 99 as the rollback point and reset all ledger state jobs from epoch 100 onward.

   If the issue persists after retrying, or you suspect broader data corruption, use rollback-data instead to roll back all data including blocks, transactions, and UTXOs:

   # Docker distribution
   ./admin-cli.sh rollback-data --epoch <FAILED_EPOCH>
    
   # ZIP distribution
   ./bin/admin-cli.sh
   admin-cli> rollback-data --epoch <FAILED_EPOCH>

3. Restart Yaci Store with the ledger-state profile to re-trigger the calculation:

The application will re-process the epoch and recalculate the AdaPot values from scratch.

Need More Help?

If your question isn’t answered here, please:

• Check the Known Issues section for documented problems
• Review the Tutorials & Use Cases for practical examples
• Visit the GitHub repository  to report issues or request features
• Join the community discussions for support and updates