[Lip 10] Libra ID Spec

[andll]

Open questions

Libra ID separator

Contenders: @, # and $
“@”:
(-) Too easy to confuse with an email
“$”:
(+/-) Already used by Ripple’s Pay ID
(+/-) Can be seen as an affiliation with USD. However, it is fairly common to use $ as a sign for “money”, rather than a specific currency, so this can also be a plus.
(+) Can be used unencoded in the URLs
“#”:
(-) If placed into URL strictly requires a URL encoding

Libra ID domain - single word or a domain name

Single word(e.g. andrey$novi):
(+) Fewer symbols to write
Domain name(e.g. andrey$novi.com):
(+) In the future if we allow unhosted wallets, we can switch to DNS lookups
(+) For the merchant use case, can create a merchant APP url using string manipulation

Profile picture sizes and image formats

We can put some limits on maximum file size and image resolution.

[andll]

cc @gdanezis @danprinz - can't assign you as reviewers, but please take a look
@danprinz Can you also cc more people from first to this LIP(don't know their github user names)

[kphfb]

Mostly just small nits. Will come back and review the meat of the protocol

[kphfb]

Suggested change

	* Sender Libra ID should have a Libra ID domain that belongs to Sender VASP. If receiver VASP makes a decision on how much information to share, based on the sender Libra ID, it should enforce this property and return 400 error code, if VASP tries to impersonate a user from Libra ID domain that it does not own.
	* Sender Libra ID must have a Libra ID domain that belongs to Sender VASP. If this is not the case, the Receiver VASP should return the `400` error code
	* Receiver VASP may optionally choose how much information to share based on the sender Libra ID. If Receiver VASP decides to not share data, it should return `400` error code.

[kphfb]

I edited it to split it out for how I believe you intended it to read, but I actually think that we shouldn't return the same error code for "i don't want to share information" that we do for "this person doesn't exist". In one of those cases, you can still choose to send money to them

[andll]

Tried to rephrase it. I think if VASP don't want to share info, but user exists, they can just return empty user object(e.g. not sharing any fields). Otherwise return error

[kphfb]

Do you think these are needed? For example, what if a VASP pre-fetches this info before their user has filled out the payment amounts?

[andll]

For prefetching, VASP should use info endpoint, this is payment endpoint, so I think currency / amount is needed

[kphfb]

Hmmm, as I look at it more, I do wonder if we actually need two endpoints. It feels like this is really just one endpoint that has a flag for if you want a reference ID or not. Otherwise, they are effectively the same thing

[andll]

To me two separate endpoints makes more sense. Yes they share some fields (like there is sender/receiver), but there are also many fields that are not shared (info endpoint don't have amounts/coin in request, and does not return reference/account address)
They also have different semantics - info endpoint is 'read' endpoint, while 'pay' is a 'write' endpoint as it needs to create an entry in the database

[davidiw]

This is an open write API, this is dangerous. Folks will mess this up and have vulnerabilities.

[kphfb]

Need to specify for this and all fields more info about them. Is this bech32?

[andll]

cc @bmaurer

[bmaurer]

It might make sense to break out standards for APIs into its own LIP. This is lacking a bit of specificity.

[bmaurer]

May make sense to discuss privacy implications (e.g., if you just hot link to another VASP that VASP can track how often the profile pic is accessed). Generally at least for FB we have it as a best practice that you always proxy this type of access.

[longbowlu]

@bmaurer can you explain the hot links and how FB proxies it?

[davidiw]

I think this is an implementation detail that someone can easily screw up as long as the URL returns an image we are good to go.

[bmaurer]

MUST NOT? (this happens a lot through this document... not going to audit each instance. I think it's worth doing a pass to audit the use of MUST/SHOULD/MAY)

[bmaurer]

At a higher level: it feels like we have a lot of overlap with the off-chain protocol / subaddresses. For example:

• If you have a subaddress you can use the off-chain protocol to get a reference ID from the subaddress (and submit travel rule info)
• If you have a libra ID, you first get a reference ID, then use the off-chain protocol with the reference ID to submit more information.

I worry that we start to get complexity from different permutations of these APIs.

Is there anything we can do to be more uniform here? Both subaddresses and LibraID are a way to reference a user within a VASP. Why entirely different flows for the two methods?

It's OK if we have regrets about APIs we designed for subaddresses and want to go a different direction. But in that case, can we come up with a new API that is unifying vs one that only addresses a subset of the use cases.

[sblackshear]

• It's not clear from this why reusing an identifier generated from a LibraID is less likely/less problematic than reusing a subaddress
• I think this could be explained more clearly without the references to subaddresses. Perhaps you could have a separate bullet that says "A Libra ID is a persistent user identifier. By contrast, a subaddress is an ephemeral user identifier that should only be used in a single transaction"

[andll]

I changed wording there, let me know what you think

[sblackshear]

• Link to PayID doc or proposal?
• I think you should either do a more detailed compare/contrast with PayID or kill this section. As-is, this section might make it seem like we're vaguely aware of PayID but haven't really looked into it enough to motivate the need for or a new standard or crisply explain the key similarities/differences. For example: does PayID also support intra-chain payments (and if so, could we use it if we thought we might eventually want X-chain payments or didn't want to develop a new standard)?

[andll]

After some thought I removed PayID section from the doc. We spent some time researching it, however perhaps it is safer to just not discuss this as part of the LIP

[sblackshear]

Some motivation for this might be helpful (and could also justify the "not expected to be common" caveat)

[andll]

There is actually more details and motivation below when discussing on-chain format and restrictions there. I am going to remove this item and keep this section focused on high level overview of ID structure, to avoid duplication and confusion

[sblackshear]

This section feels more like an extension of "motivation" or a "use-cases" section than a section describing multiple accounts per user. For example, the temporary/situational ID idea is cool and not necessarily related to multiple accounts/user (e.g., publicly shared Libra ID for donations).

[andll]

So main motivation to this question is because some people might ask 'is libra id identifying a user, or specific account of the user". So this section is trying to clarify that. Do you think i need to add some clarification for it?

[sblackshear]

Once one VASP removes a LibraIdDomain, can another VASP use the same one? And if so, is a VASP allowed to sell a LibraIdDomain to another VASP?

Answering the the first question with "no" might help to avoid squatting.

[andll]

I think since LA is allocating those 'domains' to the VASPs, there is no really problem with squatting, similarly all the questions about what happens to removed domain, etc, can be resolved by LA when specific case is reviewed. Do you think we need to include this details here?

[sblackshear]

• The analogy with credit card number seems a bit odd because my credit card number is private info, but a LibraID sounds more like a public email address
• Does the owner of a LibraID authenticate themselves to the merchant somehow (and if not, are there potentially bad consequences)?

[andll]

• There is some analogy in a sense that you enter your cc number in order to get 'routed' to the bank
• I wanted to cover it in merchant flow doc, but tldr is - yes, you need login into wallet app / web site to use your libra ID

[danprinz]

When you enter your cc number, you don't get routed to the bank (issuer). It is used as an authorizing token of the payment. The first several digits are indeed the routing path, but we may use only the Libra ID domain for that purpose.

[sblackshear]

How will they make the decision not to share information?

[andll]

Added example inline

[sblackshear]

Does using compliance_public_key make sense here? We need it for for TR because the signature will be checked on-chain, but LibraID seems like it could use a more conventional authentication mechanism. Not my area of expertise at all, but maybe someone who knows a lot about web authentication could weigh in.

[andll]

Yeah, I think currently compliance_public_key is simply overloaded - it is used to both signing KYC metadata, and for signing the requests. However, this is how things are set in lip-1(main offchain lip), and this document just re-states it for clarity

[longbowlu]

At the first beginning, we wanted to use different keys for TLS/KYC and so on. Later we decided a single key for less maintenance cost. From this point of view, another "conventional authentication mechanism" seems to make things more complicated.

cc @kchalkias

[davidiw]

I don't follow, that compliance key is an ed25519 key for signing metadata that appears on chain. I don't know why we need a compliance key in this place that is strictly used for dual attestation. This is too overloaded and has no meaning in the rest of this document. Also if we add an IP for each address, what are we doing? Can we clarify the purpose of a wallet uri?

[danprinz]

When you enter your cc number, you don't get routed to the bank (issuer). It is used as an authorizing token of the payment. The first several digits are indeed the routing path, but we may use only the Libra ID domain for that purpose.

[danprinz]

I would suggest to follow the exist scheme of URI from the off-chain protocol (https://<hostname>:<port>/<protocol_version>/<LocalVASPAddress>/<RemoteVASPAddress>/<endpoint>) -
A. It makes the system more widely consistent
B. How should the receiving VASP authenticate/verify the requested content? It must get the other VASP info to get its public key, or is there something else that I'm missing?

[andll]

I think I agree with this, I will change URL to make it more uniform

[longbowlu]

FYI: we are actually discussing whether to remove the "LocalVASPAddress", "RemoteVASPAddress" from the URL format in lip-1

B. How should the receiving VASP authenticate/verify the requested content? It must get the other VASP info to get its public key, or is there something else that I'm missing?

In LIP-1 , it says

All transmitted requests/responses are signed by the sending party using the JWS Signature standard (with the Ed25519 / EdDSA ciphersuite, and compact encoding). The party's on-chain compliance key shall be used to sign these messages. This ensures all information and meta-data about payments is authenticated and cannot be repudiated.

cc @danprinz

[danprinz]

My question was regarding where in the request can one find the sending VASP address. It either be written in the request body, or as part of the path (like in LIP-1).
If the receiver has the address at hand it should be easy to verify the request content.

If LIP-1 is going to be changed to any other format (I would suggest a more RESTful one) we should keep this one as close and consistent as we can.

[kphfb]

Agree with this comment. Let's match LIP-1 and instead of command add a new action (query? get_libra_id? etc.)

[davidiw]

Let's update here

[danprinz]

I think that using OpenAPI (3) spec would be a more convenient way to describe the API and also could be used in a wide range of web frameworks

[longbowlu]

this looks different than format in LIP-1's.

[danprinz]

That's right. I just wondered if OpenAPI spec would be more readable and common to use. Maybe we should adapt it in LIP-1 as well

[davidiw]

Please update to LIP1 but why are we repeating this information?

[danprinz]

Why not sticking to HTTP standards and reply with 404?
400 should be a signal of a bad request, and I would argue that if the target user is not found doesn't mean an error or a bad request

[longbowlu]

Above and below, we say if VASP can choose not to share whether the Libra ID exists or not. Do we want to have a very clear answer format to remove the ambiguity?

[davidiw]

Yes and let's use 404.

[danprinz]

This is a "proper" off-chain command and should be treated as such. We should aim to have the reasoning behind the URI scheme. (see above)

[andll]

Are you talking about adding <LocalVASPAddress>/<RemoteVASPAddress> part (agree with that) or something else?

[danprinz]

both the <LocalVASPAddress>/<RemoteVASPAddress> part and the pay resource name.
In general, LIP-1 (and LIP-8 as its extension) uses a single resource URI (/command) as the main entry point to all off-chain communication.
We should either keep it as is (and adapt /command notation here) or change it across all LIPs to be a logical representation of resources and actions.
I also think that we should stick to the main principles of LIP-1 CommandRequestObject and CommandResponseObject as it makes things easier for developers to have a one consistent protocol scheme/format.

[andll]

We specifically chose not to use command request/response style here to keep it simpler

[longbowlu]

@gdanezis ^^

[kphfb]

I'd agree with @danprinz here. If we are going to treat this as an action, then it should be using the same command structure as is used in LIP-1 and LIP-8. That keeps us consistent and also means we don't need to re-state so much and make it seems sort of like LIP-1 but sort of its own thing

[longbowlu]

why regex and maximum length are different from user-id's ?

[andll]

Oh, I glad you asked :)
Wanted to make sure that total length is power of 2(128).

[davidiw]

for what purpose? what are we gaining by having limits? except maybe this should be limited due to being on chain.

[andll]

I think usually you want to have length limits on any data structures. For example, some VASPs are probably going to store Libra IDs in SQL database, and they might want to use some column type that have length limit

[longbowlu]

do we mean "user-id" here instead of "Libra ID"?

[longbowlu]

how is wallet_uri gonna be used, if it has more functionalities other than display?

[andll]

This is related for merchant, since right now we don't have LIP for merchant flow, I am just going to remove it

[longbowlu]

FYI: we are actually discussing whether to remove the "LocalVASPAddress", "RemoteVASPAddress" from the URL format in lip-1

B. How should the receiving VASP authenticate/verify the requested content? It must get the other VASP info to get its public key, or is there something else that I'm missing?

In LIP-1 , it says

All transmitted requests/responses are signed by the sending party using the JWS Signature standard (with the Ed25519 / EdDSA ciphersuite, and compact encoding). The party's on-chain compliance key shall be used to sign these messages. This ensures all information and meta-data about payments is authenticated and cannot be repudiated.

cc @danprinz

[longbowlu]

At the first beginning, we wanted to use different keys for TLS/KYC and so on. Later we decided a single key for less maintenance cost. From this point of view, another "conventional authentication mechanism" seems to make things more complicated.

cc @kchalkias

[longbowlu]

This is a big change:

1. if I understand it correctly, it means that we always need to call Libra ID endpoint before KYC (to get the reference ID) end point API. I'm afraid this introduces new issues. For example, what if receive does not recognizes the reference_id ?
2. even though we want to replace address/subaddress with Libra ID, can we just use libra ID in the KYC endpoint API to save round trips?
3. from compatibility's perspective, we should add the support for Libra ID/Reference ID first, and then gradually deprecate address/subaddress

[davidiw]

agreed, we would want to state there is an additional KYC API that supports this... alternatively I would recommend that the payment_reference_id be subaddress

[longbowlu]

Can we explicitly set a message for "not intended to share information", or "information unknown"? I think this helps clarify the results for sender, so they have better wordings to communicate to their users.

[davidiw]

I would strike "depending on it's privacy choices"

If a user does not exist or has enabled contact-list mode, the VASP may choose to return either an HTTP 404 error or an empty User Object.

[longbowlu]

@bmaurer can you explain the hot links and how FB proxies it?

[longbowlu]

When fetching this URI wallet app will not provide any authentication.

So basically it means VASPs want to expires URIs often.

[kphfb]

I think a lot of this and down makes it seem like this is separate but similar to LIP-1, but to me it makes more sense to state it as an extension of LIP-1 that adds new functionality (basically a query API and a new command in the normal API). Then you don't really need to re-state the things of LIP-1 which I think kind of add confusion since we only state some of the things

[davidiw]

if we could say that this is an extension of Lip1 and make it clear how it is, I think that would be a win.

[kphfb]

Agree with this comment. Let's match LIP-1 and instead of command add a new action (query? get_libra_id? etc.)

[kphfb]

I'd agree with @danprinz here. If we are going to treat this as an action, then it should be using the same command structure as is used in LIP-1 and LIP-8. That keeps us consistent and also means we don't need to re-state so much and make it seems sort of like LIP-1 but sort of its own thing

[davidiw]

Lots of comments.... overall the story does make sense, here are my major blockers before moving this to draft:

1. Clean up the writing and make it tighter -- most of my feedback is in this category -- in general, I might recommend that we avoid crappy editor frameworks like GitHub and consider a first draft in a shared editor but let's save that battle for another day :D
2. The user story should be near the top of this document and tie together the two properties provided: easy use and anonymity on chain
3. The document is not particularly searchable the profile_picture_uri is only contained once, you should reuse the exact format in the section that describes it so that idiots like me can easily search for it
4. diminutives / abbreviations should not be in technical documents examples: txn and app
5. Unify the URL scheme with Lip-1
6. Each portion of the Lip should be very clear -- what is the wallet_uri, why are we discussing the compliance endpoint and key, what is the specific use case of each endpoint
7. Having a writable endpoint is a no go for me, I won't block on this principle but there are really great techniques to support time valid identifiers that require a zero write API -- for example get_reference_id(user_id, txn_metadata) -> hash(secret_receiver, user_id, txn_metadata)
8. Would recommend considering how to make the payment reference id compatible with a subaddress otherwise we're going to have confusing APIs or alternatively define a scheme that makes it clear that one is a libra id and the other is a subaddress

Feel free to setup some time with me if that would help.

[davidiw]

redundant with the first point

[davidiw]

I don't think this is technically correct, I could derive distinct subaddresses for each individual.

[andll]

This is not always true.
Example is this - you and friends went to restaurant and you paid for everyone. Now you have a group chat in <messenger of your choice> and want to share your Libra wallet address so that they can pay you back.

There is no convenient way to share lip-5 address so that participants can only send money, but not track payments from others. Of course in theory you can create subaddress for each, but this is not practical

[davidiw]

The following structure is a bit too much of us versus them. Instead I think it would be more influential to state the goal of the Libra ID framework, which seems to be:

• human-readable helping individuals recognize and remember it just as easily as an email address or a social networking handle
• built-in anonymization of on-chain metadata

And stating it like this makes it very easy to parse out the value. You can then have a related works section if you really want to make comparison to other technologies / solutions within the Libra tech space.

[davidiw]

would just merge the line 14 to state that this describes human-readable identifier for user accounts and the off-chain protocol for peer-2-peer payments with this identifier.

[davidiw]

agreed, we would want to state there is an additional KYC API that supports this... alternatively I would recommend that the payment_reference_id be subaddress

[davidiw]

rewrite are information, that is they are intended for UI purposes only and explicitly not establishing KYC.

[davidiw]

I would strike "depending on it's privacy choices"

If a user does not exist or has enabled contact-list mode, the VASP may choose to return either an HTTP 404 error or an empty User Object.

[davidiw]

I think this is an implementation detail that someone can easily screw up as long as the URL returns an image we are good to go.

[davidiw]

not required.

[andll]

Having a writable endpoint is a no go for me, I won't block on this principle but there are really great techniques to support time valid identifiers that require a zero write API -- for example get_reference_id(user_id, txn_metadata) -> hash(secret_receiver, user_id, txn_metadata)

I am not sure I understand, how does generating reference id with libra id different comparing to generating reference ID during KYC? Are you saying it is bad in both cases, or there is something special about libra id, that does not make it work here, but it works for KYC?

Would recommend considering how to make the payment reference id compatible with a subaddress otherwise we're going to have confusing APIs or alternatively define a scheme that makes it clear that one is a libra id and the other is a subaddress

There is a hope that with Libra ID we can actually deprecate subaddresses altogether, given their privacy implications.

[davidiw]

welcome to the club

Let's continue to tighten this up in ensuing copies:

• clearer story around building an indexer / move events
• how this works with lip 1
• general massaging with flow as we go