Enables SPSP for pull payments

[sabineschaller]

Following the discussions in #499 and with @sharafian, this addition adds the possibility for pull payments to the protocol.

[emschwartz]

Overall, I'm not a huge fan of adding more details to the SPSP response. If anything, I'd probably support taking out (or making optional) all of the details aside from the ones needed to establish a STREAM connection (destination_account and shared_secret). For pull payments in particular, it seems more useful to have a standard format for the merchant to request a token, rather than for them to have a way to query information about a token they've already gotten.

[emschwartz]

This doesn't take into account the exchange rate between the server's units and the client's units. The amounts returned in the SPSP server response are in the server's units (and the client may not know the exchange rate from the server to them).

[sabineschaller]

This is correct. @justmoon, @sharafian, @adrianhopebailie and I had a chat about this and had the idea that there should be a set of reference currencies, i.e. very common fiat currencies and maybe the most accepted crypto currencies, that the merchant and the customer decide on and this is what gets pulled, irrespective of what both of them hold in their wallets. A field for this needs to be added.

[emschwartz]

Should this be pull_balance.maximum_amount?

[sabineschaller]

Yes. And one could also add that pull_balance.maximum_amount MUST NOT be bigger than balance.current.

Suggested change

	* The `pull_balance.current_amount` MUST NOT be bigger than `balance.maximum`.
	* The `pull_balance.current_amount` MUST NOT be bigger than `pull_balance.maximum_amount`.
	* `pull_balance.maximum_amount` MUST NOT be bigger than `balance.current`.

[emschwartz]

The way this is written, it suggests that the token represents a certain amount per month with rollover. I would kind of expect $10 per month to mean that if the merchant only uses $9 this month, they lose the extra $1.

[sabineschaller]

I agree, if the merchant 'forgets' to pull the last $1 he is entitled to, he should lose it.

Suggested change

	| `pull_balance.refill_amount` | Integer String | Amount, denoted in the minimum divisible units of the server's account, that will be added to `pull_balance.current_amount` whenever now is later than `pull_balance.refill_date`. |
	| `pull_balance.refill_amount` | Integer String | Amount, denoted in the minimum divisible units of the server's account, that `pull_balance.current_amount` will be refilled to whenever now is later than `pull_balance.refill_date`. |

[emschwartz]

the highest size of an individual chunk (which is determined by pull_balance.refill_amount).

This wording is a bit confusing. I think of a "chunk" as an individual ILP packet, but I think this should be referring to the amount in a refill period, no?

Also, is the pull_balance.maximum_amount the max amount per period or the total amount ever? If I have a subscription for $10 per month, I'm not sure you'd want to have a cap on the total value to be pulled (if you want to limit the subscription, it seems more straightforward to have it expire after a certain number of months)

[sabineschaller]

pull_balance.maximum_amount was supposed to be the maximum overall that can be pulled from this endpoint. But I agree, defining the end by means of time is more straight forward. Paypal for example uses the notion of cycles, i.e. they have frequency=week, frequency_interval=2, and cycles=4, meaning that this pull payment agreement would be valid for 8 weeks.

[emschwartz]

current_amount sounds like it could mean either "how much you've already taken" or "how much you currently have left", so it might be better to pick a less ambiguous term

[sabineschaller]

I am very bad at naming so any suggestions are welcome. What about pullable_amount?

[sabineschaller]

Or available_amount

[emschwartz]

It seems more helpful to me to have a way for the merchant to request a token with specific parameters than to have a way for the merchant to check the details of the token they've got

[sabineschaller]

Does that need to be part of the protocol though or is that part or the negotiation phase that happens before and by other means?

[emschwartz]

That would be a separate negotiation, not part of SPSP (or more precisely, not part of the single HTTPS request we now think of as SPSP; we could "include" the token and token-request procedure in SPSP or call them separate but linked protocols).

[emschwartz]

This suggests that the money can only be pulled on that date, rather than after that timestamp.

