diff --git a/README.md b/README.md index 81473e8..204bb72 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Interact with the XUMM SDK from Javascript / Typescript environments. #### **Please note! The XUMM SDK (XUMM API in general) is for BACKEND USE only. Please DO NOT use your API credentials in a FRONTEND environment.** -
To implement the XUMM SKD (or XUMM API directly) in your own web project, make sure your frontend calls your own backend, where the follow up +
To implement the XUMM SDK (or XUMM API directly) in your web project, make sure your frontend calls your backend, where the follow up communication with the XUMM SDK (or XUMM API) will take place. Your XUMM credentials should never be publicly available.
## How to use the XUMM SDK @@ -34,7 +34,7 @@ const Sdk = new XummSdk() ### Credentials -The SDK will look in your environment or dotenv file (`.env`) for the `XUMM_APIKEY` and `XUMM_APISECRET` values. A `.env.sample` file is provided in this repository. A [sample dotenv file looks like this](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/.env.sample). Alternatively you can provide your XUMM API Key & Secret by passing them to the XummSdk constructor. If both your environment and the SDK constructor contain credentials, the values provided to the constructor will be used. +The SDK will look in your environment or dotenv file (`.env`) for the `XUMM_APIKEY` and `XUMM_APISECRET` values. A `.env.sample` file is provided in this repository. A [sample dotenv file looks like this](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/.env.sample). Alternatively, you can provide your XUMM API Key & Secret by passing them to the XummSdk constructor. If both your environment and the SDK constructor contain credentials, the values provided to the constructor will be used. Create your app and get your XUMM API credentials at the XUMM Developer Console: @@ -82,7 +82,7 @@ Returns [``](https://github.com/XRPL-Labs/XUMM-SDK/blob/mast ##### Sdk.getCuratedAssets() The `getCuratedAssets` method allows you to get the list of trusted issuers and IOU's. This is the same list used to -populate the "Add Asset" button at the XUMM home screan. +populate the "Add Asset" button at the XUMM home screen. ```typescript const curatedAssets = await Sdk.getCuratedAssets() @@ -108,8 +108,8 @@ Returns [``](https://github.com/XRPL-Labs/XUMM-SDK/blob/m The `getKycStatus` return the KYC status of a user based on a user_token, issued after the user signed a Sign Request (from your app) before (see Payloads - Intro). -If a user token specified is invalid, revoked, expired, etc. the method will always -return `NONE`, just like when a user didn't go through KYC. You cannot distinct a non-KYC'd user +If a user token specified is invalid, revoked, expired, etc., the method will always +return `NONE`, just like when a user didn't go through KYC. You cannot distinguish a non-KYC'd user from an invalid token. Alternatively, KYC status can be retrieved for an XPRL account address: the address selected in @@ -128,8 +128,8 @@ Returns [``](https://github.com/XRPL-Labs/XUMM-SDK/bl ###### Notes on KYC information -- Once an account has successfully completed the XUMM KYC flow, the KYC flag will be applied to the account even if the identity document used to KYC expired. The flag shows that the account was **once** KYC'd by a real person with a real identity document. -- Please note that the KYC flag provided by XUMM can't be seen as a "all good, let's go ahead" flag: it should be used as **one of the data points** to determine if an account can be trusted. There are situations where the KYC flag is still `true`, but an account can no longer be trusted. Eg. when account keys are compromised and the account is now controlled by a 3rd party. While unlikely, depending on the level of trust required for your application you may want to mitigate against these kinds of fraud. +- Once an account has completed the XUMM KYC flow, the KYC flag will be applied to the account even if the identity document used to KYC expired. The flag shows that the account was **once** KYC'd by a real person with a real identity document. +- Please note that the KYC flag provided by XUMM can't be seen as a "all good, let's go ahead" flag: it should be used as **one of the data points** to determine if an account can be trusted. There are situations where the KYC flag is still `true`, but an account can no longer be trusted. Eg. when account keys are compromised and a 3rd party now controls the account. While unlikely, depending on the level of trust required for your application you may want to mitigate against these kinds of fraud. ##### Sdk.getTransaction() @@ -147,7 +147,7 @@ Returns: ``](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/ #### App Storage -App Storage allows you to store a JSON object at the XUMM API platform, containing max 60KB of data. +App Storage allows you to store a JSON object at the XUMM API platform, containing a max of 60KB of data. Your XUMM APP storage is stored at the XUMM API backend, meaning it persists until you overwrite or delete it. This data is private, and accessible only with your own API credentials. This private JSON data can be used to store credentials / config / bootstrap info / ... for your headless application (eg. POS device). @@ -190,7 +190,7 @@ A payload can contain an XRPL transaction template. Some properties may be omitt } ``` -As you can see the payload looks like a regular XRPL transaction, wrapped in an `txjson` object, omitting the mandatory `Account`, `Fee` and `Sequence` properties. They will be added containing the correct values when the payload is signed by an app user. +As you can see, the payload looks like a regular XRPL transaction, wrapped in an `txjson` object, omitting the mandatory `Account`, `Fee` and `Sequence` properties. They will be added containing the correct values when the payload is signed by an app user. Optionally (besides `txjson`) a payload can contain these properties ([TS definition](https://github.com/XRPL-Labs/XUMM-SDK/blob/d2aae98eb8f496f4d77079c777aa41df754d4ebc/src/types/xumm-api/index.ts#L79)): @@ -267,7 +267,7 @@ The response (see: [Developer Docs](https://xumm.readme.io/docs/payload-response The `next.always` URL is the URL to send the end user to, to scan a QR code or automatically open the XUMM app (if on mobile). If a `user_token` has been provided as part of the payload data provided to `Sdk.payload.create()`, you can see if the payload has been pushed to the end user. A button "didn't receive a push notification" could then take the user to the `next.no_push_msg_received` URL. The -Alternatively user routing / instruction flows can be custom built using the QR information provided in the `refs` object, and a subscription for live status updates (opened, signed, etc.) using a WebSocket client can be setup by conneting to the `refs.websocket_status` URL. **Please note: this SDK already offers subscriptions. There's no need to setup your own WebSocket client, see [Payload subscriptions: live updates](#payload-subscriptions-live-updates).** There's more information about the [payload workflow](https://xumm.readme.io/docs/payload-workflow) and a [paylaod lifecycle](https://xumm.readme.io/docs/doc-payload-life-cycle) in the Developer Docs. +Alternatively, user routing / instruction flows can be custom-built using the QR information provided in the `refs` object, and a subscription for live status updates (opened, signed, etc.) using a WebSocket client can be setup by connecting to the `refs.websocket_status` URL. **Please note: this SDK already offers subscriptions. There's no need to setup your own WebSocket client, see [Payload subscriptions: live updates](#payload-subscriptions-live-updates).** There's more information about the [payload workflow](https://xumm.readme.io/docs/payload-workflow) and a [paylaod lifecycle](https://xumm.readme.io/docs/doc-payload-life-cycle) in the Developer Docs. ##### Sdk.payload.cancel