From 9d7d20371c72b2a5dad48a47891c2a7f64904fb9 Mon Sep 17 00:00:00 2001 From: Alec Charbonneau Date: Thu, 4 Jan 2024 12:42:30 -0800 Subject: [PATCH] add sep38 docs (#289) --- docs/building-apps/wallet/sep38.mdx | 198 ++++++++++++++++++++++++++++ docs/building-apps/wallet/sep6.mdx | 2 +- 2 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 docs/building-apps/wallet/sep38.mdx diff --git a/docs/building-apps/wallet/sep38.mdx b/docs/building-apps/wallet/sep38.mdx new file mode 100644 index 000000000..004d2364f --- /dev/null +++ b/docs/building-apps/wallet/sep38.mdx @@ -0,0 +1,198 @@ +--- +title: Quote +sidebar_position: 70 +--- + +import { LanguageSpecific } from "@site/src/components/LanguageSpecific"; + +import { WalletCodeExample as CodeExample } from "@site/src/components/WalletCodeExample"; +import Header from "./component/header.mdx"; + +
+ +The [SEP-38] 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. + +## Creating Sep-38 Object + +Let's start with creating a sep38 object, which we'll use for all SEP-38 interactions. Authentication is optional for these requests, and depends on the anchor implementation. For our example we will include it. + +Authentication is done using [Sep-10], and we add the authentication token to the sep38 object. + + + +```typescript +const accountKp = ... // our account keypair + +const auth = await anchor.sep10(); +const authToken = await auth.authenticate({ accountKp }); +const sep38 = anchor.sep38(authToken); +``` + + + +## Get Anchor Information + +First, let's get information about the anchor's support for [SEP-38]. The response gives what stellar on-chain assets and off-chain assets are available for trading. + + + +```typescript +const resp = await sep38.info(); +``` + + + +For example a response will look like this. The asset identifiers are described below in [Asset Identification Format](#asset-identification-format). + +``` +{ + assets: [ + { + asset: 'stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B' + }, + { + asset: 'iso4217:USD', + country_codes: [Array], + sell_delivery_methods: [Array], + buy_delivery_methods: [Array] + } + ] +} +``` + +## Asset Identification Format + +Before calling other endpoints we should understand the scheme used to identify assets in this protocol. The following format is used: + +``` +: +``` + +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. + + + +```typescript +const resp = await sep38.prices({ + sell_asset: "iso4217:USD", + sell_amount: "5", +}); +``` + + + +The response gives the asset prices for exchanging the requested sell asset. For example, a response look like this: + +``` +{ + "buy_assets": [ + { + "asset": "stellar:USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", + "price": "5.42", + "decimals": 7 + } + ] +} +``` + +## Get Price + +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`). + + + +```typescript +const resp = await sep38.price({ + sellAsset: "iso4217:USD", + buyAsset: + "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B", + sellAmount: "5", + context: "sep6", +}); +``` + + + +The response gives information for exchanging these assets. For example, a response will look like this: + +``` +{ price: '1.18', sell_amount: '5.00', buy_amount: '4.24' } +``` + +## 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. + +The request body is similar to the `.price()` call we made earlier. + + + +```typescript +const requestResp = await sep38.requestQuote({ + sell_asset: "iso4217:USD", + buy_asset: + "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B", + sell_amount: "5", + context: "sep6", +}); +``` + + + +However now the response gives an `id` that we can use to identify the quote. The `expires_at` field tells us how long the anchor will wait to receive funds for this quote. + +An example response looks like this: + +``` +{ + id: '019417b3-91ce-473a-929f-15e19470733a', + price: '0.81', + expires_at: '2024-01-03T20:34:48.190481Z', + sell_asset: 'iso4217:USD', + buy_asset: 'stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B', + sell_amount: '5.00', + buy_amount: '6.17' +} +``` + +## Get Quote + +Now let's get the previously requested quote. To do that we use the `id` from the `.requestQuote()` response. + + + +```typescript +const quoteId = requestResp.id; +const getResp = await sep38.getQuote(quoteId); +``` + + + +The response should match the one given from `.requestQuote()` we made earlier. + +[sep-10]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md +[sep-38]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md diff --git a/docs/building-apps/wallet/sep6.mdx b/docs/building-apps/wallet/sep6.mdx index 22581bd5d..2a94a141e 100644 --- a/docs/building-apps/wallet/sep6.mdx +++ b/docs/building-apps/wallet/sep6.mdx @@ -21,7 +21,7 @@ Let's start with creating a sep6 object, which we'll use for all SEP-6 interacti ```typescript -const sep6 = await anchor.sep6(); +const sep6 = anchor.sep6(); ```