Purpose

 
Lot of us likes to follow the best practices of not leaving any crypto on the table and by that I mean to have a secure cold wallet setup for any sort of cryptocurrencies that we own. Many people use the Ledger Nano S as their go-to hardware wallet choice but many others also like to have their own version of offline/paper wallet as a cold wallet setup where it's private key never touches the internet. The challenge which comes with that is obviously how to manage to sign your transactions offline.

I personally like to have a cold wallet setup by staying in-charge of the private key in an offline computer during its entire lifetime. For Ethereum based cold storage I followed this excellent guide from Tomshwom to setup Tails OS + KeePassX + USB drive + MyEtherWallet as cold wallet. Please check it out in case if you want to use a similar approach:

Tomshwom's Advanced Crypto Security Guide (Part 3) - Creating a Secure Wallet ¹

 

---

You can still follow this guide even if you don't have a similar setup that's mentioned above. This will be a comprehensive guide and the steps we are going to cover can be applied to any sort of offline wallet setup.

Also, you might want to find a way to follow along with this guide on a different computer/smartphone during the offline portions.

 

Overview

 
We are going to walk through the following aspects of with Stellar.

• Downloading our tools

• Securely setting up an Offline Paper Wallet

• Getting Stellar Laboratory website for offline use

• Building a transaction from a computer that is online

• Signing a transaction on a computer that is offline

• Submitting a transaction from a computer that is online

• Joining an Inflation Pool

• Enabling your wallet to deal with various Stellar Assets (tokens)

• Sending transactions for various Stellar Assets

You will also need a USB drive for securely transferring some data back and forth between your online to offline system.

 

Downloads

 
We are going to download a couple of tools from Stellar's official GitHub repositories. Stellar's Paper Wallet and the Stellar Laboratory. Obviously, we start by being on a computer which is connected to the internet.

**[Update]: Stellar will soon deprecate their paper wallet mentioned below. It is still functional right now but may not be in future. I will keep an eye out for a good platform-independent wallet generator and will include the updated version here whenever available**

 

• Download the paper wallet by visiting following link and click on "Clone or download" button.
  https://github.com/stellar/paper-wallet

• Download the Stellar Laboratory by visiting following link and click on "Clone or download" button. https://github.com/stellar/laboratory

 

Setting up Paper Wallet offline

 
I am going to outline how to set up a paper wallet on your offline system.

• For this step you will first need to plug-in the usb drive to your computer which is connected to the internet and copy the downloaded paper wallet folder to this usb drive.

• Boot the offline system/computer which should never connect to the internet. Plug in this usb drive and open index.html file from the folder.

• After that it's super simple to just click on the "Generate" button in order to generate your pair of public key (wallet address) which starts with G and secret key which starts with S.

 
You will see QR codes as well as text output. It is extremely important here to safely save your private key. This is the key used in order to do any sort of transaction from your wallet and also to recover access to your wallet if your computer is stolen or can't boot anymore due to disk failure or any other reason.

If you are storing this private key on your offline computer's hard drive/usb/sd card, then it is also very important that you store it in encrypted form. It's best to follow the guide I mentioned earlier for Tails OS Encrypted Persistence and KeyPassX setup for doubly-encrypting everything. But you can also use any other password managers or some form of encryption.

Alternatively, you can also write down this private key on the piece of paper.

 
Whether you store your private key on a physical drive in encrypted form or write it down on paper - it is extremely important to have multiple backups/copies of it and store them securely to avoid any single point of failure in case if you lose the only one copy you have.

• Save the public key (wallet address) either in a wallet.txt file on your usb drive or scan the QR code on your smartphone Be careful not to scan the QR code of the secret key. To avoid this from happening you can resize your browser window to only see the QR code of public key before you scan it.

• You can now unplug the usb drive go back to your computer which is connected to the internet.

 

Getting Stellar Laboratory for offline use.

 
For non-technical users, this is the only challenging step in this guide. But don't worry we will break it down step-by-step.

At the time of this writing, in order for us to sign transactions offline, we need a working local copy of Stellar Laboratory and I couldn't find any other way but to download it from GitHub and build it from source code. Please download it if you haven't done so from the earlier step. ²

By visiting https://github.com/stellar/laboratory, and going through Readme we can see that we can build this website as mentioned in the instructions under "Building for production". ³

Currently, we need git, node js and npm to be installed in order to build our own copy of the Stellar Laboratory website. They are free and open source, anyone can download and install them on Windows/macOS/Linux and other platforms.

 
If you need to install the latest version of git then please follow the instructions here

And there are various ways to install node and npm, you can find many resources online. I am just going to mention below guides for Mac and Windows:

