Attributes

Define attributes so that token data becomes available to Cards and Websites.

In TokenScript you can define Attributes for token or for card.

Examples of a token's attribute:

In Ethereum, all ERC20 Tokens have an balance attribute.
For a Car Ownership Token, one attribute might be its model.

The values of these tokens may have various origins defined in the <origins> element. For an Ethereum token, a typical origin would be a call to an Ethereum contract or an Ethereum event.

Having attributes and the origins of their values defined allows a TokenScript Engine to provide this data; furthermore, monitor changes to this data and push updates to the code that uses such data, such as the code in a Card. More on this can be found in the data-driven and event-driven approach that TokenScript takes.

A TokenScript Engine does not define specific token attributes, however some Operational Attributes are always assumed. When used on Ethereum token, the most important operational attribute is ownerAddress which is always the Ethereum Address of the owner.

The most commonly used attribute is "balance" as defined in ERC20.

Attributes are declared in TokenScript. The following is a minimalist declaration, where an attribute "balance" is defined. The value originates from an Ethereum function call balanceOf.

    <ts:attribute name="balance">
        <ts:origins>
            <ethereum:call function="balanceOf" as="uint">
                <ts:data><ts:address ref="ownerAddress"/></ts:data>
            </ethereum:call>
        </ts:origins>
    </ts:attribute>

Let's take another more complex example: For a token representing a ticket for a soccer match, its attributes should contain the information when and where the match happens, which teams play, which seat is reserved and so on. Another example of an Attribute declaration declares the locality of a soccer match in the TokenScript for an entry token:

 <ts:attribute name="locality">
      <ts:type><ts:syntax>1.3.6.1.4.1.1466.115.121.1.15</ts:syntax></ts:type>
      <ts:origins>
          <ethereum:call function="getLocality" contract="EntryToken" as="utf8">
              <ts:data>
                  <ts:uint256 ref="tokenId"/>
              </ts:data>
          </ethereum:call>
      </ts:origins>
</ts:attribute>

An token attribute is defined, so that the TokenScript engine knows how to get its value when needed. For example, an Action Card of an ENS TokenScript renews the ENS domain and uses the attribute ensName, which was declared in the XML file:

constructor(tokenInstance) {
        this.props = tokenInstance;
        this.props.baseNode = ".eth";
        this.props.fullName = this.props.ensName + this.props.baseNode;
        ...
    }

Once defined, the attribute is available to all of the Card defined for this token in the same TokenScript file without special permissions. It also became available in the The Token Layer to allow functionalities like:

Token Negotiation
Search / index of a token (e.g. in a market place)
Selection
Describe criteria of actions
Set the role of a token

Attributes are just declarations. They are never directly shown to a wallet. They are just here to let the wallet know and to allow TokenScript to build further operations and representations on it. To make them visible you need cards.

Attribute is a categorical declaration. There are other declarations inside the <attribute> tags, for example <origins> or <token>.

If you want TokenScript to query a non-blockchain API for information, like weather or exchange prices from a data provider, currently this can't be part of the attribute tag, but part of an action card.