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.

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

(Michael_S (talk) 9 Sept 2013)

Further enhancement: Sending 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=            i=
req-                -
req-tipaddr=        -i=

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

128 characters:

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