Verify The Transaction on Mainnet: XUMM SDK

Once payload is signed and a valid transaction is made, it is crucial to check for the transaction on main/live XRP ledger network.

For this we will be making use of a npm package: xrpl-txdata

Installing xrpl-txdata

npm install xrpl-txdata

Once this package is installed on your system, you can verify the transaction on live XRP ledger locally. “Locally” because the xrpl-txdata package will be installed locally on your machine.

Video Tutorial: Verify The Transaction on Mainnet: XUMM SDK


[youtube https://www.youtube.com/watch?v=kkGFMiX8bCY]

YouTube Link: https://www.youtube.com/watch?v=kkGFMiX8bCY [Watch the Video In Full Screen.]

Why do we need to verify transaction on main XRP Ledger?

1. The end user signed the request successfully in XUMM, but with a key that is no longer valid for a certain account (because multisign has been configured, an account has been rekeyed, etc.)

2. The user sent a Partial Payment (e.g., sending EUR to deliver XRP, while the owned amount of EUR was insufficient due to exchange rate slippage).

3. The user tried to trick you into accepting a testnet payment, by signing with a funded Testnet account.

Source Code: Verify The Transaction on Mainnet: XUMM SDK

const {XummSdk} = require('xumm-sdk')
const {TxData}  = require('xrpl-txdata')

const Sdk       = new XummSdk('xumm-app-id', 'xumm-app-secret')
const Verify    = new TxData()

const main      = async() => {
    
      const request = {
        "txjson": {
            "TransactionType": "Payment",
            "Destination": "rwietsevLFg8XSmG3bEZzFein1g8RBqWDZ",
            "Amount": "1000000"
        },
        "user_token": "343a2f1e-8160-4984-a0f0-208086509617"
      }

      const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          //console.log('New payload event',event.data)

          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
      }) 
      console.log('sign request URL',subscription.created.next.always)
      console.log('Pushed ',subscription.created.pushed ? 'Yes' : 'No')

      const resolveData = await subscription.resolved
      if(resolveData.signed == false)
      {
          console.log('The sign request was rejected!')
      }
      else
      {
        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        const VerifiedResult = await Verify.getOne(result.response.txid)
        console.log('On ledger Balance ',VerifiedResult.balanceChanges)
      }
}
main()

Output of above code

sign request URL https://xumm.app/sign/b51bda5e-ebfe-48fe-b7ba-75797147c837
Pushed  Yes

On ledger Balance {
 rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT : [{counterparty: '', currency: 'XRP', value: '-1.000012'}],
 rwietsevLFg8XSmG3bEZzFein1g8RBqWDZ : [{counterparty: '', currency: 'XRP', value: '1'}]
}

We are interested in On ledger Balance output. Here the first address is that of sender and the second address is that of receiver. So in this transaction 1.000012 XRP was sent by the end user and 0.000012 XRP was the network fee. Also note that the transaction fee will not be distributed to miners in XRPL, but instead it gets burnt permanently, reducing the over all supply of XRP.

Transaction verification Code Explained

We import xrpl-txdata package into our nodejs application, using require keyword. Next we create an instance of it called Verify.
Once the sign request is signed we get the transaction ID. i.e., we get the transaction ID only when the transaction is done.

So once we programmatically know that the transaction is made(by looking into signed: true key value in the output), we check the transaction on main/live XRP ledger, using following code:

        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        const VerifiedResult = await Verify.getOne(result.response.txid)
        console.log('On ledger Balance ',VerifiedResult.balanceChanges)

The instance Verify has a method called getOne() which checks the transaction on live XRP ledger, if we provide it with the transaction ID.

Switching from Testnet to Mainnet inside XUMM App

Open XUMM app present in your mobile phone. Navigate to Settings tab. Go to Advanced section. Then click on Node under the label XRP Ledger node and Explorer. Here you can switch between Main net and Test net. These are Main XRP ledger network and Test XRP ledger networks.

xrpl-txdata checks only against live XRP Ledger

