react-native-zcash 0.3.4 → 0.4.0

package/ios/ZCashLightClientKit/Metrics/SDKMetrics.swift

@@ -0,0 +1,270 @@
+//
+//  SDKMetrics.swift
+//  
+//
+//  Created by Lukáš Korba on 13.12.2022.
+//
+
+import Foundation
+
+/// SDK's tool for the measurement of metrics.
+/// The barebone API of the `SDKMetrics` is all about turning it on/off, pushing new reports in and popping RAW data out.
+/// The processing of data is either left to the user of `SDKMetrics` or anybody can take an advantage of extension APIs
+/// providing useful structs and reports.
+///
+/// Usage:
+/// The `SDKMetrics` API has been designed so it has the lowest impact possible on the SDK itself.
+/// Reporting of the metrics is already in place but ignored until `enableMetrics()` is called. Once turned on, the data is collected
+/// and cumulated to the in memory structural storage until `disableMetrics()` is called.
+/// `disableMetrics()` also clears out the in memory storage.
+///
+/// To collect data and process it there are 2 ways:
+///
+/// 1.
+/// Get RAW data by calling either `popBlock` or `popAllBlockReports`. The post-processing of data is then delegated to the caller.
+///
+/// 2.
+/// Get cumulated data by using an extension APIs. For the summarized collection, call `cumulativeSummary()`.
+/// Sometimes, typically when you want to run several iterations, the `cumulateReportsAndStartNewSet()` automatically computes
+/// cumulativeSummary, stores it and starts to collect a new set. All summaries can be either processed by a caller,
+/// accessing the collection `cumulativeSummaries` directly or values can be merged into one final summary by calling `summarizedCumulativeReports()`.
+///
+/// We encourage you to check`SDKMetricsTests` and other tests in the Test/PerformanceTests/ folder.
+public class SDKMetrics {
+    public struct BlockMetricReport: Equatable {
+        public let startHeight: BlockHeight
+        public let progressHeight: BlockHeight
+        public let targetHeight: BlockHeight
+        public let batchSize: Int
+        public let startTime: TimeInterval
+        public let endTime: TimeInterval
+        public var duration: TimeInterval { endTime - startTime }
+    }
+    
+    public enum Operation {
+        case downloadBlocks
+        case validateBlocks
+        case scanBlocks
+        case enhancement
+        case fetchUTXOs
+    }
+    
+    public struct SyncReport: Equatable {
+        public let startTime: TimeInterval
+        public let endTime: TimeInterval
+        public var duration: TimeInterval { endTime - startTime }
+    }
+    
+    public var cumulativeSummaries: [CumulativeSummary] = []
+    public var syncReport: SyncReport?
+    var isEnabled = false
+    var reports: [Operation: [BlockMetricReport]] = [:]
+
+    public init() { }
+    
+    /// `SDKMetrics` is disabled by default. Any pushed data are simply ignored until `enableMetrics()` is called.
+    public func enableMetrics() {
+        isEnabled = true
+    }
+    
+    public func disableMetrics() {
+        isEnabled = false
+        clearAll()
+    }
+    
+    /// `SDKMetrics` focuses deeply on sync process and metrics related to it. By default there are reports around
+    /// block operations like download, validate, etc. This method pushes data on a stack for the specific operation.
+    func pushProgressReport(
+        progress: BlockProgress,
+        start: Date,
+        end: Date,
+        batchSize: Int,
+        operation: Operation
+    ) {
+        guard isEnabled else { return }
+        
+        let blockMetricReport = BlockMetricReport(
+            startHeight: progress.startHeight,
+            progressHeight: progress.progressHeight,
+            targetHeight: progress.targetHeight,
+            batchSize: batchSize,
+            startTime: start.timeIntervalSinceReferenceDate,
+            endTime: end.timeIntervalSinceReferenceDate
+        )
+        
+        guard reports[operation] != nil else {
+            reports[operation] = [blockMetricReport]
+            return
+        }
+        
+        reports[operation]?.append(blockMetricReport)
+    }
+    
+    /// Block synchronisation consists of operations but the whole process is measured also, represented by
+    /// different struct `SyncReport`, missing specifics for the operations like batch size, etc.
+    /// Used for the total syncing time report in the first place.
+    func pushSyncReport(
+        start: Date,
+        end: Date
+    ) {
+        guard isEnabled else { return }
+        
+        let syncReport = SyncReport(
+            startTime: start.timeIntervalSinceReferenceDate,
+            endTime: end.timeIntervalSinceReferenceDate
+        )
+        
+        self.syncReport = syncReport
+    }
+    
+    /// A method allowing users of the `SDKMetrics` to pop the RAW data out of the system. For the specific `operation`
+    /// with option to either leave data in the storage or flushing it out and start the next batch of collecting new ones.
+    public func popBlock(operation: Operation, flush: Bool = false) -> [BlockMetricReport]? {
+        defer {
+            if flush { clearReport(operation) }
+        }
+        
+        return reports[operation]
+    }
+    
+    /// A method allowing users of the `SDKMetrics` to pop the RAW data out of the system. This time for all measured operations
+    /// with option to either leave data in the storage or flushing it out and start the next batch of collecting new ones.
+    public func popAllBlockReports(flush: Bool = false) -> [Operation: [BlockMetricReport]] {
+        defer {
+            if flush { clearAllBlockReports() }
+        }
+        
+        return reports
+    }
+    
+    func clearReport(_ operation: Operation) {
+        reports.removeValue(forKey: operation)
+    }
+        
+    func clearAllBlockReports() {
+        reports.removeAll()
+        cumulativeSummaries.removeAll()
+    }
+    
+    func clearAll() {
+        clearAllBlockReports()
+        syncReport = nil
+    }
+}
+
+/// This extension provides an API that provides the summary and accumulated reports.
+/// The RAW data can pulled out and be processed without this extension but we
+/// wanted to provide a way how to get essential summaries right from the SDK.
+extension SDKMetrics {
+    public struct CumulativeSummary: Equatable {
+        public let downloadedBlocksReport: ReportSummary?
+        public let validatedBlocksReport: ReportSummary?
+        public let scannedBlocksReport: ReportSummary?
+        public let enhancementReport: ReportSummary?
+        public let fetchUTXOsReport: ReportSummary?
+        public let totalSyncReport: ReportSummary?
+    }
+
+    public struct ReportSummary: Equatable {
+        public let minTime: TimeInterval
+        public let maxTime: TimeInterval
+        public let avgTime: TimeInterval
+        
+        public static let zero = Self(minTime: 0, maxTime: 0, avgTime: 0)
+    }
+
+    /// This method takes all the RAW data and computes a `CumulativeSummary` for every `operation`
+    /// independently. A `ReportSummary` is the result per `operation`, providing min, max and avg times.
+    public func cumulativeSummary() -> CumulativeSummary {
+        let downloadReport = summaryFor(reports: reports[.downloadBlocks])
+        let validateReport = summaryFor(reports: reports[.validateBlocks])
+        let scanReport = summaryFor(reports: reports[.scanBlocks])
+        let enhancementReport = summaryFor(reports: reports[.enhancement])
+        let fetchUTXOsReport = summaryFor(reports: reports[.fetchUTXOs])
+        var totalSyncReport: ReportSummary?
+        
+        if let duration = syncReport?.duration {
+            totalSyncReport = ReportSummary(minTime: duration, maxTime: duration, avgTime: duration)
+        }
+        
+        return CumulativeSummary(
+            downloadedBlocksReport: downloadReport,
+            validatedBlocksReport: validateReport,
+            scannedBlocksReport: scanReport,
+            enhancementReport: enhancementReport,
+            fetchUTXOsReport: fetchUTXOsReport,
+            totalSyncReport: totalSyncReport
+        )
+    }
+    
+    /// This method computes the `CumulativeSummary` for the RAW data already in the system, stores it
+    /// and leave room for collecting new RAW data. Typical use case is when some code is expected to run several times
+    /// and every run is expected to be a new data collection.
+    /// Usage of this API is then typically followed by calling `summarizedCumulativeReports()` which merges all stored
+    /// cumulative reports into one final report.
+    public func cumulateReportsAndStartNewSet() {
+        cumulativeSummaries.append(cumulativeSummary())
+        reports.removeAll()
+        syncReport = nil
+    }
+
+    /// This method takes all `CumulativeSummary` reports and merge them all together, providing
+    /// final `CumulativeSummary` per `operation`, ensuring right min and max values are in the place
+    /// as well as computes final avg time per `operation`.
+    public func summarizedCumulativeReports() -> CumulativeSummary? {
+        var finalSummary: CumulativeSummary?
+        
+        cumulativeSummaries.forEach { summary in
+            finalSummary = CumulativeSummary(
+                downloadedBlocksReport: accumulate(left: finalSummary?.downloadedBlocksReport, right: summary.downloadedBlocksReport),
+                validatedBlocksReport: accumulate(left: finalSummary?.validatedBlocksReport, right: summary.validatedBlocksReport),
+                scannedBlocksReport: accumulate(left: finalSummary?.scannedBlocksReport, right: summary.scannedBlocksReport),
+                enhancementReport: accumulate(left: finalSummary?.enhancementReport, right: summary.enhancementReport),
+                fetchUTXOsReport: accumulate(left: finalSummary?.fetchUTXOsReport, right: summary.fetchUTXOsReport),
+                totalSyncReport: accumulate(left: finalSummary?.totalSyncReport, right: summary.totalSyncReport)
+            )
+        }
+        
+        return finalSummary
+    }
+    
+    /// Internal helper method that accumulates `ReportSummary` times.
+    func accumulate(left: ReportSummary?, right: ReportSummary?) -> ReportSummary? {
+        guard let left, let right else {
+            if let right {
+                return ReportSummary(
+                    minTime: right.minTime,
+                    maxTime: right.maxTime,
+                    avgTime: right.avgTime
+                )
+            }
+            return nil
+        }
+        
+        return ReportSummary(
+            minTime: min(left.minTime, right.minTime),
+            maxTime: max(left.maxTime, right.maxTime),
+            avgTime: (left.avgTime + right.avgTime) * 0.5
+        )
+    }
+
+    /// Internal helper method that computes min, max and avg times for the `BlockMetricReport` collection.
+    func summaryFor(reports: [BlockMetricReport]?) -> ReportSummary? {
+        guard let reports, !reports.isEmpty else { return nil }
+        
+        var min: TimeInterval = 99999999.0
+        var max: TimeInterval = 0.0
+        var avg: TimeInterval = 0.0
+
+        reports.forEach { report in
+            let duration = report.duration
+            avg += duration
+            if duration > max { max = duration }
+            if duration < min { min = duration }
+        }
+        // reports.count is guarded to never be a zero
+        avg /= TimeInterval(reports.count)
+        
+        return ReportSummary(minTime: min, maxTime: max, avgTime: avg)
+    }
+}

