How to use the Token Instrument package¶

A Token is a simple instrument template whose economic terms on the ledger are defined by two textual fields, namely an id and a description.

It is often used to model financial instruments that do not exhibit complex lifecycling logic, such as currencies.

How to create a Token Instrument¶

The following code snippets are taken from the Getting Started tutorial, which you can install using the Daml assistant.

In order to instantiate a Token Instrument, we first need to create the corresponding instrument factory template

  tokenFactoryCid <- toInterfaceContractId @TokenFactory.I <$> submit bank do
    createCmd Token.Factory with
      provider = bank
      observers = mempty

We can then specify the terms of the instrument and exercise the Create choice in the factory to create the token.

  let
    instrumentId = Id "USD"
    instrumentVersion = "0"
    instrumentKey = InstrumentKey with
      issuer = bank
      depository = bank
      id = instrumentId
      version = instrumentVersion
      holdingStandard = TransferableFungible
  now <- getTime

  submit bank do
    exerciseCmd tokenFactoryCid TokenFactory.Create with
      token = Token with
        instrument = instrumentKey
        description = "Instrument representing units of a generic token"
        validAsOf = now
      observers = mempty

How to lifecycle a Token Instrument¶

Generic corporate actions, such as Distribution events, can be applied to Token Instruments. The Lifecycling section of the Getting Started tutorial shows how this is done in detail.

Frequently Asked Questions¶

How do I transfer or trade a Token Instrument?¶

When you have created a holding on a token instrument this can be transferred to another party. This is described in the Getting Started: Transfer tutorial.

In order to trade a token (transfer it in exchange for cash) you can also initiate a delivery versus payment with atomic settlement. This is described in the Getting Started: Settlement tutorial.