Merge pull request #2 from sublabdev/dev

Initial release

Author: Alex Oakley

.gitignore

@@ -1,7 +1,11 @@
+.DS_Store
+
 # Xcode
 #
 # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
 
+.DS_Store
+
 ## User settings
 xcuserdata/
 

Doc/RpcClient.md

@@ -0,0 +1,84 @@
+### RpcClient Example
+
+Bellow is provided an example of RPC client that handles sending requests using several different ways.
+
+## Initialization
+
+First of all, we need to create the client. `RpcClient`'s initializer takes two parameters. The
+first one is the required `URL`, and the second one is a `URLSession` which is predefined and
+can be omitted during the initialization (the `shared` session is used, by default).
+Here is how the client can be created:
+```Swift
+guard let url = URL(string: "https://www.example.com") else { return }
+let client = RpcClient(url: url)
+```
+
+## Usage
+
+After creating the client, we can send requests. There are 2 ways to do that.
+
+The first option is to use `RpcRequest` object. It's a wrapper object that encapsulates all the
+necessary data for RPC requests. Here is how it looks like:
+
+```Swift
+struct RpcRequest<T: Codable>: Codable {
+    var jsonrpc = "2.0"
+    let id: Int64
+    let method: String
+    var params: T
+}
+```
+
+As you can see, it has four properties. The first one is the `JSON RPC` version, which is
+by default set to `2.0`. The second one is the request's `id`. The third one is the `method`
+for which we want to get a response. The last one is a generic parameter called `params` which can
+be any type conforming to `Codable`.
+
+Also, there is an "empty" object `None` that conforms to `Codable` which can be used for cases
+when there is no parameter is required for the request.
+
+Here is how one could create the request:
+```Swift
+let method = "state_getMetadata"
+let id: Int64 = 0
+let request = RpcRequest(
+            id: id,
+            method: method,
+            params: Nothing()
+        )
+```
+
+After we have the `request`, we can send it using the `client`'s `send` method. It has two parameters
+the first of which the `request` itself, and the second on is the completion with either the request's optional result or `RpcError`.
+The result contains a response of type `RpcResponse`. It like the `request` has four parameters.
+
+```Swift
+struct RpcResponse<T: Codable>: Codable {
+    let jsonrpc: String
+    let id: Int64
+    var result: T? = nil
+    var error: RpcResponseError? = nil
+}
+```
+The first one is the `JSON RPC` version. The second one is the response's `id`. The third on
+is the `result` which is of a generic type, which conforms to `Codable`. And the last one
+is an optional `RpcResponseError`.
+
+Here is how the request is made by using `RpcRequest` object defined earlier.
+
+```Swift
+client.send(request) { (response: RpcResponse<String>?, error: RpcError?) in
+    // Do something with the response or the error
+ }
+```
+
+Another way of making a request is to use the `client`'s `sendRequest` method. It receives two
+parameters. The first one is the method for which we want to get a response, and the second one
+is the completion with a generic optional `Result`, conforming to `Codable` or optional `RpcError`.
+
+```Swift
+client.sendRequest(method: method) { (response: String?, error: RpcError?) in
+    // Do something with the result or error
+}
+```
+

Doc/RuntimeMetadata.md