package/ios/ZCashLightClientKit/Model/Checkpoint.swift

@@ -0,0 +1,84 @@
+//
+//  Checkpoint.swift
+//  
+//
+//  Created by Francisco Gindre on 7/12/22.
+//
+
+import Foundation
+
+/// Represents the wallet's birthday which can be thought of as a checkpoint at the earliest moment in history where
+/// transactions related to this wallet could exist. Ideally, this would correspond to the latest block height at the
+/// time the wallet key was created. Worst case, the height of Sapling activation could be used (280000).
+///
+/// Knowing a wallet's birthday can significantly reduce the amount of data that it needs to download because none of
+/// the data before that height needs to be scanned for transactions. However, we do need the Sapling tree data in
+/// order to construct valid transactions from that point forward. This birthday contains that tree data, allowing us
+/// to avoid downloading all the compact blocks required in order to generate it.
+///
+/// New wallets can ignore any blocks created before their birthday.
+///
+/// - Parameters:
+///  - height: the height at the time the wallet was born
+///  - hash: the block hash corresponding to the given height
+///  - time: the time the wallet was born, in seconds
+///  - saplingTree: the sapling tree corresponding to the given height. This takes around 15 minutes of processing to generate from scratch because all blocks since activation need to be considered. So when it is calculated in advance it can save the user a lot of time.
+///  - orchardTree: the orchard tree corresponding to the given height. This field is optional since it won't be available prior
+///   to NU5 activation height for the given network.
+struct Checkpoint: Equatable {
+    let height: BlockHeight
+    let hash: String
+    let time: UInt32
+    let saplingTree: String
+    let orchardTree: String?
+}
+
+extension Checkpoint: Decodable {
+    public enum CodingKeys: String, CodingKey {
+        case height
+        case hash
+        case time
+        case saplingTree
+        case orchardTree
+    }
+
+    public init(from decoder: Decoder) throws {
+        do {
+            let container = try decoder.container(keyedBy: CodingKeys.self)
+            self.height = try Self.getHeight(from: container)
+            self.hash = try container.decode(String.self, forKey: .hash)
+            self.time = try container.decode(UInt32.self, forKey: .time)
+            self.saplingTree = try container.decode(String.self, forKey: .saplingTree)
+            self.orchardTree = try container.decodeIfPresent(String.self, forKey: .orchardTree)
+        } catch {
+            throw ZcashError.checkpointDecode(error)
+        }
+    }
+
+    static func getHeight(from container: KeyedDecodingContainer<CodingKeys>) throws -> Int {
+        guard
+            let heightString = try? container.decode(String.self, forKey: .height),
+            let height = Int(heightString)
+        else {
+            throw DecodingError.typeMismatch(
+                String.self,
+                DecodingError.Context(
+                    codingPath: [CodingKeys.height],
+                    debugDescription: "expected height to be encoded as a string",
+                    underlyingError: nil
+                )
+            )
+        }
+        return height
+    }
+}
+
+public extension BlockHeight {
+    /// Useful when creating a new wallet to reduce sync times.
+    /// - Parameters:
+    ///  - zcashNetwork: Network to use for the block height.
+    /// - Returns: The block height of the newest checkpoint known by the SDK.
+    static func ofLatestCheckpoint(network: ZcashNetwork) -> BlockHeight {
+        Checkpoint.birthday(with: BlockHeight.max, network: network).height
+    }
+}

