Extension for BIP-0070 to support recurring payments

Extension for BIP-0070 to support recurring payments
2014-01-28  3:58 ` Kevin Greene
                   ` (3 more replies)
  
From: Stephane Brossier @ 2014-01-28  2:36 UTC (permalink / raw)
  To: bitcoin-development;  stephane, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 1979 bytes --]

Hi,

[I sent this email 2 days ago prior my registration to the mailing list; please forgive me if this is a duplicate]

I would like to propose an extension to the Payment Protocol (bip-0070) to address the case of recurring payments in Bitcoin -- new bip or modification of bip-0070.

There has been a lot of growth in the last few years in the 'subscription economy' with many new companies embracing that model -- online video, gaming, groceries, newspapers,... In parallel, Bitcoin is growing into a mainstream currency (hence bip-0070), and so the next logical step would be to define a protocol to address that need.

We have been working in the past few years on an open-source billing platform (http://kill-bill.org/), and recently came with a prototype to do recurring billing in Bitcoin (see http://thekillbillstory.wordpress.com/2014/01/20/bitcoin-plugin/ and http://thekillbillstory.wordpress.com/2014/01/11/coinbase-integration-experiment/).


The work flow would look similar to the one from bip-0070. There would need to be some additions; the flow could be summarized as follow:

0. Click: 'Subscribe Now'
1. Wallet would get  a RecurringPaymentRequestAuth which describes the nature of the future recurring payments
2. The Customer would get prompted from the wallet to authorize it.
3. The wallet would then poll the Merchant server (startup time, and/or well defined frequency) and potentially merchant would start issuing a PaymentRequest); the role of the wallet is to ensure that PaymentRequest is within the bounds of what was accepted by the customer-- amount, frequency,.. If it is, then it would make the Payment the same way it works for bip-0070

Is that something that the community would be interested in? We could provide more details about the protocol we have in mind (messages and flow), and also provide an implementation with bitcoinj as a wallet and Kill Bill as a merchant server.

Le me know what you think.

Stéphane

[-- Attachment #2: Type: text/html, Size: 2687 bytes --]

 permalink raw reply	[|nested]
2014-01-28  3:58 ` 
                   ` 
  
From: Stephane Brossier @ 2014-01-28  2:36 UTC (permalink / raw)
  To: bitcoin-development;  stephane, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 1979 bytes --]

Hi,

[I sent this email 2 days ago prior my registration to the mailing list; please forgive me if this is a duplicate]

I would like to propose an extension to the Payment Protocol (bip-0070) to address the case of recurring payments in Bitcoin -- new bip or modification of bip-0070.

There has been a lot of growth in the last few years in the 'subscription economy' with many new companies embracing that model -- online video, gaming, groceries, newspapers,... In parallel, Bitcoin is growing into a mainstream currency (hence bip-0070), and so the next logical step would be to define a protocol to address that need.

We have been working in the past few years on an open-source billing platform (http://kill-bill.org/), and recently came with a prototype to do recurring billing in Bitcoin (see http://thekillbillstory.wordpress.com/2014/01/20/bitcoin-plugin/ and http://thekillbillstory.wordpress.com/2014/01/11/coinbase-integration-experiment/).


The work flow would look similar to the one from bip-0070. There would need to be some additions; the flow could be summarized as follow:

0. Click: 'Subscribe Now'
1. Wallet would get  a RecurringPaymentRequestAuth which describes the nature of the future recurring payments
2. The Customer would get prompted from the wallet to authorize it.
3. The wallet would then poll the Merchant server (startup time, and/or well defined frequency) and potentially merchant would start issuing a PaymentRequest); the role of the wallet is to ensure that PaymentRequest is within the bounds of what was accepted by the customer-- amount, frequency,.. If it is, then it would make the Payment the same way it works for bip-0070

Is that something that the community would be interested in? We could provide more details about the protocol we have in mind (messages and flow), and also provide an implementation with bitcoinj as a wallet and Kill Bill as a merchant server.

Le me know what you think.

Stéphane

[-- Attachment #2: Type: text/html, Size: 2687 bytes --]

 permalink raw reply	[|nested]
* 
  2014-01-28  2:36 [Bitcoin-development] Extension for BIP-0070 to support recurring payments Stephane Brossier

  2014-01-28  4:29 ` 
                   ` 
  3 siblings, 0 replies; 25+ messages in thread
From: Kevin Greene @ 2014-01-28  3:58 UTC (permalink / raw)
  To: Stephane Brossier;  Bitcoin Dev, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 3086 bytes --]

+1 to the idea of recurring payment requests.

Perhaps one way to realize this would be to add an optional URL to the
PaymentRequest object where the next PaymentRequest can be fetched and the
date at which the merchant expects the next payment.


On Mon, Jan 27, 2014 at 6:36 PM, Stephane Brossier
<stephane@kill-bill•org>wrote:

> Hi,
>
> [I sent this email 2 days ago prior my registration to the mailing list;
> please forgive me if this is a duplicate]
>
> I would like to propose an extension to the Payment Protocol (bip-0070) to
> address the case of recurring payments in Bitcoin -- new bip or
> modification of bip-0070.
>
> There has been a lot of growth in the last few years in the 'subscription
> economy' with many new companies embracing that model -- online video,
> gaming, groceries, newspapers,... In parallel, Bitcoin is growing into a
> mainstream currency (hence bip-0070), and so the next logical step would be
> to define a protocol to address that need.
>
> We have been working in the past few years on an open-source billing
> platform (http://kill-bill.org/), and recently came with a prototype to
> do recurring billing in Bitcoin (see
> http://thekillbillstory.wordpress.com/2014/01/20/bitcoin-plugin/ and
> http://thekillbillstory.wordpress.com/2014/01/11/coinbase-integration-experiment/
> ).
>
>
> The work flow would look similar to the one from bip-0070. There would
> need to be some additions; the flow could be summarized as follow:
>
> 0. Click: 'Subscribe Now'
> 1. Wallet would get  a RecurringPaymentRequestAuth which describes the
> nature of the future recurring payments
> 2. The Customer would get prompted from the wallet to authorize it.
> 3. The wallet would then poll the Merchant server (startup time, and/or
> well defined frequency) and potentially merchant would start issuing a
> PaymentRequest); the role of the wallet is to ensure that PaymentRequest is
> within the bounds of what was accepted by the customer-- amount,
> frequency,.. If it is, then it would make the Payment the same way it works
> for bip-0070
>
> Is that something that the community would be interested in? We could
> provide more details about the protocol we have in mind (messages and
> flow), and also provide an implementation with bitcoinj as a wallet and
> Kill Bill as a merchant server.
>
> Le me know what you think.
>
> Stéphane
>
>
> ------------------------------------------------------------------------------
> WatchGuard Dimension instantly turns raw network data into actionable
> security intelligence. It gives you real-time visual feedback on key
> security issues and trends.  Skip the complicated setup - simply import
> a virtual appliance and go from zero to informed in seconds.
>
> http://pubads.g.doubleclick.net/gampad/clk?id=123612991&iu=/4140/ostg.clktrk
> _______________________________________________
> Bitcoin-development mailing list
> Bitcoin-development@lists•sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>
>

[-- Attachment #2: Type: text/html, Size: 4338 bytes --]

^ permalink raw reply	[|nested] 25+ messages in thread
2014-01-28  2:36 [Bitcoin-development] Extension for BIP-0070 to support recurring payments Stephane Brossier
  2014-01-28  3:58 ` Kevin Greene
  2014-01-28  4:29 ` Jeff Garzik

  2014-01-28  5:07   ` PikaPay
  2014-01-28  6:08   ` Odinn Cyberguerrilla
  2014-01-28  6:34 ` Mike Hearn
  
From: Jeff Garzik @ 2014-01-28  4:43 UTC (permalink / raw)
  To: Stephane Brossier;  Bitcoin Dev, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 1848 bytes --]

Yes, recurring payments and subscriptions is a frequently-requested
feature.  It needs a new BIP.  Here is an outline:

The situation is somewhat analogous to HTML5 local storage.  The remote
(merchant) wants to initiate a persistent behavior.  This is bitcoin, so we
have a "push" model for payment, and the user has complete control.  The
merchant can, at most, send a "subscription request."  The user is
responsible for making on-time payments after that point.

Centralized services like coinbase.com or blockchain.info will have an easy
time of it.  An automated program on their backend, sending payments as
needed, is easy and direct.

More inventive services might employ multisig transactions, generating and
signing one signature of a TX, then sending that TX to the human for
further signing and publishing.  A few competing vendors could offer bots
that provide this signing service.

Decentralized, standalone wallet clients will be somewhat troublesome.  We
can store a local subscription request, and send recurring payments...  if
the wallet app is running.  If not, the user will be missing payments, that
perhaps they intended to make (rent!).

Each of these solutions can be cancelled at any time by the user.  As such,
a courtesy "subscription cancelled" message sent to the merchant is
recommended.  User controls the usage of their money at all times, the way
things should be.

And finally, you do not want to make it /too easy/ to send money over and
over again.  From a human-interface perspective, a textual reminder to send
money might be preferred over actual recurring payment automation: reminder
email + manual spend inserts a bit of additional human thought and review
into the process, with all that entails.

-- 
Jeff Garzik
Bitcoin core developer and open source evangelist
BitPay, Inc.      https://bitpay.com/

[-- Attachment #2: Type: text/html, Size: 2160 bytes --]

 permalink raw reply	[|nested]
2014-01-28  4:43 ` Jeff Garzik

  2014-01-28  6:08   ` Odinn Cyberguerrilla
  
From: PikaPay @ 2014-01-28  5:07 UTC (permalink / raw)
  To: Jeff Garzik;  Bitcoin Dev, Stephane Brossier, Pierre-Alexandre Meyer

It could be useful to schedule x payments for y amount every z time
period, but you'd want to be able to pause or cancel at any time.

If you want the merchant to be able to request a series of payments
like a subscription, the merchant might also be able to request that
the subscription be paused or cancelled as well.


-  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
Richard Kohl  -  richard@pikapay•com

Twitter: @generalseven
Phone: +31 6 284 00112

PikaPay: Send Bitcoins with Twitter



 permalink raw reply	[|nested]
2014-01-28  4:43 ` Jeff Garzik
  2014-01-28  5:07   ` PikaPay

  2014-01-28  6:48     ` Jeff Garzik
  
From: Odinn Cyberguerrilla @ 2014-01-28  6:08 UTC (permalink / raw)
  To: Jeff Garzik;  Bitcoin Dev, Stephane Brossier, Pierre-Alexandre Meyer

Greatly appreciate seeing this discussion occur.  This is something that
potentially could be supported through a bounty - possibly a process BIP?

Possibly related: https://gist.github.com/ABISprotocol/8515891

> Yes, recurring payments and subscriptions is a frequently-requested
> feature.  It needs a new BIP.  Here is an outline:
>
> The situation is somewhat analogous to HTML5 local storage.  The remote
> (merchant) wants to initiate a persistent behavior.  This is bitcoin, so
> we
> have a "push" model for payment, and the user has complete control.  The
> merchant can, at most, send a "subscription request."  The user is
> responsible for making on-time payments after that point.
>
> Centralized services like coinbase.com or blockchain.info will have an
> easy
> time of it.  An automated program on their backend, sending payments as
> needed, is easy and direct.
>
> More inventive services might employ multisig transactions, generating and
> signing one signature of a TX, then sending that TX to the human for
> further signing and publishing.  A few competing vendors could offer bots
> that provide this signing service.
>
> Decentralized, standalone wallet clients will be somewhat troublesome.  We
> can store a local subscription request, and send recurring payments...  if
> the wallet app is running.  If not, the user will be missing payments,
> that
> perhaps they intended to make (rent!).
>
> Each of these solutions can be cancelled at any time by the user.  As
> such,
> a courtesy "subscription cancelled" message sent to the merchant is
> recommended.  User controls the usage of their money at all times, the way
> things should be.
>
> And finally, you do not want to make it /too easy/ to send money over and
> over again.  From a human-interface perspective, a textual reminder to
> send
> money might be preferred over actual recurring payment automation:
> reminder
> email + manual spend inserts a bit of additional human thought and review
> into the process, with all that entails.
>
> --
> Jeff Garzik
> Bitcoin core developer and open source evangelist
> BitPay, Inc.      https://bitpay.com/
> ------------------------------------------------------------------------------
> WatchGuard Dimension instantly turns raw network data into actionable
> security intelligence. It gives you real-time visual feedback on key
> security issues and trends.  Skip the complicated setup - simply import
> a virtual appliance and go from zero to informed in seconds.
> http://pubads.g.doubleclick.net/gampad/clk?id=123612991&iu=/4140/ostg.clktrk_______________________________________________
> Bitcoin-development mailing list
> Bitcoin-development@lists•sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>





 permalink raw reply	[|nested]
2014-01-28  2:36 [Bitcoin-development] Extension for BIP-0070 to support recurring payments Stephane Brossier
                   ` (2 preceding siblings ...)
  2014-01-28  4:43 ` Jeff Garzik

  2014-01-29  2:47   ` Stephane Brossier
  
From: Mike Hearn @ 2014-01-28  6:34 UTC (permalink / raw)
  To: Stephane Brossier;  Bitcoin Dev, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 3979 bytes --]

I think the right approach for this is to actually implement it and
*then* propose
a BIP. There are so many possible features we could add to the payment
protocol, any other approach would rapidly turn into lots of people
deciding to do the "fun bits" and often leaving others doing the hard work
with difficult or unworkable specs.

For instance, if you try to implement this, you would rapidly discover that
it probably makes more sense to do this as an additional set of fields in
PaymentDetails rather than a new message type entirely. A new top level
message type would in turn require new MIME types, URI extensions and so
on. That doesn't make any sense.

Once you decide to extend PaymentDetails, the next discovery would be that
it probably makes sense to try and solve the problem of address re-use for
recurring payments first, before speccing out time intervals and so on.
That's a separate BIP.

I'm all for adding recurring payments as a feature, that's what the
protocol is there for. But I'd like to see future protocol extension
requests come after at least one working implementation has been made .....


On Tue, Jan 28, 2014 at 3:36 AM, Stephane Brossier
<stephane@kill-bill•org>wrote:

> Hi,
>
> [I sent this email 2 days ago prior my registration to the mailing list;
> please forgive me if this is a duplicate]
>
> I would like to propose an extension to the Payment Protocol (bip-0070) to
> address the case of recurring payments in Bitcoin -- new bip or
> modification of bip-0070.
>
> There has been a lot of growth in the last few years in the 'subscription
> economy' with many new companies embracing that model -- online video,
> gaming, groceries, newspapers,... In parallel, Bitcoin is growing into a
> mainstream currency (hence bip-0070), and so the next logical step would be
> to define a protocol to address that need.
>
> We have been working in the past few years on an open-source billing
> platform (http://kill-bill.org/), and recently came with a prototype to
> do recurring billing in Bitcoin (see
> http://thekillbillstory.wordpress.com/2014/01/20/bitcoin-plugin/ and
> http://thekillbillstory.wordpress.com/2014/01/11/coinbase-integration-experiment/
> ).
>
>
> The work flow would look similar to the one from bip-0070. There would
> need to be some additions; the flow could be summarized as follow:
>
> 0. Click: 'Subscribe Now'
> 1. Wallet would get  a RecurringPaymentRequestAuth which describes the
> nature of the future recurring payments
> 2. The Customer would get prompted from the wallet to authorize it.
> 3. The wallet would then poll the Merchant server (startup time, and/or
> well defined frequency) and potentially merchant would start issuing a
> PaymentRequest); the role of the wallet is to ensure that PaymentRequest is
> within the bounds of what was accepted by the customer-- amount,
> frequency,.. If it is, then it would make the Payment the same way it works
> for bip-0070
>
> Is that something that the community would be interested in? We could
> provide more details about the protocol we have in mind (messages and
> flow), and also provide an implementation with bitcoinj as a wallet and
> Kill Bill as a merchant server.
>
> Le me know what you think.
>
> Stéphane
>
>
> ------------------------------------------------------------------------------
> WatchGuard Dimension instantly turns raw network data into actionable
> security intelligence. It gives you real-time visual feedback on key
> security issues and trends.  Skip the complicated setup - simply import
> a virtual appliance and go from zero to informed in seconds.
>
> http://pubads.g.doubleclick.net/gampad/clk?id=123612991&iu=/4140/ostg.clktrk
> _______________________________________________
> Bitcoin-development mailing list
> Bitcoin-development@lists•sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>
>

[-- Attachment #2: Type: text/html, Size: 5147 bytes --]

 permalink raw reply	[|nested]
2014-01-28  6:08   ` Odinn Cyberguerrilla

  
From: Jeff Garzik @ 2014-01-28  6:48 UTC (permalink / raw)
  To: Odinn Cyberguerrilla
  Cc: Bitcoin Dev, Stephane Brossier, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 3194 bytes --]

