docs(0009): upgrade SPSP for PSK2

[sharafian]

• Replace PSK with PSK2 (pending PSKv2 #351)
• Deprecate bob@example.com, favoring the $bob.example.com payment-pointer style instead.
• Require sender to request with Accept: application/x-spsp-response.
• Remove maximum_destination_amount and minimum_destination_amount from response.
• Make receiver_info and ledger_info optional fields from response.
• Add optional balance object in response with balance.maximum and balance.current for invoices.
• Document $bob.example.com payment-pointer identifiers.

[justmoon]

Should be asset_code and asset_scale. In case people want to use non-currency assets.

[justmoon]

Should remove this section.

[justmoon]

Should be Accept: application/spsp+json and we should get a provisional registration.

[justmoon]

We shouldn't have two types of identifiers. if we're adding the payment pointers, let's get rid of the webfinger identifiers.

[justmoon]

Should specify the exact format for payment identifiers. For example, are ? allowed? Hashes (#) presumably aren't. Is URL encoding (e.g. %20) supported? Presumably, parsing stops at the first space character? Can a payment identifier end in a period (.)? (We may want to say no to avoid ambiguity when parsing identifiers from text like: Hi everyone, my identifier is $justmoon.com/big-money.)

[emschwartz]

I kind of like the $example... format and hear the criticism of the email-style identifier, but having it start with a dollar sign makes it quite US-centric. It's unfortunate that there is no widely-recognized symbol that just means "money" or "currency" without being tied to a specific one.

@diminator, @adrianhopebailie, @earizon, @michielbdejong, @oniabifo, @nathanawmk have any thoughts about this?

[sharafian]

Most keyboards have the $, at least. It also has the connotation of being a variable that expands to something else, which is cool (it 'expands' to your ILP address)

[sharafian]

How do you feel about the name "Payment Pointer" for it?

[justmoon]

Typical American. You adopt the $ sign for your currency and suddenly it's "US-centric". ;)

The most common hypothesis for the origin of $ according to Wikipedia:

The symbol was adopted by Charles V and was part of his coat of arms representing Spain's American possessions. The symbol was later stamped on coins minted in gold and silver. The coin, also known as Spanish dollar, was the first global currency used in the entire world since the Spanish Empire was the first global Empire.

So, if anything it's Spanish Empire-centric, not US-centric.

As a result, no other symbol is used by as many different currencies:

Australian (A$), Bahamian (B$), Barbadian (Bds$), Belizean (BZ$), Bermudian (BD$), Brunei (B$), Canadian (Can$), Cayman Islands (CI$), East Caribbean (EC$), Fiji (FJ$), Guyanese (G$),[5] Hong Kong (HK$/元/圓), Jamaican (J$), Kiribati, Liberian (L$), Linden Dollar (Second Life virtual world) (L$ or LD$), Namibian (N$), New Zealand (NZ$), Singaporean (S$), Solomon Islands (SI$), Surinamese (SRD), Taiwanese (NT$/元/圓), Trinidad and Tobago (TT$), Tuvaluan, United States (US$), and Zimbabwean (Z$) dollars

Argentine, Chilean (CLP$), Colombian (COL$), Cuban ($MN), Cuban convertible (CUC$), Dominican (RD$), Mexican (Mex$), and Uruguayan ($U) pesos

It also appears in the currency symbols for Brazilian Real (R$) and Nicaraguan córdoba (C$) among a few others. That means there are people on every continent who recognize $ as the symbol for their currency. No other currency symbol comes close. You could make a case for ¥ which I would guess is the currency symbol used by the most people. But it is used only by two currencies: Chinese Renminbi yuan and Japanese yen, so I don't think you can make a strong case that it is the best global choice. There is the "generic currency sign" ¤, but nobody would recognize that thing.

There are of course also pragmatic reasons for using $. It's an IA5 character and therefore easily encoded and included in pretty much all keyboard layouts worldwide. We should check if that is still true for mobile input methods.

Is the $ perfect? No. It's not. Ideally, something like ¤ would be an IA5 character and widely recognized. But we're in the real world and out of the available choices, the $ has a huge lead. Someone patriotic whose country uses a different symbol might think it's associated with the US and feel excluded. If anyone has a solution for that, let me know. But I also think there will be a lot of people that wouldn't react that way. Speaking as a German, the $ to me just means money. The fact that the US adopted it is just another example of a young country that's perhaps lacking a little bit of cultural identity. And the fact that Americans would be worried that the $ is not culturally neutral is an example of maybe a little bit of lack of cultural awareness - the majority of people whose local currency symbol is or includes the $ are not Americans. The US is just one of several countries that used $ because they didn't have their own historic currency symbol and $ was basically the international symbol for money at the time.

[michielbdejong]

see ^

[michielbdejong]

This is a fundamental change, you're not looking up data about a person, but about an invoice. Although that may be useful by itself, that's not what we use spsp for in ilp-kit.

Can't we keep it so the sender determines the amount, like it's now in ilp-kit? Also, we need to display name and avatar.

[sharafian]

The balance object is only present if this represents an invoice. The sender can still determine the amount; in the case of an invoice it will start to raise the current balance until it reaches the maximum, and if it's just an ordinary receiver then they'll just accept funds no matter what.

The name and avatar URL are still present in the receiver_info object. They're not required fields, though, because not everyone may want to display that information.

[emschwartz]

I'm not sure we need the current balance, even for invoices. In PSK2 the receiver tells the sender with every chunk how much of the total has arrived so far. I think it's more likely that you'd use that mechanism to figure out how close it is to being paid, rather than repeatedly querying the HTTP endpoint.

[sharafian]

You may want to see the current amount paid before you start trying to pay the invoice, though

[emschwartz]

Is a partially paid invoice something you'd expect to see regularly? It seems like that's more likely to be caused by something going wrong with a chunked payment half-way.

That also reminded me, is there a case to me made for using a specific payment ID in the PSK packet that's related to the invoice, or is the assumption that you would include the type of identifying information in the ILP address that SPSP returns?

[sharafian]

I think you would probably use the ILP address to encode that information. However, when I upgraded http-ilp for PSK2, I used the payment ID as the Pay-Token rather than putting it in the PSK2 application data. Using the ILP address is a third option. We might want to decide which of those is the recommended option.

[robass1]

Evan, FWIW, partially paid invoices are a common business scenario, even aside from failed or incomplete payments.

[oniabifo]

I would say the $ sign is the closest sign to a world currency. As a Nigerian, i do not think the Naira Sign '₦' is available on any keyboard out there, even the keyboards back home do not have them. I have to make use of google to copy the code whenever i want to make use of it.

I checked the Iphone keyboard layouts also, and there are only Dollars, Euro, and pounds sign available. Most Nigerians, and even every African that i have met recognizes dollars as the world currency.

[emschwartz]

I'm not sure we need the current balance, even for invoices. In PSK2 the receiver tells the sender with every chunk how much of the total has arrived so far. I think it's more likely that you'd use that mechanism to figure out how close it is to being paid, rather than repeatedly querying the HTTP endpoint.

[emschwartz]

How would that work with Github pages? Doesn't it use https://{username}.github.io/{repo}?

[sharafian]

You can use a CNAME record to make your own domain point to your github pages. Then you put that domain behind something like cloudflare, so the CNAME resolve after the HTTPS is terminated (that way github doesn't need a cart for your site)

[emschwartz]

If this is the main identifier people are going to interact with, I think it definitely needs some version negotiation in the resolution protocol. We're not going to want to change the identifier so we should plan for different versions of SPSP and/or PSK.

[sharafian]

Right now, $bob.example.com resolves to https://spsp.bob.example.com, with the accept header application/spsp+json. The response returned has a content type of application/spsp+json as well.

If we want to add a breaking version to the protocol, we can either:

1. change the subdomain (SPSP goes to spsp.bob.example.com but new SPSP goes to spsp-v4.bob.example.com.

2. change the accept header (SPSP is returned when the accept header is application/spsp+json but SPSPv4 is returned for application/spspv4+json.

3. (potentially combined with 2) return a content type of application/spspv4+json in the Content-Type response, allowing the client to check and make sure that it received a supported SPSP version.

[adrianhopebailie]

If this is the main identifier people are going to interact with, I think it definitely needs some version negotiation in the resolution protocol.

The resolution of an endpoint to query based on the identifier needs to be simple and stable. The interaction with the endpoint can then accommodate versioning (sent in the request headers, list of versioned endpoints in the initial response etc)

[emschwartz]

Would you read this as "pay bob dot example dot com"?

If you have your own domain, this format seems pretty good: "pay sharafian dot com".

I'm less sure about the experience for people that are addressed in terms of their provider. Email addresses read nicely as "evan at provider dot com". At seems a sensible way to indicate that it's a user with a certain provider (or maybe I'm just used to that now). "pay evan dot provider dot com" sounds a little less nice to me, maybe because I'm not really used to the dot separating the username from the provider. "pay provider dot com slash evan" is even worse, in my opinion.

[sharafian]

Email addresses have their quirks too; I think having our identifiers structured similar to web URLs makes them easier to understand. It also looks a little more like a modern handle-style identifier like @example, while example@example.com feels a little more dated (maybe just to me).

It's nice having the clear delineation between user and provider, but that also precludes the ability to have a short vanity address (ie. $sharafian.com instead of pay@sharafian.com) which I think is cool.

As for the path, I would imagine it would be used more commonly for things like invoices. Something like $invoice.amazon.com/22589235 might read better than $22589235.invoice.amazon.com. It also helps us support people whose systems might not be easily set up to handle subdomains dynamically.

[adrianhopebailie]

I think having our identifiers structured similar to web URLs makes them easier to understand

This has not been true historically. The WebID standard has tried for a decade to get people to identify themselves using a URL with very little success.

It also looks a little more like a modern handle-style identifier like @example

That's why Square used the CashHash format $user. The problem is that this is a domain-less identifier. You need to have a way to scope it.

example@example.com feels a little more dated (maybe just to me)

It's a compromise. If you've got the network effect of Twitter you can have an implicit domain but even then it doesn't always work: Does @sharafian mean https://twitter.com/sharafian or https://github.com/sharafian ?

[emschwartz]

Are there use cases where you might want to send data along with the PSK payment? If so, SPSP should specify a format for the PSK data field.

[sharafian]

Not quite sure on this one. Supporting something like "source identifier" or "payment memo" might be useful. But there's a lot of use cases where we don't need that, so I think whatever we do I'd like to have the option to leave the application data blank.

[sharafian]

So after some implementation work, I noticed a problem with our subdomain method:

If you're example.com and you want your users to have $name.example.com as their payment pointer, you need an SSL cert that's valid for $spsp.name.example.com. Because the name is dynamic, you would ideally want a wildcard cert for *.example.com. Unfortunately, these wildcard certs only apply for one level of subdomain. The * must also be leftmost, so you can't do spsp.*.example.com.

It would be impractical to manually create a cert for each user in order to allow $user.example.com for all of them, and I believe it would be highly challenging to dynamically create a cert for any spsp.*.example.com subdomain.

The easy solution is to make your user's identifier $example.com/user, but that looks worse than an identifier with no path portion. It's also strange because the user's name comes last in their identifier, as opposed to first like in email addresses or payment pointers with no path.

The reason we prepend spsp. is to make it easier on people who want to keep an ordinary site on their normal domain. But if that makes it impossible for people who don't have their own name to have a nice identifier, it might not be such a good idea.

(@michielbdejong I remember you talking about some sort of dynamic SSL certs thing at one point; is that at all applicable to the situation I'm talking about?)

[michielbdejong]

yes, with letsencrypt your server can register certs whenever it needs them, but there's a rate limit of something like 5 a week per server, I think.

[oniabifo]

@sharafian i was able to use letsencrypt to get ssl certs for my subdomain but it seems to expire every three months so has to be renewed.

[adrianhopebailie]

So after some implementation work, I noticed a problem with our subdomain method

That is why I strongly recommend not mis-using subdomains in this way. Subdomains are a reverse heirarchy. I recommend the scheme I suggested in interledgerjs/ilp#126 (comment)

The scheme supports both "hosted" and "vanity" pointers and is actually pretty easy to host, even on Github pages.

For a hosted account (let's say it is hosted by red.ilpdemo.org) a user (let's say bob) can have the pointer bob$red.ilpdemo.org. An HTTP GET to https://red.ilpdemo.org/$bob should return the users SPSP response data.

No need for the host to have additional SSL certs and unlikely to have conflicts on the path starting with $. A nice property of this is that it closely resembles the default user home path of https://example.com/~user.

For a vanity pointer (e.g. I have my own domain, let's use adrianhopebailie.github.io for example) I can exclude the account portion and simply use $adrianhopebailie.github.io. That maps to the URL https://adrianhopebailie.github.io/$.

It took me 30 seconds to set that up on Github pages with no Letsencrypt, DNS or other tweaks. If you hit that URL now you'll get a static SPSP response.

[sharafian]

That is why I strongly recommend not mis-using subdomains in this way. Subdomains are a reverse heirarchy. I recommend the scheme I suggested in interledgerjs/ilp#126 (comment)

Github gives each user a subdomain so I don't think there's anything inherently wrong with the approach. It's just that adding a hard-coded domain segment won't be feasible.

For a hosted account (let's say it is hosted by red.ilpdemo.org) a user (let's say bob) can have the pointer bob$red.ilpdemo.org. An HTTP GET to https://red.ilpdemo.org/$bob should return the users SPSP response data.

How do you pronounce bob$red.ilpdemo.org? The @ in bob@example.com ("bob at example.com") makes grammatical sense, and $bob.red.ilpdemo.org could easily be read as "pay bob.red.ilpdemo.org". Would bob$red.ilpdemo.org be "bob pay red.ilpdemo.org"? In my head I can't help but read it as "bob dollar-sign red.ilpdemo.org."

Additionally, $ is a special URL character, so it would actually become https://red.ilpdemo.org/%24bob, which is strange. If we stripped the $ it may be strange too, because something like index.html$red.ilpdemo.org would likely collide with a file.

It took me 30 seconds to set that up on Github pages with no Letsencrypt, DNS or other tweaks. If you hit that URL now you'll get a static SPSP response

Because ILP addresses are liable to change frequently and a shared secret needs a live PSK2 receiver, it won't really be feasible to statically host an SPSP response. That means if you want $adrianhopebailie.github.io with your scheme, you would need to be running a live server on that domain.

I agree that it's important to be able to set up an SPSP receiver without running your own infrastructure: the big advantage of having SPSP on a separate subdomain is that you can have a CNAME record to point that at a service to act as an SPSP receiver for you. For instance, you can make the following records:

CNAME "spsp.sharafian.com" -> "raftx8Utfjznx5M3H7RWncb1w1dtAWDNZR.siren.sh"
CNAME "sharafian.com" -> "sharafian.github.io"

That allows me to have a personal website and an SPSP receiver on my domain without running a single server myself. All of that could be done through a service like cloudflare.

---

One thing that we could do would be to resolve $bob.red.ilpdemo.org in the following way:

1. https://spsp.bob.red.ilpdemo.org
2. If that fails, try https://bob.red.ilpdemo.org

The reason I don't like that is that it prioritizes the addresses of people with their own domains over people who have a personal subdomain on a provider (the bob.red.ilpdemo.org style).

Another option would be to resolve the DNS for the host (i.e. bob.red.ilpdemo.org). If a record is present for spsp.bob.red.ilpdemo.org it would use that, and otherwise it would just use bob.red.ilpdemo.org. I'm not sure how easy this is to implement, though, nor whether it would work for wildcard subdomains.

[adrianhopebailie]

Github gives each user a subdomain so I don't think there's anything inherently wrong with the approach.

They give users a subdomain under a completely different TLD though. That's not by accident. Partitioning the traffic between github.com and github.io is a crucial part of the design.

Having a per-user subdomain is not a bad thing per se, but having the subdomains below a TLD that has a completely different purpose is a recipe for disaster.

It's just that adding a hard-coded domain segment won't be feasible.

That's was my point. You are breaking the domain hierarchy. If the purpose of the domain is to express "Bob's account on the SPSP service hosted at red.ilpdemo.org" then the domain needs to be bob.spsp.red.ilpdemo.org. Resolving to that from $bob.red.ilpdemo.com is horrible because there is no way to know if the user is bob or bob.red as I pointed out above.

The hardcoded subdomain is a bad idea. Don't do it.

FYI: I'm sure there are some good mail archives at the IETF that detail specifically why using hard-coded subdomains is a bad idea, if you're interested. They'll likely revolve around the development of RFC5785 which defines a hardcoded path prefix instead.

How do you pronounce bob$red.ilpdemo.org?

Surely how you pronounce this is not as important as the practicality of implementing it!?

Personally, for "$adrianhopebailie.github.io", I would say: "Pay adrianhopebailie dot github dot io" and for "bob$red.ilpdemo.org" I would say: "Pay bob at red dot ilpdemo dot org". It's an account at a host, the fact that it's a payment tells you that the separator to use is a $ not a @.

Additionally, $ is a special URL character, so it would actually become https://red.ilpdemo.org/%24bob, which is strange.

Why is it strange? It's a perfectly valid URL. Users will never type %24, they'll always just use $. All existing systems handle this fine.

Because ILP addresses are liable to change frequently and a shared secret needs a live PSK2 receiver, it won't really be feasible to statically host an SPSP response.

If you can't have a static SPSP response I'd consider SPSP dead-in-the-water for many use cases then. I should be able to host a static response that at least redirects the client to a live endpoint. Requiring people to manage DNS in order to setup a personal service has proven historically to always be a failure.

the big advantage of having SPSP on a separate subdomain is that you can have a CNAME record to point that at a service to act as an SPSP receiver for you.

My proposal doesn't preclude you from doing that. Assuming you have the same DNS entries above you can use $spsp.sharafian.com as your payment pointer. The SPSP endpoint would be hosted at https://raftx8Utfjznx5M3H7RWncb1w1dtAWDNZR.siren.sh/$

Interestingly, another advantage of having all SPSP endpoint paths start with /$ is that it makes it very easy to setup rules on a per host basis specifically for routing SPSP requests. This would make configuring services like an nginx proxy trivially simple.

[sharafian]

Surely how you pronounce this is not as important as the practicality of implementing it!?

I completely disagree there; If we didn't care about how users read this identifier we could use any one of our less easily recognizable identifiers: bob@example.com, https://example.com/spsp/bob, or even a custom scheme like spsp://example.com/spsp/bob are all practically implementable, but are not attractive, not concise, and/or not recognizable.

The reason I'm arguing so vehemently to keep the $bob.example.com style as the identifier (regardless of how we resolve it) is that I think it's visually the best looking option, without completely compromising versatility.

If you can't have a static SPSP response I'd consider SPSP dead-in-the-water for many use cases then. I should be able to host a static response that at least redirects the client to a live endpoint. Requiring people to manage DNS in order to setup a personal service has proven historically to always be a failure.

I absolutely agree; we shouldn't require users to run their own servers just to participate in SPSP. Not sure why using DNS for vanity addresses is a problem, though. It's exactly the same as email; you can sign up for a provider without personally setting anything up, but if you want your personal site to be your email address, you have to add a couple MX records.

My proposal doesn't preclude you from doing that. Assuming you have the same DNS entries above you can use $spsp.sharafian.com as your payment pointer. The SPSP endpoint would be hosted at https://raftx8Utfjznx5M3H7RWncb1w1dtAWDNZR.siren.sh/$

If we're not adding another subdomain segment, we really don't need to have a separate account portion. We could just say that $bob.example.com points to https://bob.example.com/.

The only case where bob$example.com gives an advantage is if there's a hard-coded domain segment and we don't want to mess up the hierarchy of subdomains, like you said. But if we just don't add a hard-coded domain segment then adding a path segment for the user should be equivalent to adding a subdomain for the user.

A server providing multiple SPSP receivers could easily use this URL to generate an SPSP response for bob; in fact, I already have a working implementation of that: https://github.com/sharafian/ilp-plugin-outgoing-settle/blob/master/index.js#L73

This was the original proposal and the reason we switched from it was that @justmoon brought up the point that it made it impossible for someone hosting their personal site with something like cloudflare and github pages to ever host an SPSP receiver for their personal site's domain (in his case $justmoon.com).

Interestingly, another advantage of having all SPSP endpoint paths start with /$ is that it makes it very easy to setup rules on a per host basis specifically for routing SPSP requests. This would make configuring services like an nginx proxy trivially simple.

That's an interesting point. What if we combined the two approaches, such that $bob.example.com would direct to https://bob.example.com/.spsp, or something like that? If the SPSP identifier already has a path segment, then no .spsp would be added. Then we:

• Can distinguish an SPSP query from a normal one on the same server
• Could use cloudflare page rules or similar to host a site on example.com and a receiver on example.com/.spsp
• Can have a multi-user SPSP receiver, using subdomains.
• Get to keep a simple and nice-looking identifier.

@justmoon @adrianhopebailie @emschwartz, how do you feel about that proposal?

[adrianhopebailie]

If we didn't care about how users read this identifier we could use any one of our less easily recognizable identifiers

You are confusing how users read the identifier with selecting a recognizable identifier. They are not the same thing. We need to pick a recognizable format (hence we can't use bob@example.com because it is already used for something else) but we also need to consider the practicality of hosting the resources behind this pointer.

Once we have a recognizable format people will figure out how to read/say it that makes sense.

I agree that using a URI is not attractive and not concise which is why those are off the table.

The reason I'm arguing so vehemently to keep the $bob.example.com style as the identifier (regardless of how we resolve it) is that I think it's visually the best looking option, without completely compromising versatility.

I agree 100% with that format but I think it compromises versatility too much. I think that same format but with an optional account prefix provides more options: [<account>]$<domain>

It's exactly the same as email; you can sign up for a provider without personally setting anything up, but if you want your personal site to be your email address, you have to add a couple MX records.

No exactly. MX records are not CNAME records, they are specifically for mail services. They allow you to host two services at the SAME domain. This makes it easy for email providers to scale up to millions of accounts because the way you resolve a mail exchanger from DNS is designed to scale. You can have multiple servers at different domains and even set a priority for them all using a handful of DNS records.

What you are suggesting is that an SPSP provider that hosts SPSP services for many accounts will need to have a wildcard DNS record that captures all DNS requests for subdomains. It will work but you'd never be able to host the SPSP services on the same domain as other services (similarly to how Github has user subdomains on github.io and other services on github.com).

Unless... You have a hardcoded path (like .well-known or .spsp as you suggest or $ as I have) which means you need to intercept all HTTP requests and redirect them based on the path prefix.

NOTE: Doing this so late in the flow means you have to use the same TLS certs for WWW and SPSP services because the TLS handshake is complete before the request comes in. This is hard to get around without an explicit DNS level scaling solution like MX records. (May be worth looking at SRV records but that gets ugly because it requires clients to perform DNS queries).

I think your compromise proposal is good but I still like the path /$ because it's VERY unlikely to conflict with anything else and it preserves the symbol from the pointer.

Something to consider is that my proposal is identical to yours but with an additional option giving SPSP hosts the option to offer their users a bob$example.com type pointer OR a $bob.example.com type pointer.

So in summary, I propose we support the following:

$justmoon.com -> https://justmoon.com/$
$bob.example.com -> https://bob.example.com/$
bob$example.com -> https://example.com/$bob

If we aren't going to use the $ path prefix then I'd recommend we follow RFC5785 and use /.well-known/spsp.

[adrianhopebailie]

On re-reading this I think maybe allowing a path segment in the pointer is a good idea, that would mean no need for the account segment.

$justmoon.com -> https://justmoon.com/$
$bob.example.com -> https://bob.example.com/$
$example.com/bob -> https://example.com/$bob

[sharafian]

That last proposal sounds good to me. Only thing I'm not sure is whether we should do the $ like you suggest, or .well-known/spsp. The latter might be easier to upgrade in the future, because we could add something like .well-known/spsp4 and support the old and new versions on the same host. The $ is more concise but would be harder to upgrade (something like $4 might collide with an account.

Also not sure if https://example.com/$bob is the best way to resolve $example.com/bob, especially if we were to go with the .well-known style. If that were the case we might want to keep the path untouched and just say if you want to host a multi-user service and host other content on the same site, you should just return different results on an Accept: application/spsp+json request.

[adrianhopebailie]

The latter might be easier to upgrade in the future, because we could add something like .well-known/spsp4 and support the old and new versions on the same host.

I think we'd be better off supporting versioning through headers than hardcoding new versions as new paths. This also means we decouple this protocol (resolution of a URL from a pointer) from SPSP.

None of the registered .well-known addresses are versioned: https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

If that were the case we might want to keep the path untouched and just say if you want to host a multi-user service and host other content on the same site, you should just return different results on an Accept: application/spsp+json request.

I think it's problematic to have different behaviour specified for the endpoint depending on whether there is a path or not. We should keep this as simple as possible.

I also think it's useful to require the Accept: application/spsp+json header for all requests because the pointer $<domain> is really powerful and I expect we'll have more success at getting it standardized as we are proposing if that is flexible. I.e. Someone else can propose a different protocol to SPSP and simply use different request headers to indicate which protocol they are using (just like they would indicate which version of SPSP, e.g. Accept: application/spsp4+json).

To that end, I think using the .well-known syntax is a good idea but not .well-known/spsp. Let's register the .well-known URI pay or payee? So we end up with:

$justmoon.com -> https://justmoon.com/.well-known/pay
$bob.example.com -> https://bob.example.com/.well-known/pay
$example.com/bob -> https://example.com/.well-known/pay/bob

All requests to these endpoints should have an Accept header indicating the protocol they support. (We can also specify that where this is not provided SPSP is assumed)

We could also extend this standard in future to have pre-flight requests to that URL for protocol and version detection. (i.e. Using an OPTIONS request instead of a GET)

By the way there is also an interesting protocol called POSH which may be a good way to have hosted SPSP endpoints for custom domains but on a single host (where the host doesn't have to deploy certs for each domain): https://tools.ietf.org/html/rfc7711

[sharafian]

I also think it's useful to require the Accept: application/spsp+json header for all requests because the pointer $ is really powerful and I expect we'll have more success at getting it standardized as we are proposing if that is flexible. I.e. Someone else can propose a different protocol to SPSP and simply use different request headers to indicate which protocol they are using (just like they would indicate which version of SPSP, e.g. Accept: application/spsp4+json).

To that end, I think using the .well-known syntax is a good idea but not .well-known/spsp. Let's register the .well-known URI pay or payee?

This all sounds good to me. I like the idea of just having the SPSP receiver software change for version updates, without the resolution logic changing at all.

I think it's problematic to have different behaviour specified for the endpoint depending on whether there is a path or not. We should keep this as simple as possible.

I disagree here. I'd just explain it by saying "The default path is /.well-known/pay". I think putting a dynamic path like a username or an invoice ID under .well-known is a little weird because usually URLs under .well-known are defined in some standard.

[adrianhopebailie]

I think putting a dynamic path like a username or an invoice ID under .well-known is a little weird because usually URLs under .well-known are defined in some standard.

This would still follow the standard, note that the .well-known url still has /pay even if there is a path in the pointer. But I agree that giving hosts the option of hosting under a different URL is a good idea.

I'll try and capture this in a new IL-RFC but I think the protocol is basically this:

The ABNF definition of a payment pointer is:

  payment-pointer = "$" authority path-abempty

authority and path-abempty are defined in https://tools.ietf.org/html/rfc7230#section-2.7.2

If path-abempty is empty then it is assigned the value /.well-known/pay

A payment setup service MUST be accessible at the URL: "https:" "//" authority path-abempty

=====================

Side note:

One of the features of .well-known addresses is that unsolicited requests to the URL should be expected and most .well-known services return meta-data about the host.

So the question is, what should I expect to find at https://<popular-domain>/.well-known/pay where <popular-domain> could be gmail.com, paypal.com, microsoft.com etc.

Maybe something to add in time.

[michielbdejong]

In 2017 I would have said "don't just change stuff around", but my new approach it to embrace whatever experiments people in the Interledger community want to conduct, so I'll make sure the Interledger testnet supports these new ideas, and see if I can write a tutorial that uses your new format! :) Just:

1. clarify whether the meaning of payment pointers like $example.com/alice is the one from line 64 (https://example.com/spsp/alice) or the one from line 185 (https://spsp.example.com/alice), and whether $alice.example.com is allowed as an alternative format or not.

2. Consider removing ledger_info, or if not, at least also change it to asset_* on lines 94 and 95.

[michielbdejong]

reciever

[michielbdejong]

just one chunk? maybe say 'the first payment chunk'?

[michielbdejong]

attached how?

[emschwartz]

It's not really "attached" anymore since those fields are just in the packet

[michielbdejong]

maybe mention that it used PSK2 to derive the fulfillment from the prepare and/or its memory of the shared secret it gave out?

[michielbdejong]

information about the receiver or receiver's invoice

[michielbdejong]

"MAY NOT" is not defined by https://www.ietf.org/rfc/rfc2119.txt, do you mean 'MAY' as in 'presence and absence are both allowed', or 'SHOULD NOT' as in 'only absence is allowed, unless you have a good reason to override this'?

[sharafian]

fixed, I meant MUST NOT

[michielbdejong]

Maybe explicitly explain that, since dots are not allowed in the path after /spsp/, $michiel.ilp.michielbdejong.com translates to https://ilp.michielbdejong.com/spsp/michiel and never to https://michielbdejong.com/spsp/michiel.ilp.

[sharafian]

Actually $michiel.ilp.michielbdejong.com now becomes https://michiel.ilp.michielbdejong.com/.well-known/pay, while $michielbdejong/spsp/michiel.ilp becomes https://michielbdejong/spsp/michiel.ilp.

[michielbdejong]

Why the rename from currency_{code,scale} to asset_{code,scale}? Did the meaning stay the same?

I think these fields should now be optional, if defined at all. In PSK2, there no longer is a concept of destination ledger unit pegging (currency_code/currency_scale), because there are no more curves in route broadcasts, right? Destination ledger units are now only relevant for expressing the percentage of an invoice that is paid by one chunk. Also, they were already a problem because they allow the receiver to manipulate them, and pretend to be a cheap shop on an expensive network.

[sharafian]

Those fields are now optional, and I've renamed from ledger_info to asset_info. I see your point about manipulation by the receiver, but I'm not seeing it as an attack vector unless the sender doesn't check the source amount at all. It could make the network as a whole look bad, but that will always be a problem when you quote by destination amounts because the receiver could always put their receiver after a highly expensive connector which they control.

[michielbdejong]

Let's remove these.

[sharafian]

I think it's still useful to have these optional available to wallet software. They're still optional, though.

[michielbdejong]

Let's remove ledger_info

[michielbdejong]

The payment pointer is in the form $example.com/bob (A payment pointer with no path is also acceptable, i.e. $bob.example.com). This is converted into an SPSP URI, by removing the $ and replacing it with https://spsp.

contradicts:

$alice.example.com or $example.com/bob. This SHOULD be the only kind of SPSP identifier exposed to users.
+- Raw endpoint URI (Not recommended) https://example.com/spsp/alice.

on line 64.

[emschwartz]

I think this hasn't been updated with the result of the conversation between Ben and Adrian in the conversation tab above

[emschwartz]

Typos

[emschwartz]

Why can't the spsp uri contain query parameters?

[sharafian]

It seems like a strange way to use the identifier. Visually, keeping special characters down is nice for readability. Forbidding reserved characters also lets people pass around payment-pointers like https://wallet.example.com/?receiver=$bob.example.com without worrying about escaping. It also creates some more complexity in how we resolve the identifier by adding more moving parts. Does $example.com?foo=bar resolve to https://example.com/.well-known/pay?foo=bar or https://example.com/?foo=bar? It would also preclude us from adding any query parameters as part of the resolution protocol, if we did that sometime in the future.

I don't think any of those are super strong reasons, but I also don't think the benefit is worth it.

[emschwartz]

Specify that it's the destination amount

[emschwartz]

It seems a bit strange that the resolution behavior depends on whether there's a path. Is there a reason not to do something like webfinger where you query the endpoint with the whole identifier?

[sharafian]

yeah, that makes it very difficult to have one identifier that redirects to another. For example if my SPSP receiver is hosted on $sharafian.example.com and I set $sharafian.com to redirect there, then example.com will end up with the request https://sharafian.example.com/.well-known/pay?resource=$sharafian.com, which it won't know what to do with. This was a constant annoyance when we were using webfinger and ILP kit, so I'd be happy if we don't have to re-introduce it.

Having a default path isn't very hard behavior to implement, and I think it isn't so strange to say you use a hard-coded default unless there's a specific path specified in the identifier.

[dappelt]

reciever -> receiver

[dappelt]

MUST NOT have any authentication info

It is unclear what "authentication info" is referring to. Assuming you mean the user:pass@host notation, better stick to the terminology established in RFC 3986 and insert a link. The updated text should say something like: [...] MUST NOT have any user information [...]

[dappelt]

Say explicitly that any payment pointer that does not comply with the restrictions listed in this paragraph MUST NOT be translated to an URL.

If implementations translate invalid payment pointers into URLs it will be spoofer's paradise.

[dappelt]

Adding this subdomain allows [...]

It is not clear to what "this subdomain" refers.

[sharafian]

I believe all comments are addressed. Can we try to get this merged?

[adrianhopebailie]

@sharafian maybe the Appendix about Payment Pointers can be dropped and replaced with a link to the Payment Pointers spec?

[sharafian]

I think you're looking at an old commit; both of those things are gone now

[michielbdejong]

This is now out of date, because PSK2 has been superseded by ILP/STREAM, right?

[sharafian]

Well it reflects the current implementation so I don't know if I'd call it outdated, but you're right that ILP/STREAM will cause another change to this

[michielbdejong]

if it describes the current reference implementation, then i think we should just merge it, and maybe move the requested changes to follow-up tickets where necessary?

[adrianhopebailie]

@justmoon @emschwartz @dappelt

This is blocked on your reviews. Please review again so we can merge

[sharafian]

@justmoon @emschwartz speak now or forever hold your peace

out of date