XLS-2d Standard for XRPL destination information

[WietseWind]

Currently several apps are using a variety of methods to encode destination information;

• rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY?dt=123
• rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY:123
• Deprecated Ripple URI syntax: https://ripple.com//send?to=rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY&amount=30&dt=123

I feel the best way to implement this, is by allowing Apps to register Deep Links (URI handlers) while keeping the destinations backwards compatible with Web browsers, so users without any app to handle a URI can display a page by the app creator with an instruction.

I propose to allow any URL prefix, with a default set of GET URL params, supporting the existing params proposed in the (deprecated) Ripple URI standard;

so:

{ any URL } ? { params }

Where params may all be optional except for the account address:

• to (account address, rXXXX..)
• dt (destination tag, uint32)
• amount (float, default currency: XRP (1000000 drops))
• ...

So App 1 may use:
https://someapp.com/sendXrp?to=...

... While App 2 uses:
https://anotherapp.net/deposit-xrp?to=...&dt=1234&amount=10

[N3TC4T]

Do we need to add currency as well ?
It's good for supporting IOU's like Gatehub:EUR

[WietseWind]

@N3TC4T I'd say a &currency= field, indeed, with:
issuer:currency value, eg.
rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B:USD (Bitstamp USD)

[RichardAH]

To be backward compatible with simple QR implementations that put just the "to" address into a QR code and nothing else we should allow the first parameter to optionally be missing a key.

We should come up with a reference implementation of a URI parser and a test set of URIs to go with it. Since I'm updating this part of Toast right now I'll post a draft of this shortly

[RichardAH]

function xls2d(uri) {

	const cleaned_uri = uri.replace(/^(.*:.*)?\?/mg, "").replace(/\?/img, "&").replace(/^ripple:/img, "")

	function clean() {
		return cleaned_uri
	}

	function to() {
		//NB: this regex is case sensitive to assist in correctly matching XRP ledger addresses
		var match =  /(?:(?:^|&)(?:to|TO|tO|To)=|^)([rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz]{25,55})/mg.exec(cleaned_uri)
		return (match == null ? false : match[1])
	}

	function dt() {
		var match = /(?:^|&)dt=([0-9]+)|:([0-9]+)$/img.exec(cleaned_uri)
		if (match != null) return (match[1] ? match[1] : match[2])
		return false
	}

	function amount() {
		var match = /(?:^|&)am(?:oun)?t=([0-9\.]+)/img.exec(cleaned_uri)
		return (match == null ? false : match[1])
	}

	function currency() {
		var match = /(?:^|&)cur(?:rency)?=(?:([rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz]{25,55}):)?([A-Z]{3}|[A-Fa-f]{40})/img.exec(cleaned_uri)
		return (match == null ? false : { issuer: ( match[1] ? match[1] : false ), currency: match[2] } )
	}


	function invoiceid() {
		var match = /(?:^|&)inv(?:oice)?(?:id)?=([a-f]{64})/img.exec(cleaned_uri)
		return (match == null ? false : match[1])
	}


	return {
		uri: uri,
		clean: clean(),
		to: to(),
		dt: dt(),
		amount: amount(),
		currency: currency(),
		invoiceid: invoiceid()
	}
}

var examples = [
	"rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY?dt=123",
	"rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY:123",
	"https://ripple.com//send?to=rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY&amount=30&dt=123",
	"https://sub.domain.site.edu.au//send?to=rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY&amount=30&dt=123",
	"https://someapp.com/sendXrp?to=rRippleBlah&dt=4&invoiceid=abcdef",
	"deposit-xrp?to=blah",
	"?rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY:123",
	"rAhDr1qUEG4gHXt6m6zyRE4oogDDWmYvcgotCqyyEpArk8",
	"to=rAhDr1qUEG4gHXt6m6zyRE4oogDDWmXFdzQdZdH9SJzcNJ",
	"to=rAhDr1qUEG4gHXt6m6zyRE4oogDDWmXFdzQdZdH9SJzcNJ&currency=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B:USD",
	"to=rAhDr1qUEG4gHXt6m6zyRE4oogDDWmXFdzQdZdH9SJzcNJ&currency=USD",
	"to=rAhDr1qUEG4gHXt6m6zyRE4oogDDWmXFdzQdZdH9SJzcNJ&currency=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B:USD&invid=DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF",
	"scheme://uri/folders?rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY:123",
	"scheme://uri/folders?rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY&amount=4:123" // this one a bit iffy
]

for (var i in examples) console.log(xls2d(examples[i]));

Thoughts appreciated on the code above as draft reference implementation

[RichardAH]

Code is here https://github.com/xrp-community/standards-drafts/blob/master/xls-2d/xls-2d-reference.js

[RichardAH]

I added this into Toast 2.5.8 with one exception: URIs starting with xrpl:// don't require the ? so for example: xrpl://to=rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY&dt=123

[trueIoV]

Hi!
What if i need to add a set of memo?

[gazoscalvertos]

+1 for the memos, there is real value in this field if supported correctly.

[nbougalis]

Please also see #6 which has some overlap with this PR.

[RichardAH]

Modified the above to support ripple:rAddress legacy uris

[RichardAH]

XLS-2d is now a legacy standard for parsing old addresses and uris. New implementations should use XLS-5d. https://github.com/xrp-community/standards-drafts/tree/master/xls-5d

XLS-2d code updates will be here https://github.com/xrp-community/standards-drafts/tree/master/xls-2d