Let's keep fund raising off this mailing list, please.  PS bounties don't
work.


On Tue, Jan 28, 2014 at 1:08 AM, Odinn Cyberguerrilla <
odinn.cyberguerrilla@riseup•net> wrote:

> Greatly appreciate seeing this discussion occur.  This is something that
> potentially could be supported through a bounty - possibly a process BIP?
>
> Possibly related: https://gist.github.com/ABISprotocol/8515891
>
> > Yes, recurring payments and subscriptions is a frequently-requested
> > feature.  It needs a new BIP.  Here is an outline:
> >
> > The situation is somewhat analogous to HTML5 local storage.  The remote
> > (merchant) wants to initiate a persistent behavior.  This is bitcoin, so
> > we
> > have a "push" model for payment, and the user has complete control.  The
> > merchant can, at most, send a "subscription request."  The user is
> > responsible for making on-time payments after that point.
> >
> > Centralized services like coinbase.com or blockchain.info will have an
> > easy
> > time of it.  An automated program on their backend, sending payments as
> > needed, is easy and direct.
> >
> > More inventive services might employ multisig transactions, generating
> and
> > signing one signature of a TX, then sending that TX to the human for
> > further signing and publishing.  A few competing vendors could offer bots
> > that provide this signing service.
> >
> > Decentralized, standalone wallet clients will be somewhat troublesome.
>  We
> > can store a local subscription request, and send recurring payments...
>  if
> > the wallet app is running.  If not, the user will be missing payments,
> > that
> > perhaps they intended to make (rent!).
> >
> > Each of these solutions can be cancelled at any time by the user.  As
> > such,
> > a courtesy "subscription cancelled" message sent to the merchant is
> > recommended.  User controls the usage of their money at all times, the
> way
> > things should be.
> >
> > And finally, you do not want to make it /too easy/ to send money over and
> > over again.  From a human-interface perspective, a textual reminder to
> > send
> > money might be preferred over actual recurring payment automation:
> > reminder
> > email + manual spend inserts a bit of additional human thought and review
> > into the process, with all that entails.
> >
> > --
> > Jeff Garzik
> > Bitcoin core developer and open source evangelist
> > BitPay, Inc.      https://bitpay.com/
> >
> ------------------------------------------------------------------------------
> > WatchGuard Dimension instantly turns raw network data into actionable
> > security intelligence. It gives you real-time visual feedback on key
> > security issues and trends.  Skip the complicated setup - simply import
> > a virtual appliance and go from zero to informed in seconds.
> >
> http://pubads.g.doubleclick.net/gampad/clk?id=123612991&iu=/4140/ostg.clktrk_______________________________________________
> > Bitcoin-development mailing list
> > Bitcoin-development@lists•sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/bitcoin-development
> >
>
>
>


-- 
Jeff Garzik
Bitcoin core developer and open source evangelist
BitPay, Inc.      https://bitpay.com/

