TokenScript directives: Is there a complete list?

[theBergmann]

Do you have a complete list of tokenscript directives? I went through the examples and found these:

Action Address Attributes Cards Contract Data Denial Ethereum Header Item-View Label Ordering Origins Plurals Selection String Token Transactions Type View

Is this list complete? Can developers create new declarations? Does it depend on the wallet which terms are ok?

Can you write a few words for the most important tokenscript declarations?

From inspecting the tokenscripts, it seems there are just a few main declarations, while most others are sub-declarations. Main declarations are Token, Attributes, Label, Card, Ordering.

[weiwu.zhang]

@theBergmann

Do you have a complete list of tokenscript directives? I went through the examples and found these

If you have xidel insalled (their website offers downloads in all types of OS), you can get a full list by using this command:

$ xidel http://tokenscript.org/2020/06/tokenscript.xsd --extract '//*:element/@name'

That command only gives you the directives under TokenScript namespace. So not including:

• Blockchain-specific directives. e.g. The directives under Etheruem namespace specific to Ethereum blockchain.
• All of the ASN.X module definition can happen in TokenScript which itself has a separate vocabulary (that can be found in RFC4912).

But I don't think it is very useful knowledge to the learners:) It's perhaps as useful as a full list of English words to an English language learner:) Can't use them if you don't first understand the concepts (cards, token attributes, attestations etc).

Is this list complete? Can developers create new declarations? Does it depend on the wallet which terms are ok?

There are 3 types of developers:

1. Blockchian developer who makes blockchians.
2. TokenIssuer who makes tokens
3. Web developers who uses tokens on their website.

The first group of developers can make new declarations under their blockchain's namespace (e.g. Cardano, Nervos). An example might be a <nervos:cell> directive to access a cell in Nervos (which doesn't exist in Ethereum).

The second group only need to define Token Attributes, data objects and so like, without creating new tokenscript directives. For example, he makes Hotel Room tokens, then he defines roomType attribute using the <attribute> directive. He doesn't need to create new directives, only use existing ones to create new token attributes.

The 3rd group don't define new directives nor new Token Attributes.

Can you write a few words for the most important tokenscript declarations?

card and attribute are the most important. card defines a card (action card, token card or activity card). attribute defines a token attribute (or a card attribute if it is found in a card).

From inspecting the tokenscripts, it seems there are just a few main declarations, while most others are sub-declarations. Main declarations are Token, Attributes, Label, Card, Ordering.

Yes, and

• ordering is unimplemented so you can ignore it for this year.
• label is used for localisation, so that you see your token as Ticket if you have an English phone, Bellete if you have a Spanish phone, or 门票 if you have a Chinese phone.

So those 2 are not super important.

[theBergmann]

Hei Weiwu,

thanks for answering. Helped a lot.

I installed xidel, the list ist not as super long as I expected ...

token label origins cards card label input output token ethereum plurals string contract address interface include view item-view redeem exclude feemaster gateway prefix selection label denial grouping group consecutive_groups ordering order byName byValue attribute type syntax label transaction origins user-entry token-id ethereum

This is good, as it can be possible to describe all declarations, or at least the most important. Just with a few words. For example, what does "origin" mean? Or "view"? And why is there a need for "address" and "contract"?

Blockchain-specific directives. e.g. The directives under Etheruem namespace specific to Ethereum blockchain.

The first group of developers can make new declarations under their blockchain's namespace (e.g. Cardano, Nervos). An example might be a <nervos:cell> directive to access a cell in Nervos (which doesn't exist in Ethereum).

So TokenScript allows a namespace for each blockchain. If I am an developer for EOS or for BSV, I can use my own namespace? Do I need to register it at tokenscript, or can I just use it, as long as a wallet understands?

