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.
- Do not have anyone watching over your shoulder or viewing your screen/li>
- 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 or copy paste commands if you are using other wallets rather than trying to retype the secret key
What we will be doing
In this tutorial we will be adding our token BIZZNERD
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.
Look for the lock icon, often green, 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.
Just copy paste your Wallet address, and if you are using Keybase app follow these steps.
Switch to the Keybase app and open your wallet.
In the right corner of your wallet you will find setting options.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.
Paste the just copied address in the Source account field.
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. In next step just press link “Fetch next sequence number for account starting with …”.
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, BIZZNERD, obviously will not fit in a 4 character field, so we need to select the “Alphanumeric 12” button.
In the Asset Code text box, enter the code for the asset,
BIZZNERD for this tutorial.
In the Issuer Account ID text box, enter the account number for the asset,
GCQNVHELB3XKDBGXVWFUY2BAD5GEDGODE2SERS7R73LBXE2724PFFZAG for this tutorial.
Add finally enter the asset Issuer Account ID.
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 Wallet Secret Key
Go to your wallet and copy your secret key. Keybase and other wallet gives you an additional reminder about the importance of your secret key. That is really important that you check everything, before adding any trustline. Once someone has your secret key can do whatever he wants with all your assets on Stellar Blockchain.
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.
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.
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.
Rember, only do this process when you must. There are rare occasions when you need to that or if you are issuing token or adding some asset that you fully trust.
You can always add trustline via Keybase, StellarPort, StellarX or some other Wallet apps like Lobster.
We used our asset BizzNerd as an example, but if you want to add it to your trustlines, use Keybase or Stellarport instead.
Eager to stay in the loop?
If you want to find out more info about Keybase app read “Keybase App Tutorial“.