nahmii Guide: How to Withdraw Tokens
On 1st March 2020 the first nahmii accrual period will close. After this date, only NII tokens which are held on-chain will be eligible to accrue further transaction fees. As such, we expect that many token holders will want to withdraw their NII tokens from nahmii back to Ethereum’s mainnet. This guide will take you through the process using hubii core, our wallet management software.
Available, Staging and Staged Balances
Before we dive into the detail of how to action a withdrawal, it is helpful to begin with an explanation of how balances work within nahmii. Funds held in nahmii are described as being part of your available, staging or staged balance, depending on their status. A summary of each status is included below:
Available: these funds can be used to make payments and other transactions within nahmii, but cannot be withdrawn until they have gone through the settlement process
Staging: these funds are currently part of an ongoing settlement, they cannot be withdrawn or used to make transactions within nahmii
Staged: these funds can be withdrawn at any time, as they were part of a successful settlement process
The process of withdrawing funds from nahmii back to Ethereum is best understood in terms of these balances. We begin with available funds, which are then subject to a settlement process during which they are counted in your staging balance. Once the settlement process has been completed, these funds are then staged and available for withdrawal.
Three Steps to Withdraw
As you probably know, nahmii is a layer-2 protocol. This means that transactions within nahmii are separate from the Ethereum mainnet, which explains our vastly superior performance. When funds are deposited into nahmii, they are held in a collective smart contract known as the ClientFund. The ClientFund contract cannot see what is happening on nahmii, so when a user wishes to withdraw they must prove that their request is legitimate. This process of reconciliation between nahmii and Ethereum is known as settlement.
Settlement happens in two parts: first, a user specifies the amount of tokens that they wish to stage (i.e. prepare for withdrawal). This step includes the user providing evidence to support their request, usually in the form of a transaction receipt. Once the settlement request has been actioned, the user must then wait for five days for the settlement timer to expire (this time period is configurable and may be increased or decreased in future). During this period other users can challenge any fraudulent settlement request, again using transaction receipts as proof of any fraudulent activity.
We will soon add a feature which will allow instant settlement, as discussed in a previous blog post. This will allow users to withdraw their funds immediately, with liquidity provided by other nahmii users in exchange for a small fee. You can read more about our plans for instant settlements here.
The process of starting a settlement may sound complicated, but the most difficult parts are handled automatically by hubii core. This will be explained in more detail shortly. The second step in the settlement process is simply confirming the settlement request once the settlement timer has expired.
Once the settlement process has been completed, funds will move from a user’s staging balance to their staged balance. They can then be withdrawn back to the Ethereum mainnet with a final transaction; this is the third and final step in the process.
In summary, the process of withdrawing tokens from nahmii requires three steps:
- Start settlement
- Confirm settlement
- Withdraw
With a basic understanding of the process in place, we can now look at the individual steps in more detail.
Step 1: Start Settlement
This guide is based on the latest full release of hubii core, v1.3.0. You can download the latest version of hubii core at this link. Once you enter hubii core, please check at the top of the window that you are viewing the correct network as required, ‘mainnet’ or ‘testnet’. This can be changed in the settings menu.
To start a settlement you will first need to import your wallet into hubii core. From the hubii core landing screen, simply go to ‘My wallets’ then click on the ‘+ Add a wallet’ button in the top right hand corner:
Next, choose ‘Import an existing wallet’, then select your wallet storage type. The next steps are different depending on which option you choose. After entering your security information, set a password for this wallet on hubii core and click ‘Import Wallet’:
Now that you have imported your wallet into hubii core you can check your nahmii balance, interact with nahmii funds or you can begin the settlement process. First, select your wallet by clicking on the summary box under ‘My wallets’:
Clicking on the caret icon next to ‘nahmii balances’ will toggle the balance view on and off. Here we can see that this wallet has an available balance of 100 NII, with no balance recorded as staging or staged:
To begin the settlement process, click on ‘nahmii withdraw’ from the top menu:
Next, select the asset (NII) and amount of tokens you wish to start a settlement for. We will choose 50 NII in our example:
At this point in the process, hubii core will alert you that you do not have a sufficient staged balance to withdraw. Instead of processing the withdrawal directly, the software will start the settlement process.
To begin the settlement process, you will need to specify a fee (which is paid from your on-chain Ethereum balance in ETH) and agree to the terms and conditions. We generally recommend that users who are familiar with Ethereum gas select the ‘manual’ option, as this gives you control over ‘gas price’ and ‘gas limit’ in order to customise the transaction fee paid according to the speed the user requires.
When you click ‘Settle balance’, this will prompt you to sign the transaction. The process for signing transactions within hubii core is different depending on whether you are using a hardware or software wallet, this step should be self-explanatory:
Once the transaction is signed, you can view your pending transaction by following the Etherscan link provided. When the transaction has been mined, hubii core will update your balances and show a dialogue box explaining how long is left until the settlement challenge period has ended:
You can also see your updated balance under the ‘Details’ screen by clicking the ‘nahmii balance’ caret. In our example, my available balance has decreased by 50 NII and my staging balance has increased by 50 NII. My total balance has remained unchanged at 100 NII:
This concludes the first part of the settlement and withdrawal process.
For reference, you can also view my ‘start settlement’ transaction on Etherscan: https://ropsten.etherscan.io/tx/0xb996762d31f02b88d322592ed1a9dd13ac7ded646a015cd2d1a54df61ce084f4
Step 2: Confirm Settlement
In the previous section we explained how to import a wallet into hubii core and use it to start a settlement. The next step in the process is to confirm the settlement, which requires the user to wait until the settlement challenge period has ended.
As explained in the introduction to this guide, nahmii’s smart contracts on Ethereum do not have access to the transaction data from the second layer. This means that before funds can be released from nahmii’s ‘ClientFund’ pooled contract, users must have proved that their withdrawal request is legitimate.
The settlement process is effectively a check, whereby anyone with the right proof can demonstrate that a settlement request is fraudulent. If a settlement request is not challenged in this way, it can then be confirmed in order to move the staging funds into your staged balance. From there, staged funds can then be withdrawn.
You can see how long is left on the challenge period by checking the ‘nahmii withdraw’ page; it appears at the bottom:
When the settlement is ‘qualified’, new options will appear on the right hand side panel. It will also be indicated by a tick next to ‘Settlement qualified’ at the bottom:
To complete the settlement process, you simply need to click the ‘Complete settlement’ button and sign the associated transaction. Please note that you can set the gas cost of your transaction using the ‘Fee’ drop-down. You can see the ‘Complete settlement’ button here:
Once your transaction has been mined, which you can track using the Etherscan link provided, the settlement process will be complete. This will be reflected in your balance, where the tokens will have moved from your staging balance to your staged funds. In our example, this change has reduced my staging balance to 0 NII while increasing my staged balance to 50 NII:
Confirming the settlement is the final step in this part of the process. Now that you have tokens in your staged balance, they can be easily withdrawn back to your Ethereum wallet.
This concludes the second part of the staging and withdrawal process.
For reference, you can also view my ‘confirm settlement’ transaction on Etherscan:
https://ropsten.etherscan.io/tx/0x0a3802346c4ba805c1aaab247fa175907f66bbdbe52a859f9ab164e84036f66c
Step 3: Withdrawal
We have reached the final part of the guide, where tokens in your staged balance are withdrawn from nahmii. As before, we use the ‘nahmii withdraw’ screen in hubii core to action this request. You can see your staged funds from the previous settlement at the bottom of the page:
To request a withdrawal of staged funds we need to select the token type and provide the amount to be withdrawn. Note that you do not have to withdraw all of your staged balance, in my example I will withdraw 25 NII from my staged balance of 50 NII:
After setting the fee and agreeing to the terms and conditions, all that remains is to press the ‘Withdraw’ button and sign the associated transaction. You can see the ‘Fee’ drop-down menu and terms & conditions tick box below:
Once again, hubii core will provide an Etherscan link for you to track your pending transaction. Shortly after the transaction has been mined, funds will be transferred from nahmii’s ClientFund contract on-chain directly to your Ethereum wallet. Your transaction history in hubii core will also be updated, as shown below:
This concludes the final step in the settlement and withdrawal process.
For reference, you can view my ‘withdrawal’ transaction on Etherscan:
https://ropsten.etherscan.io/tx/0x02c2722555314841a140ed495282b343488069cb7d7c1cfe341856c80e09ec3a
