Adding CIP22 - Deep Link Specification

cip-0022.md

@@ -0,0 +1,112 @@
+    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](https://www.ietf.org/rfc/rfc3986.txt). The generic version of an URI looks like this
+
+```
+URI = SCHEME:[//AUTHORITY]PATH[?QUERY][#FRAGMENT]
+```
+
+For this proposal the components are
+
+```
+SCHEME = burst.DOMAIN
+AUTHORITY = //VERSION
+QUERY = action=IDENT&payload=BASE64
+DOMAIN = IDENT
+IDENT = ALPHA[ALPHA|DIGIT]*
+VERSION = cip[DIGIT]+
+BASE64 = ALPHA[DIGIT|ALPHA|SIGN]*[=|==]?
+ALPHA = [a-zA-Z]
+DIGIT = [0-9]
+SIGN = [+|/]
+```
+
+#### Example
+
+```
+burst.message://cip22?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 regarging 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
+
+
+### Authority
+
+The _authority_ is almost only a prefix to determine the current specification, i.e. serves as kind of versioning. The proposed value is `cip[/d]{4}`, as this allows to enhance/extend/improve this specificiation in the future using the current CIP process. On activation of this CIP, it would be `cip22`.
+
+### 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)` 
+
+
+## Summary
+
+This specification of _deep linking_ within the Burst eco-system simplies 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](https://github.com/burst-apps-team/CIPs/tree/master/cip-0022/deep-link-demo.gif)
+
+## 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.
+
+## 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
+
+* [Undocumented BRS deep link](https://github.com/burst-apps-team/burstcoin/blob/develop/src/brs/deeplink/DeeplinkQRCodeGenerator.java)
+- [RFC3986](https://www.ietf.org/rfc/rfc3986.txt)
+- [Deep Linking](https://en.wikipedia.org/wiki/Deep_linking)
+- [Nobile Deep Linking](https://en.wikipedia.org/wiki/Mobile_deep_linking)
+
+
+## Copyright
+
+This document is placed in the public domain.