Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ Add the draft of Deep Link Payment Protocol spec #145

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

✨ Add the draft of Deep Link Payment Protocol spec #145

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions spec/deep-link-payment-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
```
BIP: ?
Layer: Applications
Title: Deeplink Payment Protocol
Author: Shun Usami<[email protected]>,
Taiki Uchida<[email protected]>,
Aoi Serikawa<[email protected]>
Comments-URI: https://hackmd.io/s/BJObJntjQ
Status: Draft
Type: Standards Track
Created: 2018-10-21
```

## Abstract

Basically this is just a [BIP21(URI scheme)](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) like deeplink scheme to wallet applications with a callback url.
When the wallet app completed the requested behaviour, the wallet app ping the callback URL.
![demo](https://i.imgur.com/yXBsfJL.gif)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend adding a background section to give a quick explanation of what deeplinking is. https://en.wikipedia.org/wiki/Mobile_deep_linking is a good place to start.

## Motivation
Currently, the payment experience on mobile devices are very bad, because users have to take many steps like this.
- 1. Copy the address.
- 2. Open a wallet app.
- 3. Paste the address.
- 4. Type the amount to send.
- 5. Send to the address.
- 6. Re-open the source application.

This protocol dramatically reduces the user's required steps.
- 1. Opens the deep link to a wallet app.
- 2. Confirm payment and automatically returns to the source app.

## Specification

### Deep link Scheme
This deep link scheme is protocol for communication between wallet application and another application.

i.e.
`bch-payment:{parameters}`
`bch-sign:{parameters}`


| title | value |
|:---:|:---:|
|Custom URL scheme|bch-{type}|
Copy link
Collaborator

@jasonbcox jasonbcox Oct 24, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a long thought on the URI scheme, for which I see pros and cons. Let me know what you think:

bch-{type}:
Pros:

  • Apps only implement the types they want to support. This is less development overhead.

Cons:

  • Apps are not able to provide error messages for unsupported {types}, such as "bch-sign is not supported by this app", in order to inform the user. Instead, the user will simply not see the expected app as an option to select for the deeplink. This is a confusing user experience.

Using 'bitcoin-cash' as the URI scheme, and moving {type} to a parameter:
Pros:

  • Apps can support all {types} with varying degrees of granularity.
  • Better user experience. Error messages can be provided when a particular type is not supported, informing the user. This works especially well for new types that old versions of apps do not know about.

Cons:

  • Apps must accept all types, even if not supported. If a wallet only supports {type: payment}, they must provide a good user experience for {type: sign}, etc. This is additional work for specific-use-case app developers.

I'm leaning toward the 'bitcoin-cash' URI scheme, as that provides a better user experience.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is iOS. iOS users cannot choose application to open a deep link when multiple apps are supporting the link. In such case, iOS kind of randomly choose the app to open the link.

When users have multiple wallet apps, and some of them are supporting the {type} but some of them are not supporting the {type}. Since all the wallet seems to be supporting the link.
So users want to know if a wallet app supports {type} before opening the link.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah! I forgot iOS doesn't provide this selection process like Android does. Do action extensions provide a means to solve this? https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionOverview.html#/ From reading the doc, it seems that each wallet can implement an app extension that deeplinks to the wallet using the scheme you've described in this spec. For the "host" app (aka the store or other microtransaction app), they must call the app extension to get the list of supporting wallets.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See also: https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionScenarios.html#/



| type | explanation |
|:---:|:---:|
| payment | request a payment to wallet application |
| sign | request signing of message to wallet application |
| coming soon | coming soon ...|


### Mobile App to Wallet App Communication
![abstract:mobile-application](https://i.imgur.com/SPywIQE.png)

#### 1. Source app generates deep link to wallet app
The source app generates a deep link to wallet apps.
i.e.
`bch-payment:{addr}?amount={amount}&callback={callback_url}`

`addr` is a cashaddr without scheme.
i.e.
`qznj9wsazh379qa3dkph7qvtxdx5emkrxvsxhnyall`

|Query key| type | memo | example value|
|:---:|:---:|:---:|:---:|
|amount| Decimal | Coin value to send | 0.0001 |
|callback| String | deep link | yenom://payment-result |

#### 2. Wallet app make the payment
The wallet app build the payment transaction and broadcast it.


#### 3. Wallet app opens the deep link to the source app
The wallet app opens the deep link to the source app after broadcasting the payment transaction or cancelling the payment.
`callback_url?txid={txid}&status={status}`

|Query key| type | memo | example value |
|:---:|:---:|:---:|:---:|
|status| String | Status of the payment result. [success/error/cancel] | success |
|txid| String(optional) | Transaction id of the payment. Required if the status is success. | 0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e |

#### 4. Source app verify the tx with txid
Source app should verify the payment is done.


### Web App to Wallet App Communication
![abstract:web-application](https://i.imgur.com/tYHey1y.png)

#### 1. Source web site generates deep link to wallet app

`bch-payment:{addr}?amount={amount}&webhook={webhook_url}&callback={callback_url}`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason the {addr} is not part of the query param set? Is that because it is required and the query params are optional?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no reason about it. Let me fix it.


`addr` is a cashaddr without scheme.
i.e.
`qznj9wsazh379qa3dkph7qvtxdx5emkrxvsxhnyall`

|Query key| type | memo | example value |
|:---:|:---:|:---:|:---:|
|amount| Decimal | Coin value to send | 0.0001 |
|callback| String | web link | http://yenom.tech/payment-result |
|sessionid | String | website session id | eyJ...3mh8 |


#### 2. Wallet app build transaction with OP_RETURN output
The wallet app build and broadcast tx.
This tx should contain OP_RETURN output. This OP_RETURN output should store the SHA256 hash of session id.

[Transaction 0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e - Bitcoin Cash (BCH) Block Explorer](https://explorer.bitcoin.com/bch/tx/0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e)

#### 3. Wallet app pings the webhook URL
The wallet app send http `POST` request to `webhook_url` after broadcasting the payment transaction or cancelling the payment.

The webhook URL must accept a POST request with JSON. The object sent from the wallet app looks like this:

```
{
"status" : "success",
"txid" : "0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e"
}
```

#### 4. Wallet app opens the callback URL

And then it opens the `callback_url` as well.

`callback_url?txid={txid}&status={status}`

|Query key| type | memo | example value |
|:---:|:---:|:---:|:---:|
|status| String | status of payment result. [success/error/cancel] | success |
|txid| String | Transaction id of the payment. Required if the status is success. | 0eac357541b0ba572849113c5faa1d1990f6382741dc3e2f5507e3ca8346dc0e |

#### 5. Source website verify the tx with txid
Source app should verify the payment is done. And also check the hash of the user's session id corresponds with the OP_RETURN output of tx.


## Rationale
This protocol is quite simple.
Alternative [BIP70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki#Motivation) like design can be considered.

## Forward compatibility
Adding optional parameters can be done by simply adding them.
Adding required parameters or destructive change can be done by simply changing the type name to new one.
i.e.
`bch-payment` -> `bch-payment-v2`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the bch-{type} cons above, a new payment version would be unrecognized by old wallets. I recommend making 'version' a query param, with default value of '1'. This way, apps can error out with an informative message such as "New version of bitcoin-cash payment is not supported! Please contact the app developer."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is intended to be so.
As I stated above, the problem is iOS.

a new payment version would be unrecognized by old wallets.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about BIP21-style prefix?
If req- prefix was found and the old app wasn't able to parse the field name, the app can mark as invalid.
Many bitcoin cash wallet has already supported BIP21 so I think it would be better to follow BIP21.
https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki#forward-compatibility


## Reference implementation
Coming soon.