joakim / iota-uri-scheme Goto Github PK

The tag param is currently specified in the grammar as being a regular UTF-8 percent-encoded query parameter of any length.

tag-param = "tag=" *qchar

Yet in IOTA's reference libraries, a tag is a tryte-encoded string of max 27 trytes (eg. iota.lib.js).

The message doesn't have a maximum length (if longer than 2187 trytes, it will be fragmented and stored across multiple transactions in the bundle), so it can safely be a regular UTF-8 string of any length, later to be percent-decoded and tryte-encoded by the wallet.

But the tag's maximum length makes things more complicated, especially with percent-encoded UTF-8 characters. How to specify the max length then, so that it corresponds to 27 trytes?

I see two options…

1. Require that the tag is represented as UTF-8, but once percent-decoded and tryte-encoded, must be maximum 27 trytes.
   
   This complicates creating URIs with tags somewhat, as the length of the raw (not percent-encoded) tag should be checked before percent-encoding (16 bytes = 27 trytes) to avoid it being truncated.
   
   It also complicates using a tag that is intended to be consumed as trytes (eg. FOO is a valid tryte tag, but if provided as FOO in UTF-8, it will get tryte-encoded into PBYBYB when added to the transaction – not what one might expect).

2. Require that the tag must be specified as 27 trytes.
   
   This means that one can't write URIs by hand with tags in UTF-8 (eg. This is a tag), it must first be tryte-encoded (into CCWCXCGDEAXCGDEAPCEAHDPCVC), and the tag's plain-text value will be obfuscated.

Any other options? Ideas? Feedback?

Currently the spec requires the value to be specified in IOTAs (i). Would it be better to (also?) allow Ki, Mi, Gi, Ti and Pi units? If so, I suggest only integers, no decimal values (for clarity).

Examples (yes, they're all the same value):

iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?value=1000000
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?value=1000Ki
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?value=1Mi

Then there's the question of how apps should handle the value. Should one expect the it to use the same unit as specified in the URI? Or do as the spec currently states, use the most commonly used unit, alternatively the most logical interpretation of the value?

As an example, take 999900i. Should the client display 0.9999Mi assuming Mi is the most common unit? 999.9Ki?

I think it might be best to keep the wording in the spec and let the developers/designers decide:

IOTA clients MAY display the value in any format that is not intended to deceive the user.
IOTA clients SHOULD choose a format that is foremost least confusing, and only after that the format that is most reasonable given the value specified.

Background: IOTA uses Winternitz one-time signature (W-OTS), making address reuse problematic.

Due to its one-time nature, the security of funds in an address decreases rapidly if you sign multiple transactions using the same key. Therefore, in IOTA you never re-use an address that has been spent from (as one signature has already been shared w with the network).

This, obviously, has big implications for the iota: URI scheme, as it greatly limits its utility. For example, donation links are not possible (well, it is, but with increasing risk of losing funds for each withdrawal). The only acceptable use case is for requesting a one-time transfer, and that sucks.

This must be fixed for IOTA to become a viable micropayment solution (for human beings). Turns out Eric Hop has just proposed a clever way of solving this, using iota: deep links, aliases and cheques.

• IOTΛlias, a wallet protocol for implementing public and private aliases
• IOTA cheques: sending iotas anywhere without requiring a receive address

I think this is a very interesting proposal and I really hope it gains traction within the IOTA community!

For now I only have a few pieces of constructive feedback, and that is of course on the URI scheme :)

The URIs in the examples don't adhere to RFC 3986, in that they use double slashes (iota://), which is only reserved for URIs referencing an "authority" (ie. a server/host). More correct would be a URN style URI, like spotify: or gtalk:, as we're referencing something, not giving directions.

It would be possible to use / in the path component to differentiate between the different types of deep links proposed (alias, cheque, donate, receive, invite, chat), but that looks too much like a REST API or a filesystem path to me, and I suspect it just naturally followed from the double slashes.

How about something more URN like instead?

iota:donate:www.mywebsite.com.xdv9tlqa?value=1000
iota:chat:jimihendrix?message=Hey%20Joe!

