Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
118 lines (77 sloc) 6.2 KB
CIP: 22
Title: Burst Deep Link Specification
Author: ohager
Comments-URI:
Status: Draft
Type: Process
Created: 2019-10-21

Motivation

Currently, a few applications make use of so called deep links, which allow to open applications passing parameters and though redirecting to specific application screens. For example, Phoenix Wallet can be opened using such deep link to request Burst. Nowadays, BRS supports an undocumented deep link feature by returning a QR code for only one method, which is requestBurst. It turns out, that deep links can easily establish interoperability between different Burst applications, as it is already done with HotWallet, Phoenix Desktop Wallet, but also Mobile Apps. Today, the content of such links has no consistent structure, such that links needs be well aligned between application developers. Using a well-defined and sufficiently generic structure for deep linking, can facilitate application interoperability.

Abstract

This proposal describes how to achieve consistent interoperability between applications within the Burst ecosystem. It recommends a lightweight specification for the concept called deep linking, and how it should be implemented.

Specification

The proposed structure for the URI follows the official specification as described in RFC3986. The generic version of an URI looks like this

URI = SCHEME://[AUTHORITY]PATH[?QUERY][#FRAGMENT]

For this proposal the relevant components are

URI = SCHEME://PATH?QUERY
SCHEME = burst.DOMAIN
PATH = VERSION
QUERY = action=IDENT&payload=BASE64
DOMAIN = IDENT
IDENT = ALPHA[ALPHA|DIGIT]*
VERSION = v[DIGIT]+
BASE64 = ALPHA[DIGIT|ALPHA|SIGN]*[=|==]?
ALPHA = [a-zA-Z]
DIGIT = [0-9]
SIGN = [+|/]

Example

burst.message://v1?action=send&payload=eyJyZWNpcGllbnQiOjEyMzQsIm1lc3NhZ2UiOiJIZWxsbyx0aGlzaXNhcHJvcG9zYWxmb3JhY29uc2lzdGVudGRlZXBsaW5rc3BlY2ZvcmJ1cnN0IiwiZmVlTlFUIjoxMDAwMDAwfQ==

Scheme

A scheme determines the domain within the burst ecosystem. Technically, the scheme, also known as protocol, links the operation systems default startup for a certain application. It consists of the static prefix burst. followed by an alphanumeric string that defines the targeted domain.

Domain

A domain describes the "area" where a linked application belongs to. This implies that per platform only one application can be linked to a domain, as disambigation might lead to undefined behavior. It is possible to map one application to many domains, if that application is omnipotent

Suggested domains are

Argument Description
payment All regarding payments, like send and or receive Burst
message All regarding messaging, like sending and showing messages
contract All regarding contracts, like calling, creating etc
asset All regarding assets, like built in asset system, or even more
market All regarding market, like trading, exchange
generic No special domain, allowing arbitrary features

To do: more domains

Path

The path is almost only a prefix to determine the version of the specification. The proposed value is v[/d]*, as this allows to enhance/extend/improve this specification in the future. On activation of this CIP, it would be v1.

Query

The query segment is part of the RFC3986 normative. In the context of this proposal, the query carries information about the callers intention, i.e. action and its payload to be executed within the linked application. The query consists of two components:

  • action The alphanumeric name (in plain text) of the action that should be called within the application
  • payload Any arbitrary data decoded in base64, that is used by the action.

The caller should use actions which are supported by the linked application. If an application does not know of that action, the application must be sufficiently robust, to handle that case, e.g. ignore the action and open on default screen, and/or show a message informing about the non-supported action. The payload must be sanitized by the application to guarantee proper functioning and avoid injection attacks.

BRS API Change

BRS API supports a method called generateSendTransactionQRCode, which creates a QR-Code for a deep link with scheme burst://. It returns very specific data, and lacks versatility. In addition to this endpoint a more generic endpoint for QR Code generation should be provided:

generateDeepLinkQRCode(string domain, string action, string payload)

Additionally, another method to mount the only the link would be useful:

generateDeepLink(string domain, string action, string payload)

Summary

This specification of deep linking within the Burst eco-system simplifies the interoperability between Burst applications. It permits that the feature-rich platform can be splitted in different specialized applications, i.e. asset exchange, simple wallet, messaging application, while maintaining an integrated user-experience. It is even possible to create "meta-applications", which serves as a container for those applications.

Demo

Compatibility

The change can be applied to BRS without any impact on the network. It's merely an extension of the API. The existing QRCode Generator class will be adjusted, but for backwards compatibility the one and only method requestBurst should be kept. It's recommended to mark as deprecated. Furthermore, anendpoint for generating only the URI will be created, too.

Additional notes

Upon activation, the current deep link implementation in BRS will be adjusted to follow the suggested specification. The current API will be extended by a new endpoint.

References

Copyright

This document is placed in the public domain.

You can’t perform that action at this time.