Also, is this a date or date + time?

[sabineschaller]

I was thinking about date and time, so the correct name for it would probably be refill_time. I don't see though that this suggests that one can only pull on one specific date.

[emschwartz]

I don't quite understand this. Is this the amount of time that will pass after the refill_date before the amount is refilled again?

[sabineschaller]

Exactly. refill_date_old + refill_interval = refill_date_new. This probably needs to be split into something like 'frequency' (day, week, ...) and 'frequency_interval' (e.g. 2). What do you think?

[sabineschaller]

After some discussions and taking the comments above into consideration, I updated the response body fields, taking Paypal Subscriptions as an example. However, I tried not to over-complicate things, using as little fields as possible.

[wilsonianb]

Should pull_info instead have asset_info with code and scale?

[sabineschaller]

I thought about that but was not sure. I think you still need the "external" asset_info field because this describes the currency of the server whereas pull_info.asset_code is the currency that the sender and the receiver agreed upon when they negotiated the terms of the pull payment token. However, it does make sense to include the asset_scale unless everything is in the minimum divisible unit of that currency.
I just realized that I have to change the descriptions in pull_balance to not say "units of the server's account" but "units of the agreed upon currency".

[wilsonianb]

It seems like refill_time makes start_time either redundant or irrelevant.
Unless we need that historical information (how long has this been going on), it could be removed.

[sabineschaller]

I agree.

[adrianhopebailie]

This is not really an issue with this PR per se, but perhaps a bigger issue with SPSP in general.

It is very difficult to infer the entities involved or the relationships between the entities involved in a payment from the data model of the SPSP response. As such it's hard to reason about the design.

Does an SPSP document represent a payment, a receiver, a server or just some collection of data?

SPSP has evolved so that we can now make the following assumptions:

• An SPSP response contains at least an ILP address and secret which are used by the client to create a STREAM connection.
• We CAN'T assume that the entity hosting the server is the owner of the ILP address in the response.
• We CAN'T assume that the client is always the sender in subsequent payments.

