[#1537] Birthdate estimate based on a given date

Sources/ZcashLightClientKit/Checkpoint/BundleCheckpointSource.swift

@@ -30,4 +30,86 @@ struct BundleCheckpointSource: CheckpointSource {
             checkpointDirectory: BundleCheckpointURLProvider.default.url(self.network)
         ) ?? saplingActivation
     }
+    
+    func estimateBirthdayHeight(for date: Date) -> BlockHeight {
+        // the average time between 2500 blocks during last 10 checkpoints (estimated March 31, 2025) is 52.33 hours for mainnet
+        // the average time between 10,000 blocks during last 10 checkpoints (estimated March 31, 2025) is 134.93 hours for testnet
+        let avgIntervalTime: TimeInterval = network == .mainnet ? 52.33 : 134.93
+        let blockInterval: Double = network == .mainnet ? 2500 : 10_000
+        let saplingActivationHeight = network == .mainnet
+        ? ZcashMainnet().constants.saplingActivationHeight
+        : ZcashTestnet().constants.saplingActivationHeight
+
+        let latestCheckpoint = latestKnownCheckpoint()
+        let latestCheckpointTime = TimeInterval(latestCheckpoint.time)
+
+        // above latest checkpoint, return it
+        guard date.timeIntervalSince1970 < latestCheckpointTime else {
+            return latestCheckpoint.height
+        }
+        
+        // Phase 1, estimate possible height
+        let nowTimeIntervalSince1970 = Date().timeIntervalSince1970
+        let timeDiff = (nowTimeIntervalSince1970 - date.timeIntervalSince1970) - (nowTimeIntervalSince1970 - latestCheckpointTime)
+        let blockDiff = ((timeDiff / 3600) / avgIntervalTime) * blockInterval
+
+        var heightToLookAround = Double(Int(latestCheckpoint.height - Int(blockDiff)) / Int(blockInterval)) * blockInterval
+
+        // bellow sapling activation height
+        guard Int(heightToLookAround) > saplingActivationHeight else {
+            return saplingActivationHeight
+        }
+        
+        // Phase 2, load checkpoint and evaluate against given date
+        guard let loadedCheckpoint = Checkpoint.birthday(
+            with: BlockHeight(heightToLookAround),
+            checkpointDirectory: BundleCheckpointURLProvider.default.url(self.network)
+        ) else {
+            return saplingActivationHeight
+        }
+        
+        // loaded checkpoint is exactly the one
+        var hoursApart = (TimeInterval(loadedCheckpoint.time) - date.timeIntervalSince1970) / 3600
+        if hoursApart < 0 && abs(hoursApart) < avgIntervalTime {
+            return loadedCheckpoint.height
+        }
+        
+        if hoursApart < 0 {
+            // loaded checkpoint is lower, increase until reached the one
+            while abs(hoursApart) > avgIntervalTime {
+                heightToLookAround += blockInterval
+                
+                if let loadedCheckpoint = Checkpoint.birthday(
+                    with: BlockHeight(heightToLookAround),
+                    checkpointDirectory: BundleCheckpointURLProvider.default.url(self.network)
+                ) {
+                    hoursApart = (TimeInterval(loadedCheckpoint.time) - date.timeIntervalSince1970) / 3600
+                    if hoursApart < 0 && abs(hoursApart) < avgIntervalTime {
+                        return loadedCheckpoint.height
+                    }
+                } else {
+                    return saplingActivationHeight
+                }
+            }
+        } else {
+            // loaded checkpoint is higher, descrease until reached the one
+            while hoursApart > 0 || abs(hoursApart) > avgIntervalTime {
+                heightToLookAround -= blockInterval
+                
+                if let loadedCheckpoint = Checkpoint.birthday(
+                    with: BlockHeight(heightToLookAround),
+                    checkpointDirectory: BundleCheckpointURLProvider.default.url(self.network)
+                ) {
+                    hoursApart = (TimeInterval(loadedCheckpoint.time) - date.timeIntervalSince1970) / 3600
+                    if hoursApart < 0 && abs(hoursApart) < avgIntervalTime {
+                        return loadedCheckpoint.height
+                    }
+                } else {
+                    return saplingActivationHeight
+                }
+            }
+        }
+
+        return saplingActivationHeight
+    }
 }

Sources/ZcashLightClientKit/Checkpoint/CheckpointSource.swift

@@ -31,4 +31,8 @@ protocol CheckpointSource {
     /// - Note: When the user knows the exact height of the first received funds for a wallet,
     /// the effective birthday of that wallet is `transaction.height - 1`.
     func birthday(for height: BlockHeight) -> Checkpoint
+    
+    /// Takes a given date and finds out the closes checkpoint's height for it.
+    /// Each checkpoint has a timestamp stored so it can be used for the calculations.
+    func estimateBirthdayHeight(for date: Date) -> BlockHeight
 }

