Talk:BIP 0021

Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --Gmaxwell (talk) 23:04, 23 April 2013 (GMT)

--> (Michael_S (talk) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):

bitcoinurn      = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]
bitcoinparams   = *bitcoinparamamp
bitcoinparamamp = "&" bitcoinparam

Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps")

(Michael_S (talk) 8 Sept 2013)

I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.

When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.

Enhancement proposal:

bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
bitcoinaddress = base58 *base58
bitcoinparams  = *bitcoinparam
bitcoinparam   = amountparam | labelparam | messageparam | tipparam | otherparam | reqparam
amountparam    = "amount=" *digit [ "." *digit ]
labelparam     = "label=" *pchar
messageparam   = "message=" *pchar
tipparam       = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]
otherparam     = pchar *pchar "=" *pchar
reqparam       = "req-" pchar *pchar "=" *pchar

Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.

The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.

Examples for the following scenario:

Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:

Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=

Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=0

Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=0.08505
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25
  [URI code of the percentage character is "%25"]
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%
  ["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI
  should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand
  this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such
  a "lazy" URI]

Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&message=Charly%27s%20Bar

Explanation:

• The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.
• Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.

The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.

Standard send dialog (no tips):

Advanced send dialog for giving tips:

Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.

But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.

Further enhancement for paying tips in restaurant/bar: "tip address"

(Michael_S (talk) 9 Sept 2013)

Further enhancement: Sending billing amount and tip to separate addresses:

(Note: This feature is typically invisible in the GUI of the customer's wallet app)

bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
bitcoinaddress = base58 *base58
bitcoinparams  = *bitcoinparam
bitcoinparam   = amountparam | labelparam | messageparam | tipparam | tipaddrparam | otherparam | reqparam
amountparam    = "amount=" *digit [ "." *digit ]
labelparam     = "label=" *pchar
messageparam   = "message=" *pchar
tipparam       = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]
tipaddrparam   = "tipaddr=" bitcoinaddress
otherparam     = pchar *pchar "=" *pchar
reqparam       = "req-" pchar *pchar "=" *pchar

Example:

 bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2

The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall preferably send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.

If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:

reqtipaddrparam = "req-tipaddr=" bitcoinaddress

Example:

 bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2

In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).

Short parameter tags yielding shorter URIs for QR codes

(Michael_S (talk) 10 Sept 2013)

Another proposal: Allow short forms for the parameter tags, to shorten the URIs.

This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.

Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:

Parameter Tag       Alias
amount=             a=
label=              l=
message=            m=
tip=                t=
tipaddr=            ta=
req-                -
req-tipaddr=        -ta=
req-aal=            -aal=

Hence, for example the following URIs are fully equivalent:

155 characters:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar

129 characters:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-ta=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar

Critical Improvement of BIP 0021 for "req-" param

(Michael_S (talk) 12 Sept 2013)

One aspect of current BIP 0021 is critical:

It says that wallets that do not know one or several "req-" keys in the URI should reject (i.e. not process) the complete URI, to avoid doing anything in the wrong way.

However, very old wallet apps may have not even implemented this rule and may still process the "known part" of the URI, thereby causing an unwanted result.

The solution to the problem is to specify BIP 0021 in a way that, in case that at least one "req-" key is used, some other details of the URI must be modified too, such that it becomes "incompatible" and "undecodable" by older apps.

The concrete proposal here is to append "R-" directly after "bitcoin:". Then a string with a "req-" parameter would look like this:

bitcoin:R-175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar

The BFN Syntax then looks as follows:

 bitcoinurn     = "bitcoin:" [ "R-" ] bitcoinaddress [ "?" bitcoinparams ]

where "R-" is mandatory as soon as at least one "reqparam" is used.

Paying to Multiple Outputs

(Michael_S (talk) 12 Sept 2013)

Another Enhancement relates to the "Humble Bundle" scenario: Paying one transaction with multiple outputs, specifying a dedicated amount for each output address.

This scenario allows to specify additional pairs of addresses and amounts. Optionally, also further labels can be specified. We call the new parameter "req-aal" for address-amount-label, and we specify it as a required parameter because procesing an incomplete URI would result in sending only a partial amount.

bitcoinparam   = amountparam | labelparam | reqaalparam | messageparam | tipparam | tipaddrparam | otherparam | reqparam
reqaalparam    = "req-aal=" bitcoinaddress ":" *digit [ "." *digit ] [ ":" *pchar]

Example:

bitcoin:R-175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&label=book&req-aal=1tZdShH7b38klseWrTZm5sE8PrtZPwqdK:0.123:game&message=Thank%20You

Feed partially signed transactions for wallet to sign

Example  bitcoin:ANYaddress?presig=45505446ff0002000000000101beee3e40b018f740df8a88ddb411862abf5a634................1231e61c33b4d6992fb61871a2ec711e7b5793c69632b22ea342804110000050054aedf370900