[Feature] Allow path finding payments (Sign Requests)

[WietseWind]

In retail environments, the store/shop/... wants to receive a fixed asset and amount. The consumer should be able to select what they want to pay with.

Offering this feature to the end user must be an optional param, as the recipient must explicitly be OK with these kinds of payments because the burden of verifying the outcome is on them.

Proposal:

1. A payload option: options.pathfinding, default false, can be true
2. This option is only valid for Payment transaction types, and otherwise can be ignored (and will always be false).
3. The payload must not specify a difference between sending and receiving: no Max, DeliverMin, etc.: just the Amount in XRP or issued asset notation, which is then used as the amount to deliver (path finding)
4. If the payload has the pathfinding option on true, the Sign Request must use the path_find command to find payment options based on the Payload Destination & Amount
5. The payment options are to be presented to the end user, only when one is selected the Slide to Send button is available.
6. The payment options have a 45 (?) second time out after which they are gone and users can opt in to find new paths.
7. The pathfinding state must be reset & rerun on source account change.

Warning on path finding (!)

There are two methods, ripple_path_find (old) and path_find (new). The old one is a one off command that returns when all path finding is finished. The new one is a (much more efficient) subscription.

We must use the path_find command, the subscription one. This means that:

1. Results come in and get updated async
2. As updates come in async, we must make sure that the presented list of options does not jump all over the place. They must be updated 'in place', and appended if new source currencies are found.
3. When we're done finding paths (e.g. timeout, or: user selected something, or: user closes screen) we must cancel the path finding subscription: https://xrpl.org/path_find.html#path_find-close

To consider: 1:1 payments (no converting path needed, e.g. GH EUR<>GH EUR, XRP<>XRP)

To prevent the user from spending extra time waiting for payment options when they own the asset requested by the counterparty, if this applies, the counterparty assets must be offered immediately as payment option.

• If the shop e.g. wants to receive 5 Gatehub EUR
• And the end user owns 5+ Gatehub EUR
• So: the user can immediately pay in the requested currency
• Then: don't offer pathfinding by default: first show the 1:1 option (5 GH eur to 5 GH eur) as if that path is already found
• Then: below that, show the "Find new payment options" but call it "Find other payment options" and then run pathfinding.
• Finally: merge the pathfinding options with the "faux" 1:1 payment option, show the 1:1 option on top.

Screens

1. Initially: path finding starts

   

2. If no paths are found with in e.g. 30 seconds (await response) - a user can retry with the btn

   

3. If paths are found, they are presented to the user. There is no default selection. When one is selected, the slide to send button is available. The path returned by the path_find command is then used in the signed payment. Also take "To consider: 1:1 payments (no converting path needed)" into account.

   

4. Found paths, even if selected, time out. Rates can change. Users can find new paths.

   

Impact

• [x] Backend / data model @WietseWind
• [x] API + API Documentation @WietseWind
• [x] SDKs @WietseWind
• [ ] App @N3TC4T

Involved

@KoenPaas @DominiqueBlomsma

[WietseWind]

Forget about payment options expired: with pathfinding as a subscription they will be updated in place 😎

[WietseWind]

• [x] Backend POST (options: pathfinding: Boolean / Number / String[true|false])
• [x] Backend GET (meta.pathfinding: Boolean)
• [x] Backend: only allow pathfinding option for Payments
• [x] SDK Types (1.3.5)