Since xrpl-txdata checks only against live/main XRP ledger network, if you’re using testnet to send payments, it’ll throw error message that the transaction is not found on the main XRPL network – as your transactions will be present on test XRPL network and not on main/live XRPL network.

That’s it! You made it

If you’re this far into learning about XUMM SDK and working with XRP Ledger, then you might consider building some app, even if it’s just a hobby project.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL

Send Sign Request As Push Notification: XUMM SDK

You have sent your first Payload request and also signed and/or rejected the sign request, by scanning the QR code. Now lets see how we can get user specific user token and start sending sign request as push notification to the end user.

Payload using create() method

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const payload = await Sdk.payload.create(request, true)
  console.log(payload)
}
main()

Above code is from our previous video tutorial where we sent our first payload using create method.

Video Tutorial: Send Sign Request As Push Notification: XUMM SDK


[youtube https://www.youtube.com/watch?v=4Wxcz0jvA9A]

YouTube Link: https://www.youtube.com/watch?v=4Wxcz0jvA9A [Watch the Video In Full Screen.]

Payload using createAndSubscribe() method

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
      console.log('New payload event',event.data)
  })
  console.log('sign request URL',subscription.created.next.always)
  console.log('Pushed ',subscription.created.pushed)
}

main()

Here we use createAndSubscribe() method instead of create() method. createAndSubscribe() also takes 2 arguments. The first argument is the payload information and the second argument is method/function that gets invoked every time the XUMM platform asynchronously sends an update about the created payload.

Running The Application

We issue the command node index.js to run our application and we get the following output:

sign request URL https://xumm.app/sign/e917182a-b64f-474d-ab24-8792d6b0ca6c
Pushed  false
New payload event { message: 'Welcome e917182a-b64f-474d-ab24-8792d6b0ca6c' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }

Since main() is a asynchronous method and a child thread keeps waiting for Sdk.payload.createAndSubscribe() method to be resolved(it gets resolved once end user either signs or rejects the sign request, or when the payload expires). If we want to exit the waiting and kill the child process – get on the output terminal and press CTRL + C buttons(on windows PC).

The constant subscription(from above code) has information regarding the payload, payload status, signing URL, QR code information etc. Sdk.payload.createAndSubscribe() second argument keeps updating the payload status like expiration time until the user performs some action on the sign request. If user doesn’t perform any action until the payload gets expired, then the payload information gets expired and will be removed from the XUMM platform.

Once Payload is Resolved

Once user opens the QR code present on sign request URL(check above code output), scans it and signs or rejects the sign request, the method in seconds argument of Sdk.payload.createAndSubscribe() gets triggered and sends the updated status of the sign request.

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          console.log('New payload event',event.data)
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
  })
  console.log('sign request URL',subscription.created.next.always)
  console.log('Pushed ',subscription.created.pushed)
}

main()

The Object.keys you see in above code is standard Javascript code. When we pass an object to it, and chain indexOf() method and pass the key name to indexOf() method, it returns the index position of that key in the object. Index starts from 0. So it returns the event.data if and when the user interacts with the payload QR code and either signs or rejects the payload. Until user performs some action with the generated payload, event.data will not have the key signed in its output.

Lets execute above code
We issue the command node index.js to run our application and we get the following output:

sign request URL https://xumm.app/sign/e917182a-b64f-474d-ab24-8792d6b0ca6c
Pushed  false
New payload event { message: 'Welcome e917182a-b64f-474d-ab24-8792d6b0ca6c' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }

Copy the sign request URL from above output and past it in a browser and open your XUMM app in your phone, scan the QR code and sign or reject the sign request and look out for the status change.

Output when the sign request gets rejected

sign request URL https://xumm.app/sign/972d25fe-413a-48a3-8935-dd95c6cdf8ef
Pushed  false
New payload event { message: 'Welcome 972d25fe-413a-48a3-8935-dd95c6cdf8ef' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }
New payload event { opened: true }
New payload event {
  payload_uuidv4: '972d25fe-413a-48a3-8935-dd95c6cdf8ef',
  reference_call_uuidv4: 'd81ae124-527d-40b6-ad38-c272f9b71134',  
  signed: false,
  user_token: true,
  return_url: { app: null, web: null },
  opened_by_deeplink: false,
  custom_meta: { identifier: null, blob: null, instruction: null }
}