@@ -0,0 +1,47 @@
+### RuntimeMetadata example
+
+Bellow is provided an example of how RPC client can be used to fetch runtime metadata.
+
+*NOTE:* `CommonSwift` library can be found [here](https://github.com/sublabdev/common-swift).
+The `hex` extension for `String` is defined in `CommonSwift` library.
+`ScaleCodecSwift` library can be found [here](https://github.com/sublabdev/scale-codec-swift). `ScaleCoder` is defined in `ScaleCodecSwift` library.
+
+## Initialization
+
+First of all, we need to create the client. `RpcClient`'s initializer takes two parameters. The
+first one is the required `URL`, and the second one is a `URLSession` which is predefined and
+can be omitted during the initialization (the `shared` session is used, by default).
+Here is how the client can be created:
+```Swift
+guard let url = URL(string: "https://www.example.com") else { return }
+let client = RpcClient(url: url)
+```
+
+## Usage
+
+After getting the client, we can send requests. For that we will use the `client`'s `sendRequest` method.
+It receives two parameters. The first one is the method for which we want to get a response, and the second one
+is the completion with a generic optional `Result`, conforming to `Codable` or optional `RpcError`.
+If we have a response, we try to get a metadata from it.
+
+```Swift
+client.sendRequest(method: method) { [weak self] (response: String?, error: RpcError?) in
+    guard let string = response else { return }
+
+        do {
+          guard let hexData = string.hex.decode() else { return }
+
+          let codec = ScaleCoder.defaultCoder()
+          let runtimeMetadata = codec.decoder.decode(RuntimeMetadata.self, from: hexData)
+
+          // Do something with the metadata
+        } catch let error {
+          // Do something with the error
+    }
+}
+```
+
+To get a metadata from the response first we try to decode the hex-encoded string (result from the request above).
+After doing that we decode the decoded data to `RuntimeMetadata` object.
+`RuntimeMetadata` holds all the necessary information for the metadata. It has a magic number,
+version, runtime lookup, an array of runtime modules and a runtime extrinsic.

Doc/SubstrateConstantsService.md

@@ -0,0 +1,92 @@
+### SubstrateConstantsService example
+
+Bellow is provided an example of how `SubstrateConstantsService` can be used to get runtime module
+constant and/or it's value bytes decoded to a specified generic type `T` conforming to `Codable`.
+
+## Initialization
+
+First of all, we need to create the client. `SubstrateClient`'s initializer takes two parameters.
+The first one is the required `URL`, and the second one is settings. It helps to define how the
+data should be fetched and how it should be handled after that and on which dispatch queue
+the results should be returned. It has a static func `default()`
+which provides the settings with a default configuration. In this case the main
+thread is used. There is another method called `default(clientQueue:)` where a custom
+queue can be created. The settings parameter in`SubstrateClient`'s
+initializer is predefined and set to default.
+
+Here is how one could create a client:
+
+```Swift
+guard let url = URL(string: network.endpointInfo.url) else { return nil }
+let client = SubstrateClient(url: url)
+```
+or 
+
+```Swift
+let client = SubstrateClient(url: url, settings: SubstrateClientSettings.default(clientQueue: DispatchQueue(label: "Some queue"))
+```
+
+The client has a property called `module` from where we can get access to an interface for getting
+`RuntimeMetadata` and fetching `StorageItems`.
+
+Next we need to get `SubstrateConstantsService`. To do that we can call
+`constantsService(completion:)` method on the client. It will return a ready service to be used:
+
+```Swift
+client.constantsService { constantService in
+    // Do something with the service
+}
+```
+Before taking a look how to use the service, it's worth mentioning that runtime
+module constant is defined by the following object:
+```Swift
+public class RuntimeModuleConstant: Codable {
+    let name: String
+    let type: BigUInt
+    let valueBytes: [UInt8]
+    let docs: [String]
+
+    init(name: String, type: BigUInt, valueBytes: [UInt8], docs: [String]) {
+        self.name = name
+        self.type = type
+        self.valueBytes = valueBytes
+        self.docs = docs
+    }
+}
+```
+It's `valueBytes` property is decoded into a specified generic `T` type.
+
+## Usage
+
+Now, when we have all the required components, we can start getting the constants. To do that
+we should call `fetch(moduleName:constantName:completion:)` method on `SubstrateConstantsService`.
+This method finds a runtime module constant by the constant's name in a specified module
+and in its completion it returns the module's value bytes decoded into a specified type.
+
+```Swift
+try constantService.fetch(
+            moduleName: constant.module,
+            constantName: constant.constant
+        ) { (storageItem: T?) in
+          // Do something with the storage item
+        }
+```
+
+Also, it's possible to get `RuntimeModuleConstant` object itself, to access
+it's other properties.
+
+```Swift
+try constantService.find(
+            moduleName: constant.module,
+            constantName: constant.constant
+        ) { runtimeModuleConstant in
+          // Do something with the runtime module constant
+        }
+```
+
+After that, the module constant can be used to get a decoded object of a
+generic type `T` from it's `valueBytes` property.
+
+```Swift
+let fetchedValue = try service.fetch(T.self, constant: runtimeModuleConstant)
+```

Doc/SubstrateExtrinsicsService.md

@@ -0,0 +1,54 @@
+### SubstrateExtrinsicsService example
+
+Bellow is provided an example of how `SubstrateExtrinsicsService` can be used to get extrinsics.
+
+## Initialization
+
+First of all, we need to create the client. `SubstrateClient`'s initializer takes two parameters.
+The first one is the required `URL`, and the second one is settings. It helps to define how the
+data should be fetched and how it should be handled after that and on which dispatch queue
+the results should be returned. It has a static func `default()`
+which provides the settings with a default configuration. In this case the main
+thread is used. There is another method called `default(clientQueue:)` where a custom
+queue can be created. The settings parameter in`SubstrateClient`'s
+initializer is predefined and set to default.
+
+Here is how one could create a client:
+
+```Swift
+guard let url = URL(string: network.endpointInfo.url) else { return nil }
+let client = SubstrateClient(url: url)
+```
+
+or
+
+```
+let client = SubstrateClient(url: url, settings: SubstrateClientSettings.default(clientQueue: DispatchQueue(label: "Some queue"))
+```
+
+## Usage
+
+Now when we have the client, we can get the extrinsics service.
+
+```Swift
+client.extrinsicsService { [weak self] extrinsicsService in
+        // Do something with the extrinsics service
+    }
+```
+
+After getting the extrinsics service, we can get an unsigned extrinsic itself.
+
+```Swift
+extrinsicsService.makeUnsigned(
+                moduleName: "moduleName",
+                callName: "callName",
+                callValue: T
+            ) { unsigned in
+                // Do something with the unsigned extrinsic
+            }
+```
+
+The method takes a module name and a call name as `String`s and a call value
+of a generic type `T` conforming to `Codable`. The last parameter of the method
+is a completion closure with an unsigned extrinsic on our specified queue on
+the client above.

Doc/SubstrateStorageService.md

@@ -0,0 +1,79 @@
+### SubstrateStorageService example
+
+Bellow is provided an example of how `SubstrateStorageService` can be used to get a storage item.
+
+## Initialization
+
+First of all, we need to create the client. `SubstrateClient`'s initializer takes two parameters.
+The first one is the required `URL`, and the second one is settings. It has a static func `default()`
+which provides the settings with a default configuration. In this case the main
+thread is used. There is another method called `default(clientQueue:)` where a custom
+queue can be created. The settings parameter in`SubstrateClient`'s
+initializer is predefined and set to default.
+
+Here is how one could create a client:
+
+```Swift
+guard let url = URL(string: network.endpointInfo.url) else { return nil }
+let client = SubstrateClient(url: url)
+```
+
+or
+
+```Swift
+let client = SubstrateClient(url: url, settings: SubstrateClientSettings.default(clientQueue: DispatchQueue(label: "Some queue"))
+```
+
+The client has a property called `module` from where we can get access to an interface for getting
+`RuntimeMetadata` and fetching `StorageItems`.
+
+After the client is created, we need to create a substrate storage service. It can be done
+by calling `storageService(completion:)` method on the client. It's completion closure has
+one parameter which ia `SubstrateStorageService` object.
+
+```Swift
+client.storageService { storageService in
+}
+```
+
+## Usage
+
+Now, when we have all the required components, we can start getting storage items. To do that
+we should call `fetch(moduleName:itemName:keys:completion)` method on `SubstrateStorageService`.
+This method's completion has either a response of optional generic type `T` which conforms to
+`Codable` or an optional `RpcError`.
+
+```Swift
+let keysExample: [Data] = []
+storageService.fetch(
+            moduleName: "timestamp",
+            itemName: "now",
+            keys: keysExample
+        ) { (response: T?, error: RpcError?) in
+            // Do something with the response or with the error
+        }
+```
+
+Also, it is possible to fetch the wrapper object (`FindStorageItemResult`) over
+runtime module storage item and runtime module storage itself separately to have
+a more control over the process.
+
+```Swift
+let result = try storageService.find(moduleName: "timestamp", itemName: "now")
+```
+
+And after that the fetching method can be called on the service using the data from
+the `result` above
+
+```Swift
+guard let storage = result?.storage, let resultItem = result?.item else { return }
+    do {
+        try service.fetch(
+            item: resultItem,
+            keys: item.keys,
+            storage: storage
+            ) { (response: T?, error: RpcError?)  in
+            // Do something with the response or with the error
+        }
+    }
+```