Quick Start

In this tutorial we guide you through the process of setting up a very easy TokenScript and deploy it to AlphaWallet.

TokenScript has a lot of functionalities, but we start with an easy example: Add information to your token. This is not a small deal, since wallets usually don't know anything about a token. As you will see, this is also the starting point to create offchain apps for your token.

Create your testnet token

If you want a really quick start, you don't need to create your own token. Just add the "Coin" token on Ropsten address 0xe35FE4A1B17d50A8022078d98162DB25bC860834 to AlphaWallet (you can scan it from Etherscan). Enable "show zero balance token" in your settings to show it. If you need help adding the token, read this mini guide.

To launch your own token we recommend to use Ethereum studio and start with a template for a simple token. Then recreate the files in Remix, connect your wallet, get some Ropsten coins from a faucet and deploy your smart contract. Our mini guide explains in detail how to do. Alternatively you can follow this more detailed tutorial.

After you deployed your token on Ropsten, copy the contract address and add the token to AlphaWallet.

At this step you have a new token in AlphaWallet. But AlphaWallet remains dumb. It can only send and receive the token. It doesn't know anything about it other than the symbol. This is what we are going to change now.

Create the TokenScript files

You could create the TokenScript file from scratch. To do so, you should understand the basic concepts and study the source code of examples.

But for this exercise you don't need to. You can use ABI to TokenScript, a simple tool to get the TokenScript files from the smart contract ABI. You find the ABI either in Studio or get it from Etherscan.io.

Now download the files in a folder on your computer and inspect them.

Most important is the token.xml file (here: Coin.xml). It declares the TokenScript structure. Also important are the JavaScript files. They contain the dynamic code for Action Cards which is executed in AlphaWallet. The Makefile is needed to finish the TokenScript creation.

The XML file

Here we will only present some parts of the XML file. To learn more about the syntax, you find an overview here.

The header

The file header will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE token [
  <!ENTITY style SYSTEM "shared.css">
  <!ENTITY about.en SYSTEM "about.en.js">
  <!ENTITY approve.en SYSTEM "approve.en.js">
  <!ENTITY foryou.en SYSTEM "foryou.en.js">
]>
The first line declares the XML version of the document. Inside the !DOCTYPE tag you declare other files to use. In this case it are the JavaScript files for your Action Cards. Keep this in mind.

Declare contract, network and name

Every TokenScript file needs to contain some basic info about the token: On which network does it run, what is the address of its smart contract, and what is its name? This is declared with this code:

<ts:contract interface="erc20" name="Coin">
     <ts:address network="3">0xe35FE4A1B17d50A8022078d98162DB25bC860834</ts:address></ts:contract>
<ts:origins>
     <ts:ethereum contract="Coin"/>
</ts:origins>

As you see, the Coin token is an ERC20 smart contract. The network number 3 means that it is on Ropsten testnet.

Action Cards

Now we talk about Action Cards. This is where the fun begins and where we can enrich our token with information and even with applications. See how they are declared in the XML file:

The part we are interested in starts with the <ts:cards> tag and ends with </ts:cards>. Inside of these tags we put the individual cards. In this example an Action Card is added which provides information about the token:
 <ts:card type="action">
     <ts:label>
          <ts:string xml:lang="en">About this token</ts:string>
     </ts:label>
     <ts:view xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
         <style type="text/css">&style;</style>
         <script type="text/javascript">&about.en;</script>
     </ts:view>
 </ts:card>

The starting tag explains TokenScript that this is an Action Card. AlphaWallet will know how to deal with it. Inside the label tags we find the english version of what will be on the button to show information: "About this token". The "view" tags declare what the user will see. Here we place a reference to a CSS and a JavaScript file.

The JavaScript file

You should have two JavaScript files in your folder: about.en.js and approve.en.js. We ignore the approve file and open the about.en.js file to inspect it:

The file starts with the declaration of the Token class, and ends with a web3 command. In this guide we only focus on one part inside the Token class - the render() function:
 render() {
     return`
     <div class="ui container">
         <div class="ui segment">
             <img src="https://www.bitcoin-buch.org/bitcoin-geschichte-front-1.jpg" />
             <span><bold><h1>This is the Token of Christoph!</h1></bold><br /><br />It                     is a one of the century chance to invest!</span>
         </div>
     </div>
     `;
 }

This function renders the display after the user tapped the "about the token" button. Inside you find some basic HTML: A div of the class "ui container", and in it a div of the class "ui segment". Inside this div there is a picture, a headline and a text.

Add your personal note to your token

Now that you know some basics about the TokenScript architecture, it is easy to add your own Action Card with your personal information: Create a file called hello.en.js. Copy the content of about.en.js in this file, change the part inside the rendered div to display your personal message, save it. Then open the xml file, declare your JavaScript file in the header, copy the Action Card for "about", put it into the Card section, and modify the content that it loads the hello.en.js file.

Canonicalize your TokenScript

We are almost here. The next step is that you have to create a canonicalized XML file containing all files in the folder.

Thanks to Makefile the canonicalization is easy: Type "make token.canonicalized.xml" in the console while being in the folder with the TokenScript files, with "token" as the name of your token. If your system has all dependencies, you will get a file named "token.canonicalized.xml.TEST". Rename the file into token.canonicalized.xml.

If the make commaned doesn't work, you might lack some software. You can use xmllint, which is available for both Ubuntu and Windows. Here you find the commands how to install it.

Put the TokenScript on your Smartphone

Finally you need to connect your smartphone to your computer. Open the filesystem and navigate to the AlphaWallet folder. Now paste the token.canonicalized.xml in the AlphaWallet folder.

For iOS you should exchange the file somehow, maybe with twitter, facebook or telegram, and than open it with AlphaWallet.

Now start AlphaWallet and select your token. Click the […] button in the right buttom, select "hello" and look at the information you added. This is your first TokenScript.

Whenever you want to change the information or add another Action Card, you can simply repeat the former steps.

Beyond information

Adding a bit of information to a token in a wallet might sound trivial. But it's no small deal. Common wallets don't know anything about a token, and if they do, then it is because the wallet developers selected a coin to add information. With AlphaWallet and TokenScript you can add information to any Token.

It doesn't require much fantasy to imagine how this simple Action Card can become the base for apps. With JavaScript you are not restricted to show information. You can do everything JavaScript can do, and you can connect to an API to get information. If you know how to sign a message with a key inside TokenScript, you can even design your API so that it only sends information to a wallet holding a required amount of your tokens. You can bind any subscription based app to a token and launch it in AlphaWallet.