Perhaps then the best way to model this is to think of an SPSP response as representing a STREAM connection (or more precisely a session, although I'm not sure if STREAM uses that terminology or differentiates between the two).

The ILP Address is the unique identifier for the session and the secret is the "bearer token" that allows the client to create the session.

The remainder of the SPSP response defines properties of the session.

Some suggestions:

Use balance for both push and pull. Negative means the client is expected to be a sender. It shouldn't need asset details like scale and code because these are shared when the STREAM connection is established. Having them in the SPSP response may be useful but then we need to define how a client should behave if it gets different info via SPSP and STREAM.

Rename receiver to counterparty or some similar non-specific name.

Separate validity data related to the session (start and expiry) from data about frequency (i.e. how often is the balance on the connection changed).

I think these changes make SPSP much cleaner but they are also not backwards compatible so probably need to use a new protocol version header.

[adrianhopebailie]

The replacing of 'receiver' with 'server' and 'sender' with 'client' is a little inconsistent.

[adrianhopebailie]

Suggest replacing:

The client can set up and send or pull multiple ILP payments using the details provided by the server.

with

The client can use this information to establish a STREAM connection and begin sending or receiving payments.

[adrianhopebailie]

We should define the entity that handles the incoming STREAM connection. Maybe call it the STREAM server? It may or may not be the same entity as the SPSP server but is also not necessarily the receiver/payee.

[adrianhopebailie]

Is the response "server info"?
Perhaps this could simply be:

The SPSP Endpoint responds with an ILP address and a shared secret to be used in a new STREAM connection. It MAY respond with additional information if it is an invoice server or a pull payment server.

[adrianhopebailie]

Terminology is nuanced here. What is an "ILP payment"?

Strictly speaking a "payment" could be completed through the exchange of multiple ILP packets. i.e. A payment is not a technical concept but a packet is and ILP has no concept of non-technical concepts.

I think this step could be left out entirely.

[adrianhopebailie]

As above, it would be useful to explain how the values of sendMax and receiveMax relate to the values in the SPSP response or even link to another part of the document where this is explained.

[adrianhopebailie]

The server may "return" an invoice or token? (As opposed to "be").

Suggest using "URL" instead of "URI" as the spec defines the query protocol as HTTP over TLS.

The SPSP endpoint URI MUST NOT contain query string parameters. The sender SHOULD treat the URI as opaque.

If this is re-written as testable normative requirements for the client and server I'd rather say:

Clients MUST NOT send query string parameters in requests to the SPSP endpoint URI. Servers that receive query string parameters in an SPSP request MUST reject the request with a 400 Bad Request HTTP response code. Clients SHOULD treat the URI as opaque and not depend on any information they derive from the URI.

[adrianhopebailie]

Suggest:

The client queries the SPSP endpoint to get information about the payment:

[adrianhopebailie]

Possibly reword so this doesn't imply that the payment is "pulled from the server" but rather that the server provides details (and a token) that allow the bearer to to pull a payment from a sender.

[adrianhopebailie]

Should be:

The response MUST contain at least the following fields

[sabineschaller]

Use balance for both push and pull. Negative means the client is expected to be a sender.

I really like that idea.

[sabineschaller]

It shouldn't need asset details like scale and code because these are shared when the STREAM connection is established. Having them in the SPSP response may be useful but then we need to define how a client should behave if it gets different info via SPSP and STREAM.

I do believe we need that because the server could be in XRP, the client in ETH, but the pull agreement was made in a fiat currency, e.g. USD. They both need to use this to adjust their sendMax and receiveMax.

[wilsonianb]

Would it instead be the client constructing the stream to initiate the pull payment?

[sabineschaller]

The way I have it implemented right now is that the client connects to the server (i.e. opens the STREAM connection) and on that connection, the server opens the stream and sends the payments to the client. So technically, it is not a pull payment but the client requests the server to send him the agreed upon amount (or something less than that) right now (on connection).

[justmoon]

My main comment would be that pull payments should not be part of the SPSP spec. I think the SPSP spec should have some provisions for extensibility, e.g. how to define additional fields for the SPSP response, and then there should be a different RFC that specifies pull payments.

I think this goes in line with @emschwartz's comment not to add more to the SPSP response. My recommendation would be to view SPSP more like HTTP - a general-purpose baseline that is very extensible for different use cases. (Of which there could be many. I keep thinking back on ISO 20022's dedicated schemas for wage garnishment.)

[adrianhopebailie]

My recommendation would be to view SPSP more like HTTP - a general-purpose baseline that is very extensible for different use cases.

In that vein, maybe the ilp address and secret shouldn't be returned in the response but rather in headers.

This frees up the response to be a regular HTTP response and have different types.

i.e. SPSP is simply a spec for augmenting any HTTPS response with two standard headers?

[sabineschaller]

i.e. SPSP is simply a spec for augmenting any HTTPS response with two standard headers?

This would mean making the SPSP spec slimmer and introducing two new specs, one for push and one for pull payments over SPSP, @adrianhopebailie?

[adrianhopebailie]

@sabinebertram yes, that's my proposal but interested to hear from @sharafian @justmoon and @emschwartz too. We've all talked in circles around SPSP for some time and it came up on the community call yesterday too.

My proposal, concretely, is this:

• Any HTTPS request can be treated as an SPSP request by a web server. (By default a Payment Pointer is resolved to a URL and client performs a GET on that URL but this is specified in the Payment Pointer spec not the SPSP spec.)
• The HTTP response should contain headers that carry the ILP address and the shared secret to use to establish the STREAM connection.
• The definition of the HTTP response body and content-type can be defined in another spec (and possibly even leverage existing standards for eInvoices etc)
• This could also be leveraged by websites as an alternative to a Web Monetization <meta> tag in the page (@sharafian @justmoon ?).

