Once we establish connection to the XUMM platform using XUMM SDK, its time to actually learn about sending payload. Payload is nothing buy “transaction template”.
What is a Payload or “Transaction Template”?
Think of Payload or “Transaction Template” as invoice. The minimum things which an invoice should include are: 1. What kind of an invoice it is. 2. The destination address for payment.
We could even leave the amounts section empty assuming that the client will fill it.
This is the bare minimal Payload or Transaction template we can write. It has transaction type and destination address(XRP address). The keywords “TransactionType”: “Payment” and “Destination” should be formatted as per XRP ledger transaction specifications.
If we don’t mention amount in our payload, end user can edit and enter the amount himself or herself after opening the payload request using their XUMM App. If we mention the amount in payload or transaction template, then he or she will not be able to edit it while signing.
Signing simply means authorizing the payment request. Or authorizing the sign request.
Here we’ve explicitly mentioned the “Amount” which is 1 Million, which means 1 XRP. i.e., one XRP is one million Drops. And a Memo (HEX encoded string). TransactionType and Destination are mandatory fields, all other fields are optional.
1. A payload (sign request) sent to the XUMM platform should be formatted as per XRP ledger transaction specifications, but some fields may be omitted as XUMM will automatically fill them in if able to do so.
2. Usually, a payload sent to the XUMM platform will be signed by the end user (e.g., for a sign in, subscription, payment, escrow creation etc). For this tutorial, you will be the initiator and the end user, either signing or rejecting your own payload.
3. The first sign request from a specific XUMM app will always have to be scanned using a QR code on the desktop. Once an end user trusts your application, by signing your sign request, your application can obtain a user specific user token to deliver future sign requests using push notification.
Here we are making use of Sdk.payload.create() method to generate sign request URL and QR code and other outputs. We pass 2 arguments to Sdk.payload.create(). First argument is the payload or the transaction template(in above code the constant by name request), and the second argument will be a flag (boolean, true) telling the code to return an error, if one occurs.
Running The Application
We issue the command node index.js to run our application and we get the following output: payload
Your output will be different, and most part of this output will be unique. The output at payload.next.always is the sign request URL. payload.refs.qr_png is the QR code which has sign request information encoded. payload.pushed is false as this is the first time we are sending payload to the end user and we do not yet have the user token. We get the user token if the user successfully signs the sign request. We store this user token, which is specific to XUMM platform and from next time we can send sign request as push notification to the end users mobile device.
Action Steps
Now you can open YOUR payload output and navigate to payload.next.always or payload.refs.qr_png, open the XUMM app present on your mobile phone, scan the QR code and sign or reject the sign request and check for the status changes at payload.next.always URL.
Benefits of using XUMM Platform for our Application
1. DEX or any site can make use of XUMM “sign” transaction type for authorization – for example, for signing up for a DEX account or for creating an account on an app etc.
2. We can use XUMM platform to create and accept payments and/or subscription services.
3. Once the user signs/authorizes our first sign request, we can start sending payments/sign requests as push notification directly to their XUMM app in their mobile devices. That’s so convenient and seamless payments experience.
Lets write a nodejs program to fetch application details from XUMM platform. We’ll also see how to retrieve all the IOU details using single line of code.
Video Tutorial: Send Ping Request To XUMM Platform and Get Application Details
We are writing a asynchronous function and the child process waits for the result from Sdk.ping() method. Once the result is retrieved, the result is printed on to the console window.
Since we are writing asynchronous method, we need to use await keyword to wait for the result or the promise to be resolved.
If we do not write the await keyword, you’ll get the following result:
IOU means “I owe you”. An “issuer” is the one who owe you, if you get funds as IOU transaction on XRP Ledger.
The acronym IOU stands for “I owe you” and refers to an informal document that acknowledges a debt one party owes to another.
When you run above code you can, programmatically, get to see all the supported IOU’s on XUMM platform. You can even get the issuer details, currency symbol and the name of the currency – just by running a single line of code.
IOU Details From Above Output
Bitstamp supports following currencies: 1. USD(US Dollar) 2. BTC(Bitcoin).
Towo Labs supports following currency: 1. XTK(XTK)
Sologenic supports following currency: 1. SOLO(SOLO)
Wietse supports following currency: 1. WIE(Wietse)
Here ‘Bitstamp’, ‘GateHub’, ‘Towo Labs’, ‘Sologenic’, ‘Wietse’ are the issuers of the respective currencies. So you can transact above currencies on XRP Ledger via XUMM application.
As you can see from above examples, we’re successfully able to connect and communicate with XUMM platform. So in our next video tutorial lets send a simple PAYLOAD. More on that in next video tutorial, stay subscribed to our blog and YouTube channel.
console.log("WELCOME TO XUMM SDK/API VIDEO TUTORIALS!")
console.log("WELCOME TO XUMM SDK/API VIDEO TUTORIALS!")
Running Node Application Command
>node index.js
>node index.js
Output WELCOME TO XUMM SDK/API VIDEO TUTORIALS!
If you get above output then your installation is working correctly. Lets move forward.
Installing xumm-sdk Package
Lets install xumm-sdk node package and try to connect with XUMM platform.
npm install xumm-sdk
npm install xumm-sdk
It might take couple of seconds to couple of minutes depending on your internet connection speed. So you may have to wait patiently.
Error Message: Your npm doesn’t work with the version of Node
If you start getting error messages like: “npm WARN npm npm does not support Node.js” Just download lower version of Nodejs and try to run the program once again. In most of the cases the issue will be resolved.
Source Code: Importing xumm-sdk package into our project
const Sdk = new XummSdk('Your-API-Id', 'Your-API-Secret')
const main = async () => {
console.log('XUMM SDK VIDEO TUTORIALS!')
}
main()
const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('Your-API-Id', 'Your-API-Secret')
const main = async () => {
console.log('XUMM SDK VIDEO TUTORIALS!')
}
main()
Run The Application Command
>node index.js
>node index.js
Output XUMM SDK VIDEO TUTORIALS!
In the first line, we are importing xumm-sdk package. Next we create an instance of XummSdk, by passing XUMM application credentials.
Next we write a asynchronous function, which creates a child progress or a thread and waits for the response. Meanwhile the main thread or the main process continues to execute the code after it.
In above code, we simply output a message to the console window.
Note: By connecting to XUMM platform we can indirectly interact with XRP Ledger(XRPL).
To start working with XUMM SDK and API, the first thing you’ll need is application credentials. Application credentials are: App ID and App Secret, which you’ll get once you signup and register your application at apps.xumm.dev
Application Creation: XUMM Platform
All the application details can be modified later after creating the application, so need not stress too much to get it perfect the first time. You can even re-upload the application icon later on.
You can register multiple applications inside single xumm developer account. And you can also delete the registered application, by visiting the applications details page.
1. You can get App ID any time you log into your XUMM developer dashboard, but App Secret will be shown to you only once. i.e., when you create your application you’ll be shown the App Secret, after that it’ll be permanently hidden. You need to copy and paste it in safe place.
2. Please do not place your application credentials in client side code. These credentials are meant to be in server side code. If you place it in client side code, someone can get hold of it and use it for wrong things.
3. If you think your application credentials are compromised, then you can log into your xumm developer dashboard and generate a new one. Once you generate new App Secret, do not forget to replace the old one in your application.
4. Make sure to keep checking the LOGS and PAYLOADS section inside your XUMM developer dashboard.
That’s where you’ll get valuable information about your program execution. Whenever you encounter a bug in your code, check the terminal output and then immediately check the LOGS and PAYLOADS section inside your XUMM developer account. It’ll have valuable information which can help you fix the issue sooner.
Note: Using your Application credentials you can connect to XUMM platform and then interact with XRP Ledger(XRPL) via XUMM SDK/API.
XRP Ledger(XRPL) was developed by Ripple founders and is now open sourced.
Ripple is a real-time gross settlement system, currency exchange and remittance network created by Ripple Labs Inc., a US-based technology company. XRP is the underlying crypto-asset.
Not everyone will be comfortable digging deep into how XRPL works and how to change/modify the code once the XRPL gets updated(through proposals, voting & amendments). And not everyone of us can host a XRPL node. But still if you are willing to create applications for payments, subscription, signing in, escrow account creation etc, then you can simply make use of XUMM platform.
Developers can use XUMM platform to interact with XRPL and also make use of XUMM specific features like sending payments/subscription related messages as push notification. The best thing about XUMM app is there is very less changes of miss transactions, as there are only 2 types of transactions your users will be involved – either they initiate a transaction or they scan a QR code and make a payment. In both the cases it involves very less to no possibilities of making a miss transaction using this app.
Also note that XUMM is developed by “XRPL LABS” team and the project is supported by Ripple / RippleX.
In this video tutorial series we shall learn how to work with XUMM SDK and XUMM API to interact with XRP Ledger, and also see how to make use of XUMM platform specific features to enhance the end user experience.
While following these video tutorials, occasionally you may have to create new XRPL accounts and make transactions and check the results: you can use OsmWallet for that. OsmWallet is a non-custodial wallet and it is a browser extension like MetaMask, but for XRP Ledger.
