Ren UX Best Practice
This section will outline the best practices and things to keep in mind when integrating RenVM via RenJS.
We strongly suggest putting in a checkbox via opt-in - regarding loss of funds if a user makes a mistake.
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).
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.
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.
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.
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).
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.
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.
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.
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.
- 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/