Another thing I noticed is the use of query params like order=3432.8995.67&article=Kindle%20Fire or cheque=hsoyytrbkd&from=John%20Doe&reason=Birthday%20gift. All the possible special cases that could arise would be difficult to handle for wallet apps. Although my proposed scheme spec does support custom params like that, you can't guarantee widespread support among wallet apps unless the params were standardized. Wouldn't it be better to simply use the ?message= param (#1) and URL encode whatever it is you need to attach to the transfer? The message could even be structured data in whatever format you prefer. The wallet app would URL decode the query params anyway upon receiving the link.

Finally, I'm a bit confused with all the different types of deep links (what's the difference between alias, donate, request, receive?). I think I have to look closer at these later. Being a believer in simplicity, maybe it's possible to simplify some of them..?

Overall, I'm impressed and very positive to IOTΛlias! I'd be happy to modify this proposal to better fit its requirements, as I think the solution it provides is essential for iota: links to be useful. Alternatively, others are always welcome to fork my proposal and take it from there (it's CC licensed, so it's up for grabs).

runplay/run-wallet-android#6

Just to clarify why I believe iota: is the correct choice for this URI scheme.

From RFC 7595 (URI Scheme Guidelines), section 3.2:

   Schemes SHOULD avoid improper use of "//".  The use of double slashes
   in the first part of a URI is not a stylistic indicator that what
   follows is a URI: double slashes are intended for use ONLY when the
   syntax of the <scheme-specific-part> contains a hierarchical
   structure.  In URIs from such schemes, the use of double slashes
   indicates that what follows is the top hierarchical element for a
   naming authority (Section 3.2 of RFC 3986 has more details).  Schemes
   that do not contain a conformant hierarchical structure in their
   <scheme-specific-part> SHOULD NOT use double slashes following the
   "<scheme>:" string.

See also the discussion in #5 and discussions in the #trinity channel on Discord.

There are only two hard things in Computer Science: cache invalidation and naming things.

What should be the name of the query parameter specifying how many iotas to transfer?

When writing this proposal, I went with IOTA's own term, value. I've since come to think that maybe amount is a more user friendly term. So, what should it be?

Value

Monetary or material worth. An amount, as of goods, services, or money, considered to be a fair and suitable equivalent for something else; a fair price or return.

• The term used in IOTA itself
• Also used by various websites and services in the IOTA ecosystem, e.g. TheTangle.org

Amount

A number; a sum. The total of two or more quantities; the aggregate.

• The term used by most (almost all?) wallets
• Also used elsewhere in the context of transactions, for example by PayPal

My input:

• value reflects IOTA's own internal naming, and is a more technical term ("the transaction's value")
• amount is often used in UI, and is a more user-friendly term ("sending X amount of iotas")

So what it comes down to is whether to use a technical term or a user-friendly term. Whether to map to IOTA's internal name for it, or to map to the term users see in their wallet apps.

If IOTA users only see "Amount" and maybe never encounter the technical term value, they might expect the URI scheme to accept iota:<address>?amount=<amount>, which if it didn't would result in the value/amount being ignored by the app. There are way more end users than there are devs, so I think amount is what will cause the least trouble/side-effects.

Naming is hard. Thank goodness there's no cache invalidation to worry about :)

Besides the optional tag, IOTA also supports adding a message to a transfer.

I left this out the URI scheme proposal simply because the official IOTA wallet app doesn't have a message field. I haven't used many other wallet apps, but if it turns out others do support messages, adding it to the URI scheme should be considered.

However, what if a user clicks on an iota: link with ?message= and their IOTA client doesn't have a message field. Is it OK to silently ignore the provided message?

What the title says… not all apps have fields for message and/or tag.

How should an app handle these URIs if it has no fields for entering tags or messages:
iota:MZLFXAZOHO…?tag=important
iota:MZLFXAZOHO…?message=Very%20important%20information

1. Ignore the tag/message?
2. Silently include the tag/message in the transaction, without the user knowing it?

Tough one.

How could the spec prevent this?

Requiring that apps must be able to display tags and messages if provided by the URI is a tall order. It adds extra code and complicates UI, but is the only way to guarantee that the information is not lost or hidden from the user.

A more dev friendly option would be to offer a way out by saying it SHOULD show the tag and message, but if it can't, it MUST inform the user that the message/tag was dropped. That way, at least the user doesn't send information in a transaction without being aware of it.