• Installing Node.js® and NPM on Mac
• Installing Node.js® and NPM on Windows

 
After verifying your installation, you can then build your local copy of Stellar Laboratory.

 
On macOS/Linux:
Open Terminal and run below commands in sequence

- cd ~/Downloads/laboratory-master/
- npm install
- ./node_modules/.bin/gulp build

 
On Windows:
Extract the zip file and then open Command Prompt by clicking on start menu and type: cmd. After that run below commands in sequence (replace <YOUR_USERNAME> with your windows account username)

- cd C:\Users\<YOUR_USERNAME>\Downloads\laboratory-master\
- npm install
- node_modules\.bin\gulp build

 
If everything goes well then go back to the laboratory-master folder that you downloaded and you will see that there is a folder named "dist" which got created. This folder has everything that you need in order to have your own working local copy of Stellar Laboratory. You can verify this by opening index.html file from it.

• Plug in the usb drive and copy this dist folder in it. You will need this when we need to sign transactions offline.

If you are not a computer savvy user and if you have made it this far then Congratulate yourself! Because now you have all the necessary tools to start working on your transactions!

 

Building a transaction

 
There are two ways we can build a transaction. Either by using mystellar.tools website or by using Stellar Laboratory website. For simplicity, we are going to use mystellar.tools

 
Go to: mystellar.tools

• Enter your Public Key and click ENTER:

 

• To send a payment in XLM- click on Send from the left menu. And fill out the details below:

 

• After you click the VERIFY button, you will see the below verification page. Click SEND

 

• As soon as you click on send you will see below message will appear.

 

The message is self-explanatory. Basically, all it's saying is that since we have entered the application without using our secret key, it cannot sign the transaction before sending it. But we can use this transaction information to sign it offline on our own.

• Copy the Transaction hash and the Transaction evelope (XDR). And save it into a txt file. Let's name it tx_unsigned.txt. Save this file to your usb drive.

 

Signing a transaction offline

 
Before we go to sign our transaction offline make sure you have following two things in your usb drive.

• The folder named dist which is the local copy of Stellar Laboratory website that we built.

• The file tx_unsigned.txt which has the Hash and XDR data of our transaction.

 

Boot up your computer which is offline and plug this usb drive in it.

• Copy the dist folder locally on your desktop from your usb drive. Open index.html file in the browser so you get Stellar Laboratory running offline. Now make sure that you select the public tab on top right. This ensures that everything will be done for the public network.

• Click on Transaction Signer from the top menu bar.

• This will give you an option to- "Import a transaction envelope in XDR format:"

• Now open tx_unsigned.txt file from usb drive and only copy transaction data under XDR:. Don't copy the Hash which is above that. See the highlighted part below:

 

• Go back to the browser and paste that into the text box.

• Make sure there are no leading or trailing whitespaces and it should display a message: "Valid Transaction Envelope XDR"

 

• Click Import Transaction button.

• You will now see all the data of your transaction getting displayed. Verify the Transaction Hash field that's been displayed vs the Hash: that you saved in your tx_unsigned.txt file. They should match. This will help you make sure that you have been doing all the steps correctly and you imported the transaction correctly.

• Now for the next step, you will need access to your secret key which starts with S. Please have it handy either from this offline computer or if you wrote it down on a paper.

• Under the Signatures section there is an option Add Signer: enter your secret key here. (please make sure the secret key you enter here is the one associated with your public key otherwise submitting this transaction will fail). You only need to enter this one key as a signer.

• As soon as you entered the secret key you will see that it generated an output XDR in the box below it. It will display the message "Transaction signed!".

 

• Copy the XDR (highlight above) that was generated and save it in a text file named tx_signed.txt. Save this file in your usb drive and then unplug it.

• You will need this file when we submit the transaction online using mystellar.tools

---

Please make sure that at no point you are copying/saving your secret key anywhere on your usb drive. In such setup, your secret key always needs to stay isolated and should never come on any device which will connect to the internet.

---

 

Submitting a transaction

 
This is the moment we have been waiting for!

Let's go back to your computer which is connected to the internet.

• Plug-in your usb drive.

• Go to mystellar.tools, enter your public key if required, then from the left menu click on Submit transaction.

• Enter your transaction XDR from tx_signed.txt file from your usb file. And click on SUBMIT button.

• It will display the result along with response in JSON format. If you got any error then please see error codes help section at the bottom of this guide.

• Go to Payments from menu to verify it.

 

Joining an Inflation Pool

 
If you are not familiar with the concept of inflation in Stellar then I encourage you to go check out this guide on How Inflation works

There are many Inflation pools which you can join. One of the community-driven Inflation pool that I can recommend to join is Lumenaut.

• Go to How to Join the Inflation Pool guide on Lumenaut's website and copy their Inflation Destination address.