Sources/ZcashLightClientKit/ClosureSynchronizer.swift

@@ -156,6 +156,8 @@ public protocol ClosureSynchronizer {
 
     func refreshExchangeRateUSD()
 
+    func estimateBirthdayHeight(for date: Date, completion: @escaping (BlockHeight) -> Void)
+
     /*
      It can be missleading that these two methods are returning Publisher even this protocol is closure based. Reason is that Synchronizer doesn't
      provide different implementations for these two methods. So Combine it is even here.

Sources/ZcashLightClientKit/CombineSynchronizer.swift

@@ -148,6 +148,8 @@ public protocol CombineSynchronizer {
 
     func refreshExchangeRateUSD()
 
+    func estimateBirthdayHeight(for date: Date) -> SinglePublisher<BlockHeight, Error>
+
     func rewind(_ policy: RewindPolicy) -> CompletablePublisher<Error>
     func wipe() -> CompletablePublisher<Error>
 }

Sources/ZcashLightClientKit/Synchronizer.swift

@@ -426,6 +426,10 @@ public protocol Synchronizer: AnyObject {
         kServers: Int,
         network: NetworkType
     ) async -> [LightWalletEndpoint]
+    
+    /// Takes a given date and finds out the closes checkpoint's height for it.
+    /// Each checkpoint has a timestamp stored so it can be used for the calculations.
+    func estimateBirthdayHeight(for date: Date) -> BlockHeight
 }
 
 public enum SyncStatus: Equatable {

Sources/ZcashLightClientKit/Synchronizer/ClosureSDKSynchronizer.swift

@@ -256,6 +256,11 @@ extension ClosureSDKSynchronizer: ClosureSynchronizer {
         synchronizer.refreshExchangeRateUSD()
     }
 
+    public func estimateBirthdayHeight(for date: Date, completion: @escaping (BlockHeight) -> Void) {
+        let height = synchronizer.estimateBirthdayHeight(for: date)
+        completion(height)
+    }
+
     /*
      It can be missleading that these two methods are returning Publisher even this protocol is closure based. Reason is that Synchronizer doesn't
      provide different implementations for these two methods. So Combine it is even here.

Sources/ZcashLightClientKit/Synchronizer/CombineSDKSynchronizer.swift

@@ -254,6 +254,14 @@ extension CombineSDKSynchronizer: CombineSynchronizer {
         synchronizer.refreshExchangeRateUSD()
     }
 
+    public func estimateBirthdayHeight(for date: Date) -> SinglePublisher<BlockHeight, Error> {
+        let height = synchronizer.estimateBirthdayHeight(for: date)
+        let subject = PassthroughSubject<BlockHeight, Error>()
+        subject.send(height)
+        subject.send(completion: .finished)
+        return subject.eraseToAnyPublisher()
+    }
+
     public func rewind(_ policy: RewindPolicy) -> CompletablePublisher<Error> { synchronizer.rewind(policy) }
     public func wipe() -> CompletablePublisher<Error> { synchronizer.wipe() }
 }

Sources/ZcashLightClientKit/Synchronizer/SDKSynchronizer.swift

@@ -866,6 +866,10 @@ public class SDKSynchronizer: Synchronizer {
         return finalResult
     }
     
+    public func estimateBirthdayHeight(for date: Date) -> BlockHeight {
+        initializer.container.resolve(CheckpointSource.self).estimateBirthdayHeight(for: date)
+    }
+    
     // MARK: Server switch
 
     public func switchTo(endpoint: LightWalletEndpoint) async throws {

Tests/TestUtils/Sourcery/GeneratedMocks/AutoMockable.generated.swift

@@ -2072,6 +2072,26 @@ class SynchronizerMock: Synchronizer {
         }
     }
 
+    // MARK: - estimateBirthdayHeight
+
+    var estimateBirthdayHeightForCallsCount = 0
+    var estimateBirthdayHeightForCalled: Bool {
+        return estimateBirthdayHeightForCallsCount > 0
+    }
+    var estimateBirthdayHeightForReceivedDate: Date?
+    var estimateBirthdayHeightForReturnValue: BlockHeight!
+    var estimateBirthdayHeightForClosure: ((Date) -> BlockHeight)?
+
+    func estimateBirthdayHeight(for date: Date) -> BlockHeight {
+        estimateBirthdayHeightForCallsCount += 1
+        estimateBirthdayHeightForReceivedDate = date
+        if let closure = estimateBirthdayHeightForClosure {
+            return closure(date)
+        } else {
+            return estimateBirthdayHeightForReturnValue
+        }
+    }
+
 }
 class TransactionRepositoryMock: TransactionRepository {