package/ios/ZCashLightClientKit/Model/Memo.swift

@@ -0,0 +1,236 @@
+//
+//  Memo.swift
+//  
+//
+//  Created by Pacu on 5/11/22.
+//
+
+import Foundation
+
+public enum Memo: Equatable {
+    case empty
+    case text(MemoText)
+    case future(MemoBytes)
+    case arbitrary([UInt8])
+
+    /// Parses the given bytes as in ZIP-302
+    public init(bytes: [UInt8]) throws {
+        self = try MemoBytes(bytes: bytes).intoMemo()
+    }
+
+    /// Converts these memo bytes into a ZIP-302 Memo
+    public init(memoBytes: MemoBytes) throws {
+        self = try memoBytes.intoMemo()
+    }
+
+    /// Creates a `.text(TextMemo)` Memo using the `UTF8View` of the given string
+    /// - Throws:
+    ///   - `MemoBytes.Errors.tooLong(length)` if the UTF-8 length
+    /// of this string is greater than `MemoBytes.capacity`  (512 bytes)
+    public init(string: String) throws {
+        self = .text(try MemoText(String(string.utf8)))
+    }
+    
+    /// Represent memo as String. Only `.text` memo can be represented as String.
+    /// - Returns: Valid String if it can be created from memo; otherwise `nil`.
+    public func toString() -> String? {
+        switch self {
+        case .empty, .future, .arbitrary:
+            return nil
+            
+        case .text(let text):
+            return text.string
+        }
+    }
+}
+
+public extension Memo {
+    /// Use this function to know the size of this text in memo bytes.
+    /// - Parameter memotext: the string you want to turn into a
+    /// a memo.
+    /// - Returns: the size of this string in bytes using UTF-8 encoding.
+    /// - note: According to ZIP-302, memos have a length limit of 512 bytes.
+    /// Attempting to create a memo that exceeds that capacity will
+    /// throw an error.
+    static func length(for memoText: String) -> Int {
+        memoText.lengthOfBytes(using: .utf8)
+    }
+}
+
+public extension Memo {
+    func asMemoBytes() throws -> MemoBytes {
+        switch self {
+        case .empty:
+            return MemoBytes.empty()
+
+        case .text(let textMemo):
+            guard let bytes = textMemo.string.data(using: .utf8)?.bytes else {
+                throw ZcashError.memoTextInvalidUTF8
+            }
+
+            return try MemoBytes(bytes: bytes)
+
+        case .future(let memoBytes):
+            return memoBytes
+
+        case .arbitrary(var arbitraryBytes):
+            arbitraryBytes.insert(0xFF, at: 0)
+            return try MemoBytes(bytes: arbitraryBytes)
+        }
+    }
+}
+
+/// A wrapper on `String` so that `Memo` can't be created with an invalid String
+public struct MemoText: Equatable {
+    public let string: String
+
+    init(_ string: String) throws {
+        let trimmedString = String(string.reversed().drop(while: { $0 == "\u{0}" }).reversed())
+
+        guard trimmedString.count == string.count else {
+            throw ZcashError.memoTextInputEndsWithNullBytes
+        }
+
+        guard string.utf8.count <= MemoBytes.capacity else {
+            throw ZcashError.memoTextInputTooLong(string.utf8.count)
+        }
+
+        self.string = string
+    }
+}
+
+public struct MemoBytes: Equatable {
+    public enum Errors: Error {
+        /// Invalid UTF-8 Bytes where detected when attempting to create a Text Memo
+        case invalidUTF8
+        /// Trailing null-bytes were found when attempting to create a Text memo
+        case endsWithNullBytes
+        /// the resulting bytes provided are too long to be stored as a Memo in any of its forms.
+        case tooLong(Int)
+    }
+
+    public static let capacity: Int = 512
+
+    public let bytes: [UInt8]
+
+    /// Copies the given bytes into the inner array if this struct in the context of ZIP-302
+    /// and returns a `MemoBytes`  struct
+    /// - Throws: `Errors.tooLong(bytes.count)` if the count is greater than
+    /// 512 bytes.
+    ///
+    public init(bytes: [UInt8]) throws {
+        guard bytes.count <= Self.capacity else { throw ZcashError.memoBytesInputTooLong(bytes.count) }
+
+        var rawBytes = [UInt8](repeating: 0x0, count: Self.capacity)
+
+        // replacing range is quite slow an inefficient. Use bare metal impl
+        _ = bytes.withUnsafeBufferPointer { ptr in
+            memmove(&rawBytes[0], ptr.baseAddress, ptr.count)
+        }
+
+        self.bytes = rawBytes
+    }
+
+    init(contiguousBytes: ContiguousArray<UInt8>) throws {
+        guard contiguousBytes.capacity <= Self.capacity else { throw ZcashError.memoBytesInputTooLong(contiguousBytes.capacity) }
+
+        var rawBytes = [UInt8](repeating: 0x0, count: Self.capacity)
+
+        _ = contiguousBytes.withUnsafeBufferPointer { ptr in
+            memmove(&rawBytes[0], ptr.baseAddress, ptr.count)
+        }
+
+        self.bytes = rawBytes
+    }
+
+    public static func empty() -> Self {
+        // swiftlint:disable:next force_try
+        try! Self(bytes: .emptyMemoBytes)
+    }
+}
+
+public extension MemoBytes {
+    /// Parsing of the MemoBytes in terms of ZIP-302 Specification
+    /// See https://zips.z.cash/zip-0302#specification
+    /// - Returns:
+    ///   - `.text(MemoText)` If the first byte (byte 0) has a value of 0xF4 or smaller
+    ///   - `.future(MemoBytes)`  If the memo matches any of these patterns, then this memo is from the future,
+    ///     because these ranges are reserved for future updates to this specification:
+    ///      - The first byte has a value of 0xF5.
+    ///      - The first byte has a value of 0xF6, and the remaining 511 bytes are not all 0x00.
+    ///      - The first byte has a value between 0xF7 and 0xFE inclusive.
+    ///   - `.arbitrary(Bytes)` when the first byte is 0xFF. The Bytes don't include the 0xFF leading byte.
+    /// - Throws:
+    ///  - `MemoBytes.Errors.invalidUTF8` when the case of Text memo is found but then invalid UTF-8 is found
+    func intoMemo() throws -> Memo {
+        switch self.bytes[0] {
+        case 0x00 ... 0xF4:
+            let unpaddedBytes = self.unpaddedRawBytes()
+            guard let validatedUTF8String = String(bytes: unpaddedBytes, encoding: .utf8) else {
+                throw ZcashError.memoBytesInvalidUTF8
+            }
+
+            return .text(try MemoText(validatedUTF8String))
+
+        case 0xF5:
+            return Memo.future(self)
+
+        case 0xF6:
+            return self.bytes.dropFirst().first(where: { $0 != 0 }) == nil ?
+                Memo.empty :
+                Memo.future(self)
+
+        case 0xF7 ... 0xFE:
+            return Memo.future(self)
+
+        case 0xFF:
+            return .arbitrary([UInt8](bytes[1...]))
+
+        default:
+            return .future(self)
+        }
+    }
+}
+
+extension MemoBytes {
+    ///  Returns raw bytes, excluding null padding
+    func unpaddedRawBytes() -> [UInt8] {
+        self.bytes.unpaddedRawBytes()
+    }
+}
+
+extension Array where Element == UInt8 {
+    static var emptyMemoBytes: [UInt8] {
+        var emptyMemo = [UInt8](repeating: 0x00, count: MemoBytes.capacity)
+        emptyMemo[0] = 0xF6
+        return emptyMemo
+    }
+
+    func unpaddedRawBytes() -> [UInt8] {
+        guard let lastNullByte = self.enumerated()
+            .reversed()
+            .first(where: { $0.1 != 0 })
+            .map({ $0.0 + 1 }) else {
+                return []
+        }
+
+        return [UInt8](self[0 ..< lastNullByte])
+    }
+}
+
+extension Optional where WrappedType == String {
+    func intoMemo() throws -> Memo {
+        switch self {
+        case .none:
+            return .empty
+        case .some(let string):
+            return try Memo(string: string)
+        }
+    }
+}
+
+extension Data {
+    func intoMemoBytes() throws -> MemoBytes? {
+        try MemoBytes(bytes: self.bytes)
+    }
+}