Website integration with Byteball wallets

The latest upgrade of Byteball Market offers users to authenticate themselves in order to keep track of their assets and issuing identities, make modifications and publish asset names to wallets.
The authentication is somewhat different to what most of us are used to since it does not require a sign up procedure entering a user name, email or password. Instead, users simply scan a QR code with their Byteball wallet and in the next moment the user is authenticated and logged into the website effectively pairing their device with Byteball Market.

This mechanism is exactly the same when two Byteball users, who can be completely strangers, pair their devices in order to trade assets, it does not reveal any sensitive financial information about the user. Note however, that the device name is shared so be careful not to expose any information in it that you do not want others to know.

Let's see the whole process in a little more detail. There are three main steps:

• show a unique invitation (pairing) code to the user
• let the user accept the invitation code
• match the correct pairing event with the user

Once these steps are completed the user is authenticated and the device address can be used to associate orders, assets or issuers etc.

Showing a unique invitation code

The first step is to offer the user a Byteball invitation aka pairing code:

• an http session is created for each visiting user
• a random token, called the pairing secret, is generated an mapped to the http session (the token could be the http session id as well)
• the pairing secret is stored in the temporary pairing secrets table (pairing_secrets) of the local byteball database of the bot
• using the pairing secret, a pairing code is created
• the pairing code is shown to the user rendered as a QR code image

The resulting pairing code looks like this:

AlwsdxZStf7sCHFrFZFzDYG3hRsK65tv9HM/YGPxGJFd@byteball.org/bb#K7ZZnkyIxVwLJAAAF

It contains the Byteball Market device public key, the byteball hub address the Byteball Market device is logged in and lastly the pairing secret that makes the pairing code unique for each visitor. Note, that the byteball: protocol prefix is added to the QR code encoded pairing code in order for the mobile OS be able to open the Byteball wallet should a 3rd party QR scanner be used.

The user accepts the invitation code

This is the easiest step from the implementation point of view since we only need to wait for the user to scan the QR code with the Byteball wallet or a 3rd party QR code scanner. In addition to the QR code reading the users can also simply copy the invitation code and paste it in the "Accept invitation from the other device" function of the wallet under Chat->Add new device menu. This is useful if the user is using a desktop wallet and cannot scan the QR code.

Matching the pairing event

When the user scans the QR code, it pairs their device with the Byteball Market bot which triggers a pairing event in it, called paired. Since byteballcore library version 0.2.86 this event is extended with a new parameter in addition to the user's device address: the pairing secret that is echoed back from the device that used the pairing code.
The paired event then can be easily used to look up the corresponding http session to which we earlier mapped the pairing secret and associate the user's device with it.

eventBus.on("paired", function(from_address, pairing_secret) {
    // lookup http session using pairing_secret
    // store from_address in the http session
}

This approach works also if the user has already paired their device and so it can be used multiple times for authentication purposes.

Conclusion

Byteball Market integrates a Byteball bot, a website and the user device in way that is very convenient for the user and still secure. It does not require the user to remember yet another user name or password or register with an email address. Once authenticated, the website is able to use the backend bot to communicate with the user device for example to send confirmation messages or payment or profile requests. And of course this works the other way around as well: the user can send text messages to the bot via the Byteball wallet and perform any operations the bot offers via the chat interface of which result can also be reflected in the website for the user account.