Other Configurations

Other configurations

Each store implementation in yaci-store has its own configuration options. We will try to highlight a few key configurations here. These store-specific configurations can be set in the application.properties file.

Pruning Configuration

Sometimes you may not want to store all historical data in a store. If you are using yaci-store as a library, you can customize it to only store specific data in your own custom storage implementation. However, if you want to delete historical data from a store database, you can use the pruning configuration.

Currently, pruning configuration is only supported for the following stores. In the future, we will add support for other stores as well.

  • utxo
  • transaction
💡

By default, pruning is disabled for all stores.

Utxo Pruning

To enable utxo pruning, you can set the following configurations in the application.properties file.

store.utxo.pruning-enabled=true
store.utxo.pruning.interval=600

The above configuration will run utxo pruning every 600 seconds.

There is also another configuration, store.utxo.pruning-safe-blocks, which can be used to specify the number of safe blocks to keep in the store. By default, this is set to 2160 blocks, same as the security parameter in Cardano mainnet.

Transaction Pruning

To enable transaction pruning, you can set the following configurations in the application.properties file.

store.transaction.pruning-enabled=true
store.transaction.pruning.interval=86400

Epoch Stake Pruning

To enable epoch stake pruning, you can set the following configurations in the application.properties file.

store.adapot.epoch-stake-pruning-enabled=true
store.adapot.epoch-stake-pruning-interval=86400

The above configuration will run transaction pruning every 86400 seconds or 1 day.

There is also another configuration, store.adapot.epoch-stake-safe-epochs, which can be used to specify the number of safe epochs to keep in the store. By default, this is set to 4 epochs.

Reward Pruning

To enable reward pruning, add the following configurations to your application.properties file:

store.adapot.reward-pruning-enabled=true
store.adapot.reward-pruning-interval=86400

The above configuration will run reward pruning every 86400 seconds (1 day).

You can also specify how many safe slots to keep in the reward table using:

store.adapot.reward-pruning-safe-slots=43200

By default, this is set to 43200 slots. Reward records are only eligible for pruning if:

  • The reward's slot is less than or equal to the latest completed reward calculation job slot minus this safe slot threshold.
  • There exists a withdrawal for the same address, where the withdrawal's slot is greater than the reward's slot and less than the current pruning slot.

Rewards that have not been withdrawn (i.e., do not have a matching withdrawal after their slot) will never be pruned.

💡

Reward pruning will only remove reward records that have already been withdrawn (i.e., there is a withdrawal after the reward's slot for the same address). Rewards that have not been withdrawn will never be pruned.

Transaction Witness Saving

The transaction store supports configurable saving of witness data. This feature allows you to enable or disable the saving of transaction witnesses in the database, which can help reduce storage requirements if witness data is not required for your use case. By default, saving of transaction witness data is disabled.

store.transaction.save-witness=false

Auto-Restart Configuration

Yaci-store includes an auto-restart feature that automatically handles recoverable sync errors, such as IntersectionNotFound errors that can occur after network disconnections and node rollbacks.

The auto-restart system uses an event-driven architecture to detect sync issues and restart the sync process with proper backpressure controls.

# Auto-restart configuration (enabled by default)
store.auto-restart.enabled=true
store.auto-restart.debounce-window-ms=30000
store.auto-restart.max-attempts=5
store.auto-restart.backoff-base-ms=5000

Configuration Options

  • store.auto-restart.enabled (default: true): Enable or disable the auto-restart feature
  • store.auto-restart.debounce-window-ms (default: 30000): Time window in milliseconds to prevent multiple restart attempts. If multiple restart events occur within this window, only the first one will be processed
  • store.auto-restart.max-attempts (default: 5): Maximum number of restart attempts before giving up and requiring manual intervention
  • store.auto-restart.backoff-base-ms (default: 5000): Base delay in milliseconds for exponential backoff between restart attempts

How It Works

The auto-restart system automatically handles:

  • IntersectionNotFound errors: When the node can't find a common intersection point after network issues
  • Health check failures: When the auto-recovery service detects sync problems

The system includes safeguards to prevent restart storms:

  • Debouncing: Ignores rapid restart requests within the configured window
  • Exponential backoff: Increases delay between retry attempts (5s, 10s, 20s, 40s, 60s max)
  • Retry limits: Stops trying after the maximum attempts are reached
  • Success tracking: Resets the retry counter after 5 minutes of stable sync
💡

The auto-restart feature is enabled by default since IntersectionNotFound is a valid scenario that should be handled automatically, especially in production environments.

Auto-Recovery Service

In addition to the auto-restart feature, yaci-store provides an auto-recovery service that monitors the overall health of the sync process and triggers restarts when health issues are detected.

The auto-recovery service performs periodic health checks and publishes restart events when:

  • Connection to the Cardano node is not alive
  • Sync process is in an error state
  • General sync health problems are detected
# Auto-recovery service configuration (disabled by default)
store.admin.auto-recovery-enabled=false
store.admin.health-check-interval=120

Configuration Options

  • store.admin.auto-recovery-enabled (default: false): Enable or disable the auto-recovery service
  • store.admin.health-check-interval (default: 120): Health check interval in seconds

How Auto-Recovery Works

The auto-recovery service:

  1. Periodic Health Monitoring: Runs health checks at the configured interval
  2. Connection Monitoring: Checks if the connection to the Cardano node is alive
  3. Error Detection: Monitors for sync errors and problematic states
  4. Event Publishing: Publishes restart events that are handled by the auto-restart system
💡

The auto-recovery service is disabled by default. It should only be enabled in environments where you want comprehensive health monitoring beyond just IntersectionNotFound errors. When enabled, it works together with the auto-restart system to provide robust sync reliability.

Relationship Between Auto-Restart and Auto-Recovery

  • Auto-Restart: Always enabled by default, handles specific recoverable errors like IntersectionNotFound
  • Auto-Recovery: Disabled by default, provides broader health monitoring and triggers restarts for general health issues
  • Both systems work together through the same event-driven architecture
  • Auto-recovery publishes events that are processed by the auto-restart system's backpressure controls

Auto Sync off

Ideally, you should only have one write instance of yaci-store. However, if you want to set up multiple read-only yaci-store instances alongside one write instance, you can disable auto-sync in the read-only instances. This way, the read-only instances will only read from the database and not write to it.

store.sync-auto-start=false

Store specific application

Yaci Store bundles all stores by default, and you can enable or disable stores by setting a store-specific enable flag in the application.properties file. This makes it possible to have multiple instances of yaci-store with different stores enabled. These individual instances can write to their own separate databases with the default configuration.

However, if you want to have multiple store-specific yaci-store applications writing to the same database, each application needs to maintain its own cursor in the cursor_ table.

This is achievable by assigning a unique event publisher ID to each yaci-store application. This can be done by setting the following configuration in each application's application.properties file.

store.event-publisher-id=1000  //some unique id
Plugin ConfigurationLedger State Mismatches