0002 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/XRPLF/XRPL-Standards/tree/master/XLS-0005-tagged-addresses#readme

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

[WietseWind]

Note: embedded in Code section:
https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-2d

[rsteimen]

For an easier integration and broader acceptance we should try to align with BIP-0021 (Bitcoin) and EIP-681 (Ethereum). Further for accounting systems, we should implement a creditor reference (ISO 11649). An issuer of a bill can append a creditor reference which (when used in payment) allows to match issued bill with received payment.

Syntax propose
xrpl:address[?tag=tag][?amt=amount][?isc=issuerAddressOfCurrency][?ccy=currencyCode][?ref=creditorReference][?msg=message]

xrpl: network, static xrpl
address: target wallet
tag: target wallet tag (optional)
amt: amount in specified currency (optional)
isc: issuer wallet of expected currency (optional, obligatory when using ccy or ccy is not xrp, xrp if omitted)
ccy: currency code of expected currency issued by isc (optional, obligatory when using isc, xrp if omitted)
ref: unformatted creditor reference as described in ISO 11649 (optional)
msg: http url encoded freetext as memo (optional)

Examples
Send 0.1234 XRP to rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?amt=0.1234
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?amt=0.1234&ccy=xrp

Send 0.1234 XRP to rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL (Bitstamp) with tag 112233
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?tag=112233&0.1234

Send 0.1234 XRP to rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL using creditor reference
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?amt=0.1234&ref=RF18000000000539007547034

Send 0.1234 XRP to rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL using creditor reference and message
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?amt=0.1234&ref=RF18000000000539007547034&msg=Order%202021-02-26%2C%20ABC-123456

Send 10.1234 USD to rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL
xrpl:rdcFHYneRoYFie7vpRR2TFYCHdokkQCoL?amt=10.1234&isc=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B&ccy=usd

[WietseWind]

Good idea to turn this in a stricter standard. Parsing that + backwards compatibility with old formats is another thing. Maybe we can match existing common formats as much as possible, to prevent this from happening.

Regarding the creditor reference: I propose we use the existing InvoiceID field for that (?) as supported by Payment transactions:

[WietseWind]

Here's the parser supporting even more formats found 'in the wild' in XUMM:
https://github.com/XRPL-Labs/xumm-string-decode

Test cases for:
https://github.com/XRPL-Labs/xumm-string-decode/blob/master/test/XrplDestination.json

Like @rsteimen I feel that it makes sense to define a standard once and for all, eg. URI format, but I strongly prefer to keep that as close to the common used formats as possible, to prevent this from happening.

[rsteimen]

Thanks for clarification @WietseWind. I misinterpreted InvoiceID. The posted documentation already allows creditor references (ISO 11649) in InvoiceID.

All my shown examples are already represented in xls-2d-reference.js. I also agree with @wiese we should prevent creating "just another one". I like the idea that all values are represented as querystring parameters. It allows flexibility in different usecases.

For currencies I like @N3TC4T proposal. It ensures both issuer and currency are defined.