card` defines a card (action card, token card or activity card)

This is still a bit confusing. Maybe because the word "card" doesn't match a ring inside me. I know about "Action Card". But what are token cards and activity cards?

[weiwu.zhang]

@theBergmann

This is good, as it can be possible to describe all declarations, or at least the most important. Just with a few words. For example, what does "origin" mean? Or "view"? And why is there a need for "address" and "contract"?

Oh, I think there is a better way of learning the structure of a TokenScript file, as not all these are equally important. You can use the TokenScript Viewer to see the major parts in a TokenScript file.

Here is the instruction:

1. Check your dependency. On OS X everything needed is shipped. On Ubuntu, you need to install 3 packages: tcl, tk, tdom at the outset.

2. Clone it to get the source code:

$ git clone https://github.com/AlphaWallet/TokenScript-Viewer

3. Go to src directory and run ./tsviewer.tcl

$ cd src
src$ ./tsviewer

4. You should see a new window, use "File -> Open" to open a tokenscript file (signed or unsigned doesn't matter). You will get something like this:

Tokenscript Viewer is an in-development tool that is not yet released, hence I provide the instruction on a forum. Ultimately you should be able to have an installable package instead of having to get the code and run it yourself.

Where you get a visual. You asked:

describe … the most important ones. Just with a few words. For example, what does "origin" mean? Or "view"?

My answer:

• Smart Contracts, declared by <contract>, are all contracts that the token issuer trusts enough to get token data from and writing transactions to.
• Token Attributes, declared by <attribute>, are all token attributes. e.g. if you have a car-lease token (representing your right to use a car for a certain amount of time), then one of the token attribute would be named expiry.
• Cards, defined by <card>, are the collection of action cards (what actions can be done with or to the token), token cards (how the token is rendered in various contexts), activity cards (what has happened / will happy / ready to happen to a token).
• Data Object defined by <asnx:module>, are data objects explained in a separate aritcle. For an example: an offer (like "I am willing to sell this kitty of mine at 3Ξ").
• Strings are typically in <label> and <message>. These are text which appear to the users in their own language (we often only cover Chinese, Spanish and English in examples).
• Selection defined by <selection>, are a way to categorise token instances so that you can select them together or define an action for. It was originally called grouping back in 2018 but I forgot why it has turned into selection as the tech gets standardised for wider use.

For example, what does "origin" mean?

Regarding origins - they can be found under Token Attribute tab. As you can see from the above screenshot, some of these attribute's value originates from ts:user-entry, some from ethereum:call - there are others that are from attestations or token-ids. I can't cover all details here.

And why is there a need for "address" and "contract"?

It would make a lot sense if you open a TokenScript file with a text editor to see. e.g.:

<ts:contract name="UEFA" interface="erc721">
    <ts:address network="100">0x0f43923667843bccafd12a5c001a7838fa5fc8ab</ts:address>
    <ts:address network="3">0xc2f901070AdcfA07Bc5c46cc2390063248eb9E81</ts:address>
    <ts:address network="4">0x9693a618E4FC4912986b2e5342A82BaC47CF4d52</ts:address>
</ts:contract>

This is still a bit confusing. Maybe because the word "card" doesn't match a ring inside me. I know about "Action Card". But what are token cards and activity cards?

I think what is a Card is a topic that deserves a discussion thread on its own. Can you open a new question?

TokenScript includes a namespace for blockchains. If I am an developer for EOS or for BSV, I can use my own namespace? Do I need to register it at tokenscript, or can I just use it, as long as a wallet understands?

Yes. If you are someone who wants to bring TokenScript tech to EOS or BSV, you can do this:

1. Fork a TokenScript implementation and add your blockchain-specific tech in your own namespace (e.g. elements that declares a contract to be trusted in your blockchain). This is needed to make TokenScript that uses your special blockchain to work.
2. (Optional) Tell us your namespace by filing an issue under TokenScript project so we can make the schema open to that namespace. This allows a standard TokenScript tool (like the TokenScript Viewer I just showed you above) to validate a TokenScript that uses your blockchain without throwing an error.

There is no standard registry for all blockchains and what namespace do each one use. Ethereum allows Plasma which allows each Plasma blockchain to work differently with different consensus mechanism, so a full registration is perhaps overkill and exposes some info about the blockchains that are intended private.