As you can see in the output above, the payload event status shows when the user opened his/her XUMM app and scanned the QR code { opened: true }. In above case the end user has rejected the sign request, so the signed key has a value of false. The key opened_by_deeplink is new and is implemented in XUMM SDK 0.2.2 to further improve user flows – its value is null if unopened, true if opened using a mobile deeplink/push, false if QR scan opened. Technically it is present to let the developer know whether the sign request was opened from a deeplink URL or not.

Output when the sign request is signed

sign request URL https://xumm.app/sign/848ff099-4161-4911-a024-d27c15e87f62
Pushed  false
New payload event { message: 'Welcome 848ff099-4161-4911-a024-d27c15e87f62' }
New payload event { expires_in_seconds: 86399 }
New payload event { opened: true }
New payload event { expires_in_seconds: 86384 }
New payload event {
  payload_uuidv4: '848ff099-4161-4911-a024-d27c15e87f62',
  reference_call_uuidv4: 'bc98f5b6-d960-41a3-884a-3c9dced5b0e2',  
  signed: true,
  user_token: true,
  return_url: { app: null, web: null },
  opened_by_deeplink: false,
  custom_meta: { identifier: null, blob: null, instruction: null }
}

As you can see from above output, the value of signed is true. That means end user has successfully signed the sign request. Now we take the payload_uuidv4 value and fetch the user token from it.

Fetching user_token from payload_uuidv4

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          // console.log('New payload event',event.data)
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
  })
      console.log('sign request URL',subscription.created.next.always)
      console.log('Pushed ',subscription.created.pushed ? 'Yes' : 'No')

      const resolveData = await subscription.resolved
      if(resolveData.signed == false)
      {
          console.log('The sign request was rejected!')
      }
      else
      {
        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        console.log('User_token: ',result.application)
      }
}

main()

We take another constant and await for subscription to be resolved. Once the end user signs the sign request we pass the resolveData.payload_uuidv4 information to Sdk.payload.get() which outputs a lot of json results. In that we pick up the user_token present under result.application as value for key issued_user_token.

Output of above code:

sign request URL https://xumm.app/sign/da54ac54-549f-42d2-a239-8ae6086eafbd
Pushed  No
New payload event { message: 'Welcome da54ac54-549f-42d2-a239-8ae6086eafbd' }
New payload event { expires_in_seconds: 86397 }
New payload event { opened: true }
New payload event { expires_in_seconds: 86382 }
The sign request was Signed!!
User_token: {
    name: 'My Super Duper App!',
    description: 'Demo App To Show New SDK Features',
    disabled: 0,
    uuidv4: '401015ee-7edc-4469-bdfd-3af11f229885',
    icon_url: 'https://xumm-cdn.imgix.net/app-logo/2a14d2f7-d0a8-432a-a40f-b45eddb70fc4.png',
    issued_user_token: '343a2f1e-8160-4984-a0f0-208086509617'
  }

In this we are interested in issued_user_token, which will be used to send push notifications to end user. To pick it up we write result.application.issued_user_token and store it inside the database.

Sending sign request as Push Notification

The user_token is a unique token for your XUMM app in combination with the specific XUMM user. To use the token to deliver a sign requst per Push notification, let’s adjust our first (minimal) sample payload or the ‘transaction template’ to include the user token:
This payload is XRPL specific

const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "10000",
  }

Now lets add user_token information to it.

{
  "txjson": {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "10000"
  },
  "user_token": "343a2f1e-8160-4984-a0f0-208086509617"
}

As you can see from above code, all the XRP Ledger specific payload information has been moved into a separate block under key txjson. All the other information outside of object txjson is specific to XUMM platform. Other XUMM platform specific information are: options, custom_meta and the user_token etc.

