Ren UX Best Practice

This section will outline the best practices and things to keep in mind when integrating RenVM via RenJS.

The docs are in the process of being moved.

The latest version of this page can be found here: https://renproject.github.io/ren-client-docs/ren-js/best-practices/ui-best-practices

Cross-chain transactions are a new experience for users of decentralized protocols therefore there is not a lot of precedent for the ideal User Experience (UX). Below is a set of guidelines aiming to increase the usability of a third-party application that chooses to integrate Ren’s native cross-chain experience, utilizing the RenJS JavaScript framework.

Top 10 UX Considerations

1) Explicit Warnings | Loss of Funds

We strongly suggest putting in a checkbox via opt-in - regarding loss of funds if a user makes a mistake.

It should be clear that if the user makes a mistake (sends funds to the wrong address, deposits multiple TXs, etc.) that their funds are permanently lost (as with any other blockchain mistake).

It's very important to set the expectations upfront, as the Ren team will not be able to assist with loss of funds.

2) Explicit Disclosures | Ren is new technology and that users should not send funds they can’t afford to lose

While after four security audits and years of testing... given the nature of blockchains, there is always a chance things can go wrong. It's obligatory that you warn users.

Your dApps front-end should state clearly that there are risks. Example: “Ren is new technology and security audits don't completely eliminate risks. Please don’t supply assets you can’t afford to lose.”

3) A Gateway Address is only valid for 24 hours

Ren generates “Gateway Addresses”. Users transfer assets to the gateway address on one blockchain, and Ren mints a tokenized representation of those assets on another blockchain.

For example, if I was sending BTC to Ethereum, Ren would generate a unique BTC public key that integrations would show on their front end. A user would then transfer an amount of BTC to this address and Ren would in turn mint renBTC on Ethereum (an ERC20).

These addresses are only valid for 24 hours. Your front-end should indicate this to the user to avoid them generating a Gateway Address and returning more than 24 hours later to deposit assets to it. If they deposit assets to an old Gateway Address the funds will be lose.

4) A Gateway Address can only be used once

Gateway Addresses should only be used to deposit funds one-time. Your front-end should alert users to only deposit to a Gateway Address once. If users want to make multiple deposits, they should wait until the first is complete.

If a user send multiple deposits to an Gateway Address the funds will be lost.

5) Storing Orders

As transactions move from one blockchain to another, the individual order needs to be stored and retrieved incase a user closes their web browser, clears cache & cookies, etc. Ren does not inherently store this information, so each integrators needs to implement a storage solution.

It can be stored in the web browser, be persistent storage via a decentralized (3box) or centralized (Firebase) solution, but one must be chosen and then conveyed to users, so they know how to retrieve the information.

Example: An integrator made persistent storage optional but didn't properly warn the user what would happen if they refreshed without storage enabled.

In general, the best UX is that storage is always enabled and mint details are stored before showing a deposit address to users.

6) Minimum Order Amounts & Fees

There are a few fees that need to be considered when using Ren. Example (BTC to Ethereum) : Bitcoin Miner Fee Ethereum Miner Fee Ren Fee As you can imagine these add up, making small transactions not worth it. Its recommended there is typically a 50$ USD minimum (depending on networks congestion), so you should make sure users are aware of this.

If users send less than the total fees, funds are lost. This should be made clear in the UI.

7) Display the blockchain confirmations and blockchain TX details

Before RenVM mints a tokenized representation, it must wait for a number of confirmations on the guest blockchain.

E.G RenVM waits for 6 confirmations on Bitcoin before minting the user the tokenized representation on Ethereum (renBTC). The front-end should display to the user the number of confirmations as an indication of how much longer they need to wait.

Further, it is advised to provide a hyperlink to the relevant on-chain transactions for transparency. If a user is moving BTC to ETH, then provide a link to BTC TX (e.g Sochain) and once the ETH TX has been initiated, the same applies (Etherscan).

This is important for transparency and so the user feels at ease when waiting.

8) After RenVM has witnessed the required number of confirmations, the user must submit a Mint transaction on the Host blockchain

For example, if a user is sending BTC to Ethereum, after 6 confirmations they are required to sign a transaction with a web3 enabled Ethereum wallet (such as MetaMask).

After detecting that a user has deposited the Host asset, your front-end should alert the user that they’ll need to return after the required amount of confirmations. If the user walks away after simply depositing to the Gateway Address and does not return to submit the Mint transaction, their funds will be custodied by RenVM but RenVM will not receive any instructions to mint the tokenized representation. The user must return before 24 hours to submit to the Destination Chain.

Be sure to convey to users that they must return to the UI, to trigger the secondary TX and complete the transactions.

9) Your front-end should always indicate to a user when they are required to conduct an action with their Web3 wallet

In the few instances exemplified above, a user will be required to sign with their Web3 wallet when submitting a mint transaction to Ethereum. For the below example we’ll use MetaMask.

When a front-end triggers a MetaMask interaction, the user won’t always receive a pop-up. Instead, they’ll need to click on the MetaMask icon in the browser menu.

To ensure a user is aware that their attention is required on MetaMask, your front-end should alert them that they are required to sign with their wallet. For example, “Sign with wallet to continue.”.

10) Set user expectations

Because RenVM needs to wait for a safe amount of blockchain confirmations (to prevent double spend, etc), which can take up to 1 hour (for BTC), ensure you set user-expectations.

BTC Example: Your front-end should alert users that the task is going to take about 1 hour (6 BTC Confirmations) before the secondary TX needs to be triggered (interaction with ETH or a web 3 wallet) This will help avoid confusion and ensure users return to sign for the transaction.

Looking Forward

The Ren team will be adapting this list over time, so check back frequently to ensure your RenVM integration is using the best UX practices. These guidelines are intended to reduce the amount of opportunity a user has to make an error, and should reduce loss of funds.

If you have any suggestions, get in touch via [e-mail].

Additional reading

1. Consensys’ Rimble is a front-end component library for building Decentralized Applications (dApps) on Ethereum. It includes some best practice but is more relevant to Ethereum based User Experiences. https://rimble.consensys.design/