feat: update developer portal for swap

LedgerHQ · May 7, 2024 · deb5dc9 · deb5dc9
1 parent d2125bc
commit deb5dc9
Show file tree

Hide file tree

Showing 6 changed files with 227 additions and 25 deletions.
diff --git a/pages/docs/exchange/swap.mdx b/pages/docs/exchange/swap.mdx
@@ -39,3 +39,4 @@ In the following pages, you will find:
 - [Backend](swap/providers-backend): details on the main endpoints needed for the chosen operation, the payload, the signature, and your public/private key.
 - [Test & Submit](swap/providers-test-and-submit): details on how to use the Ledger Live Developer Mode and other tools (coming soon) to test your integration end-to-end, as well as how to submit it. 
 - [Flow Breakdown](swap/flow): Details UX, advanced flows and architecture diagrams.
+- [Supported Currencies](swap/providers-currencies): List of supported currencies.
diff --git a/pages/docs/exchange/swap/flow/transaction-status.mdx b/pages/docs/exchange/swap/flow/transaction-status.mdx
@@ -11,6 +11,7 @@ As such, the user must be able to follow the status of the swap to avoid having
 The history tab contains the swap transactions for a given Ledger Live instance.
 
 The following information is displayed to the user:
+
 - Date of Swap and time
 - Partner name
 - Source account
@@ -20,6 +21,7 @@ The following information is displayed to the user:
 - Swap status
 
 By clicking on a given swap, more information is displayed:
+
 - **Provider**: Link to the provider’s website
 - **Swap ID**: This information is generated by the partner and sent back to Ledger backend at the swap creation. This ID must be used by the user if they need to contact the partner’s support.
 - **Status**: Detail of Status in the next section.
@@ -31,18 +33,27 @@ By clicking on a given swap, more information is displayed:
 - **Credited amount**: Amount of destination token credited
 - **Provider address**: Destination address of the provider
 
+An url will be made available to the user to get more information about the swap transaction.
+You should provide this url to Ledger, accepting the following query parameters:
+
+- **swapId**: Swap ID
+
 ## Status
 
 Users can check the status of the swap transaction in the history tab. Ledger Live backend calls the partner with the Swap ID to get the status for each transaction (until the transaction is “FINISHED”).
 
 The statuses are:
+
 1. non final
-	- **Pending**: Transaction is ongoing
-	- **OnHold**: Provider has received funds but funds on transaction hold on provider’s side 
+
+- **Pending**: Transaction is ongoing
+- **OnHold**: Provider has received funds but funds on transaction hold on provider’s side
+
 2. final (can’t be changed)
-	- **Expired**: User’s transaction has failed. funds stay in their wallet
-	- **Finished**: Transaction completed and fund sent
-	- **Refunded**: Funds are back in user’s wallet
+
+- **Expired**: User’s transaction has failed. funds stay in their wallet
+- **Finished**: Transaction completed and fund sent
+- **Refunded**: Funds are back in user’s wallet
 
 You can add more detailed statuses (KYC, swap withdrawal failure, network congestion, refund failure, etc) by providing a mapping of your status along with the two status above.
 

diff --git a/pages/docs/exchange/swap/providers-backend.mdx b/pages/docs/exchange/swap/providers-backend.mdx
@@ -4,7 +4,7 @@ import { Tabs } from 'nextra/components'
 import { Callout } from 'nextra/components'
 import BackendIntro from '../../../../public/exchange/import/backend-intro.mdx'
 import PayloadAndSignature from '../../../../public/exchange/import/payload-and-signature.mdx'
- 
+
 # Backend
 
 <BackendIntro />
@@ -14,42 +14,42 @@ import PayloadAndSignature from '../../../../public/exchange/import/payload-and-
 In order to communicate with Ledger’s backend, you must provide standardised APIs for Ledger's SWAP aggregator services to call.
 
 <Callout type="info" emoji="🔗">