[-- Attachment #2: Type: text/html, Size: 4605 bytes --]

 permalink raw reply	[|nested]
2014-01-28  6:34 ` Mike Hearn

  2014-01-31 18:13     ` Mike Hearn
  
From: Stephane Brossier @ 2014-01-29  2:47 UTC (permalink / raw)
  To: bitcoin-development;  Pierre-Alexandre Meyer, PikaPay

[-- Attachment #1: Type: text/plain, Size: 6602 bytes --]

From what I have seen so far, there seems to be an agreement that this is a nice feature to add. We are pretty new to that community and so we don't know exactly what the process is, and in particular how we reach consensus via email. I am certainly open to follow 'the way' if there is one, but one solution would be to follow Mike's suggestion on providing a (prototype) implementation first and then defining/refining the BIP. Odinn also suggested a possible retribution for our time through crowd-sourcing which I am interested to pursue if that makes sense.


We have quite some experience on the subscription side of things and while we are growing our knowledge on the Bitcoin technology (and ecosystem at large) we would benefit from:
* some feedbacks on the high level proposal
* additional requirements we might have missed

So, below is a high level description of what we have in mind. If this sounds reasonable, we could start working on an implementation.


 
I. Abstract
---------------

This describes a protocol to enable recurring payments in bitcoins and can be seen as an extension of BIP-0070. The main goal here is to have the customer subscribe to a service of some kind (that is, agreeing on the terms of that subscription contract), and then have the wallet make recurring payments without any intervention from the customer as long as the payments match what the customer agreed on paying.

An example of such service would be an online streaming website, to which a user pays a fixed recurring monthly fee to access videos (a.k.a. resources). Note that there is also usage based billing: for example, the user may need to purchase additional access for premium videos (overage charges). This type of billing is more complicated and there are many variations to it used in the industry (pre-paid, …). For the sake of discussion, we’ll focus on fixed recurring payments only, but we will keep usage in mind to make sure the protocol will be able to support it as well.


II. Motivation
------------------

Subscription based services have been growing in the past few years and so the intent it to make it possible for customers to pay in bitcoins. 

Bitcoin’s push model presents new advantages for the customer compared to traditional payment methods: the user has control over the subscription (for example, there is no need to call the merchant to explicitly cancel the credit card payments). It also opens the door to subscription management tools in wallets (e.g. Hive apps), which would give user an overview of what they are paying each month.


III. Flow of Operations
----------------------------------------


Creation of the subscription:
- - - - - - - - - - - - - - - - - - - - - - 

1. The customer clicks 'subscribe' -> A message is sent to the merchant.
2. The merchant sends back a message to the wallet with the details of the subscription such as the amount to be paid. In reality, there will be more information but for the purpose of the prototype implementation this is sufficient.
3. The wallet prompts the customer for authorization.
4. The customer authorizes (or denies) it.
5. The wallet sends the confirmation to the merchant.
6. The merchant confirms the subscription was created.

Ongoing payments:
- - - - - - - - - - - - - - - -

From that time on and since Bitcoin is a 'push' model, the wallet is responsible to poll the merchant for due payments associated with that subscription. Note that the merchant could specify hints to the wallet on when to poll (specific dates) or not during the registration of the subscription.

Note that we can't simply have the wallet push X bitcoins every month: the user account on the merchant side may have gotten credits, invoice adjustments, etc. since the last invoice, so the amount to pay for a given billing period may be lower than the regular amount. It could even be zero if the user decides to make a one-time payment to the merchant directly using a different wallet. Hence, the wallet needs to get the latest invoice balance to make sure how much it should pay. This also opens the door for the support of overage charges.


Quick note on the implementation on the merchant side: an entitlement system is a piece of logic on the merchant side which grants the user access to certain resources depending on the account status (unpaid invoices, etc.). This goes often hand in hand with a dunning system, which progressively restricts access as the user's account is more and more overdue. Since wallets can be offline for an extended period of time, payments may be missed and lead to an overdue state (e.g. extra fees, service degraded). It is the responsibility of the customer to ensure the wallet is up often enough for payments to happen.


In that recurring phase where the wallet polls the merchant, the wallet is responsible to check that payments match the subscription contract; that is, the amount, frequency of payments, … match what the customer agreed on. If so, the payment is made without asking for explicit approval from customer, and the flow is similar to BIP-0070: The message is sent to the merchant, and in parallel, a transaction is sent to the btcnet. The merchant sends an ACK to the wallet and of course checks the states of the transactions on the btcnet to mark that payment as successful.

Subscription change (optional):
- - - - - - - - - - - - - - - - - - - - - - - - 

Optionally we could implement a change in the ongoing subscription to address the upgrade/downgrade scenarios. Of course, we could also simply support a cancellation followed by a creation of a new subscription, but having that as a one atomic message is probably better. The steps are very similar to the initial registration.

1. The customer clicks 'upgrade', 'downgrade', … -> A msg is sent to the merchant.
2. The merchant sends back a msg to the wallet with the detail of the NEW subscription. 
3. The wallet prompts the customer for authorization.
4. The customer authorizes (or denies) it.
5. The wallet sends the confirmation to the merchant.
6. The merchant confirms the change in the subscription.

Cancellation of the subscription:
- - - - - - - - - - - - - - - - - - - - - - - - - 

The cancellation is initiated from the customer:

1. The customer clicks 'cancel' -> The wallet is informed that it  should not accept any new payment associated to that subscription.
2. The wallet sends a message to the merchant to inform about the cancellation.
3. The merchant confirms the subscription was cancelled.



[-- Attachment #2: Type: text/html, Size: 20159 bytes --]

 permalink raw reply	[|nested]
2014-01-29  2:47   ` Stephane Brossier

  2014-02-08  2:57       ` Stephane Brossier
  
From: Mike Hearn @ 2014-01-31 18:13 UTC (permalink / raw)
  To: Stephane Brossier;  bitcoin-development, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 7457 bytes --]

That looks OK at a very high level. Things you probably want to think about:

   - How to trigger it off the existing payment protocol (no new top level
   messages or mime types or uri extensions please)
   - Data structures to define the payment schedule
   - Do you allow pre-submission of time locked transactions or not?

I think as you prototype these things will become clearer.  You could try
prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the
PaymentSession class).



On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier
<stephane@kill-bill•org>wrote:

>
>
>
>
>
>
>
>
>
>
>
>
>
> *From what I have seen so far, there seems to be an agreement that this is
> a nice feature to add. We are pretty new to that community and so we don't
> know exactly what the process is, and in particular how we reach consensus
> via email. I am certainly open to follow 'the way' if there is one, but one
> solution would be to follow Mike's suggestion on providing a (prototype)
> implementation first and then defining/refining the BIP. Odinn also
> suggested a possible retribution for our time through crowd-sourcing which
> I am interested to pursue if that makes sense.We have quite some experience
> on the subscription side of things and while we are growing our knowledge
> on the Bitcoin technology (and ecosystem at large) we would benefit from:*
> some feedbacks on the high level proposal* additional requirements we might
> have missedSo, below is a high level description of what we have in mind.
> If this sounds reasonable, we could start working on an implementation. I.
> Abstract---------------This describes a protocol to enable recurring
> payments in bitcoins and can be seen as an extension of BIP-0070. The main
> goal here is to have the customer subscribe to a service of some kind (that
> is, agreeing on the terms of that subscription contract), and then have the
> wallet make recurring payments without any intervention from the customer
> as long as the payments match what the customer agreed on paying.An example
> of such service would be an online streaming website, to which a user pays
> a fixed recurring monthly fee to access videos (a.k.a. resources). Note
> that there is also usage based billing: for example, the user may need to
> purchase additional access for premium videos (overage charges). This type
> of billing is more complicated and there are many variations to it used in
> the industry (pre-paid, …). For the sake of discussion, we’ll focus on
> fixed recurring payments only, but we will keep usage in mind to make sure
> the protocol will be able to support it as well.II.
> Motivation------------------Subscription based services have been growing
> in the past few years and so the intent it to make it possible for
> customers to pay in bitcoins. Bitcoin’s push model presents new advantages
> for the customer compared to traditional payment methods: the user has
> control over the subscription (for example, there is no need to call the
> merchant to explicitly cancel the credit card payments). It also opens the
> door to subscription management tools in wallets (e.g. Hive apps), which
> would give user an overview of what they are paying each month.III. Flow of
> Operations----------------------------------------*
>
>
>
>
> *Creation of the subscription:- - - - - - - - - - - - - - - - - - - - - -
> 1. The customer clicks 'subscribe' -> A message is sent to the merchant.2.
> The merchant sends back a message to the wallet with the details of the
> subscription such as the amount to be paid. In reality, there will be more
> information but for the purpose of the prototype implementation this is
> sufficient.3. The wallet prompts the customer for authorization.4. The
> customer authorizes (or denies) it.5. The wallet sends the confirmation to
> the merchant.6. The merchant confirms the subscription was created.Ongoing
> payments:*
>
> *- - - - - - - - - - - - - - - -*
>
>
>
>
>
>
> *From that time on and since Bitcoin is a 'push' model, the wallet is
> responsible to poll the merchant for due payments associated with that
> subscription. Note that the merchant could specify hints to the wallet on
> when to poll (specific dates) or not during the registration of the
> subscription.Note that we can't simply have the wallet push X bitcoins
> every month: the user account on the merchant side may have gotten credits,
> invoice adjustments, etc. since the last invoice, so the amount to pay for
> a given billing period may be lower than the regular amount. It could even
> be zero if the user decides to make a one-time payment to the merchant
> directly using a different wallet. Hence, the wallet needs to get the
> latest invoice balance to make sure how much it should pay. This also opens
> the door for the support of overage charges.Quick note on the
> implementation on the merchant side: an entitlement system is a piece of
> logic on the merchant side which grants the user access to certain
> resources depending on the account status (unpaid invoices, etc.). This
> goes often hand in hand with a dunning system, which progressively
> restricts access as the user's account is more and more overdue. Since
> wallets can be offline for an extended period of time, payments may be
> missed and lead to an overdue state (e.g. extra fees, service degraded). It
> is the responsibility of the customer to ensure the wallet is up often
> enough for payments to happen.In that recurring phase where the wallet
> polls the merchant, the wallet is responsible to check that payments match
> the subscription contract; that is, the amount, frequency of payments, …
> match what the customer agreed on. If so, the payment is made without
> asking for explicit approval from customer, and the flow is similar to
> BIP-0070: The message is sent to the merchant, and in parallel, a
> transaction is sent to the btcnet. The merchant sends an ACK to the wallet
> and of course checks the states of the transactions on the btcnet to mark
> that payment as successful.Subscription change (optional):*
>
> *- - - - - - - - - - - - - - - - - - - - - - - - *
>
>
> *Optionally we could implement a change in the ongoing subscription to
> address the upgrade/downgrade scenarios. Of course, we could also simply
> support a cancellation followed by a creation of a new subscription, but
> having that as a one atomic message is probably better. The steps are very
> similar to the initial registration.1. The customer clicks 'upgrade',
> 'downgrade', … -> A msg is sent to the merchant.2. The merchant sends back
> a msg to the wallet with the detail of the NEW subscription. 3. The wallet
> prompts the customer for authorization.4. The customer authorizes (or
> denies) it.5. The wallet sends the confirmation to the merchant.6. The
> merchant confirms the change in the subscription.Cancellation of the
> subscription:*
>
> *- - - - - - - - - - - - - - - - - - - - - - - - - *
>
>
>
> *The cancellation is initiated from the customer:1. The customer clicks
> 'cancel' -> The wallet is informed that it  should not accept any new
> payment associated to that subscription.2. The wallet sends a message to
> the merchant to inform about the cancellation.3. The merchant confirms the
> subscription was cancelled.*
>

[-- Attachment #2: Type: text/html, Size: 19947 bytes --]

 permalink raw reply	[|nested]
2014-01-31 18:13     ` Mike Hearn

  2014-02-09  2:48         ` Stephane Brossier
  2014-02-11 16:24         ` Mike Hearn
  
From: Stephane Brossier @ 2014-02-08  2:57 UTC (permalink / raw)
  To: Mike Hearn;  bitcoin-development, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 8633 bytes --]

Mike and all,

Pierre and I just committed a prototype implementation of the recurring payment protocol using bitcoinj. You can find the diff on our fork: 
https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7

We did not write the server (merchant side), but wanted to have some feedback before going deeper (merchant implementation and tests). We did our best to build it on top of the existing BIP-0070 protocol-- only a few additions in the messages, but no new calls and no new uri scheme. We created a new package 'recurring' where most of the new code lives.

At a high level:

1. Creation of the subscription:

The initial handshake for creating the subscription is exactly similar to the one for the payment protocol (PaymentRequest is used to provide the contract)

2. Wallet can decide to poll the merchants for its active subscriptions.

Here the flow is exactly similar to the payment protocol but the wallet receives a callback to verify the payment matches the contract and should go through.

Please give us some feedback whenever you have the chance. In the meantime we will start implementing the merchant side and test the code.

Cheers!



On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:

> That looks OK at a very high level. Things you probably want to think about:
> How to trigger it off the existing payment protocol (no new top level messages or mime types or uri extensions please)
> Data structures to define the payment schedule
> Do you allow pre-submission of time locked transactions or not?
> I think as you prototype these things will become clearer.  You could try prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the PaymentSession class).
> 
> 
> 
> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <stephane@kill-bill•org> wrote:
> From what I have seen so far, there seems to be an agreement that this is a nice feature to add.  We are pretty new to that community and so we don't know exactly what the process is, and in particular how we reach consensus via email. I am certainly open to follow 'the way' if there is one, but one solution would be to follow Mike's suggestion on providing a (prototype) implementation first and then defining/refining the BIP. Odinn also suggested a possible retribution for our time through crowd-sourcing which I am interested to pursue if that makes sense.
> 
> 
> We have quite some experience on the subscription side of things and while we are growing our knowledge on the Bitcoin technology (and ecosystem at large) we would benefit from:
> * some feedbacks on the high level proposal
> * additional requirements we might have missed
> 
> So, below is a high level description of what we have in mind. If this sounds reasonable, we could start working on an implementation.
> 
> 
>  
> I. Abstract
> ---------------
> 
> This describes a protocol to enable recurring payments in bitcoins and can be seen as an extension of BIP-0070. The main goal here is to have the customer subscribe to a service of some kind (that is, agreeing on the terms of that subscription contract), and then have the wallet make recurring payments without any intervention from the customer as long as the payments match what the customer agreed on paying.
> 
> An example of such service would be an online streaming website, to which a user pays a fixed recurring monthly fee to access videos (a.k.a. resources). Note that there is also usage based billing: for example, the user may need to purchase additional access for premium videos (overage charges). This type of billing is more complicated and there are many variations to it used in the industry (pre-paid, …). For the sake of discussion, we’ll focus on fixed recurring payments only, but we will keep usage in mind to make sure the protocol will be able to support it as well.
> 
> 
> II. Motivation
> ------------------
> 
> Subscription based services have been growing in the past few years and so the intent it to make it possible for customers to pay in bitcoins. 
> 
> Bitcoin’s push model presents new advantages for the customer compared to traditional payment methods: the user has control over the subscription (for example, there is no need to call the merchant to explicitly cancel the credit card payments). It also opens the door to subscription management tools in wallets (e.g. Hive apps), which would give user an overview of what they are paying each month.
> 
> 
> III. Flow of Operations
> ----------------------------------------
> 
> 
> Creation of the subscription:
> - - - - - - - - - - - - - - - - - - - - - - 
> 
> 1. The customer clicks 'subscribe' -> A message is sent to the merchant.
> 2. The merchant sends back a message to the wallet with the details of the subscription such as the amount to be paid. In reality, there will be more information but for the purpose of the prototype implementation this is sufficient.
> 3. The wallet prompts the customer for authorization.
> 4. The customer authorizes (or denies) it.
> 5. The wallet sends the confirmation to the merchant.
> 6. The merchant confirms the subscription was created.
> 
> Ongoing payments:
> - - - - - - - - - - - - - - - -
> 
> From that time on and since Bitcoin is a 'push' model, the wallet is responsible to poll the merchant for due payments associated with that subscription. Note that the merchant could specify hints to the wallet on when to poll (specific dates) or not during the registration of the subscription.
> 
> Note that we can't simply have the wallet push X bitcoins every month: the user account on the merchant side may have gotten credits, invoice adjustments, etc. since the last invoice, so the amount to pay for a given billing period may be lower than the regular amount. It could even be zero if the user decides to make a one-time payment to the merchant directly using a different wallet. Hence, the wallet needs to get the latest invoice balance to make sure how much it should pay. This also opens the door for the support of overage charges.
> 
> 
> Quick note on the implementation on the merchant side: an entitlement system is a piece of logic on the merchant side which grants the user access to certain resources depending on the account status (unpaid invoices, etc.). This goes often hand in hand with a dunning system, which progressively restricts access as the user's account is more and more overdue. Since wallets can be offline for an extended period of time, payments may be missed and lead to an overdue state (e.g. extra fees, service degraded). It is the responsibility of the customer to ensure the wallet is up often enough for payments to happen.
> 
> 
> In that recurring phase where the wallet polls the merchant, the wallet is responsible to check that payments match the subscription contract; that is, the amount, frequency of payments, … match what the customer agreed on. If so, the payment is made without asking for explicit approval from customer, and the flow is similar to BIP-0070: The message is sent to the merchant, and in parallel, a transaction is sent to the btcnet. The merchant sends an ACK to the wallet and of course checks the states of the transactions on the btcnet to mark that payment as successful.
> 
> Subscription change (optional):
> - - - - - - - - - - - - - - - - - - - - - - - - 
> 
> Optionally we could implement a change in the ongoing subscription to address the upgrade/downgrade scenarios. Of course, we could also simply support a cancellation followed by a creation of a new subscription, but having that as a one atomic message is probably better. The steps are very similar to the initial registration.
> 
> 1. The customer clicks 'upgrade', 'downgrade', … -> A msg is sent to the merchant.
> 2. The merchant sends back a msg to the wallet with the detail of the NEW subscription. 
> 3. The wallet prompts the customer for authorization.
> 4. The customer authorizes (or denies) it.
> 5. The wallet sends the confirmation to the merchant.
> 6. The merchant confirms the change in the subscription.
> 
> Cancellation of the subscription:
> - - - - - - - - - - - - - - - - - - - - - - - - - 
> 
> The cancellation is initiated from the customer:
> 
> 1. The customer clicks 'cancel' -> The wallet is informed that it  should not accept any new payment associated to that subscription.
> 2. The wallet sends a message to the merchant to inform about the cancellation.
> 3. The merchant confirms the subscription was cancelled.
> 
> 
> 


[-- Attachment #2: Type: text/html, Size: 21861 bytes --]

 permalink raw reply	[|nested]
2014-02-08  2:57       ` Stephane Brossier

  2014-02-11 10:00           ` Kevin Greene
  2014-02-11 16:24         ` Mike Hearn
  
From: Stephane Brossier @ 2014-02-09  2:48 UTC (permalink / raw)
  To: Mike Hearn, gavinandresen;  bitcoin-development, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 9716 bytes --]

Mike, Gavin,


We started to work on the merchant side to test the integration of our prototype for the recurring payments. We modified the 'Payment Request Generator' from Gavin to include a new check box 'set recurring'. We forked the code and checked in our modification here: https://github.com/killbill/paymentrequest/commit/e530f6ec528266aacfd076d7c3154ad39267c3f3

We also found a few issues with the code diff that we sent yesterday for bitcoinj and checked in the bug fixes  in our fork-- so the diff sent yesterday is slightly outdated.

So at this point we have a working prototype for bitcoinj and we are waiting for your feedbacks. We also started to look at integrating the protocol in Kill Bill to check that what is proposed supports indeed the business cases of a full recurring billing platform.

Hope to hear from you guys soon!


On Feb 7, 2014, at 6:57 PM, Stephane Brossier <stephane@kill-bill•org> wrote:

> Mike and all,
> 
> Pierre and I just committed a prototype implementation of the recurring payment protocol using bitcoinj. You can find the diff on our fork: 
> https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7
> 
> We did not write the server (merchant side), but wanted to have some feedback before going deeper (merchant implementation and tests). We did our best to build it on top of the existing BIP-0070 protocol-- only a few additions in the messages, but no new calls and no new uri scheme. We created a new package 'recurring' where most of the new code lives.
> 
> At a high level:
> 
> 1. Creation of the subscription:
> 
> The initial handshake for creating the subscription is exactly similar to the one for the payment protocol (PaymentRequest is used to provide the contract)
> 
> 2. Wallet can decide to poll the merchants for its active subscriptions.
> 
> Here the flow is exactly similar to the payment protocol but the wallet receives a callback to verify the payment matches the contract and should go through.
> 
> Please give us some feedback whenever you have the chance. In the meantime we will start implementing the merchant side and test the code.
> 
> Cheers!
> 
> 
> 
> On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:
> 
>> That looks OK at a very high level. Things you probably want to think about:
>> How to trigger it off the existing payment protocol (no new top level messages or mime types or uri extensions please)
>> Data structures to define the payment schedule
>> Do you allow pre-submission of time locked transactions or not?
>> I think as you prototype these things will become clearer.  You could try prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the PaymentSession class).
>> 
>> 
>> 
>> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <stephane@kill-bill•org> wrote:
>> From what I have seen so far, there seems to be an agreement that this is a nice feature to add.  We are pretty new to that community and so we don't know exactly what the process is, and in particular how we reach consensus via email. I am certainly open to follow 'the way' if there is one, but one solution would be to follow Mike's suggestion on providing a (prototype) implementation first and then defining/refining the BIP. Odinn also suggested a possible retribution for our time through crowd-sourcing which I am interested to pursue if that makes sense.
>> 
>> 
>> We have quite some experience on the subscription side of things and while we are growing our knowledge on the Bitcoin technology (and ecosystem at large) we would benefit from:
>> * some feedbacks on the high level proposal
>> * additional requirements we might have missed
>> 
>> So, below is a high level description of what we have in mind. If this sounds reasonable, we could start working on an implementation.
>> 
>> 
>>  
>> I. Abstract
>> ---------------
>> 
>> This describes a protocol to enable recurring payments in bitcoins and can be seen as an extension of BIP-0070. The main goal here is to have the customer subscribe to a service of some kind (that is, agreeing on the terms of that subscription contract), and then have the wallet make recurring payments without any intervention from the customer as long as the payments match what the customer agreed on paying.
>> 
>> An example of such service would be an online streaming website, to which a user pays a fixed recurring monthly fee to access videos (a.k.a. resources). Note that there is also usage based billing: for example, the user may need to purchase additional access for premium videos (overage charges). This type of billing is more complicated and there are many variations to it used in the industry (pre-paid, …). For the sake of discussion, we’ll focus on fixed recurring payments only, but we will keep usage in mind to make sure the protocol will be able to support it as well.
>> 
>> 
>> II. Motivation
>> ------------------
>> 
>> Subscription based services have been growing in the past few years and so the intent it to make it possible for customers to pay in bitcoins. 
>> 
>> Bitcoin’s push model presents new advantages for the customer compared to traditional payment methods: the user has control over the subscription (for example, there is no need to call the merchant to explicitly cancel the credit card payments). It also opens the door to subscription management tools in wallets (e.g. Hive apps), which would give user an overview of what they are paying each month.
>> 
>> 
>> III. Flow of Operations
>> ----------------------------------------
>> 
>> 
>> Creation of the subscription:
>> - - - - - - - - - - - - - - - - - - - - - - 
>> 
>> 1. The customer clicks 'subscribe' -> A message is sent to the merchant.
>> 2. The merchant sends back a message to the wallet with the details of the subscription such as the amount to be paid. In reality, there will be more information but for the purpose of the prototype implementation this is sufficient.
>> 3. The wallet prompts the customer for authorization.
>> 4. The customer authorizes (or denies) it.
>> 5. The wallet sends the confirmation to the merchant.
>> 6. The merchant confirms the subscription was created.
>> 
>> Ongoing payments:
>> - - - - - - - - - - - - - - - -
>> 
>> From that time on and since Bitcoin is a 'push' model, the wallet is responsible to poll the merchant for due payments associated with that subscription. Note that the merchant could specify hints to the wallet on when to poll (specific dates) or not during the registration of the subscription.
>> 
>> Note that we can't simply have the wallet push X bitcoins every month: the user account on the merchant side may have gotten credits, invoice adjustments, etc. since the last invoice, so the amount to pay for a given billing period may be lower than the regular amount. It could even be zero if the user decides to make a one-time payment to the merchant directly using a different wallet. Hence, the wallet needs to get the latest invoice balance to make sure how much it should pay. This also opens the door for the support of overage charges.
>> 
>> 
>> Quick note on the implementation on the merchant side: an entitlement system is a piece of logic on the merchant side which grants the user access to certain resources depending on the account status (unpaid invoices, etc.). This goes often hand in hand with a dunning system, which progressively restricts access as the user's account is more and more overdue. Since wallets can be offline for an extended period of time, payments may be missed and lead to an overdue state (e.g. extra fees, service degraded). It is the responsibility of the customer to ensure the wallet is up often enough for payments to happen.
>> 
>> 
>> In that recurring phase where the wallet polls the merchant, the wallet is responsible to check that payments match the subscription contract; that is, the amount, frequency of payments, … match what the customer agreed on. If so, the payment is made without asking for explicit approval from customer, and the flow is similar to BIP-0070: The message is sent to the merchant, and in parallel, a transaction is sent to the btcnet. The merchant sends an ACK to the wallet and of course checks the states of the transactions on the btcnet to mark that payment as successful.
>> 
>> Subscription change (optional):
>> - - - - - - - - - - - - - - - - - - - - - - - - 
>> 
>> Optionally we could implement a change in the ongoing subscription to address the upgrade/downgrade scenarios. Of course, we could also simply support a cancellation followed by a creation of a new subscription, but having that as a one atomic message is probably better. The steps are very similar to the initial registration.
>> 
>> 1. The customer clicks 'upgrade', 'downgrade', … -> A msg is sent to the merchant.
>> 2. The merchant sends back a msg to the wallet with the detail of the NEW subscription. 
>> 3. The wallet prompts the customer for authorization.
>> 4. The customer authorizes (or denies) it.
>> 5. The wallet sends the confirmation to the merchant.
>> 6. The merchant confirms the change in the subscription.
>> 
>> Cancellation of the subscription:
>> - - - - - - - - - - - - - - - - - - - - - - - - - 
>> 
>> The cancellation is initiated from the customer:
>> 
>> 1. The customer clicks 'cancel' -> The wallet is informed that it  should not accept any new payment associated to that subscription.
>> 2. The wallet sends a message to the merchant to inform about the cancellation.
>> 3. The merchant confirms the subscription was cancelled.
>> 
>> 
>> 
> 


[-- Attachment #2: Type: text/html, Size: 23372 bytes --]

 permalink raw reply	[|nested]
2014-02-09  2:48         ` Stephane Brossier

  2014-02-11 18:01             ` Stephane Brossier
  
From: Kevin Greene @ 2014-02-11 10:00 UTC (permalink / raw)
  To: Stephane Brossier;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 11309 bytes --]

Figured I would have a crack at reviewing this since Mike is out for a bit.
It was great running into you guys at the bitcoin fair in SF! Small world :)

I like how simple this is. You just give it an url to fetch the next
payment request and a date to fetch it.

What should happen if the client tries to fetch the PaymentRequest early or
late? Does it become valid after some date and stay valid for some length
of time? Also, what should happen if the client tries to consume the same
PaymentRequest twice (or multiple times) during the same period?

I do not think daily/weekly/monthly is flexible enough. What do you think
about having a concrete start time and end time when the next
PaymentRequest will be valid? This also prevents the wallet from having to
remember when it last sent a payment and getting skewed over time.

When a wallet hits the polling_url to download the next PaymentRequest, it
seems we need a way to communicate an error code to the wallet, for example
if the server canceled the contract without the wallet knowing. Perhaps a
separate polling_status_url, with a corresponding ACK message to indicate
if the PaymentRequest is available. What do you think of that idea?

One high-level comment -- the wallet in this design doesn't have any way of
knowing when the payments are supposed to end. I feel this is important to
show to the user before they start their wallet polling infinitely.




On Sat, Feb 8, 2014 at 6:48 PM, Stephane Brossier <stephane@kill-bill•org>wrote:

> Mike, Gavin,
>
>
> We started to work on the merchant side to test the integration of our
> prototype for the recurring payments. We modified the 'Payment Request
> Generator' from Gavin to include a new check box 'set recurring'. We forked
> the code and checked in our modification here:
> https://github.com/killbill/paymentrequest/commit/e530f6ec528266aacfd076d7c3154ad39267c3f3
>
> We also found a few issues with the code diff that we sent yesterday for
> bitcoinj and checked in the bug fixes  in our fork-- so the diff sent
> yesterday is slightly outdated.
>
> So at this point we have a working prototype for bitcoinj and we are
> waiting for your feedbacks. We also started to look at integrating the
> protocol in Kill Bill to check that what is proposed supports indeed the
> business cases of a full recurring billing platform.
>
> Hope to hear from you guys soon!
>
>
> On Feb 7, 2014, at 6:57 PM, Stephane Brossier <stephane@kill-bill•org>
> wrote:
>
> Mike and all,
>
> Pierre and I just committed a prototype implementation of the recurring
> payment protocol using bitcoinj. You can find the diff on our fork:
>
> https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7
>
> We did not write the server (merchant side), but wanted to have some
> feedback before going deeper (merchant implementation and tests). We did
> our best to build it on top of the existing BIP-0070 protocol-- only a few
> additions in the messages, but no new calls and no new uri scheme. We
> created a new package 'recurring' where most of the new code lives.
>
> At a high level:
>
> 1. Creation of the subscription:
>
> The initial handshake for creating the subscription is exactly similar to
> the one for the payment protocol (PaymentRequest is used to provide the
> contract)
>
> 2. Wallet can decide to poll the merchants for its active subscriptions.
>
> Here the flow is exactly similar to the payment protocol but the wallet
> receives a callback to verify the payment matches the contract and should
> go through.
>
> Please give us some feedback whenever you have the chance. In the meantime
> we will start implementing the merchant side and test the code.
>
> Cheers!
>
>
>
> On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:
>
> That looks OK at a very high level. Things you probably want to think
> about:
>
>    - How to trigger it off the existing payment protocol (no new top
>    level messages or mime types or uri extensions please)
>    - Data structures to define the payment schedule
>    - Do you allow pre-submission of time locked transactions or not?
>
> I think as you prototype these things will become clearer.  You could try
> prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the
> PaymentSession class).
>
>
>
> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <stephane@kill-bill•org
> > wrote:
>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> *From what I have seen so far, there seems to be an agreement that this
>> is a nice feature to add. We are pretty new to that community and so we
>> don't know exactly what the process is, and in particular how we reach
>> consensus via email. I am certainly open to follow 'the way' if there is
>> one, but one solution would be to follow Mike's suggestion on providing a
>> (prototype) implementation first and then defining/refining the BIP. Odinn
>> also suggested a possible retribution for our time through crowd-sourcing
>> which I am interested to pursue if that makes sense. We have quite some
>> experience on the subscription side of things and while we are growing our
>> knowledge on the Bitcoin technology (and ecosystem at large) we would
>> benefit from: * some feedbacks on the high level proposal * additional
>> requirements we might have missed So, below is a high level description of
>> what we have in mind. If this sounds reasonable, we could start working on
>> an implementation. I. Abstract --------------- This describes a protocol to
>> enable recurring payments in bitcoins and can be seen as an extension of
>> BIP-0070. The main goal here is to have the customer subscribe to a service
>> of some kind (that is, agreeing on the terms of that subscription
>> contract), and then have the wallet make recurring payments without any
>> intervention from the customer as long as the payments match what the
>> customer agreed on paying. An example of such service would be an online
>> streaming website, to which a user pays a fixed recurring monthly fee to
>> access videos (a.k.a. resources). Note that there is also usage based
>> billing: for example, the user may need to purchase additional access for
>> premium videos (overage charges). This type of billing is more complicated
>> and there are many variations to it used in the industry (pre-paid, ...). For
>> the sake of discussion, we'll focus on fixed recurring payments only, but
>> we will keep usage in mind to make sure the protocol will be able to
>> support it as well. II. Motivation ------------------ Subscription based
>> services have been growing in the past few years and so the intent it to
>> make it possible for customers to pay in bitcoins. Bitcoin's push model
>> presents new advantages for the customer compared to traditional payment
>> methods: the user has control over the subscription (for example, there is
>> no need to call the merchant to explicitly cancel the credit card
>> payments). It also opens the door to subscription management tools in
>> wallets (e.g. Hive apps), which would give user an overview of what they
>> are paying each month. III. Flow of
>> Operations----------------------------------------*
>>
>>
>>
>>
>> * Creation of the subscription: - - - - - - - - - - - - - - - - - - - - -
>> - 1. The customer clicks 'subscribe' -> A message is sent to the merchant.
>> 2. The merchant sends back a message to the wallet with the details of the
>> subscription such as the amount to be paid. In reality, there will be more
>> information but for the purpose of the prototype implementation this is
>> sufficient. 3. The wallet prompts the customer for authorization. 4. The
>> customer authorizes (or denies) it. 5. The wallet sends the confirmation to
>> the merchant. 6. The merchant confirms the subscription was created.
>> Ongoing payments: *
>>
>> *- - - - - - - - - - - - - - - - *
>>
>>
>>
>>
>>
>>
>> * From that time on and since Bitcoin is a 'push' model, the wallet is
>> responsible to poll the merchant for due payments associated with that
>> subscription. Note that the merchant could specify hints to the wallet on
>> when to poll (specific dates) or not during the registration of the
>> subscription. Note that we can't simply have the wallet push X bitcoins
>> every month: the user account on the merchant side may have gotten credits,
>> invoice adjustments, etc. since the last invoice, so the amount to pay for
>> a given billing period may be lower than the regular amount. It could even
>> be zero if the user decides to make a one-time payment to the merchant
>> directly using a different wallet. Hence, the wallet needs to get the
>> latest invoice balance to make sure how much it should pay. This also opens
>> the door for the support of overage charges. Quick note on the
>> implementation on the merchant side: an entitlement system is a piece of
>> logic on the merchant side which grants the user access to certain
>> resources depending on the account status (unpaid invoices, etc.). This
>> goes often hand in hand with a dunning system, which progressively
>> restricts access as the user's account is more and more overdue. Since
>> wallets can be offline for an extended period of time, payments may be
>> missed and lead to an overdue state (e.g. extra fees, service degraded). It
>> is the responsibility of the customer to ensure the wallet is up often
>> enough for payments to happen. In that recurring phase where the wallet
>> polls the merchant, the wallet is responsible to check that payments match
>> the subscription contract; that is, the amount, frequency of payments, ...
>> match what the customer agreed on. If so, the payment is made without
>> asking for explicit approval from customer, and the flow is similar to
>> BIP-0070: The message is sent to the merchant, and in parallel, a
>> transaction is sent to the btcnet. The merchant sends an ACK to the wallet
>> and of course checks the states of the transactions on the btcnet to mark
>> that payment as successful. Subscription change (optional): *
>>
>> *- - - - - - - - - - - - - - - - - - - - - - - - *
>>
>>
>> * Optionally we could implement a change in the ongoing subscription to
>> address the upgrade/downgrade scenarios. Of course, we could also simply
>> support a cancellation followed by a creation of a new subscription, but
>> having that as a one atomic message is probably better. The steps are very
>> similar to the initial registration. 1. The customer clicks 'upgrade',
>> 'downgrade', ... -> A msg is sent to the merchant. 2. The merchant sends back
>> a msg to the wallet with the detail of the NEW subscription. 3. The wallet
>> prompts the customer for authorization. 4. The customer authorizes (or
>> denies) it. 5. The wallet sends the confirmation to the merchant. 6. The
>> merchant confirms the change in the subscription. Cancellation of the
>> subscription: *
>>
>> *- - - - - - - - - - - - - - - - - - - - - - - - - *
>>
>>
>>
>> * The cancellation is initiated from the customer: 1. The customer clicks
>> 'cancel' -> The wallet is informed that it  should not accept any new
>> payment associated to that subscription. 2. The wallet sends a message to
>> the merchant to inform about the cancellation. 3. The merchant confirms the
>> subscription was cancelled. *
>>
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 26133 bytes --]

 permalink raw reply	[|nested]
2014-02-08  2:57       ` Stephane Brossier
  2014-02-09  2:48         ` Stephane Brossier

  
From: Mike Hearn @ 2014-02-11 16:24 UTC (permalink / raw)
  To: Stephane Brossier;  Bitcoin Dev, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 9260 bytes --]

Hey guys,

I'm on vacation now so won't be able to take a look until I'm back in a
couple of weeks but the approach sounds reasonable based on your
description.
On 8 Feb 2014 08:28, "Stephane Brossier" <stephane@kill-bill•org> wrote:

> Mike and all,
>
> Pierre and I just committed a prototype implementation of the recurring
> payment protocol using bitcoinj. You can find the diff on our fork:
>
> https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7
>
> We did not write the server (merchant side), but wanted to have some
> feedback before going deeper (merchant implementation and tests). We did
> our best to build it on top of the existing BIP-0070 protocol-- only a few
> additions in the messages, but no new calls and no new uri scheme. We
> created a new package 'recurring' where most of the new code lives.
>
> At a high level:
>
> 1. Creation of the subscription:
>
> The initial handshake for creating the subscription is exactly similar to
> the one for the payment protocol (PaymentRequest is used to provide the
> contract)
>
> 2. Wallet can decide to poll the merchants for its active subscriptions.
>
> Here the flow is exactly similar to the payment protocol but the wallet
> receives a callback to verify the payment matches the contract and should
> go through.
>
> Please give us some feedback whenever you have the chance. In the meantime
> we will start implementing the merchant side and test the code.
>
> Cheers!
>
>
>
> On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:
>
> That looks OK at a very high level. Things you probably want to think
> about:
>
>    - How to trigger it off the existing payment protocol (no new top
>    level messages or mime types or uri extensions please)
>    - Data structures to define the payment schedule
>    - Do you allow pre-submission of time locked transactions or not?
>
> I think as you prototype these things will become clearer.  You could try
> prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the
> PaymentSession class).
>
>
>
> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <stephane@kill-bill•org
> > wrote:
>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> *From what I have seen so far, there seems to be an agreement that this
>> is a nice feature to add. We are pretty new to that community and so we
>> don't know exactly what the process is, and in particular how we reach
>> consensus via email. I am certainly open to follow 'the way' if there is
>> one, but one solution would be to follow Mike's suggestion on providing a
>> (prototype) implementation first and then defining/refining the BIP. Odinn
>> also suggested a possible retribution for our time through crowd-sourcing
>> which I am interested to pursue if that makes sense. We have quite some
>> experience on the subscription side of things and while we are growing our
>> knowledge on the Bitcoin technology (and ecosystem at large) we would
>> benefit from: * some feedbacks on the high level proposal * additional
>> requirements we might have missed So, below is a high level description of
>> what we have in mind. If this sounds reasonable, we could start working on
>> an implementation. I. Abstract --------------- This describes a protocol to
>> enable recurring payments in bitcoins and can be seen as an extension of
>> BIP-0070. The main goal here is to have the customer subscribe to a service
>> of some kind (that is, agreeing on the terms of that subscription
>> contract), and then have the wallet make recurring payments without any
>> intervention from the customer as long as the payments match what the
>> customer agreed on paying. An example of such service would be an online
>> streaming website, to which a user pays a fixed recurring monthly fee to
>> access videos (a.k.a. resources). Note that there is also usage based
>> billing: for example, the user may need to purchase additional access for
>> premium videos (overage charges). This type of billing is more complicated
>> and there are many variations to it used in the industry (pre-paid, …). For
>> the sake of discussion, we’ll focus on fixed recurring payments only, but
>> we will keep usage in mind to make sure the protocol will be able to
>> support it as well. II. Motivation ------------------ Subscription based
>> services have been growing in the past few years and so the intent it to
>> make it possible for customers to pay in bitcoins. Bitcoin’s push model
>> presents new advantages for the customer compared to traditional payment
>> methods: the user has control over the subscription (for example, there is
>> no need to call the merchant to explicitly cancel the credit card
>> payments). It also opens the door to subscription management tools in
>> wallets (e.g. Hive apps), which would give user an overview of what they
>> are paying each month. III. Flow of
>> Operations----------------------------------------*
>>
>>
>>
>>
>> * Creation of the subscription: - - - - - - - - - - - - - - - - - - - - -
>> - 1. The customer clicks 'subscribe' -> A message is sent to the merchant.
>> 2. The merchant sends back a message to the wallet with the details of the
>> subscription such as the amount to be paid. In reality, there will be more
>> information but for the purpose of the prototype implementation this is
>> sufficient. 3. The wallet prompts the customer for authorization. 4. The
>> customer authorizes (or denies) it. 5. The wallet sends the confirmation to
>> the merchant. 6. The merchant confirms the subscription was created.
>> Ongoing payments: *
>>
>> *- - - - - - - - - - - - - - - - *
>>
>>
>>
>>
>>
>>
>> * From that time on and since Bitcoin is a 'push' model, the wallet is
>> responsible to poll the merchant for due payments associated with that
>> subscription. Note that the merchant could specify hints to the wallet on
>> when to poll (specific dates) or not during the registration of the
>> subscription. Note that we can't simply have the wallet push X bitcoins
>> every month: the user account on the merchant side may have gotten credits,
>> invoice adjustments, etc. since the last invoice, so the amount to pay for
>> a given billing period may be lower than the regular amount. It could even
>> be zero if the user decides to make a one-time payment to the merchant
>> directly using a different wallet. Hence, the wallet needs to get the
>> latest invoice balance to make sure how much it should pay. This also opens
>> the door for the support of overage charges. Quick note on the
>> implementation on the merchant side: an entitlement system is a piece of
>> logic on the merchant side which grants the user access to certain
>> resources depending on the account status (unpaid invoices, etc.). This
>> goes often hand in hand with a dunning system, which progressively
>> restricts access as the user's account is more and more overdue. Since
>> wallets can be offline for an extended period of time, payments may be
>> missed and lead to an overdue state (e.g. extra fees, service degraded). It
>> is the responsibility of the customer to ensure the wallet is up often
>> enough for payments to happen. In that recurring phase where the wallet
>> polls the merchant, the wallet is responsible to check that payments match
>> the subscription contract; that is, the amount, frequency of payments, …
>> match what the customer agreed on. If so, the payment is made without
>> asking for explicit approval from customer, and the flow is similar to
>> BIP-0070: The message is sent to the merchant, and in parallel, a
>> transaction is sent to the btcnet. The merchant sends an ACK to the wallet
>> and of course checks the states of the transactions on the btcnet to mark
>> that payment as successful. Subscription change (optional): *
>>
>> *- - - - - - - - - - - - - - - - - - - - - - - - *
>>
>>
>> * Optionally we could implement a change in the ongoing subscription to
>> address the upgrade/downgrade scenarios. Of course, we could also simply
>> support a cancellation followed by a creation of a new subscription, but
>> having that as a one atomic message is probably better. The steps are very
>> similar to the initial registration. 1. The customer clicks 'upgrade',
>> 'downgrade', … -> A msg is sent to the merchant. 2. The merchant sends back
>> a msg to the wallet with the detail of the NEW subscription. 3. The wallet
>> prompts the customer for authorization. 4. The customer authorizes (or
>> denies) it. 5. The wallet sends the confirmation to the merchant. 6. The
>> merchant confirms the change in the subscription. Cancellation of the
>> subscription: *
>>
>> *- - - - - - - - - - - - - - - - - - - - - - - - - *
>>
>>
>>
>> * The cancellation is initiated from the customer: 1. The customer clicks
>> 'cancel' -> The wallet is informed that it  should not accept any new
>> payment associated to that subscription. 2. The wallet sends a message to
>> the merchant to inform about the cancellation. 3. The merchant confirms the
>> subscription was cancelled. *
>>
>
>
>

[-- Attachment #2: Type: text/html, Size: 22382 bytes --]

 permalink raw reply	[|nested]
2014-02-11 10:00           ` Kevin Greene

  2014-02-12  6:32               ` Kevin Greene
  
From: Stephane Brossier @ 2014-02-11 18:01 UTC (permalink / raw)
  To: Kevin Greene;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 14273 bytes --]

Hi Kevin,

On Feb 11, 2014, at 2:00 AM, Kevin Greene <kgreenek@gmail•com> wrote:

> Figured I would have a crack at reviewing this since Mike is out for a bit. It was great running into you guys at the bitcoin fair in SF! Small world :)

Indeed! It was great meeting you! It's always nice to meet people in person...

> I like how simple this is. You just give it an url to fetch the next payment request and a date to fetch it.
> 
> What should happen if the client tries to fetch the PaymentRequest early or late?

If the client tries to fetch too early, then  the merchant will return a PaymentRequest with no output (there is nothing to pay yet). If it fetches too late, this is merchant specific. It could be that the service got discontinued -- extreme case -- or that there are now multiple PaymentRequest pending or that the merchant decided to aggregate those into one. In that scenario, it could lead to a case where the amount to pay goes beyond the contract and the wallet would refuse to make the recurring payment.

> Does it become valid after some date and stay valid for some length of time?

The protocol we sketched does not include (yet) an expiration date. At this point the contract is fairly minimal, and we could envision adding more parameters such as expiration date. So at this point the behavior would be dictated by the merchant.

> Also, what should happen if the client tries to consume the same PaymentRequest twice (or multiple times) during the same period?

The merchant initiates the PaymentRequest and is in charge to make sure they match the invoices that the client should pay. On the client side, the wallet is responsible to verify that the contract is respected, so if a merchant were to issue multiple times the same PaymentRequest, the wallet would detect it goes beyond the bonds defined in the contract and would refuse to make the additional Payments.

