Adding Trustlines to the Keybase Wallet
Enabling the Keybase wallet to hold assets in addition to Stellar Lumen.
This tutorial shows, in simple steps, how to add a trustline to the Keybase wallet using the tools provided by the Stellar website.
Why add trustlines to the Keybase wallet?
The wallet built into the Keybase app holds Stellar Lumens (XLM). To hold other assets in the wallet, it is necessary to add a trustline for that asset. Other assets may include other crypto currencies, such as Ethereum (ETC) and Bitcoin (BTC). Also included in other assets can be fiat currencies such as EUR and USD, using asset tokens.
The Stellar Consensus Protocol allows tokens for any asset which can be bought, sold, and owned. Something as global as gold and silver, or something as local as BerkShares. Once a trustline is established for them, the tokens representing that asset can be held in your Keybase wallet.
The built-in system and its limitations
The wallet in the Keybase app has the ability to add trustlines to the account built in. Unfortunately, for an emerging, or unknown asset, adding a trustline is not always possible using that option. The main Stellar website has a tool to accomplish this, as long as someone has issued a token on the Stellar Consensus Protocol to represent that asset.
Using the tools on the Stellar website requires you to enter your Keybase wallet’s secret key. With the Keybase wallet, or any other wallet, you are the bank. All the crypto value of your wallet is locked behind the secret keys of that wallet. Protect that secret key like you would the keys to a vault.
There are some simple things you can do to help keep your secret key secret in this process.
- Verify, twice, that the Stellar site is using HTTPS ¹
- Use the private, or incognito, mode for your browser ²
- Open exactly one tab and close the browser once you are done
- Use the built in “copy-to-clipboard” button in Keybase rather than trying to retype the secret key ³
What we will be doing
In this tutorial we will be adding the asset STELLARTALK
Any asset or token listed with Stellar can be added using this method, including ones which can be added using the built in controls of the Keybase wallet.
How to add a trustline
You will need to have both your web browser, and your Keybase app open. It is easier to do this using the desktop version of the app. It is possible to use the mobile version of the app as well, just not as easy to manage the multiple windows needed.
Build the transaction to add a trustline
Connect to the Stellar public network in Transaction Builder
Stellar provides a set of pages, called the “Laboratory” for dealing with the network without an additional program. There are two networks, testing and public. The testing network allows developers to try different things without creating real transactions on the ledger. The public network is the “real” network, were everything goes into the ledger, and becomes a part of the record. The Transaction Builder is the tool where we need to begin.
Open the browser in a private window and go to the address https://stellar.org/laboratory.
Check that your browser indicates that it is a secure site, usually a lock icon in the address bar.
If not STOP! Find out why your connection is not secure and try again.
Do not continue without a secure, HTTPS, session!
Check the top right corner of the web page to be sure you are not on the test network.
If you are, then click on the “Public” button to switch to the live system.
Click the link to the “Transaction Builder”
Next we have to gather the information about the transaction we want to build and enter it into the form provided.
Enter your Stellar Address
Adding a trustline to your wallet has to be connected to your Stellar address. That address has to be entered into the form. These steps will accomplish this.
Switch to the Keybase app and open your wallet.
Next to the name of your account is a gear icon.
Click that to open the setting for the wallet, which includes the public and secret keys for your account.
Click on the clipboard icon next to the box with your Stellar Address. This will automatically copy your Stellar address to the clipboard.
Return to the Transaction Builder in your browser.
Generate a sequence number
Every transaction on the Stellar network must have a sequence number. The sequence number is associated with the account, and should always be 1 greater than the current number. Knowing what that number is, when many things can affect it, is impractical for most people. The Transaction Builder can look up the current sequence number and automatically fill in the new value for you.
Enter the information about the trustline to create
Find the “Operation Type” field, and click on the “Select operation type” dropdown.
select “Change Trust” from the dropdown. Do not get this confused with the “Allow Trust” which is a different thing.
New fields are added to the Transaction Builder form based on the operation type selected. The Change Trust operation requires information about the asset to be trusted. Asset names can be long, or short, with the long version having a limit of 12 characters and the short version having a limit of 4 characters.
The asset selected for this tutorial, STELLARTALK, obviously will not fit in a 4 character field, so we need to select the “Alphanumeric 12” button.
Now there are two new boxes for the information about the asset to trust.
In the Asset Code text box, enter the code for the asset,
STELLARTALK for this tutorial.
In the Issuer Account ID text box, enter the account number for the asset,
GD6NJNNQ75TB4B5UM3PGRUMSM2JCMYPQTDDHGIJVLEZEHNOM5GVZX5VD for this tutorial.
The Asset information should now look like this.
The other two fields, Trust Limit and Source Account, remain blank.
Set the time bounds
The transaction we are building can be set to happen at a specific time, and can be set to expire at a later time. The later upper bound is not when an offer, or some other transaction is cancelled, it is when this operation is no longer valid. If, for some reason, there is enough network traffic that this transaction is not executed within the upper limit set, it will simply not be executed and never be added to the ledger.
When adding a trustline, this may not be so important, but for other operation types it could be significant. As a standard habit to develop, we can set an upper time bound now anyway. It has even been made real simple, by adding a button to set the time to 5 minutes from now. Even though this is a tutorial, and could be slow to work through, it should be done in 5 minutes or less, so click the handy button to “Set to 5 minutes from now.”
Sign and submit the transaction
At this point the transaction has been successfully created.
The Transaction builder says that the transaction still needs to be signed before it can become part of the ledger.
Load the Transaction Signer page
After building a transaction, the next step is to sign the transaction. There is even a handy button to take us to the Transaction Signer page. Click the button “Sign in Transaction Signer” and the next web page is ready to use.
Sign with your Keybase Wallet Secret Key
Go back to the Keybase app, which should still be on the wallet settings. Keybase gives you an additional reminder about the importance of your secret key.
Click on the clipboard icon next to the hidden text of the secret key. This copies the secret key to the clipboard, without revealing it on the screen.
Return to the Trasaction Signer page in your browser. Double check, one more time, that it is a secure connection. This is the last chance to protect your secret key.
Paste your secret key into the Add Signer box. You only need to do it once.
Each entry in the text box opens another text box to add another signer. The second box is for those who have set up their account to require more than one signer to allow operations to be done.
Submit the transaction to the ledger
The transaction is now signed, and ready for the next step.
Now click the Submit to Post Transaction endpoint button.
The last chance for backing out is now. Click the Submit button and the transaction will be submitted to the ledger.
Each trustline added to the account requires a 0.5 XLM reserve. If your account does not have that much extra available, the transaction will be denied.
If the account does have the needed reserve, then the success message will be your reward.
Verify new trustline
Return to the Keybase wallet settings and click on the Manage trustlines button near the bottom.
If all has been done correctly, you will have
STELLARTALK in your list of trustlines.
Now your Keybase wallet can hold
STELLARTALK tokens, and you can send, receive, buy, sell, and trade them as easily as you can Stellar Lumen.
The same process can be used to add any asset tokens available on the Stellar network, as long as you know their Asset Code, and the Issuer Account ID.
: The HTTPS protocol encrypts all the data you send to the server. Anyone evesdropping on your network will not be able to see the secret key you send to the website.
: The data, including your secret key, is entered into fields of a form. Most browsers will store form data to make it faster to fill in the same form when you return to that site. That form data will include your wallet’s secret key, which you don’t want stored anywhere but the Keybase wallet itself. Using private mode, if the browser is compliant, prevents the storing of any information from the session, including form data, and cookies. You will still have access to data previously saved from a regular (non-private) session, such as login information if needed.
: Using the app’s ability to place the secret key directly into the clipboard prevents errors in typing it and prevents a key logger from seeing it when you type it. It will not be shown on the Keybase app. It will, however, be visible on the Transaction Signer page.
Eager to stay in the loop?
If you want to find out more info about Keybase app read “Keybase App Tutorial“.