An introduction to Loopr wallet

Daniel Wang

Published in

Loopring Protocol

10 min readDec 27, 2017

We introduce you, Loopr, our wallet that has been integrated with our protocol 1.0.0 deployment on Ethereum mainnet.

Background

The three most important components for Loopring ecosystem are:

1. the Loopring Protocol smart-contracts

2. relays that manage order pools and mine order-rings

3. wallets that can help users to manage their assets and orders

Loopr is a wallet developed by the Loopring Foundation, its very first version (beta1) had been implemented to verify the aforementioned components can indeed be integrated into a reliable solution. We are pleased to announce that beta1 is now available for invitation-only testing at https://loopring.io. As beta1 was not designed with optimized user experience, we feel obligated to have this post to introduce you to a trustless and decentralized ERC20 token trading experience.

If you don’t like the way Loopr works, no worries — a beta2 version is currently being designed to provide a much better user experience for normal users.

Popular Wallet Operations

We will cover the following user interactions:

Browse markets
Generate and unlock your wallet
ETH/WETH conversions
Authorize for allowance
Submit orders
Browse trades and orders
Browse order-rings
Cancel an order
Cancel all orders

Browse markets

You can go to https://loopring.io/#/markets for a list of all (over 60) markets that Loopr currently supports. In the future, we’ll support most ERC20 token to ETH markets and even any-to-any markets. To quickly search for a market, we suggest you take advantage of the search box on the top-right corner, then bookmark the search results if you’ll revisit some of those markets later.

Once markets are bookmarked, they will show up under the “My Favorite” tab (you need to clear the search box first, this is something we need to fix in beta2).

You will notice that most tokens are traded with WETH. WETH stands for “Wrapped ETH”, it is also known as “Ether Token”.

Generate and unlock your wallet

To generate and unlock your wallet, you can follow the following workflow. If you have a keystore file already, you can click on “Unlock Keystore File” in the second step.

One thing to keep in mind: Loopr does NOT have a backend database to store your wallets or private keys. If you lose your keystore file or forget your password, you’ll lose access to all of your tokens and Ether. There is NO way we can help you to recover. We always suggest you to backup your wallet (keystore) files and make sure you remember the passwords BEFORE storing any value in the newly generated wallets

Loopr will NEVER send your private keys over the network to anyone. To make sure of it, you can check out our source code at https://github.com/Loopring/loopr, or you can open browser’s development console, then open a zero-balanced wallet to verify our claim (as shown in the following image).

Several sections that follow assume you have certain ETH and LRC in your unlocked wallets.

ETH/WETH conversions

The Loopring Protocol can facilitate trading between ERC20 tokens. Loopr needs to convert Ether to Ether Token for trading as Ether is not ERC20 compatible, but Ether Token is. Converting between Ether and Ether Token will be done for you automatically when you submit an order, but if you want to trade frequently, we strongly suggest you convert some Ether to Ether Token beforehand manually; otherwise, each order will take one more blockchain transaction just for the ETH-WETH conversion which takes time and gas.

Conversions between ETH and WETH are done on-chain through Ethereum transactions. ETH and WETH are always converted 1:1 which is guaranteed by the WETH smart contract. The WETH smart contract also guarantees the total WETH issued is exactly the total ETH deposited. In other words, ETH and WETH is equiviate in value, and WETH is just the ERC20 form of ETH.

Now let me show you how to convert ETH to WETH. Converting WETH back to ETH is similar.

First, you need to click on “Convert” button in the same row as ETH,

Then input the amount of ETH you want to conver to WETH. You can only convert up to the amount of ETH you have minus some transaction fee. Then click the button to generate an transaction.

A dialog will pop up for you to review the transaction (both raw and signed), you can click on “Convert ETH to WETH” to toggle the display of details. Again, Loopr’s source code is available for you to review. If all look OK, you can click on “Send Transaction” button. You’ll see a confirmation message (with green background) telling you the transaction has been sent to Ethereum mainnet. You can click the transaction’s URL in the message to monitor transaction progress on https://etherscan.io.

Once the transaction is mined into an Ethereum block, you can check your balance of both ETH and WETH. (Tip: to reload balances, you can switch the secondary tabs.)

Again, converting between ETH and WETH is done on-chain using smart-contract, therefore conversions are secure and trustless. If you do a lot of trading, convert a big portion of your ETH to WETH to avoid unnecessary small conversion transactions.

Authorize for allowance

To submit orders, you need to authorize the Loopring Protocol for settlement. Let say you want to buy LRC using WETH (which is the same as “selling WETH for LRC”), you need to authorize the protocol a WETH allowance up to the total amount you would like to sell in the near future.

