add sep-38 support

Soneso · Feb 20, 2024 · 952762a · 952762a
1 parent b3eb5cb
commit 952762a
Show file tree

Hide file tree

Showing 18 changed files with 1,477 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ To integrate stellar SDK into your Xcode project using CocoaPods, specify it in
 use_frameworks!
 
 target '<Your Target Name>' do
-    pod 'stellar-ios-mac-sdk', '~> 2.5.3'
+    pod 'stellar-ios-mac-sdk', '~> 2.5.4'
 end
 ```
 
@@ -44,15 +44,15 @@ $ brew install carthage
 To integrate stellar-ios-mac-sdk into your Xcode project using Carthage, specify it in your `Cartfile`:
 
 ```ogdl
-github "soneso/stellar-ios-mac-sdk" ~> 2.5.3
+github "soneso/stellar-ios-mac-sdk" ~> 2.5.4
 ```
 
 Run `carthage update` to build the framework and drag the build `stellar-ios-mac-sdk.framework` into your Xcode project.
 
 ### Swift Package Manager
 
 ```swift
-.package(name: "stellarsdk", url: "[email protected]:Soneso/stellar-ios-mac-sdk.git", from: "2.5.3"),
+.package(name: "stellarsdk", url: "[email protected]:Soneso/stellar-ios-mac-sdk.git", from: "2.5.4"),
 ```
 
 ### Manual
@@ -666,6 +666,7 @@ Our SDK is also used by the [LOBSTR Wallet](https://lobstr.co).
 - [SEP-0012](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) - Anchor/Client customer info transfer
 - [SEP-0024](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) - Hosted Deposit and Withdrawal
 - [SEP-0030](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md) - Account Recovery
+- [SEP-0038](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md) - Anchor RFQ API
 
 ## Soroban support
 

diff --git a/docs/SEP-0030.md b/docs/SEP-0030.md
@@ -5,7 +5,7 @@ Enables an individual (e.g., a user or wallet) to regain access to a Stellar acc
 [SEP-0030: Account Recovery](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md).
 
 
-## Create a SEP30RecoveryService instance
+## Create a RecoveryService instance
 
 **By providing the recovery server url directly via the constructor:**
 

diff --git a/docs/SEP-0038.md b/docs/SEP-0038.md
@@ -0,0 +1,157 @@
+
+# SEP-0038 - Anchor RFQ API
+
+The [SEP-38](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md) standard defines a way for anchors to provide quotes for the exchange of an off-chain asset and a different on-chain asset, and vice versa. 
+Quotes may be [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) or [firm](https://www.investopedia.com/terms/f/firmquote.asp) ones.
+When either is used is explained in the sections below.
+
+
+## Create a `QuoteService` instance
+
+**By providing the quote server url directly via the constructor:**
+
+```swift
+quoteService = QuoteService(serviceAddress: "http://api.stellar-anchor.org/quote")
+```
+
+## Authentication
+
+Authentication is done using the [Sep-10 WebAuth Service](https://github.com/Soneso/stellar_flutter_sdk/blob/master/documentation/sdk_examples/sep-0010-webauth.md), and we will use the authentication token in the SEP-38 requests.
+
+## Get Anchor Information
+
+First, let's get information about the anchor's support for [SEP-38](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md). The response gives what stellar on-chain assets and off-chain assets are available for trading.
+
+```swift
+quoteService.info(jwt: jwtToken) { (response) -> (Void) in
+    switch response {
+    case .success(let response):
+        let assets = response.assets;
+        // ...
+    case .failure(let err):
+       // ...
+    }
+}
+```
+
+## Asset Identification Format
+
+Before calling other endpoints we should understand the scheme used to identify assets in this protocol. The following format is used:
+
+`<scheme>:<identifer>`
+
+The currently accepted scheme values are `stellar` for Stellar assets, and `iso4217` for fiat currencies.
+
+For example to identify USDC on Stellar we would use:
+
+`stellar:USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`
+
+And to identify fiat USD we would use:
+
+`iso4217:USD`
+
+Further explanation can be found in [SEP-38 specification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md#asset-identification-format).
+
+## Get Prices
+
+Now let's get [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) prices from the anchor in exchange for a given asset. This is an indicative price. The actual price will be calculated at conversion time once the Anchor receives the funds from a user.
+
+In our example we're getting prices for selling 5 fiat USD.
+
+```swift
+quoteService.prices(sellAsset: "iso4217:USD",
+                    sellAmount: "5",
+                    jwt: jwtToken) { (response) -> (Void) in
+
+    switch response {
+    case .success(let response):
+        let buyAssets = response.buyAssets;
+        // ...
+    case .failure(let err):
+       // ...
+    }
+}
+```
+
+The response gives the asset prices for exchanging the requested sell asset.
+
+## Get Prices
+
+Next, let's get an [indicative](https://www.investopedia.com/terms/i/indicativequote.asp) price for a certain pair.
+
+Once again this is an indicative value. The actual price will be calculated at conversion time once the Anchor receives the funds from a User.
+
+Either a `sellAmount` or `buyAmount` value must be given, but not both. And `context` refers to what Stellar SEP context this will be used for (ie. `sep6`, `sep24`, or `sep31``).
+
+```swift
+quoteService.price(
+                context:"sep6",
+                sellAsset: "iso4217:USD",
+                buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
+                sellAmount: "5",
+                jwt: jwtToken) { (response) -> (Void) in
+
+    switch response {
+    case .success(let response):
+        let totalPrice = response.totalPrice
+        // ...
+    case .failure(let err):
+       // ...
+    }
+}
+```
+
+The response gives information for exchanging these assets.
+
+## Post Quote
+
+Now let's get a [firm](https://www.investopedia.com/terms/f/firmquote.asp) quote from the anchor. 
+As opposed to the earlier endpoints, this quote is stored by the anchor for a certain period of time. 
+We will show how we can grab the quote again later.
+
+```swift
+var request = Sep38PostQuoteRequest(
+    context: "sep31",
+    sellAsset: "iso4217:USD", 
+    buyAsset: "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B")
+
+request.sellAmount = "5"
+
+
+quoteService.postQuote(request: request, jwt: jwtToken) { (response) -> (Void) in
+
+    switch response {
+    case .success(let response):
+        let quoteId = response.id;
+        let expirationDate = response.expiresAt;
+        let totalPrice = response.totalPrice;   
+        // ...
+    case .failure(let err):
+       // ...
+    }
+}
+// ...
+```
+However now the response gives an `id` that we can use to identify the quote. The `expiresAt` field tells us how long the anchor will wait to receive funds for this quote.
+
+## Get Quote
+
+Now let's get the previously requested quote. To do that we use the `id` from the `.postQuote()` response.
+
+```swift
+quoteService.getQuote(id: quoteId, jwt: jwtToken) { (response) -> (Void) in
+
+    switch response {
+    case .success(let response):
+        let totalPrice = response.totalPrice;   
+        // ...
+    case .failure(let err):
+       // ...
+    }
+}
+```
+The response should match the one given from `.postQuote()` we made earlier.
+
+### Further readings
+
+For more info, see also the class [QuoteService](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/stellarsdk/stellarsdk/quote/QuoteService.swift) and the SDK's [SEP-38 test cases](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/stellarsdk/stellarsdkTests/quote/QuoteServiceTestCase.swift).
diff --git a/docs/seps.md b/docs/seps.md
@@ -14,7 +14,8 @@ This SDK provides implementations of following SEPs:
 - [SEP-0011](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0011.md) - Txrep
 - [SEP-0012](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) - Anchor/Client customer info transfer
 - [SEP-0024](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) - Hosted Deposit and Withdrawal
-
+- [SEP-0030](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md) - Account Recovery
+- [SEP-0038](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md) - Anchor RFQ API (Quotes)
 
 # Stellar Info File - SEP-0001
 
@@ -402,4 +403,12 @@ You can find more source code examples regarding SEP-0011 in this [SDK test case
 
 # Hosted Deposit and Withdrawal
 
-see [SEP-24 - interactive](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs/SEP-0024.md)
+see [SEP-24 - interactive](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs/SEP-0024.md)
+
+#  Account Recovery
+
+see [SEP-30 - Account Recovery](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs/SEP-0030.md)
+
+#  Quotes
+
+see [SEP-38 - Anchor RFQ API](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs/SEP-0038.md)
diff --git a/stellar-ios-mac-sdk.podspec b/stellar-ios-mac-sdk.podspec
@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
   #
 
   s.name         = "stellar-ios-mac-sdk"
-  s.version      = "2.5.3"
+  s.version      = "2.5.4"
   s.summary      = "Fully featured iOS and macOS SDK that provides APIs to build transactions and connect to Horizon server for the Stellar ecosystem."
   s.module_name  = 'stellarsdk'
   s.swift_version = '5.0'