Package xyz.tcheeric.cashu.voucher.app

Class VoucherBackupService

java.lang.Object
xyz.tcheeric.cashu.voucher.app.VoucherBackupService
public class VoucherBackupService extends Object
Service for managing voucher backup operations.

This service provides higher-level backup management beyond the basic backup/restore operations, including:

  • Intelligent backup scheduling (only backup changed vouchers)
  • Conflict resolution during restore
  • Backup verification and integrity checks
  • Merge logic for combining local and remote vouchers

Backup Strategy

Vouchers are non-deterministic (unlike NUT-13 secrets), so they MUST be backed up to recoverable storage. This service implements an incremental backup strategy to minimize bandwidth and storage usage.

Usage Example

 VoucherBackupService service = new VoucherBackupService(voucherService);

 // Backup vouchers that need backing up
 List<StoredVoucher> vouchers = wallet.getVouchers();
 int backedUp = service.backupIfNeeded(vouchers, userPrivateKey);

 // Restore and merge with local vouchers
 List<StoredVoucher> local = wallet.getVouchers();
 List<StoredVoucher> merged = service.restoreAndMerge(local, userPrivateKey);
See Also:

  • Constructor Details

    • VoucherBackupService

      public VoucherBackupService(@NonNull @NonNull VoucherService voucherService)
      Constructs a VoucherBackupService.
      Parameters:
      voucherService - the underlying voucher service (must not be null)

  • Method Details

    • backupIfNeeded

      public int backupIfNeeded(@NonNull @NonNull List<StoredVoucher> vouchers, @NonNull @NonNull String userPrivateKey)
      Backs up vouchers that need backing up (incremental backup).

      This method filters the vouchers to only backup those that:

      • Have never been backed up (lastBackupAt is null)
      • Have been modified since last backup (addedAt > lastBackupAt)
      Parameters:
      vouchers - the list of stored vouchers to check (must not be null)
      userPrivateKey - the user's private key for encryption (must not be null or blank)
      Returns:
      the number of vouchers backed up
      Throws:
      IllegalArgumentException - if parameters are invalid
      RuntimeException - if backup fails

    • backupAll

      public void backupAll(@NonNull @NonNull List<StoredVoucher> vouchers, @NonNull @NonNull String userPrivateKey)
      Backs up all vouchers regardless of their backup status.
      Parameters:
      vouchers - the list of stored vouchers to backup (must not be null)
      userPrivateKey - the user's private key for encryption (must not be null or blank)
      Throws:
      IllegalArgumentException - if parameters are invalid
      RuntimeException - if backup fails

    • restoreAndMerge

      public List<StoredVoucher> restoreAndMerge(@NonNull @NonNull List<StoredVoucher> localVouchers, @NonNull @NonNull String userPrivateKey)
      Restores vouchers from backup and merges with local vouchers.

      Merge strategy:

      • If voucher exists in both: keep local version (user may have updated status)
      • If voucher only in backup: add to result (recovery scenario)
      • If voucher only local: keep in result
      Parameters:
      localVouchers - the current local vouchers (must not be null, can be empty)
      userPrivateKey - the user's private key for decryption (must not be null or blank)
      Returns:
      the merged list of vouchers
      Throws:
      IllegalArgumentException - if parameters are invalid
      RuntimeException - if restore fails

    • restore

      public List<StoredVoucher> restore(@NonNull @NonNull String userPrivateKey)
      Restores vouchers from backup without merging.
      Parameters:
      userPrivateKey - the user's private key for decryption (must not be null or blank)
      Returns:
      the list of restored vouchers as StoredVoucher objects
      Throws:
      IllegalArgumentException - if userPrivateKey is invalid
      RuntimeException - if restore fails

    • verifyBackup

      public boolean verifyBackup(@NonNull @NonNull List<String> expectedVoucherIds, @NonNull @NonNull String userPrivateKey)
      Verifies backup integrity by restoring and comparing.

      This method restores vouchers from backup and checks if all expected vouchers are present. Useful for backup verification.

      Parameters:
      expectedVoucherIds - the list of voucher IDs that should be in backup
      userPrivateKey - the user's private key
      Returns:
      true if all expected vouchers are in backup, false otherwise