A proposal on the header format is to follow the same pattern as the authorization header: <protocol> <details>. Here <protocol> could be STREAM and <details> could be the base64 string that decodes to : (to avoid case changes in-flight)

Aside: I drafted a spec for the IETF a while back that proposed bringing the payment request from the W3C into HTTP: https://tools.ietf.org/html/draft-dold-payto-02

I think that this proposal is a better option than the previous IETF draft because it doesn't need to carry the details of the payment in the header, just the details of the counter-party and how to establish a secure "payment connection" with them.

If we can settle on a spec for this we should consider also submitting to IETF.

[emschwartz]

This discussion is moving beyond the scope of the original PR. I'd suggest opening a separate issue to discuss changing SPSP to be just headers.

FWIW, I'm hesitant to make any breaking changes that aren't very substantive (like moving the STREAM secret and address from the body of a given request to the headers), but this would mean effectively merging SPSP and the HTTP-ILP specs, which doesn't sound terrible. I'm still doubtful how important this is for pull payments because it seems like the main issues are a) how to get the token that you'll use to make the SPSP request or get the STREAM details and b) the format of that token (rather than how to query details about the parameters of the token once you have it).

[sabineschaller]

After discussions with @sharafian and @wilsonianb, I made the SPSP spec backwards compatible by leaving the destination_account and the shared_secret in the body, however, removing the notion of push and pull payments form the spec. It only defines how to request these information and that they are used for creating a stream connection.
I created two new specs called SPSP Push Payments and SPSP Pull Payments that concentrate on the payments and the parameters in the response body.

[adrianhopebailie]

I really like the new split between 3 specs.

Some clarity on how the SPSP request and STREAM connection are correlated would be useful especially for implementors that wish to implement stateless servers.

[adrianhopebailie]

I don't think this is correct. The client may be sending in a different currency.

The amount the client is willing to send is a business decision based on the expected amount (balance.max - balance.current), the anticipated exchange rate, and the slippage the client will allow.

[sabineschaller]

You are right. That was blind copy-pasting. I'll fix it.

[adrianhopebailie]

This is a new specification. We don't need to use receiver_info for backwards compatibility and this is actually the sender.

Can we use a more neutral term like "counterparty"?

[sabineschaller]

I actually had the receiver in mind. This could be useful for an end user application (a wallet supporting pull payments) to display details about this particular pull agreement. But maybe there should be a field called counterparty_info that contains the details about sender and receiver.

[adrianhopebailie]

Creating a token doesn't seem to be an interoperability requirement.

The end result is a Payment Pointer that contains a bearer token. How that is created doesn't need to be standardised.

I would recommend noting that this part of the specification is not normative.

[sabineschaller]

Fair enough.

[adrianhopebailie]

Some mention of how the server identifies that this connection is related to the SPSP request would be useful.

Is the ILP address unique per transaction or is the identifier the secret?

When a connection is established with a specific ILP address and secret I assume the server knows which payment it relates to and so can set the appropriate sendMax?

Is there a way to do this that doesn't require the server to store this data somewhere (i.e. allow the server to be stateless)?

[sabineschaller]

Instead of storing the information, the token could be a JWT. The client could connect to the endpoint without suffix, i.e. to /.well-known/pay instead of /tokenUUID and if the first thing that is received by the server is a JWT, it parses and validates it and streams the according funds.
However, one would probably still have to store balances somewhere to make sure that the client doesn't connect and pull more than allowed.

[sabineschaller]

I updated the basic SPSP spec and the pull payment spec according to our discussions on the Forum (Pull Payments and Push Payments and Invoices). The invoice spec still needs work but there have not been any further discussions.

[sabineschaller]

I'm closing this PR and will open individual ones for the new 'basic SPSP' spec as well as the stand-alone pull payment spec. I may also open one on invoices but there have not been any further discussions regarding that spec on the forum so it is on pause.