main network upgrade

Author: davidscheutz

README.md

@@ -5,9 +5,6 @@
 
 Official Swift SDK to interact with the [Keeta Network](https://keeta.com/).
 
-> [!WARNING]  
-> These APIs are not considered stable and may change with any update. Specify a version using `exact:` to avoid breaking changes.
-
 ### Installation
 
 This package uses Swift Package Manager. To add it to your project using Xcode:
@@ -139,7 +136,7 @@ let consecutiveBlock = try BlockBuilder()
         .add(operation: SetInfoOperation(name: "Demo Account".uppercased()))
         .seal()
 
-// Blocks can be published together using either the KeetaClient or KeetaApi
+// Manually constructed blocks can be published using the KeetaApi. Please check the fees section for further details.
 ```
 
 ### KeetaClient
@@ -163,3 +160,23 @@ Interact with the network directly, specify which rep to talk to, recover accoun
 ```js
 let api = try KeetaApi(config: .create(for: .test))
 ```
+
+### Fees
+
+Representatives may charge a fee to issue permanent votes. Permanent votes are required to publish a block to the network. Fees are handled automatically when using the `KeetaClient`. When publishing blocks manually using the `KeetaApi`, an additional block to pay the fees has to be included using the `feeBlockBuilder` completion.
+
+**Publish a Block via API**
+```js
+let network: NetworkAlias = .main
+
+let api = try KeetaApi(network: network)
+
+// Use the `AccountBuilder` to create a 'senderAccount'
+// Use the `BlockBuilder` to construct a 'sendBlock'
+
+try await api.publish(blocks: [sendBlock]) { temporaryStaple in
+    // Compute the fee block, will be published together with the 'sendBlock'
+    try BlockBuilder.feeBlock(for: temporaryStaple, account: senderAccount, network: network)
+}
+```
+

Sources/KeetaClient/Account/Account.swift

@@ -43,11 +43,11 @@ public struct Account: Codable, Hashable {
     public let publicKeyAndType: PublicKeyAndType
     public let keyAlgorithm: KeyAlgorithm
 
-    var canSign: Bool {
+    public var canSign: Bool {
         keyPair.hasPrivateKey
     }
 
-    var isIdentifier: Bool {
+    public var isIdentifier: Bool {
         [.TOKEN, .NETWORK].contains(keyAlgorithm)
     }
 

Sources/KeetaClient/Account/AccountBalance.swift

@@ -4,4 +4,10 @@ public struct AccountBalance {
     public let account: String
     public let balances: [String: BigInt]
     public let currentHeadBlock: String?
+    
+    public func canCover(fees: [String: BigInt]) -> Bool {
+        !fees.contains { feeToken, feeAmount in
+            balances[feeToken, default: 0] < feeAmount
+        }
+    }
 }

Sources/KeetaClient/Block/Block.swift

@@ -6,25 +6,46 @@ public typealias Signature = [UInt8]
 public typealias NetworkID = BigInt
 public typealias SubnetID = BigInt
 
+public enum BlockSignature: Hashable {
+    case single(Signature)
+    case multi([Signature])
+    
+    func toHexString() -> String {
+        switch self {
+        case .single(let signature): signature.toHexString()
+        case .multi(let signatures): "Multi-signatures not implemented"
+        }
+    }
+}
+
 public struct Block {
-    public typealias Version = Int
+    public typealias Signature = BlockSignature
 
     public let rawData: RawBlockData
     public let opening: Bool
     public let hash: String
     public let signature: Signature
 
-    static let asn1Schema: Schema = .sequence([
-        "version": .integer(),
-        "network": .integer(),
-        "subnet": .choiceOf([.integer(), .null]),
-        "date": .time(kind: .generalized),
-        "signer": .octetString(),
-        "account": .choiceOf([.octetString(), .null]),
-        "previous": .octetString(),
-        "operations": .sequenceOf(.any),
-        "signature": .integer()
-    ])
+    public enum Version: Int, CaseIterable {
+        case v1
+        case v2
+        
+        public var value: BigInt { BigInt(rawValue) }
+        public var tag: UInt8 { UInt8(rawValue) }
+        public static var all: [Self] { allCases }
+        public static var latest: Self { all.last! }
+        
+        public static func > (lhs: Version, rhs: Version) -> Bool {
+            lhs.rawValue > rhs.rawValue
+        }
+    }
+    
+    public enum Purpose: Int {
+        case generic
+        case fee
+        
+        public var value: BigInt { BigInt(rawValue) }
+    }
 
     public static func accountOpeningHash(for account: Account) throws -> String {
         let publicKeyBytes = try account.keyPair.publicKey.toBytes()
@@ -37,13 +58,18 @@ public struct Block {
 
         let verifiedSignature: Signature
         if let signature = signature {
-            let verified = try rawBlock.signer.verify(data: Data(hashBytes), signature: signature)
-            guard verified else {
-                throw BlockError.invalidSignature
+            switch signature {
+            case .single(let signature):
+                let verified = try rawBlock.signer.verify(data: Data(hashBytes), signature: signature)
+                guard verified else {
+                    throw BlockError.invalidSignature
+                }
+                verifiedSignature = .single(signature)
+            case .multi:
+                throw NSError(domain: "Multi-signatures not implemented", code: 0)
             }
-            verifiedSignature = signature
         } else {
-            verifiedSignature = try rawBlock.signer.sign(data: Data(hashBytes))
+            verifiedSignature = .single(try rawBlock.signer.sign(data: Data(hashBytes)))
         }
 
         self.rawData = rawBlock
@@ -55,17 +81,82 @@ public struct Block {
     public init(from data: Data) throws {
         let asn1 = try ASN1Serialization.asn1(fromDER: data)
 
-        guard let sequence = asn1.first?.sequenceValue else {
-            throw BlockError.invalidASN1Sequence
+        let data: [ASN1]
+        let version: Block.Version
+        
+        if let sequence = asn1.first?.sequenceValue {
+            data = sequence
+            
+            guard let rawVersion = data[0].integerValue,
+                  let versionValue = Block.Version(rawValue: Int(rawVersion)),
+                  versionValue == .v1 else {
+                throw BlockError.invalidVersion
+            }
+            version = versionValue
+        } else if let tagged = asn1.first?.taggedValue {
+            let asn1 = try ASN1Serialization.asn1(fromDER: tagged.data)
+            guard let sequence = asn1.first?.sequenceValue else {
+                throw BlockError.invalidASN1Sequence
+            }
+            data = sequence
+            
+            guard let rawVersion = tagged.contextSpecificTag,
+                  let versionValue = Block.Version(rawValue: Int(rawVersion)),
+                    versionValue > .v1 else {
+                throw BlockError.invalidVersion
+            }
+            version = versionValue
+        } else {
+            throw BlockError.invalidASN1Schema
         }
-        guard sequence.count == 9 else {
+        
+        guard data.count == 8 || data.count == 9 else {
             throw BlockError.invalidASN1SequenceLength
         }
 
-        guard let version = sequence[0].integerValue else {
-            throw BlockError.invalidVersion
+        let rawBlock: RawBlockData
+        let signature: Signature
+        let opening: Bool
+        
+        switch version {
+        case .v1: (rawBlock, signature, opening) = try Self.blockDataV1(for: data)
+        case .v2: (rawBlock, signature, opening) = try Self.blockDataV2(for: data)
         }
 
+        self.rawData = rawBlock
+        self.opening = opening
+        self.hash = try rawBlock.hash()
+        self.signature = signature
+    }
+    
+    public func toAsn1() throws -> [ASN1] {
+        let rawASN1 = try rawData.asn1Values()
+        
+        return switch signature {
+        case .single(let signature):
+            rawASN1 + [.octetString(.init(signature))]
+        case .multi(let signatures):
+            rawASN1 + signatures.map { .octetString(.init($0)) }
+        }
+    }
+    
+    public func toData() throws -> Data {
+        switch rawData.version {
+        case .v1:
+            return try toAsn1().toData()
+        case .v2:
+            let tag = try TaggedValue.contextSpecific(tag: rawData.version.tag, try toAsn1())
+            return try tag.toData()
+        }
+    }
+    
+    public func base64String() throws -> String {
+        try toData().base64EncodedString()
+    }
+    
+    // MARK: Helper
+    
+    private static func blockDataV1(for sequence: [ASN1]) throws -> (RawBlockData, Signature, Bool) {
         guard let network = sequence[1].integerValue else {
             throw BlockError.invalidNetwork
         }
@@ -108,7 +199,8 @@ public struct Block {
         let opening = previousHash == account.publicKeyString
 
         let rawBlock = RawBlockData(
-            version: Int(version) + 1,
+            version: .v1,
+            purpose: .generic,
             previous: previousHash,
             network: network,
             subnet: subnet,
@@ -118,22 +210,74 @@ public struct Block {
             created: anyTime.zonedDate.utcDate
         )
 
-        self.rawData = rawBlock
-        self.opening = opening
-        self.hash = try rawBlock.hash()
-        self.signature = signature.bytes
-    }
-
-    public func toAsn1() throws -> [ASN1] {
-        let rawASN1 = try rawData.asn1Values()
-        return rawASN1 + [.octetString(.init(signature))]
-    }
-    
-    public func toData() throws -> Data {
-        try toAsn1().toData()
+        return (rawBlock, .single(signature.bytes), opening)
     }
 
-    public func base64String() throws -> String {
-        try toData().base64EncodedString()
+    private static func blockDataV2(for sequence: [ASN1]) throws -> (RawBlockData, Signature, Bool) {
+        guard let network = sequence[0].integerValue else {
+            throw BlockError.invalidNetwork
+        }
+        let subnet = sequence[1].integerValue
+        
+        let offset = subnet != nil ? 0 : 1
+        
+        guard let anyTime = sequence[2 - offset].generalizedTimeValue else {
+            throw BlockError.invalidDate
+        }
+        guard let purposeRaw = sequence[3 - offset].integerValue,
+                let purpose = Block.Purpose(rawValue: Int(purposeRaw)) else {
+            throw BlockError.invalidPurpose
+        }
+        
+        guard let accountData = sequence[4 - offset].octetStringValue else {
+            throw BlockError.invalidSigner
+        }
+        let account = try Account(data: accountData)
+        
+        let signerContainer = sequence[5 - offset]
+        let signer: Account
+        if signerContainer.isNull {
+            signer = account
+        } else if let signerData = signerContainer.octetStringValue {
+            signer = try Account(data: signerData)
+        } else {
+            // TODO: implement 'this.signer = parseBlockSignerFieldContainer(signersContainer).parsed;'
+            throw NSError(domain: "Multi-signatures not implemented", code: 0)
+        }
+        
+        guard let previousHashData = sequence[6 - offset].octetStringValue else {
+            throw BlockError.invalidHash
+        }
+        let previousHash = previousHashData.toHexString()
+        
+        guard let operationsSequence = sequence[7 - offset].sequenceValue else {
+            throw BlockError.invalidOperationsSequence
+        }
+        let operations = try operationsSequence.map { try BlockOperationBuilder.create(from: $0) }
+        
+        let signatureContainer = sequence[8 - offset]
+        let signature: Signature
+        if let signatureValue = signatureContainer.octetStringValue {
+            signature = .single(signatureValue.bytes)
+        } else {
+            // TODO: implement 'assertBlockSignatureField(signatureContainer);'
+            throw BlockError.invalidSignature
+        }
+        
+        let opening = previousHash == account.publicKeyString
+        
+        let rawBlock = RawBlockData(
+            version: .v2,
+            purpose: purpose,
+            previous: previousHash,
+            network: network,
+            subnet: subnet,
+            signer: signer,
+            account: account,
+            operations: operations,
+            created: anyTime.zonedDate.utcDate
+        )
+        
+        return (rawBlock, signature, opening)
     }
 }