-You will find all the information regarding the SWAP endpoints here: https://exchange-integration-swap.redoc.ly/, as well as additional details on some endpoints below. 
+You will find all the information regarding the SWAP endpoints here: https://exchange-integration-swap.redoc.ly/, as well as additional details on some endpoints below.
 </Callout>
 
 There are 5 main endpoints needed for the swap:
-  - To get the list of available currencies: [/currencies](https://exchange-integration-swap.redoc.ly/#operation/getCurrencies).
-  - To get the list of tradable pairs: [/pairs](https://exchange-integration-swap.redoc.ly/#operation/getPairs).
-  - To query a rate: [/quote](https://exchange-integration-swap.redoc.ly/#operation/postQuote).
-  - To create a signed swap binary payload [/swap](https://exchange-integration-swap.redoc.ly/#operation/postSwap).
-  - To query a swap status: [/status](https://exchange-integration-swap.redoc.ly/#operation/getStatus).
 
+- To get the list of available currencies: [/currencies](https://exchange-integration-swap.redoc.ly/#operation/getCurrencies).
+- To get the list of tradable pairs: [/pairs](https://exchange-integration-swap.redoc.ly/#operation/getPairs).
+- To query a rate: [/quote](https://exchange-integration-swap.redoc.ly/#operation/postQuote).
+- To create a signed swap binary payload [/swap](https://exchange-integration-swap.redoc.ly/#operation/postSwap).
+- To query a swap status: [/status](https://exchange-integration-swap.redoc.ly/#operation/getStatus).
 
 <details>
   <summary>Additional Details: GET /pairs</summary>
-    
+
     This endpoint is not required if all permutations returned by [/currencies](https://exchange-integration-swap.redoc.ly/#operation/getCurrencies) are supported.
 
     **Fixed quote**: The quote price is guaranteed until execution (or until end of quote validity period).
 
     **Float quote**: The quote price is indicative only, real price is computed at execution time.
-    
+
 </details>
 
 <details>
   <summary>Additional Details: POST /quote</summary>
-        
+
     All fees are expressed in output currency. For example, during a ETH to USDT on ethereum swap, the fees are expressed in USDT on ethereum.
 
     Some requirements about the **/quote** endpoint:
     - The quote must work without user auth. It can require a Ledger auth.
     - The quote must be valid long enough (at least a few minutes).
-        
+
 </details>
 
 <details>
   <summary>Additional Details: POST /swap</summary>
-            
+
     Your Protobuf message should have the following structure:
 
     ```go copy
@@ -121,17 +121,14 @@ There are 5 main endpoints needed for the swap:
         - `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction)
         - `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
         - `UNKNOWN`: Trade is in unknown state. User must contact support.  
-
-</details>
 
+</details>
 
 [//]: # (Info needed to be exchange with the provider, but not out loud publicly)
 [//]: # (**IP address checking** )
 [//]: # (Additionally, we also need a way to know if a user will be able to perform a coin swap given his IP.)
 [//]: # (Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user’s IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected.)
 
-
-
 ## Payload & Signature
 
 Here is a little diagram to explain how the `payload` and the `signature` are generated:
@@ -150,6 +147,7 @@ Here is a little diagram to explain how the `payload` and the `signature` are ge
 
 - Payload and Signature  
 From the provider to Ledger Live. The payload is a protobuf message containing the trade data. It is generated by the provider and sent to Ledger Live.
+
 ```go copy
 type Payload struct {
   payin_address,      // address (of provider)
@@ -168,13 +166,15 @@ R, S := Sign(payload, privKey)
 
 - Validate  
 Exchange app checks and validates the payload (signature and content).
+
 ```go copy
 // Compare nonce in payload
 Verify((R, S), payload, pubKey)
 ```
 
 - Display  
-Exchange app requests approval to the user by displaying the operation summary on screen. 
+Exchange app requests approval to the user by displaying the operation summary on screen.
+
 ```c copy
 Validate?
 Send currency_from amount_to_provider
@@ -183,3 +183,48 @@ Receive currency_to amount_to_wallet
 
 <PayloadAndSignature />
 
+## Reference Error Codes
+
+REGION_RESTRICTED_ERROR
+- HTTP status code 451
+- Endpoints: `/quote`, `/swap`
+- Description: When the user's IP address is in a restricted region.
+FROM_CURRENCY_MINIMUM_AMOUNT_ERROR
+- HTTP status code 400
+- Endpoints: `/quote`
+- Context: { minSwapAmount: string }
+- Description: When the amount to swap is below the minimum amount.
+- Response
+TO_CURRENCY_MAXIMUM_AMOUNT_ERROR
+- HTTP status code 400
+- Endpoints: `/quote`
+- Context: { maxSwapAmount: string }
+- Description: When the amount to swap is above the maximum amount.
+SWAP_PAIR_NOT_FOUND_ERROR
+- HTTP status code 404
+- Endpoints: `/quote`
+- Description: When the pair is not found.
+CURRENCY_REGION_RESTRICTED_ERROR
+- HTTP status code 451
+- Endpoints: `/quote`
+- Description: When the currency is in a restricted region.
+NO_DEPOSIT_WALLET_ERROR
+- HTTP status code 400
+- Endpoints: `/swap`
+- Description: When the deposit wallet is not available.
+CURRENCY_FROM_NOT_FOUND_ERROR
+- HTTP status code 404
+- Endpoints: `/swap`
+- Description: When the currency from is not found.
+CURRENCY_TO_NOT_FOUND_ERROR
+- HTTP status code 404
+- Endpoints: `/swap`
+- Description: When the currency to is not found.
+SWAP_QUOTE_NOT_FOUND_ERROR
+- HTTP status code 404
+- Endpoints: `/swap`
+- Description: When the swap quote is not found.
+SWAP_TRANSACTION_NOT_FOUND_ERROR
+- HTTP status code 404
+- Endpoints: `/status`
+- Description: When the swap transaction is not found.
diff --git a/pages/docs/exchange/swap/providers-currencies.mdx b/pages/docs/exchange/swap/providers-currencies.mdx
@@ -0,0 +1,24 @@
+import { Tabs } from 'nextra/components'
+import { Callout } from 'nextra/components'
+
+# Supported currencies
+
+## Blockchain Supported
+- bitcoin
+- bitcoin_cash
+- bitcoin_gold
+- bsc
+- dash
+- digibyte
+- dogecoin
+- ethereum
+- litecoin
+- polkadot
+- polygon
+- qtum
+- ripple
+- solana
+- stellar
+- tezos
+- zcash
+- zencash
diff --git a/pages/docs/exchange/swap/providers-liveapp.mdx b/pages/docs/exchange/swap/providers-liveapp.mdx
@@ -58,6 +58,9 @@ The LiveApp URL format is already fixed and will depend on the information you p
   * `initFeeTotalValue`: initial transaction total fee.
   * `customFeeConfig`(optional, required for `CUSTOM` feeStrategy): Custom fee configuration in case the strategy is of type `CUSTOM`. The key-value object is encoded in URI parameter.
   * `ledger-transaction-id`: id used by ledger to track transactions and their completion statuses.
+  * `fiatCurrencyId`: The fiat currency id used as reference for the quote.
+  * `theme`: The theme used in Ledger Live.
+  * `displayLanguage`: The language used in Ledger Live.
 
 __Example__:
 ```
@@ -83,4 +86,4 @@ Your [LiveApp manifest](../../../../APIs/wallet-api/appendix/manifest) should co
 
 ## Flow/UX requirements
 
-Please refer to the [Flow Breakdown](./flow) section for more information. 
+Please refer to the [Flow Breakdown](./flow) section for more information.