Merge 04ca05428f into e5e826d133

CHANGELOG.md

@@ -6,6 +6,11 @@ and this library adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
+## Added
+- `SDKSynchronizer.estimateBirthdayHeight(for date: Date)`: Get an estimated height for a given date, typically used for estimating birthday.
+
+# 2.2.11 - 2025-04-03
+
 ## Fixed
 - `transparent_gap_limit_handling` migration, whereby wallets having received transparent outputs at child indices below the index of the default address could cause the migration to fail.
 

Example/ZcashLightClientSample/ZcashLightClientSample/Sync Blocks/SyncBlocksViewController.swift

@@ -87,9 +87,19 @@ class SyncBlocksViewController: UIViewController {
     }
     
     @IBAction func startStop() {
-        Task { @MainActor in
-            await doStartStop()
+        var components = DateComponents()
+        components.year = 2019
+        components.month = 11
+        components.day = 1
+
+        let calendar = Calendar.current
+        if let date = calendar.date(from: components) {
+            synchronizer.estimateBirthdayHeight(for: date)
         }
+        
+//        Task { @MainActor in
+//            await doStartStop()
+//        }
     }
 
     func doStartStop() async {

Sources/ZcashLightClientKit/Checkpoint/BundleCheckpointSource.swift

@@ -30,4 +30,91 @@ 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
+            var closestHeight = loadedCheckpoint.height
+            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 if hoursApart >= 0 {
+                        return closestHeight
+                    }
+
+                    closestHeight = loadedCheckpoint.height
+                } else {
+                    return saplingActivationHeight
+                }
+            }
+        } else {
+            // loaded checkpoint is higher, descrease until reached the one
+            while hoursApart > 0 {
+                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 {
+                        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 {