> I do not think daily/weekly/monthly is flexible enough. What do you think about having a concrete start time and end time when the next PaymentRequest will be valid?

I agree that daily/weekly/monthly may not be flexible enough. However specifying a fixed date may be very tricky because in some cases a monthly subscription may start on a 31st of a month, and depending on the month, the due date will vary -- could be 30th, 28th, 29th, ... Also note that the frequency (daily/weekly/monthly) is not used as a polling interval, but is only used to verify the contract is respected. 

There are multiple viable options to specify that contract and ideally we could/should support multiple schemes; different merchants could use different schemes, and the client would decide wether or not he is ready to accept the terms that will later be enforced by the wallet. But of course all this flexibility goes against simplicity and so this is tradeoff...


> This also prevents the wallet from having to remember when it last sent a payment and getting skewed over time.

Today, our current prototype is polling every day -- which is the lowest granularity we introduced -- and so there is no risk of getting skewed.


> When a wallet hits the polling_url to download the next PaymentRequest, it seems we need a way to communicate an error code to the wallet, for example if the server canceled the contract without the wallet knowing. Perhaps a separate polling_status_url, with a corresponding ACK message to indicate if the PaymentRequest is available. What do you think of that idea?

I think reporting such errors to the wallet would make complete sense. However i am not clear why we would a separate url for that?

> One high-level comment -- the wallet in this design doesn't have any way of knowing when the payments are supposed to end. I feel this is important to show to the user before they start their wallet polling infinitely.

Subscriptions are non ending by definition, but at any time the client (through the wallet) or the merchant can decide to terminate the subscriptions -- we did not yet implement cancellation in that prototype but we are planning to add it later this week. Think of your Netflix subscriptions, this is never ending (evergreen) until you decide to terminate it or Netflix does it (abuse, bills not paid,...)

Thanks for taking a look!

> 
> On Sat, Feb 8, 2014 at 6:48 PM, Stephane Brossier <stephane@kill-bill•org> wrote:
> Mike, Gavin,
> 
> 
> We started to work on the merchant side to test the integration of our prototype for the recurring payments. We modified the 'Payment Request Generator' from Gavin to include a new check box 'set recurring'. We forked the code and checked in our modification here: https://github.com/killbill/paymentrequest/commit/e530f6ec528266aacfd076d7c3154ad39267c3f3
> 
> We also found a few issues with the code diff that we sent yesterday for bitcoinj and checked in the bug fixes  in our fork-- so the diff sent yesterday is slightly outdated.
> 
> So at this point we have a working prototype for bitcoinj and we are waiting for your feedbacks. We also started to look at integrating the protocol in Kill Bill to check that what is proposed supports indeed the business cases of a full recurring billing platform.
> 
> Hope to hear from you guys soon!
> 
> 
> On Feb 7, 2014, at 6:57 PM, Stephane Brossier <stephane@kill-bill•org> wrote:
> 
>> Mike and all,
>> 
>> Pierre and I just committed a prototype implementation of the recurring payment protocol using bitcoinj. You can find the diff on our fork: 
>> https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7
>> 
>> We did not write the server (merchant side), but wanted to have some feedback before going deeper (merchant implementation and tests). We did our best to build it on top of the existing BIP-0070 protocol-- only a few additions in the messages, but no new calls and no new uri scheme. We created a new package 'recurring' where most of the new code lives.
>> 
>> At a high level:
>> 
>> 1. Creation of the subscription:
>> 
>> The initial handshake for creating the subscription is exactly similar to the one for the payment protocol (PaymentRequest is used to provide the contract)
>> 
>> 2. Wallet can decide to poll the merchants for its active subscriptions.
>> 
>> Here the flow is exactly similar to the payment protocol but the wallet receives a callback to verify the payment matches the contract and should go through.
>> 
>> Please give us some feedback whenever you have the chance. In the meantime we will start implementing the merchant side and test the code.
>> 
>> Cheers!
>> 
>> 
>> 
>> On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:
>> 
>>> That looks OK at a very high level. Things you probably want to think about:
>>> How to trigger it off the existing payment protocol (no new top level messages or mime types or uri extensions please)
>>> Data structures to define the payment schedule
>>> Do you allow pre-submission of time locked transactions or not?
>>> I think as you prototype these things will become clearer.  You could try prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the PaymentSession class).
>>> 
>>> 
>>> 
>>> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <stephane@kill-bill•org> wrote:
>>> From what I have seen so far, there seems to be an agreement that this is a nice feature to add.   We are pretty new to that community and so we don't know exactly what the process is, and in particular how we reach consensus via email. I am certainly open to follow 'the way' if there is one, but one solution would be to follow Mike's suggestion on providing a (prototype) implementation first and then defining/refining the BIP. Odinn also suggested a possible retribution for our time through crowd-sourcing which I am interested to pursue if that makes sense.
>>> 
>>> 
>>> We have quite some experience on the subscription side of things and while we are growing our knowledge on the Bitcoin technology (and ecosystem at large) we would benefit from:
>>> * some feedbacks on the high level proposal
>>> * additional requirements we might have missed
>>> 
>>> So, below is a high level description of what we have in mind. If this sounds reasonable, we could start working on an implementation.
>>> 
>>> 
>>>  
>>> I. Abstract
>>> ---------------
>>> 
>>> This describes a protocol to enable recurring payments in bitcoins and can be seen as an extension of BIP-0070. The main goal here is to have the customer subscribe to a service of some kind (that is, agreeing on the terms of that subscription contract), and then have the wallet make recurring payments without any intervention from the customer as long as the payments match what the customer agreed on paying.
>>> 
>>> An example of such service would be an online streaming website, to which a user pays a fixed recurring monthly fee to access videos (a.k.a. resources). Note that there is also usage based billing: for example, the user may need to purchase additional access for premium videos (overage charges). This type of billing is more complicated and there are many variations to it used in the industry (pre-paid, …). For the sake of discussion, we’ll focus on fixed recurring payments only, but we will keep usage in mind to make sure the protocol will be able to support it as well.
>>> 
>>> 
>>> II. Motivation
>>> ------------------
>>> 
>>> Subscription based services have been growing in the past few years and so the intent it to make it possible for customers to pay in bitcoins. 
>>> 
>>> Bitcoin’s push model presents new advantages for the customer compared to traditional payment methods: the user has control over the subscription (for example, there is no need to call the merchant to explicitly cancel the credit card payments). It also opens the door to subscription management tools in wallets (e.g. Hive apps), which would give user an overview of what they are paying each month.
>>> 
>>> 
>>> III. Flow of Operations
>>> ----------------------------------------
>>> 
>>> 
>>> Creation of the subscription:
>>> - - - - - - - - - - - - - - - - - - - - - - 
>>> 
>>> 1. The customer clicks 'subscribe' -> A message is sent to the merchant.
>>> 2. The merchant sends back a message to the wallet with the details of the subscription such as the amount to be paid. In reality, there will be more information but for the purpose of the prototype implementation this is sufficient.
>>> 3. The wallet prompts the customer for authorization.
>>> 4. The customer authorizes (or denies) it.
>>> 5. The wallet sends the confirmation to the merchant.
>>> 6. The merchant confirms the subscription was created.
>>> 
>>> Ongoing payments:
>>> - - - - - - - - - - - - - - - -
>>> 
>>> From that time on and since Bitcoin is a 'push' model, the wallet is responsible to poll the merchant for due payments associated with that subscription. Note that the merchant could specify hints to the wallet on when to poll (specific dates) or not during the registration of the subscription.
>>> 
>>> Note that we can't simply have the wallet push X bitcoins every month: the user account on the merchant side may have gotten credits, invoice adjustments, etc. since the last invoice, so the amount to pay for a given billing period may be lower than the regular amount. It could even be zero if the user decides to make a one-time payment to the merchant directly using a different wallet. Hence, the wallet needs to get the latest invoice balance to make sure how much it should pay. This also opens the door for the support of overage charges.
>>> 
>>> 
>>> Quick note on the implementation on the merchant side: an entitlement system is a piece of logic on the merchant side which grants the user access to certain resources depending on the account status (unpaid invoices, etc.). This goes often hand in hand with a dunning system, which progressively restricts access as the user's account is more and more overdue. Since wallets can be offline for an extended period of time, payments may be missed and lead to an overdue state (e.g. extra fees, service degraded). It is the responsibility of the customer to ensure the wallet is up often enough for payments to happen.
>>> 
>>> 
>>> In that recurring phase where the wallet polls the merchant, the wallet is responsible to check that payments match the subscription contract; that is, the amount, frequency of payments, … match what the customer agreed on. If so, the payment is made without asking for explicit approval from customer, and the flow is similar to BIP-0070: The message is sent to the merchant, and in parallel, a transaction is sent to the btcnet. The merchant sends an ACK to the wallet and of course checks the states of the transactions on the btcnet to mark that payment as successful.
>>> 
>>> Subscription change (optional):
>>> - - - - - - - - - - - - - - - - - - - - - - - - 
>>> 
>>> Optionally we could implement a change in the ongoing subscription to address the upgrade/downgrade scenarios. Of course, we could also simply support a cancellation followed by a creation of a new subscription, but having that as a one atomic message is probably better. The steps are very similar to the initial registration.
>>> 
>>> 1. The customer clicks 'upgrade', 'downgrade', … -> A msg is sent to the merchant.
>>> 2. The merchant sends back a msg to the wallet with the detail of the NEW subscription. 
>>> 3. The wallet prompts the customer for authorization.
>>> 4. The customer authorizes (or denies) it.
>>> 5. The wallet sends the confirmation to the merchant.
>>> 6. The merchant confirms the change in the subscription.
>>> 
>>> Cancellation of the subscription:
>>> - - - - - - - - - - - - - - - - - - - - - - - - - 
>>> 
>>> The cancellation is initiated from the customer:
>>> 
>>> 1. The customer clicks 'cancel' -> The wallet is informed that it  should not accept any new payment associated to that subscription.
>>> 2. The wallet sends a message to the merchant to inform about the cancellation.
>>> 3. The merchant confirms the subscription was cancelled.
>>> 
>>> 
>>> 
>> 
> 
> 


[-- Attachment #2: Type: text/html, Size: 29763 bytes --]

 permalink raw reply	[|nested]
2014-02-11 18:01             ` Stephane Brossier

  2014-02-12  6:37                 ` Kevin Greene
  
From: Kevin Greene @ 2014-02-12  6:32 UTC (permalink / raw)
  To: Stephane Brossier;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 15432 bytes --]

Thanks for humoring my questions!

>I think reporting such errors to the wallet would make complete sense.
However i am not clear why we would a separate url for that?

Hmm, thinking about this more, adding a simple status_code in
PaymentRequest would be a much easier way to achieve this. However,
continuing to think about this even more, maybe the simple memo field along
with an empty set of outputs is enough already.

In bitcoinj, right now the code will throw a
PaymentRequestException.InvalidOutputs exception if the set of outputs is
empty with a message of "No Outputs". There isn't a good way to tell the
difference between a payment request that had no outputs and a payment
request that had some invalid output(s).

*Question to everyone:*
How does bitcoin-qt handle a PaymentRequest with no outputs?



On Tue, Feb 11, 2014 at 10:01 AM, Stephane Brossier
<stephane@kill-bill•org>wrote:

