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.

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

:sparkles: Add the draft of Deep Link Payment Protocol spec #145

Open
wants to merge 1 commit into
base: master
from

Conversation

@usatie
Copy link
Contributor

commented Oct 24, 2018

Propose a specification for Deep Link Payment Protocol.

This protocol is meant to be used for communication between mobile wallet app and other applications.

With this protocol, the communication wallet application and other applications will be very smooth.

This PR is meant to start discussion.

demo

@usatie

This comment has been minimized.

Copy link
Contributor Author

commented Oct 24, 2018

These are useful referencing materials to start discussion.

BIP70
bitpay/jsonPaymentProtocol
unwriter/fatURI

Things to be considered are these

  • How to prevent MITM(Man In The Middle) attack?
  • passing feePerByte info?
  • passing minConf info?
  • passing outputs?
  • passing rawtx?
@usatie

This comment has been minimized.

Copy link
Contributor Author

commented Oct 24, 2018

We already got some pieces of advice.

  • Better to specify the encoding format for URL
  • How to deal with the case when txid is malformed?
  • Better to pass session id hash instead of session id itself. Or maybe more general argument name like "nonce" or "merchant_data" is better.
@usatie

This comment has been minimized.

Copy link
Contributor Author

commented Oct 24, 2018

I think the level of complexity and flexibility is tradeoff, so we should set different types for different purposes.

i.e.
bch-payment:// type contains only amount and address.
bch-outputs:// type contains several hex format of outputs.
bch-rawtx:// type contains only hex format of rawtx.

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)

This comment has been minimized.

Copy link
@jasonbcox

jasonbcox Oct 24, 2018

Collaborator

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.

@jasonbcox

This comment has been minimized.

Copy link
Collaborator

commented Oct 24, 2018

Regarding your question on how to prevent MITM attacks: This is not necessary as it is done for you. Both iOS and Android operating systems have an app selection process (usually involving a prompt to the user) that determines where the deeplink request is forwarded to. Assuming the OS is not compromised, other apps on the device are unable to modify the request in transit.


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

This comment has been minimized.

Copy link
@jasonbcox

jasonbcox Oct 24, 2018

Collaborator

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.

This comment has been minimized.

Copy link
@usatie

usatie Oct 25, 2018

Author Contributor

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.

This comment has been minimized.

Copy link
@jasonbcox

jasonbcox Oct 28, 2018

Collaborator

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.


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

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

This comment has been minimized.

Copy link
@jasonbcox

jasonbcox Oct 24, 2018

Collaborator

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

This comment has been minimized.

Copy link
@usatie

usatie Oct 25, 2018

Author Contributor

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

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`

This comment has been minimized.

Copy link
@jasonbcox

jasonbcox Oct 24, 2018

Collaborator

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."

This comment has been minimized.

Copy link
@usatie

usatie Oct 25, 2018

Author Contributor

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

a new payment version would be unrecognized by old wallets.

This comment has been minimized.

Copy link
@MissMonacoin

MissMonacoin Nov 22, 2018

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

@usatie

This comment has been minimized.

Copy link
Contributor Author

commented Oct 25, 2018

@GitCash send 1000 bits to @jasonbcox

I think MITM attack can be done by browsers and browser extensions.
What do you think?

Regarding your question on how to prevent MITM attacks: This is not necessary as it is done for you. Both iOS and Android operating systems have an app selection process (usually involving a prompt to the user) that determines where the deeplink request is forwarded to. Assuming the OS is not compromised, other apps on the device are unable to modify the request in transit.

@GitCash

This comment has been minimized.

Copy link

commented Oct 25, 2018

Hey jasonbcox, user usatie tipped you 1000 bits in Bitcoin Cash ( ~ $0.439 ).

Click here to claim it!

You can also add the "thumbs down" reaction to usatie's comment above to prevent future tips.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.