Stage is set to send sign request as Push Notification

Now lets use the user_token we received from our previously signed payload and use that in our final source code. Once you execute this final source code, the end user(user identified by user_token) will receive the sign request as push notification. Exciting!!

Source Code: To Send Sign Request As Push Notification: XUMM SDK

const {XummSdk} = require('xumm-sdk')
const {Txdata, TxData}  = require('xrpl-txdata')

const Sdk       = new XummSdk('401015ee-7edc-4469-bdfd-3af11f229885', '267b909b-0374-450b-a05b-5df60bc1f57a')
const Verify    = new TxData()

const main      = async() => {
    
      const request = {
        "txjson": {
            "TransactionType": "Payment",
            "Destination": "rwietsevLFg8XSmG3bEZzFein1g8RBqWDZ",
            "Amount": "1000000"
        },
        "user_token": "343a2f1e-8160-4984-a0f0-208086509617"
      }

      const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
      }) 
      console.log('sign request URL',subscription.created.next.always)
      console.log('Pushed ',subscription.created.pushed ? 'Yes' : 'No')

      const resolveData = await subscription.resolved
      if(resolveData.signed == false)
      {
          console.log('The sign request was rejected!')
      }
      else
      {
        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        console.log('User_token: ',result.application.issued_user_token)
      }
}
main()

Here is the push notification on my phone
xumm sign request as push notification

We can click on the push notification bubble or open the XUMM App directly on our phone and navigate to “Events” tab and open the new sign request there and choose to sign or reject the request.

Output
The output of above source code will be same as we’ve posted previously for signing and rejecting the sign request. Now the only difference is, value of key pushed will be true as sign request was sent as push notification directly to the end users phone.

Important Note

Its best practice to check the value of key pushed in the output. If its false(maybe user revoked the permission), then its always good to show the user with the QR code to manually scan and make the payment. If value of pushed is false, that means the end user has not received the push notification.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL

Your First Payload: XUMM SDK

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.

Simple Transaction Template

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT"
}

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.

Sample Transaction Template With More Information

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
  "Amount": "1000000",
  "Memos": [
    {
      "Memo": {
        "MemoData": "F09F94A520546563686E6F7469702E636F6D"
      }
    }
  ]
}

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.

Generating Memo(HEX encoded string)

const hex = Buffer.from('🔥 Technotip.com').toString('hex').toUpperCase()
console.log(hex)

Buffer is a nodejs packages built-in property, so you need not install any other packages once again.

Video Tutorial: Your First Payload: XUMM SDK


[youtube https://www.youtube.com/watch?v=RYAHzvUqM64]

YouTube Link: https://www.youtube.com/watch?v=RYAHzvUqM64 [Watch the Video In Full Screen.]

Things To Keep In Mind While Sending Payload

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.

Source Code: Complete Code To Send Payload

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000",
    "Memos": [
      {
        "Memo": {
          "MemoData": "F09F94A520546563686E6F7469702E636F6D"
        }
      }
    ]
  }

  const payload = await Sdk.payload.create(request, true)
  console.log(payload)
}
main()

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

{
  uuid: '127287c3-bf55-40ee-b0ab-345f9edc8840',
  next: {
    always: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'
  },
  refs: {
    qr_png: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.png',    
    qr_matrix: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.json',
    qr_uri_quality_opts: [ 'm', 'q', 'h' ],
    websocket_status: 
'wss://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'   
  },
  pushed: false
}

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.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL

Working With XUMM SDK/API: XRPL

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.

xumm logo

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.

Sample App Built using XUMM API

Automate Digital Sales using XUMM Payment

XUMM SDK/API Video Tutorial Playlist


[youtube https://www.youtube.com/watch?v=tdoLbHiMTGo&list=PLM4pPs1mzl_NjoQPoMlJEx2XAEpDQ-Vhq]

YouTube Link: XUMM SDK/API playlist [Watch the Video In Full Screen.]

XUMM SDK/API, Free Video Tutorials List

Please follow the tutorials in the same order as listed below