• Then go to mystellar.tools, from the left menu click Set Options. At the bottom of the page under Others, enter the Inflation destination address that you copied and click on SET.

 

It will display the message saying that it cannot sign the transaction because you have not entered any secret key, along with all the transaction information. Save this information on your usb drive, sign the transaction offline, and then come back to mystellar.tools to submit it.

 

Enabling your wallet to deal with various Stellar Assets (tokens)

 
The Stellar distributed network can be used to track, hold, and transfer any type of Assets: dollars, euros, bitcoin, stocks, gold, and other tokens of value.

When you hold assets, you’re actually holding credit from a particular issuer.
In order to be able to receive any other Asset (token) from an issuer you much first establish a trustline with that issuer. (Basically, you “trust” the “issuer” for issuing/crediting their tokens to your wallet.)

Entities (individuals, small businesses, local communities, nonprofits, organizations, etc) who can issue you assets are called Anchors.

Each Anchor has an issuing account from which it issues the asset. All anchors, when issuing an asset, give it an asset code. Assets are uniquely identified by the asset code and the issuer's address (wallet address)

We need to find out the issuer's wallet address with whom we can establish a trustline. Stellar uses Federation protocol to map a user-friendly name like domain name, email address, etc., to a wallet address.

 

We will take a look at how we can establish a trustline with the anchor mobius.network to receive their token MOBI. Same steps can be followed for all other Anchors and their assets (tokens) that they provide.

• In mystellar.tools, on the left menu click Manage Trustlines. Under Create a trustline search for the Anchor's Domain: __mobius.network.

• It will show you the list of assets that the anchor provides. Click on MOBI and it will show you the details. Click ADD in order to add trustline with this Anchor to enable your wallet to receive MOBI tokens.

 
As soon as you click that, it will display the message saying that it cannot sign the transaction. Save the transaction information on your usb drive, sign the transaction offline, and then come back to mystellar.tools to submit it.

Once you submit the transaction, verify it by clicking All operations menu on the left.

 

Sending transactions of various Stellar Assets

 
After you have created a trustline with the Anchor and received their tokens, let's look at how can you send them across to someone. An important thing to note here is that the destination wallet to which you are sending a particular token should also have a trustline established with this Anchor. Because after all the token is actually credited by this issuer (via Anchor) to the destination wallet address.

• In mystellar.tools, on the left menu click Send.

• Fill in the Recipient address and Amount of tokens that you want to send. Under Asset click the drop-down menu and then enter New Asset Code: MOBI. and click SET.

• Click on VERIFY and then SEND. It will display the transaction information, save it on your usb drive, sign the transaction offline, and then come back to mystellar.tools to submit it.

 
 
 

Error codes help:

 
Following are some transaction response error codes which you might encounter while submitting your transactions.

- tx_no_source_account: You used incorrect source wallet address from which you are sending this transaction.

- tx_bad_auth: You signed the transaction incorrectly or used an incorrect secret key for the corresponding public key. Please make sure that you also select "public" tab in Stellar Laboratory. This signs the transaction properly for the public network.

- tx_bad_seq: Rarely, you can also get this error if the transaction sequence during the time when you build your transaction is no longer valid. Start a new transaction from scratch and please also make sure that you select "public" tab in Stellar Laboratory.

- op_no_destination: The destination address doesn't exist or doesn't hold the minimum required balance. ⁴

- op_no_trust: The destination address doesn't have a trustline which the Anchor and hence it can't receive the token that you are trying to send.

 

Conclusion

 
Security needs to be a paramount importance when it comes to how you handle cryptocurrencies. For this purpose I recommend everyone to have a cold wallet for long-term storage.

We have covered major aspects of cold wallet setup and signing transactions offline with Stellar. I hope this guide helps you to keep a secure cold wallet setup while still be able to perform basic transactions with Stellar.

Please let me know if you have any questions or if you get stuck somewhere.

 

I wish you a Stellar journey in your endeavors!

 

 

If for any reason you are curious​ on how to do these steps using Stellar Laboratory the checkout this guide and reddit comment.

¹ If you are going to use Tails OS then please make sure to use v3.2. Because the TOR browser in later versions isn't getting the right permissions in AppGuard and hence CSS files are not working properly. See here

² The developer of mystellar.tools has hinted that currently, development for a standalone cross-platform tool to sign transactions offline is underway. I will post an update with a link whenever this is available.

³ The instructions mentioned in the README file to build the website can change so it is always better to first check it on GitHub

⁴ In this case you can build a transaction in Stellar Laboratory under Transaction Builder of type Create Account. Under Destination Address enter the address of account to be funded for the first time and enter the Starting Balance amount.