> Hi Kevin,
>
> On Feb 11, 2014, at 2:00 AM, Kevin Greene <kgreenek@gmail•com> wrote:
>
> Figured I would have a crack at reviewing this since Mike is out for a
> bit. It was great running into you guys at the bitcoin fair in SF! Small
> world :)
>
>
> Indeed! It was great meeting you! It's always nice to meet people in
> person...
>
> I like how simple this is. You just give it an url to fetch the next
> payment request and a date to fetch it.
>
> What should happen if the client tries to fetch the PaymentRequest early
> or late?
>
>
> If the client tries to fetch too early, then  the merchant will return a
> PaymentRequest with no output (there is nothing to pay yet). If it fetches
> too late, this is merchant specific. It could be that the service got
> discontinued -- extreme case -- or that there are now multiple
> PaymentRequest pending or that the merchant decided to aggregate those into
> one. In that scenario, it could lead to a case where the amount to pay goes
> beyond the contract and the wallet would refuse to make the recurring
> payment.
>
> Does it become valid after some date and stay valid for some length of
> time?
>
>
> The protocol we sketched does not include (yet) an expiration date. At
> this point the contract is fairly minimal, and we could envision adding
> more parameters such as expiration date. So at this point the behavior
> would be dictated by the merchant.
>
> Also, what should happen if the client tries to consume the same
> PaymentRequest twice (or multiple times) during the same period?
>
>
> The merchant initiates the PaymentRequest and is in charge to make sure
> they match the invoices that the client should pay. On the client side, the
> wallet is responsible to verify that the contract is respected, so if a
> merchant were to issue multiple times the same PaymentRequest, the wallet
> would detect it goes beyond the bonds defined in the contract and would
> refuse to make the additional Payments.
>
> I do not think daily/weekly/monthly is flexible enough. What do you think
> about having a concrete start time and end time when the next
> PaymentRequest will be valid?
>
>
> I agree that daily/weekly/monthly may not be flexible enough. However
> specifying a fixed date may be very tricky because in some cases a monthly
> subscription may start on a 31st of a month, and depending on the month,
> the due date will vary -- could be 30th, 28th, 29th, ... Also note that the
> frequency (daily/weekly/monthly) is not used as a polling interval, but is
> only used to verify the contract is respected.
>
> There are multiple viable options to specify that contract and ideally we
> could/should support multiple schemes; different merchants could use
> different schemes, and the client would decide wether or not he is ready to
> accept the terms that will later be enforced by the wallet. But of course
> all this flexibility goes against simplicity and so this is tradeoff...
>
>
> This also prevents the wallet from having to remember when it last sent a
> payment and getting skewed over time.
>
>
> Today, our current prototype is polling every day -- which is the lowest
> granularity we introduced -- and so there is no risk of getting skewed.
>
>
> When a wallet hits the polling_url to download the next PaymentRequest, it
> seems we need a way to communicate an error code to the wallet, for example
> if the server canceled the contract without the wallet knowing. Perhaps a
> separate polling_status_url, with a corresponding ACK message to indicate
> if the PaymentRequest is available. What do you think of that idea?
>
>
> I think reporting such errors to the wallet would make complete sense.
> However i am not clear why we would a separate url for that?
>
>  One high-level comment -- the wallet in this design doesn't have any way
> of knowing when the payments are supposed to end. I feel this is important
> to show to the user before they start their wallet polling infinitely.
>
>
> Subscriptions are non ending by definition, but at any time the client
> (through the wallet) or the merchant can decide to terminate the
> subscriptions -- we did not yet implement cancellation in that prototype
> but we are planning to add it later this week. Think of your Netflix
> subscriptions, this is never ending (evergreen) until you decide to
> terminate it or Netflix does it (abuse, bills not paid,...)
>
> Thanks for taking a look!
>
>
> On Sat, Feb 8, 2014 at 6:48 PM, Stephane Brossier <stephane@kill-bill•org>wrote:
>
>> Mike, Gavin,
>>
>>
>> We started to work on the merchant side to test the integration of our
>> prototype for the recurring payments. We modified the 'Payment Request
>> Generator' from Gavin to include a new check box 'set recurring'. We forked
>> the code and checked in our modification here:
>> https://github.com/killbill/paymentrequest/commit/e530f6ec528266aacfd076d7c3154ad39267c3f3
>>
>> We also found a few issues with the code diff that we sent yesterday for
>> bitcoinj and checked in the bug fixes  in our fork-- so the diff sent
>> yesterday is slightly outdated.
>>
>> So at this point we have a working prototype for bitcoinj and we are
>> waiting for your feedbacks. We also started to look at integrating the
>> protocol in Kill Bill to check that what is proposed supports indeed the
>> business cases of a full recurring billing platform.
>>
>> Hope to hear from you guys soon!
>>
>>
>> On Feb 7, 2014, at 6:57 PM, Stephane Brossier <stephane@kill-bill•org>
>> wrote:
>>
>> Mike and all,
>>
>> Pierre and I just committed a prototype implementation of the recurring
>> payment protocol using bitcoinj. You can find the diff on our fork:
>>
>> https://github.com/killbill/bitcoinj/commit/40c657c4191498f12539c60316116aa68af368a7
>>
>> We did not write the server (merchant side), but wanted to have some
>> feedback before going deeper (merchant implementation and tests). We did
>> our best to build it on top of the existing BIP-0070 protocol-- only a few
>> additions in the messages, but no new calls and no new uri scheme. We
>> created a new package 'recurring' where most of the new code lives.
>>
>> At a high level:
>>
>> 1. Creation of the subscription:
>>
>> The initial handshake for creating the subscription is exactly similar to
>> the one for the payment protocol (PaymentRequest is used to provide the
>> contract)
>>
>> 2. Wallet can decide to poll the merchants for its active subscriptions.
>>
>> Here the flow is exactly similar to the payment protocol but the wallet
>> receives a callback to verify the payment matches the contract and should
>> go through.
>>
>> Please give us some feedback whenever you have the chance. In the
>> meantime we will start implementing the merchant side and test the code.
>>
>> Cheers!
>>
>>
>>
>> On Jan 31, 2014, at 10:13 AM, Mike Hearn <mike@plan99•net> wrote:
>>
>> That looks OK at a very high level. Things you probably want to think
>> about:
>>
>>    - How to trigger it off the existing payment protocol (no new top
>>    level messages or mime types or uri extensions please)
>>    - Data structures to define the payment schedule
>>    - Do you allow pre-submission of time locked transactions or not?
>>
>> I think as you prototype these things will become clearer.  You could try
>> prototyping either in Bitcoin Core (C++) or bitcoinj (java, look at the
>> PaymentSession class).
>>
>>
>>
>> On Wed, Jan 29, 2014 at 3:47 AM, Stephane Brossier <
>> stephane@kill-bill•org> wrote:
>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> *From what I have seen so far, there seems to be an agreement that this
>>> is a nice feature to add. We are pretty new to that community and so we
>>> don't know exactly what the process is, and in particular how we reach
>>> consensus via email. I am certainly open to follow 'the way' if there is
>>> one, but one solution would be to follow Mike's suggestion on providing a
>>> (prototype) implementation first and then defining/refining the BIP. Odinn
>>> also suggested a possible retribution for our time through crowd-sourcing
>>> which I am interested to pursue if that makes sense. We have quite some
>>> experience on the subscription side of things and while we are growing our
>>> knowledge on the Bitcoin technology (and ecosystem at large) we would
>>> benefit from: * some feedbacks on the high level proposal * additional
>>> requirements we might have missed So, below is a high level description of
>>> what we have in mind. If this sounds reasonable, we could start working on
>>> an implementation. I. Abstract --------------- This describes a protocol to
>>> enable recurring payments in bitcoins and can be seen as an extension of
>>> BIP-0070. The main goal here is to have the customer subscribe to a service
>>> of some kind (that is, agreeing on the terms of that subscription
>>> contract), and then have the wallet make recurring payments without any
>>> intervention from the customer as long as the payments match what the
>>> customer agreed on paying. An example of such service would be an online
>>> streaming website, to which a user pays a fixed recurring monthly fee to
>>> access videos (a.k.a. resources). Note that there is also usage based
>>> billing: for example, the user may need to purchase additional access for
>>> premium videos (overage charges). This type of billing is more complicated
>>> and there are many variations to it used in the industry (pre-paid, ...). For
>>> the sake of discussion, we'll focus on fixed recurring payments only, but
>>> we will keep usage in mind to make sure the protocol will be able to
>>> support it as well. II. Motivation ------------------ Subscription based
>>> services have been growing in the past few years and so the intent it to
>>> make it possible for customers to pay in bitcoins. Bitcoin's push model
>>> presents new advantages for the customer compared to traditional payment
>>> methods: the user has control over the subscription (for example, there is
>>> no need to call the merchant to explicitly cancel the credit card
>>> payments). It also opens the door to subscription management tools in
>>> wallets (e.g. Hive apps), which would give user an overview of what they
>>> are paying each month. III. Flow of
>>> Operations----------------------------------------*
>>>
>>>
>>>
>>>
>>> * Creation of the subscription: - - - - - - - - - - - - - - - - - - - -
>>> - - 1. The customer clicks 'subscribe' -> A message is sent to the
>>> merchant. 2. The merchant sends back a message to the wallet with the
>>> details of the subscription such as the amount to be paid. In reality,
>>> there will be more information but for the purpose of the prototype
>>> implementation this is sufficient. 3. The wallet prompts the customer for
>>> authorization. 4. The customer authorizes (or denies) it. 5. The wallet
>>> sends the confirmation to the merchant. 6. The merchant confirms the
>>> subscription was created. Ongoing payments: *
>>>
>>> *- - - - - - - - - - - - - - - - *
>>>
>>>
>>>
>>>
>>>
>>>
>>> * From that time on and since Bitcoin is a 'push' model, the wallet is
>>> responsible to poll the merchant for due payments associated with that
>>> subscription. Note that the merchant could specify hints to the wallet on
>>> when to poll (specific dates) or not during the registration of the
>>> subscription. Note that we can't simply have the wallet push X bitcoins
>>> every month: the user account on the merchant side may have gotten credits,
>>> invoice adjustments, etc. since the last invoice, so the amount to pay for
>>> a given billing period may be lower than the regular amount. It could even
>>> be zero if the user decides to make a one-time payment to the merchant
>>> directly using a different wallet. Hence, the wallet needs to get the
>>> latest invoice balance to make sure how much it should pay. This also opens
>>> the door for the support of overage charges. Quick note on the
>>> implementation on the merchant side: an entitlement system is a piece of
>>> logic on the merchant side which grants the user access to certain
>>> resources depending on the account status (unpaid invoices, etc.). This
>>> goes often hand in hand with a dunning system, which progressively
>>> restricts access as the user's account is more and more overdue. Since
>>> wallets can be offline for an extended period of time, payments may be
>>> missed and lead to an overdue state (e.g. extra fees, service degraded). It
>>> is the responsibility of the customer to ensure the wallet is up often
>>> enough for payments to happen. In that recurring phase where the wallet
>>> polls the merchant, the wallet is responsible to check that payments match
>>> the subscription contract; that is, the amount, frequency of payments, ...
>>> match what the customer agreed on. If so, the payment is made without
>>> asking for explicit approval from customer, and the flow is similar to
>>> BIP-0070: The message is sent to the merchant, and in parallel, a
>>> transaction is sent to the btcnet. The merchant sends an ACK to the wallet
>>> and of course checks the states of the transactions on the btcnet to mark
>>> that payment as successful. Subscription change (optional): *
>>>
>>> *- - - - - - - - - - - - - - - - - - - - - - - - *
>>>
>>>
>>> * Optionally we could implement a change in the ongoing subscription to
>>> address the upgrade/downgrade scenarios. Of course, we could also simply
>>> support a cancellation followed by a creation of a new subscription, but
>>> having that as a one atomic message is probably better. The steps are very
>>> similar to the initial registration. 1. The customer clicks 'upgrade',
>>> 'downgrade', ... -> A msg is sent to the merchant. 2. The merchant sends back
>>> a msg to the wallet with the detail of the NEW subscription. 3. The wallet
>>> prompts the customer for authorization. 4. The customer authorizes (or
>>> denies) it. 5. The wallet sends the confirmation to the merchant. 6. The
>>> merchant confirms the change in the subscription. Cancellation of the
>>> subscription: *
>>>
>>> *- - - - - - - - - - - - - - - - - - - - - - - - - *
>>>
>>>
>>>
>>> * The cancellation is initiated from the customer: 1. The customer
>>> clicks 'cancel' -> The wallet is informed that it  should not accept any
>>> new payment associated to that subscription. 2. The wallet sends a message
>>> to the merchant to inform about the cancellation. 3. The merchant confirms
>>> the subscription was cancelled. *
>>>
>>
>>
>>
>>
>
>

[-- Attachment #2: Type: text/html, Size: 32344 bytes --]

 permalink raw reply	[|nested]
2014-02-12  6:32               ` Kevin Greene

  2014-02-14 20:28                   ` Stephane Brossier
  
From: Kevin Greene @ 2014-02-12  6:37 UTC (permalink / raw)
  To: Stephane Brossier;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 914 bytes --]

Sending this again and truncating since apparently the message body was too
long.

Thanks for humoring my questions!

>I think reporting such errors to the wallet would make complete sense.
However i am not clear why we would a separate url for that?

Hmm, thinking about this more, adding a simple status_code in
PaymentRequest would be a much easier way to achieve this. However,
continuing to think about this even more, maybe the simple memo field along
with an empty set of outputs is enough already.

In bitcoinj, right now the code will throw a
PaymentRequestException.InvalidOutputs exception if the set of outputs is
empty with a message of "No Outputs". Because of that, there isn't a good
way to tell the difference between a payment request that had no outputs
and a payment request that had some invalid output(s).

*Question to everyone:*
How does bitcoin-qt handle a PaymentRequest with no outputs?

[-- Attachment #2: Type: text/html, Size: 2124 bytes --]

 permalink raw reply	[|nested]
2014-02-12  6:37                 ` Kevin Greene

  2014-02-24 18:04                     ` Stephane Brossier
  
From: Stephane Brossier @ 2014-02-14 20:28 UTC (permalink / raw)
  To: Kevin Greene;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 3303 bytes --]

Kevin,

We did a second iteration on the prototype to implement subscription cancellation and upgrade/downgrade. We checked in both the bitcoinj and php server to be able to test it.
We also worked on our side of the merchant implementation (Kill Bill) to feel confident that the protocol will support advanced business cases. At this point it is looking promising, but more work is needed to conclude.

We wanted to follow up on a few pervious points you raised:

> However, continuing to think about this even more, maybe the simple memo field along with an empty set of outputs is enough already.