In this example, I’ll authorize the protocol with 2000 WETH allowance. Note that we only have 1.99 in my wallet. Allowance can be as large as possible regardless of the real balance. As a matter of fact, we encourage you to set an allowance of a really big number (for example 1,000,000,000) just in case you want to use Loopring Protocol for trading more. Given that our protocol is open-sourced and has been carefully reviewed. Allowance is considered secure, you don’t need to worry.

First, you need to click the “Approve” button for the token you want to authorize, in our case, this is WETH.

Then, put “2000” as the amount of allowance. Again, in real-world usage, we strongly recommend giving this a very large number. Then click “Generate Transaction”.

Again, review your transaction then click on “Send Transaction”.

Please also follow the same procedure to set up a 20000 LRC allowance. Then you should see something like this:

Now you can submit orders.

Submit orders

We will show you how to submit an order to buy 1000LRC at the price of 0.00042ETH/LRC, then submit an order to sell 500LRC at a lower price of 0.00040ETH/LRC, the miner should mine them into a ring.

To start trading, click on the “Trade” button from inside of the “Assets” page, or you can navigate to a market of your interest through the “Markets” top page.

In the market, you can use the form to submit a buy order as illustrated in the image below:

Notice that LRC fees are calculated automatically based on your settings. By default, if your order’s estimated fiat value is X, you’ll pay (X * 0.2%) worth of LRC as a trading fee. You will by default also pay 50% margin-split if miner chooses to take margin-split instead of LRC as mining fee. You can change these settings in the “Settings” page:

In most cases, we don’t recommend you to change these settings. Lowering LRC trading fee or margin-split will slow down or even disable your orders being fulfilled. To speed up trading, we strongly recommend you have some LRC in your wallet and set up LRC allowance. If you want to learn more about the fee model of the Loopring Protocol, please take a look at this blog.

Once you have specified your order parameters, click on “Buy” then you’ll see a dialog popping up for you to confirm the action before signing the order.

Order submission will not involve Ethereum transaction, instead, orders will be broadcast our off-chain relay network for ring-matching.

Let us submit the sell order as follows:

After about then seconds, you’ll see these orders are mined into a ring. If you repeat my operations, it’s possible that your first order will be mined into a ring with someone else’s order.

Browse trades and orders

Click on “My Trades” to see the list of your recent trades. Since all Loopring trades are settled on-chain, sometimes a wallet (Loopr included) may suffer from network delays. Loopring is not designed for realtime or high-frequency trading. You would have to fall back to a centralized exchange for that kind of trading activities.

In the image above you can see two trades, this is because we submit a buy order and a sell order using the same address. We won’t explain the math behind the scene, but apparently, the miner chose LRC fee instead of margin-split. Currently, Loopr doesn’t display trading price but it will in beta2.

If you click on “My Orders”, you will see the two orders, one is fully filled and the second one is partially filled.

Browse order-rings

You can browse the entire list of Loopring (v1.0.0) rings on etherscan.io:

https://etherscan.io/address/ringmatch.eth

The ring containing our 2 orders is available at:

https://etherscan.io/tx/0x71a2bfcb3e7226a86843279414daa53c9baccba2cbc682d63e20b2aecb3117c6

This is not a typical ring as our address is trading with itself (therefore some internal self-to-self transactions are avoided) A typical ring will involves several small internal transactions (for a ring of N ,up to 3*N internal transactions).

Cancel an order

Canceling an order takes an Ethereum transaction. This should be avoided by all means, and it can be done by specifying a short time-to-live (TTL) for your orders. In other words, if you specify 30 seconds as the TTL for your orders, then if they haven’t been mined into rings within 30 seconds, these orders expire automatically (which is guaranteed by the Loopring smart contract). Currently, Loopr doesn’t provide UI to specify TTL, but we’ll soon add such functionality to beta1.

Cancel all orders

You can cancel all pending orders with one Ethereum transaction. Technically we call this a “cutoff”. In Loopr you will find a “Commit Cutoff” button. It will be renamed to “Cancel all my orders” or something like that. You can also ignore the date-time selector on it’s left for now (it will become a read-only timestamp indicating when you conducted the last cancel-all action).

Smart Actions

Loopr has a feature called “smarter actions”. It helps users generate prerequisite transactions required for an order to be submitted.

For example, if my allowance of WETH is insufficient for my new order, Loopr will automatically generate two transactions, one for resetting the allowance and one for setting up the new allowance to match my order’s spending.