CIP: 22 Title: Burst Deep Link Specification Author: ohager Comments-URI: Status: Draft Type: Process Created: 2019-10-21
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.
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.
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 = [+|/]
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.
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
|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
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
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)
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.
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.
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.
This document is placed in the public domain.