From our merchant side (Kill Bill), we do indeed use this field to report successes or errors. Maybe it would be useful to extend PaymentACK with a boolean success field (so the wallet doesn't commit the transaction in case of failures)?

> One high-level comment -- the wallet in this design doesn't have any way of knowing when the payments are supposed to end. I feel this is important to show to the user before they start their wallet polling infinitely.

We extended our RecurringPaymentDetails message to support this use case, as it solves the problem of subscription changes and cancellations for free.

We introduced the concept of a subscription, referred to by a unique id (the tuple merchant_id,subscription_id should be globally unique), which has multiple contracts (RecurringPaymentContract). Besides payment bounds, each contract has a validity period: generally, a subscription will have a unique active contract at a given time and potentially one or more pending ones.

For example, say you are on the gold plan (1 BTC/mo.) and want to downgrade to a bronze plan (0.5 BTC/mo.) at your next billing date. Wshen you click "Downgrade" on the merchant site, you will update your wallet with two contracts: the current valid one until your next billing date (for up to 1 BTC), and a pending one, starting at your next billing date (for up to 0.5 BTC/mo. and without an ending date).
Upon cancellation of the bronze plan, the end date of the contract will be updated and polling will stop eventually.

All of this contract metadata is returned to the wallet so the user can make an informed decision.


Thanks for your feedbacks!

S.


On Feb 11, 2014, at 10:37 PM, Kevin Greene <kgreenek@gmail•com> wrote:

> Sending this again and truncating since apparently the message body was too long.
> 
> Thanks for humoring my questions!
> 
> >I think reporting such errors to the wallet would make complete sense. However i am not clear why we would a separate url for that?
> 
> Hmm, thinking about this more, adding a simple status_code in PaymentRequest would be a much easier way to achieve this. However, continuing to think about this even more, maybe the simple memo field along with an empty set of outputs is enough already.
> 
> In bitcoinj, right now the code will throw a PaymentRequestException.InvalidOutputs exception if the set of outputs is empty with a message of "No Outputs". Because of that, there isn't a good way to tell the difference between a payment request that had no outputs and a payment request that had some invalid output(s).
> 
> Question to everyone:
> How does bitcoin-qt handle a PaymentRequest with no outputs?


[-- Attachment #2: Type: text/html, Size: 5138 bytes --]

 permalink raw reply	[|nested]
2014-02-14 20:28                   ` Stephane Brossier

  2014-02-25 16:29                       ` Mike Hearn
  
From: Stephane Brossier @ 2014-02-24 18:04 UTC (permalink / raw)
  To: Mike Hearn;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 4547 bytes --]

Mike,


Just want to follow up with you and the community in general regarding the BIP0070 extension for recurring billing. At this point we have a working prototype that we checked-in in our fork of bitcoinj (https://github.com/killbill/bitcoinj). We tested it by extending the php 'payment server' from Gavin which we also check-in in a fork (https://github.com/killbill/paymentrequest). I think it does not make much sense from our side to invest more efforts until we hear some feedbacks.

Once we agree/integrate any feedbacks you guys may have-- a proposal for next steps would be:
* Turn that into a actual BIP so as to detail how that works, 
* Write some more serious unit tests
* Merge back code into bitconj trunk

Down the line write the C++ code, but of course that would assume BIP0070 is also implemented in C++ as we rely on it.

I understand you guys may have more important matters to solve these days with the recent malleability issue, but i want to make it clear that we are waiting for feedbacks to make additional progress.

Thanks!

S.




On Feb 14, 2014, at 12:28 PM, Stephane Brossier <stephane@kill-bill•org> wrote:

> Kevin,
> 
> We did a second iteration on the prototype to implement subscription cancellation and upgrade/downgrade. We checked in both the bitcoinj and php server to be able to test it.
> We also worked on our side of the merchant implementation (Kill Bill) to feel confident that the protocol will support advanced business cases. At this point it is looking promising, but more work is needed to conclude.
> 
> We wanted to follow up on a few pervious points you raised:
> 
> > However, continuing to think about this even more, maybe the simple memo field along with an empty set of outputs is enough already.
> 
> From our merchant side (Kill Bill), we do indeed use this field to report successes or errors. Maybe it would be useful to extend PaymentACK with a boolean success field (so the wallet doesn't commit the transaction in case of failures)?
> 
> > One high-level comment -- the wallet in this design doesn't have any way of knowing when the payments are supposed to end. I feel this is important to show to the user before they start their wallet polling infinitely.
> 
> We extended our RecurringPaymentDetails message to support this use case, as it solves the problem of subscription changes and cancellations for free.
> 
> We introduced the concept of a subscription, referred to by a unique id (the tuple merchant_id,subscription_id should be globally unique), which has multiple contracts (RecurringPaymentContract). Besides payment bounds, each contract has a validity period: generally, a subscription will have a unique active contract at a given time and potentially one or more pending ones.
> 
> For example, say you are on the gold plan (1 BTC/mo.) and want to downgrade to a bronze plan (0.5 BTC/mo.) at your next billing date. Wshen you click "Downgrade" on the merchant site, you will update your wallet with two contracts: the current valid one until your next billing date (for up to 1 BTC), and a pending one, starting at your next billing date (for up to 0.5 BTC/mo. and without an ending date).
> Upon cancellation of the bronze plan, the end date of the contract will be updated and polling will stop eventually.
> 
> All of this contract metadata is returned to the wallet so the user can make an informed decision.
> 
> 
> Thanks for your feedbacks!
> 
> S.
> 
> 
> On Feb 11, 2014, at 10:37 PM, Kevin Greene <kgreenek@gmail•com> wrote:
> 
>> Sending this again and truncating since apparently the message body was too long.
>> 
>> Thanks for humoring my questions!
>> 
>> >I think reporting such errors to the wallet would make complete sense. However i am not clear why we would a separate url for that?
>> 
>> Hmm, thinking about this more, adding a simple status_code in PaymentRequest would be a much easier way to achieve this. However, continuing to think about this even more, maybe the simple memo field along with an empty set of outputs is enough already.
>> 
>> In bitcoinj, right now the code will throw a PaymentRequestException.InvalidOutputs exception if the set of outputs is empty with a message of "No Outputs". Because of that, there isn't a good way to tell the difference between a payment request that had no outputs and a payment request that had some invalid output(s).
>> 
>> Question to everyone:
>> How does bitcoin-qt handle a PaymentRequest with no outputs?
> 


[-- Attachment #2: Type: text/html, Size: 6983 bytes --]

 permalink raw reply	[|nested]
2014-02-24 18:04                     ` Stephane Brossier

  2014-02-25 18:40                         ` Drak
  2014-02-26  3:53                         ` Stephane Brossier
  
From: Mike Hearn @ 2014-02-25 16:29 UTC (permalink / raw)
  To: Stephane Brossier;  Pierre-Alexandre Meyer, Bitcoin Dev

[-- Attachment #1: Type: text/plain, Size: 5126 bytes --]

Hey there,

So the essence of this protocol is as follows:

enum PaymentFrequencyType {
        WEEKLY = 1;
        MONTHLY = 2;
        QUARTERLY = 3;
        ANNUAL = 4;
}
message RecurringPaymentDetails {
        // Namespace for the merchant such as org.foo.bar
        required string merchant_id = 1;
        // Id for the recurring subscription
        required bytes subscription_id = 2;
        // Contracts associated with a given subscription
        repeated RecurringPaymentContract contracts = 3;
}
message RecurringPaymentContract {
        // Unique id for a given contract
        required bytes contract_id = 1;
        // URL to poll to get the next PaymentRequest
        required string polling_url = 2;
        // Timestamp; when this contract starts
        required uint64 starts = 3;
        // Timestamp; when this contract should be considered invalid
        optional uint64 ends = 4;
        // Expected payment frequency
        optional PaymentFrequencyType payment_frequency_type = 5;
        // Max payment amount within that frequency (e.g. no more than
5 BTC per month)
        optional uint64 max_payment_per_period  = 6;
        // Max payment amount (e.g. no more than 3 BTC per payment)
        optional uint64 max_payment_amount = 7;
}

I have the following comments:

   1. There's no need to serialize RecurringPaymentDetails as bytes here.
   It's done that way outside of PaymentDetails in order to support digital
   signatures over protobufs that may have extensions the wallet app isn't
   aware of, but it's a pain and inside PaymentDetails (and therefore for most
   extensions) it shouldn't be necessary. So you can just use "optional
   RecurringPamentDetails recurring_payments = 8;"

   2. There's only 4 possibilities here for recurrences. That seems rather
   restrictive. Is the cost of being more expressive really so high? Why not
   allow more flexible specification of periods?

   3. If there's no payment_frequency_type field then what happens? A quirk
   of protobufs to be aware of is that making an enum field "required" can
   hurt backwards compatibility. Because it will be expressed using a
   languages underlying enum type, if there's a new enum member added later
   old software that attempts to deserialize this will throw exceptions
   because the new "unknown" member would be unrepresentable in the old model.
   Making the field optional avoids this problem (it will be treated as
   missing instead) but means software needs to be written to know what to do
   when it can't read the enum value / sees enum values from the future.

   4. I assume the amounts are specified in terms of satoshi, and
   timestamps are UNIX time, but better to make that explicit.

   5. Seems there's an implicit value constraint that max_payment_amount <=
   max_payment_per_period. What happens if that constraint is violated? Best
   to document that.

   6. What's the "merchant ID" namespace thing about? What's it for? What
   happens if I set my competitors merchant ID there?

   7. What's the "subscription ID"? Is this stuff not duplicative/redundant
   with the existing merchant_data field?

   8. In what situations would you have >1 contract per payment request?
   I'm not sure I understand why it's repeated. Presumably if there are zero
   contracts included the data should be ignored, or an error thrown and the
   entire payment request rejected? Which should it be?

   9. It's unclear to me given such a contract when the payment should
   actually occur. For instance if it's "monthly" then what day in the month
   would the payment occur?

   10. You'll notice I moved the comments to be above the field
   definitions. I know the current proto isn't done that way, but let's change
   it - long comments are good and putting them above the field definitions
   encourages people to write enough detail without being put off by line
   length constraints


I think the next step would be to talk to BitPay/get Jeff+Stephen involved
because I know they have customers that really want recurring payments, and
those guys will have a clearer idea of customer requirements than we do. I
feel uncomfortable with designing or reviewing in a vacuum without some
actual people who would use it chiming in, as I don't really know much
about the underlying business processes.

I have some other comments about the bitcoinj implementation specifically -
for instance, we don't have a "wallet directory" concept: everything goes
into the wallet file. So we'll need to think about how to structure the
code to allow that. Also, just using a background polling thread is likely
not flexible enough, as on some platforms you can't stay running all the
time (e.g. Android) without upsetting people, but the underlying OS can
wake you up at the right times, so wallet apps should have an ability to
control wakeup tasks. But we can discuss that over on the bitcoinj list
specifically. Let's keep this thread for the general protocol design.

BIP 70 is indeed implemented in Bitcoin Core on the C++ side, so that isn't
a concern. It could be done there too.

[-- Attachment #2: Type: text/html, Size: 12325 bytes --]

 permalink raw reply	[|nested]
2014-02-25 16:29                       ` Mike Hearn

  2014-02-25 19:03                           ` Jeremy Spilman
  2014-02-25 19:06                           ` Christophe Biocca
  2014-02-26  3:53                         ` Stephane Brossier
  
From: Drak @ 2014-02-25 18:40 UTC (permalink / raw)
  To: Mike Hearn;  Bitcoin Dev, Stephane Brossier, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 6759 bytes --]

Forgive me if I missed it, but the spec doesnt look like it can handle only
handle periods of per week, per month, per quarter rather than 'n period'.
I take Paypal as a reference example for subscription payments where you
can set recurring to every: n days, n weeks, n months, n years. That way a
quarterly payment is every 3 months. This fine granularity is necessary
because sometime a payment scheme can be per 4 weekly rather than per
monthly.

So in summary the spec needs daily as an option, and to specify the
recurring cycle as every n*period (one of daily, weekly, monthly, yearly):
and you can drop quarterly since it's just expressed as per 3*monthly.

Drak


On 25 February 2014 16:29, Mike Hearn <mike@plan99•net> wrote:

> Hey there,
>
> So the essence of this protocol is as follows:
>
> enum PaymentFrequencyType {
>
>         WEEKLY = 1;
>
>         MONTHLY = 2;
>
>         QUARTERLY = 3;
>
>         ANNUAL = 4;
> }
> message RecurringPaymentDetails {
>         // Namespace for the merchant such as org.foo.bar
>
>         required string merchant_id = 1;
>
>         // Id for the recurring subscription
>         required bytes subscription_id = 2;
>
>         // Contracts associated with a given subscription
>
>         repeated RecurringPaymentContract contracts = 3;
>
> }
> message RecurringPaymentContract {
>
>         // Unique id for a given contract
>
>         required bytes contract_id = 1;
>
>         // URL to poll to get the next PaymentRequest
>
>         required string polling_url = 2;
>
>         // Timestamp; when this contract starts
>         required uint64 starts = 3;
>
>         // Timestamp; when this contract should be considered invalid
>
>         optional uint64 ends = 4;
>
>         // Expected payment frequency
>         optional PaymentFrequencyType payment_frequency_type = 5;
>
>         // Max payment amount within that frequency (e.g. no more than 5 BTC per month)
>
>         optional uint64 max_payment_per_period  = 6;
>
>         // Max payment amount (e.g. no more than 3 BTC per payment)
>
>         optional uint64 max_payment_amount = 7;
>
> }
>
> I have the following comments:
>
>    1. There's no need to serialize RecurringPaymentDetails as bytes here.
>    It's done that way outside of PaymentDetails in order to support digital
>    signatures over protobufs that may have extensions the wallet app isn't
>    aware of, but it's a pain and inside PaymentDetails (and therefore for most
>    extensions) it shouldn't be necessary. So you can just use "optional
>    RecurringPamentDetails recurring_payments = 8;"
>
>    2. There's only 4 possibilities here for recurrences. That seems
>    rather restrictive. Is the cost of being more expressive really so high?
>    Why not allow more flexible specification of periods?
>
>    3. If there's no payment_frequency_type field then what happens? A
>    quirk of protobufs to be aware of is that making an enum field "required"
>    can hurt backwards compatibility. Because it will be expressed using a
>    languages underlying enum type, if there's a new enum member added later
>    old software that attempts to deserialize this will throw exceptions
>    because the new "unknown" member would be unrepresentable in the old model.
>    Making the field optional avoids this problem (it will be treated as
>    missing instead) but means software needs to be written to know what to do
>    when it can't read the enum value / sees enum values from the future.
>
>    4. I assume the amounts are specified in terms of satoshi, and
>    timestamps are UNIX time, but better to make that explicit.
>
>    5. Seems there's an implicit value constraint that max_payment_amount
>    <= max_payment_per_period. What happens if that constraint is violated?
>    Best to document that.
>
>    6. What's the "merchant ID" namespace thing about? What's it for? What
>    happens if I set my competitors merchant ID there?
>
>    7. What's the "subscription ID"? Is this stuff not
>    duplicative/redundant with the existing merchant_data field?
>
>    8. In what situations would you have >1 contract per payment request?
>    I'm not sure I understand why it's repeated. Presumably if there are zero
>    contracts included the data should be ignored, or an error thrown and the
>    entire payment request rejected? Which should it be?
>
>    9. It's unclear to me given such a contract when the payment should
>    actually occur. For instance if it's "monthly" then what day in the month
>    would the payment occur?
>
>    10. You'll notice I moved the comments to be above the field
>    definitions. I know the current proto isn't done that way, but let's change
>    it - long comments are good and putting them above the field definitions
>    encourages people to write enough detail without being put off by line
>    length constraints
>
>
> I think the next step would be to talk to BitPay/get Jeff+Stephen involved
> because I know they have customers that really want recurring payments, and
> those guys will have a clearer idea of customer requirements than we do. I
> feel uncomfortable with designing or reviewing in a vacuum without some
> actual people who would use it chiming in, as I don't really know much
> about the underlying business processes.
>
> I have some other comments about the bitcoinj implementation specifically
> - for instance, we don't have a "wallet directory" concept: everything goes
> into the wallet file. So we'll need to think about how to structure the
> code to allow that. Also, just using a background polling thread is likely
> not flexible enough, as on some platforms you can't stay running all the
> time (e.g. Android) without upsetting people, but the underlying OS can
> wake you up at the right times, so wallet apps should have an ability to
> control wakeup tasks. But we can discuss that over on the bitcoinj list
> specifically. Let's keep this thread for the general protocol design.
>
> BIP 70 is indeed implemented in Bitcoin Core on the C++ side, so that
> isn't a concern. It could be done there too.
>
>
>
> ------------------------------------------------------------------------------
> Flow-based real-time traffic analytics software. Cisco certified tool.
> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
> Customize your own dashboards, set traffic alerts and generate reports.
> Network behavioral analysis & security monitoring. All-in-one tool.
>
> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
> _______________________________________________
> Bitcoin-development mailing list
> Bitcoin-development@lists•sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>
>

[-- Attachment #2: Type: text/html, Size: 12946 bytes --]

 permalink raw reply	[|nested]
2014-02-25 18:40                         ` Drak

  2014-02-25 19:06                           ` Christophe Biocca
  
From: Jeremy Spilman @ 2014-02-25 19:03 UTC (permalink / raw)
  To: Mike Hearn, Drak;  Bitcoin Dev, Stephane Brossier, Pierre-Alexandre Meyer


>
> So in summary the spec needs daily as an option, and to specify the  
> recurring cycle as every n*period >(one of daily, weekly, monthly,  
> yearly): and you can drop quarterly since it's just expressed as per  
> >3*monthly.

If you're going to go the direction of a {unitType, unitsPerInterval}  
tuple, then I think the only two units you could ever want are minutes and  
months. All other standard units of time can be expressed in terms of  
those two, right?

Also consider changing "optional uint64 ends = 4;" to be a interval count  
instead of a UTC timestamp, to avoid any ambiguity over how the 'while'  
loop should be implemented.








 permalink raw reply	[|nested]
2014-02-25 18:40                         ` Drak
  2014-02-25 19:03                           ` Jeremy Spilman

  
From: Christophe Biocca @ 2014-02-25 19:06 UTC (permalink / raw)
  To: Bitcoin Dev

Given the enormous number of variations on time periods for a
recurring payment, might it be better to simple allow a list of
timestamps? It costs almost nothing, bandwidth wise, and shifts the
thinking to the merchant platform. That doesn't give you an infinite
time frame, but you just get a new list of timestamps every time you
pay the service.

Continuing that thought, is a "next_payment_time" field with each
incremental transaction enough to cover everything?

On Tue, Feb 25, 2014 at 1:40 PM, Drak <drak@zikula•org> wrote:
> Forgive me if I missed it, but the spec doesnt look like it can handle only
> handle periods of per week, per month, per quarter rather than 'n period'. I
> take Paypal as a reference example for subscription payments where you can
> set recurring to every: n days, n weeks, n months, n years. That way a
> quarterly payment is every 3 months. This fine granularity is necessary
> because sometime a payment scheme can be per 4 weekly rather than per
> monthly.
>
> So in summary the spec needs daily as an option, and to specify the
> recurring cycle as every n*period (one of daily, weekly, monthly, yearly):
> and you can drop quarterly since it's just expressed as per 3*monthly.
>
> Drak
>
>
> On 25 February 2014 16:29, Mike Hearn <mike@plan99•net> wrote:
>>
>> Hey there,
>>
>> So the essence of this protocol is as follows:
>>
>>
>> enum PaymentFrequencyType {
>>         WEEKLY = 1;
>>         MONTHLY = 2;
>>         QUARTERLY = 3;
>>         ANNUAL = 4;
>> }
>> message RecurringPaymentDetails {
>>         // Namespace for the merchant such as org.foo.bar
>>         required string merchant_id = 1;
>>
>>
>>         // Id for the recurring subscription
>>         required bytes subscription_id = 2;
>>
>>
>>         // Contracts associated with a given subscription
>>         repeated RecurringPaymentContract contracts = 3;
>>
>>
>> }
>> message RecurringPaymentContract {
>>
>>
>>         // Unique id for a given contract
>>         required bytes contract_id = 1;
>>
>>
>>         // URL to poll to get the next PaymentRequest
>>         required string polling_url = 2;
>>
>>
>>         // Timestamp; when this contract starts
>>         required uint64 starts = 3;
>>
>>
>>         // Timestamp; when this contract should be considered invalid
>>         optional uint64 ends = 4;
>>
>>
>>         // Expected payment frequency
>>         optional PaymentFrequencyType payment_frequency_type = 5;
>>
>>
>>         // Max payment amount within that frequency (e.g. no more than 5
>> BTC per month)
>>         optional uint64 max_payment_per_period  = 6;
>>
>>
>>         // Max payment amount (e.g. no more than 3 BTC per payment)
>>         optional uint64 max_payment_amount = 7;
>>
>>
>> }
>>
>> I have the following comments:
>>
>> There's no need to serialize RecurringPaymentDetails as bytes here. It's
>> done that way outside of PaymentDetails in order to support digital
>> signatures over protobufs that may have extensions the wallet app isn't
>> aware of, but it's a pain and inside PaymentDetails (and therefore for most
>> extensions) it shouldn't be necessary. So you can just use "optional
>> RecurringPamentDetails recurring_payments = 8;"
>>
>> There's only 4 possibilities here for recurrences. That seems rather
>> restrictive. Is the cost of being more expressive really so high? Why not
>> allow more flexible specification of periods?
>>
>> If there's no payment_frequency_type field then what happens? A quirk of
>> protobufs to be aware of is that making an enum field "required" can hurt
>> backwards compatibility. Because it will be expressed using a languages
>> underlying enum type, if there's a new enum member added later old software
>> that attempts to deserialize this will throw exceptions because the new
>> "unknown" member would be unrepresentable in the old model. Making the field
>> optional avoids this problem (it will be treated as missing instead) but
>> means software needs to be written to know what to do when it can't read the
>> enum value / sees enum values from the future.
>>
>> I assume the amounts are specified in terms of satoshi, and timestamps are
>> UNIX time, but better to make that explicit.
>>
>> Seems there's an implicit value constraint that max_payment_amount <=
>> max_payment_per_period. What happens if that constraint is violated? Best to
>> document that.
>>
>> What's the "merchant ID" namespace thing about? What's it for? What
>> happens if I set my competitors merchant ID there?
>>
>> What's the "subscription ID"? Is this stuff not duplicative/redundant with
>> the existing merchant_data field?
>>
>> In what situations would you have >1 contract per payment request? I'm not
>> sure I understand why it's repeated. Presumably if there are zero contracts
>> included the data should be ignored, or an error thrown and the entire
>> payment request rejected? Which should it be?
>>
>> It's unclear to me given such a contract when the payment should actually
>> occur. For instance if it's "monthly" then what day in the month would the
>> payment occur?
>>
>> You'll notice I moved the comments to be above the field definitions. I
>> know the current proto isn't done that way, but let's change it - long
>> comments are good and putting them above the field definitions encourages
>> people to write enough detail without being put off by line length
>> constraints
>>
>>
>> I think the next step would be to talk to BitPay/get Jeff+Stephen involved
>> because I know they have customers that really want recurring payments, and
>> those guys will have a clearer idea of customer requirements than we do. I
>> feel uncomfortable with designing or reviewing in a vacuum without some
>> actual people who would use it chiming in, as I don't really know much about
>> the underlying business processes.
>>
>> I have some other comments about the bitcoinj implementation specifically
>> - for instance, we don't have a "wallet directory" concept: everything goes
>> into the wallet file. So we'll need to think about how to structure the code
>> to allow that. Also, just using a background polling thread is likely not
>> flexible enough, as on some platforms you can't stay running all the time
>> (e.g. Android) without upsetting people, but the underlying OS can wake you
>> up at the right times, so wallet apps should have an ability to control
>> wakeup tasks. But we can discuss that over on the bitcoinj list
>> specifically. Let's keep this thread for the general protocol design.
>>
>> BIP 70 is indeed implemented in Bitcoin Core on the C++ side, so that
>> isn't a concern. It could be done there too.
>>
>>
>>
>> ------------------------------------------------------------------------------
>> Flow-based real-time traffic analytics software. Cisco certified tool.
>> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
>> Customize your own dashboards, set traffic alerts and generate reports.
>> Network behavioral analysis & security monitoring. All-in-one tool.
>>
>> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
>>
>> _______________________________________________
>> Bitcoin-development mailing list
>> Bitcoin-development@lists•sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>>
>
>
> ------------------------------------------------------------------------------
> Flow-based real-time traffic analytics software. Cisco certified tool.
> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
> Customize your own dashboards, set traffic alerts and generate reports.
> Network behavioral analysis & security monitoring. All-in-one tool.
> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
> _______________________________________________
> Bitcoin-development mailing list
> Bitcoin-development@lists•sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/bitcoin-development
>



 permalink raw reply	[|nested]
2014-02-25 16:29                       ` Mike Hearn
  2014-02-25 18:40                         ` Drak

  2014-02-26 10:30                           ` Mike Hearn
  
From: Stephane Brossier @ 2014-02-26  3:53 UTC (permalink / raw)
  To: Mike Hearn;  Bitcoin Dev, Pierre-Alexandre Meyer

[-- Attachment #1: Type: text/plain, Size: 8720 bytes --]

Hi Mike, Jeremy, Drak,

Before going through your questions, I would like to bring some clarity on a few key elements in that protocol. There are really two aspects to it:
The contract negotiation; when the user first subscribes, it is prompted by a contract that will define the payment bounds associated with that subscription. 
Once accepted, the wallet is in charge and the user does not have to interact anymore -- this is the point of the recurring payment protocol. The wallet will poll the merchant and issue payments as they are requested by the merchant as long as they stay within the bounds of what was specified by the contract (and accepted by the customer).

I think it would help to explain how we ended up with the type of contract we introduced in that protocol. In an ideal world and in a NON recurring scheme, the contract should simply be the exact amount to be paid. In our case the exact amount may not be completely known in advance -- for e.g taxes, shipping, pro-rations, … and so we decided to introduce first a max amount per payment, and also a max amount per period. It is up to the merchant to decide whether to specify none, any or both bounds (max amount per payment and max amount per period). By specifying both, the contract is tighter and the client would feel safer to accept it. In the extreme case, by specifying none, the client would be presented with a contract to pay whatever is requested -- probably not a good option in the Bitcoin world unless there is a high sense of trust with the merchant.   

From reading your comments, it appears we have not been clear on how that frequency (PaymentFrequencyType) is being used. Its sole purpose is to define the max amount per period in the contract. The frequency of the payment is implicitly dictated by the merchant but not specified in the protocol by design: the wallet has to poll with a fine granularity (ideally each day when it is up) to understand if there is something pending. In the same way, a specified amount was not enough in the contract, we feel it would be restrictive to specify in advance when payments are due. There are a lot of complex scenarios in the billing space, and having the wallet poll the merchant to inquire for pending payments is the most flexible option and the contract is there to ensure the client will not be abused. To give a concrete example, imagine a data plan where you pay a base recurring price of $70 per month, but you are charged $10 per GB of data used beyond your included limit. If you exceed your limit on the 15th and the 23rd of a given month, two extra payment attempts will be requested by the merchant, that you couldn’t predict (this scenario is often referred to as usage billing with Prepay Credits and Top-up, where the customer pays in advance for blocks of N units, and once they are consumed another N are purchased).


See answers in your questions inlined below:

> 
> I have the following comments:
> There's no need to serialize RecurringPaymentDetails as bytes here. It's done that way outside of PaymentDetails in order to support digital signatures over protobufs that may have extensions the wallet app isn't aware of, but it's a pain and inside PaymentDetails (and therefore for most extensions) it shouldn't be necessary. So you can just use "optional RecurringPamentDetails recurring_payments = 8;"
> 

OK, we'll fix it.


> There's only 4 possibilities here for recurrences. That seems rather restrictive. Is the cost of being more expressive really so high? Why not allow more flexible specification of periods?
> If there's no payment_frequency_type field then what happens? A quirk of protobufs to be aware of is that making an enum field "required" can hurt backwards compatibility. Because it will be expressed using a languages underlying enum type, if there's a new enum member added later old software that attempts to deserialize this will throw exceptions because the new "unknown" member would be unrepresentable in the old model. Making the field optional avoids this problem (it will be treated as missing instead) but means software needs to be written to know what to do when it can't read the enum value / sees enum values from the future.
> 

I hope the explanation above answers the questions.

> I assume the amounts are specified in terms of satoshi, and timestamps are UNIX time, but better to make that explicit.
> 

Yes.

> Seems there's an implicit value constraint that max_payment_amount <= max_payment_per_period. What happens if that constraint is violated? Best to document that.
> 

As explained above, contract would define none, 1 or both conditions.  First the merchant should not return such 'conditions' but if it does the client should not accept the contract. If the client decides to accept it anyway, then the wallet just verifies both conditions are met separately regardless of whether there is such violation and if so, makes the payment.

> What's the "merchant ID" namespace thing about? What's it for? What happens if I set my competitors merchant ID there?

I agree, we can easily get rid of it.

> What's the "subscription ID"? Is this stuff not duplicative/redundant with the existing merchant_data field?

In an ideal world the merchant should return unique subscriptionId (UUID for instance). That subscriptionId is used in the code to identify the contracts associated with the subscription. The merchant_data if i understand correctly the payment protocol is opaque from the client point of view, so it cannot be used by the client for that purpose. 
> In what situations would you have >1 contract per payment request? I'm not sure I understand why it's repeated. Presumably if there are zero contracts included the data should be ignored, or an error thrown and the entire payment request rejected? Which should it be?
> 


There are many example where that could  happen; for instance if you subscribe to a service,  then later decide to downgrade to a lower product. The merchant may decide to only let you downgrade at the end of your paid period-- to avoid generating extra credit-- and in that situation you end up with two contracts: One for the current product you are in and one for the future product you will end up on when the downgrade becomes effective.


> It's unclear to me given such a contract when the payment should actually occur. For instance if it's "monthly" then what day in the month would the payment occur?
> 

As outlined above in the introduction, the protocol is designed in such a way that the wallet does not have to know what is the exact date when payment should occur, but instead polls the merchant for pending payments. There are many situations when specifying an exact payment date is not an option so that flexibility is essential. A simple example would be for a customer who started subscribing on the 31th of a month. Since there will be months with 28/29/30 days, the payment date would change depending on the month.




> You'll notice I moved the comments to be above the field definitions. I know the current proto isn't done that way, but let's change it - long comments are good and putting them above the field definitions encourages people to write enough detail without being put off by line length constraints
> 

Fine.


> I think the next step would be to talk to BitPay/get Jeff+Stephen involved because I know they have customers that really want recurring payments, and those guys will have a clearer idea of customer requirements than we do. I feel uncomfortable with designing or reviewing in a vacuum without some actual people who would use it chiming in, as I don't really know much about the underlying business processes.


We are totally open to receive feedbacks from them.. How do we bring them in the discussion?

> 
> I have some other comments about the bitcoinj implementation specifically - for instance, we don't have a "wallet directory" concept: everything goes into the wallet file. So we'll need to think about how to structure the code to allow that. Also, just using a background polling thread is likely not flexible enough, as on some platforms you can't stay running all the time (e.g. Android) without upsetting people, but the underlying OS can wake you up at the right times, so wallet apps should have an ability to control wakeup tasks. But we can discuss that over on the bitcoinj list specifically. Let's keep this thread for the general protocol design.

Ok that makes sense.

> 
> BIP 70 is indeed implemented in Bitcoin Core on the C++ side, so that isn't a concern. It could be done there too.
> 

Great to know.




[-- Attachment #2: Type: text/html, Size: 13407 bytes --]

 permalink raw reply	[|nested]
2014-02-26  3:53                         ` Stephane Brossier

  
From: Mike Hearn @ 2014-02-26 10:30 UTC ( / )
  To: Stephane Brossier;  Bitcoin Dev, Pierre-Alexandre Meyer



Thanks for the explanation. I agree that makes sense, and you did actually
explain this before, I just didn't connect the dots :)

The accompanying BIP should explain all this, so the rationale for the
design and how you use it is made clear to developers.

I've CCd Jeff and Stephen on this thread, so they can go review it and
weigh in with any comments. They may want to go back to customers who
requested this feature and ask if it'd satisfy their needs.


On Wed, Feb 26, 2014 at 9:23 AM, Stephane Brossier
<stephane@kill-bill•org>wrote:

>
>
>
>
>
>
> *Hi Mike, Jeremy, Drak,Before going through your questions, I would like
> to bring some clarity on a few key elements in that protocol. There are
> really two aspects to it: 1. The contract negotiation; when the user first
> subscribes, it is prompted by a contract that will define the payment
> bounds associated with that subscription. 2. Once accepted, the wallet is
> in charge and the user does not have to interact anymore -- this is the
> point of the recurring payment protocol. The wallet will poll the merchant
> and issue payments as they are requested by the merchant as long as they
> stay within the bounds of what was specified by the contract (and accepted
> by the customer).I think it would help to explain how we ended up with the
> type of contract we introduced in that protocol. In an ideal world and in a
> NON recurring scheme, the contract should simply be the exact amount to be
> paid. In our case the exact amount may not be completely known in advance
> -- for e.g taxes, shipping, pro-rations, … and so we decided to introduce
> first a max amount per payment, and also a max amount per period. It is up
> to the merchant to decide whether to specify none, any or both bounds (max
> amount per payment and max amount per period). By specifying both, the
> contract is tighter and the client would feel safer to accept it. In the
> extreme case, by specifying none, the client would be presented with a
> contract to pay whatever is requested -- probably not a good option in the
> Bitcoin world unless there is a high sense of trust with the merchant.
>   From reading your comments, it appears we have not been clear on how that
> frequency (PaymentFrequencyType) is being used. Its sole purpose is to
> define the max amount per period in the contract. The frequency of the
> payment is implicitly dictated by the merchant but not specified in the
> protocol by design: the wallet has to poll with a fine granularity (ideally
> each day when it is up) to understand if there is something pending. In the
> same way, a specified amount was not enough in the contract, we feel it
> would be restrictive to specify in advance when payments are due. There are
> a lot of complex scenarios in the billing space, and having the wallet poll
> the merchant to inquire for pending payments is the most flexible option
> and the contract is there to ensure the client will not be abused. To give
> a concrete example, imagine a data plan where you pay a base recurring
> price of $70 per month, but you are charged $10 per GB of data used beyond
> your included limit. If you exceed your limit on the 15th and the 23rd of a
> given month, two extra payment attempts will be requested by the merchant,
> that you couldn’t predict (this scenario is often referred to as usage
> billing with Prepay Credits and Top-up, where the customer pays in advance
> for blocks of N units, and once they are consumed another N are purchased).*
>
>
> *See answers in your questions inlined below:*
>
>
> I have the following comments:
>
>    1. There's no need to serialize RecurringPaymentDetails as bytes here.
>    It's done that way outside of PaymentDetails in order to support digital
>    signatures over protobufs that may have extensions the wallet app isn't
>    aware of, but it's a pain and inside PaymentDetails (and therefore for most
>    extensions) it shouldn't be necessary. So you can just use "optional
>    RecurringPamentDetails recurring_payments = 8;"
>
>
>
> OK, we'll fix it.
>
>
>
>    1. There's only 4 possibilities here for recurrences. That seems
>    rather restrictive. Is the cost of being more expressive really so high?
>    Why not allow more flexible specification of periods?
>
>
>    1. If there's no payment_frequency_type field then what happens? A
>    quirk of protobufs to be aware of is that making an enum field "required"
>    can hurt backwards compatibility. Because it will be expressed using a
>    languages underlying enum type, if there's a new enum member added later
>    old software that attempts to deserialize this will throw exceptions
>    because the new "unknown" member would be unrepresentable in the old model.
>    Making the field optional avoids this problem (it will be treated as
>    missing instead) but means software needs to be written to know what to do
>    when it can't read the enum value / sees enum values from the future.
>
>
>
> I hope the explanation above answers the questions.
>
>
>    1. I assume the amounts are specified in terms of satoshi, and
>    timestamps are UNIX time, but better to make that explicit.
>
>
>
> Yes.
>
>
>    1. Seems there's an implicit value constraint that max_payment_amount
>    <= max_payment_per_period. What happens if that constraint is violated?
>    Best to document that.
>
>
>
> As explained above, contract would define none, 1 or both conditions.
>  First the merchant should not return such 'conditions' but if it does the
> client should not accept the contract. If the client decides to accept it
> anyway, then the wallet just verifies both conditions are met separately
> regardless of whether there is such violation and if so, makes the payment.
>
>
>    1. What's the "merchant ID" namespace thing about? What's it for? What
>    happens if I set my competitors merchant ID there?
>
>
> I agree, we can easily get rid of it.
>
>
>    1. What's the "subscription ID"? Is this stuff not
>    duplicative/redundant with the existing merchant_data field?
>
>
> In an ideal world the merchant should return unique subscriptionId (UUID
> for instance). That subscriptionId is used in the code to identify the
> contracts associated with the subscription. The merchant_data if i
> understand correctly the payment protocol is opaque from the client point
> of view, so it cannot be used by the client for that purpose.
>
>
>    1. In what situations would you have >1 contract per payment request?
>    I'm not sure I understand why it's repeated. Presumably if there are zero
>    contracts included the data should be ignored, or an error thrown and the
>    entire payment request rejected? Which should it be?
>
>
>
>
> There are many example where that could  happen; for instance if you
> subscribe to a service,  then later decide to downgrade to a lower product.
> The merchant may decide to only let you downgrade at the end of your paid
> period-- to avoid generating extra credit-- and in that situation you end
> up with two contracts: One for the current product you are in and one for
> the future product you will end up on when the downgrade becomes effective.
>
>
>
>    1. It's unclear to me given such a contract when the payment should
>    actually occur. For instance if it's "monthly" then what day in the month
>    would the payment occur?
>
>
>
> As outlined above in the introduction, the protocol is designed in such a
> way that the wallet does not have to know what is the exact date when
> payment should occur, but instead polls the merchant for pending payments.
> There are many situations when specifying an exact payment date is not an
> option so that flexibility is essential. A simple example would be for a
> customer who started subscribing on the 31th of a month. Since there will
> be months with 28/29/30 days, the payment date would change depending on
> the month.
>
>
>
>
>
>    1. You'll notice I moved the comments to be above the field
>    definitions. I know the current proto isn't done that way, but let's change
>    it - long comments are good and putting them above the field definitions
>    encourages people to write enough detail without being put off by line
>    length constraints
>
>
>
> Fine.
>
>
> I think the next step would be to talk to BitPay/get Jeff+Stephen involved
> because I know they have customers that really want recurring payments, and
> those guys will have a clearer idea of customer requirements than we do. I
> feel uncomfortable with designing or reviewing in a vacuum without some
> actual people who would use it chiming in, as I don't really know much
> about the underlying business processes.
>
>
>
> We are totally open to receive feedbacks from them.. How do we bring them
> in the discussion?
>
>
> I have some other comments about the bitcoinj implementation specifically
> - for instance, we don't have a "wallet directory" concept: everything goes
> into the wallet file. So we'll need to think about how to structure the
> code to allow that. Also, just using a background polling thread is likely
> not flexible enough, as on some platforms you can't stay running all the
> time (e.g. Android) without upsetting people, but the underlying OS can
> wake you up at the right times, so wallet apps should have an ability to
> control wakeup tasks. But we can discuss that over on the bitcoinj list
> specifically. Let's keep this thread for the general protocol design.
>
>
> Ok that makes sense.
>
>
> BIP 70 is indeed implemented in Bitcoin Core on the C++ side, so that
> isn't a concern. It could be done there too.
>
>
> Great to know.
>
>
>
>