How To Use the Option Extension Package

To follow the script used in this tutorial, you can clone the Daml Finance repository. In particular, the Option test folder Instrument/Option/Test/ is the starting point of this tutorial.

How To Create an Option Instrument

In order to create an option instrument, you first have to decide what type of option you need. The option extension package currently supports the following types of options:

European Options

European options give the holder the right, but not the obligation, to buy (in case of a call) or to sell (in case of a put) the underlying asset at predetermined strike price on a specific expiry date in the future.

Daml Finance supports two types of European Options:

Physically settled European Option

The EuropeanPhysical instrument models physically settled call or put options.

There are two important characteristics of this instrument:

  1. physical settlement: option holders that choose to exercise will buy (in case of a call) or sell (in case of a put) the underlying asset at the predetermined strike price. Since this option instrument is physically settled, it means that the underlying asset will change hands.
  2. manual exercise: This option instrument is not automatically exercised. Instead, the option holder must manually decide whether or not to exercise. This is done by making an Election.

As an example, consider an option instrument that gives the holder the right to buy AAPL stock at a given price. This example is taken from Instrument/Option/Test/EuropeanPhysical.daml , where all the details are available. Also, Check out the Election based lifecycling tutorial for more details on how how to define and process an Election in practice.

You start by defining the terms:

    strike = 50.0
    expiryDate = date 2019 May 15

Now that the terms have been defined, you can create the option instrument:

    let
      instrument = InstrumentKey with
        issuer
        depository
        id = Id label
        version = "0"
        holdingStandard

    cid <- submitMulti [issuer] [publicParty] do
      exerciseCmd europeanPhysicalOptionFactoryCid EuropeanPhysicalOptionFactory.Create with
        european = EuropeanPhysicalOption.European with
          instrument
          description
          expiryDate
          optionType
          strike
          referenceAsset
          ownerReceives
          currency
          lastEventTimestamp
          prevEvents = []
        observers = Map.fromList observers

Once this is done, you can create a holding on it using Account.Credit.

Cash-settled European Option

The EuropeanCash instrument models cash-settled, auto-exercising call or put options. They are similar to the EuropeanPhysical instrument described above, but there are two important differences:

  1. cash settlement: This means that the underlying asset will not change hands. Instead, a cash settlemement will take place (if the option is exercised).
  2. automatic exercise: This option instrument is automatically exercised. No manual Election is required by the holder.

As an example, consider an option instrument that gives the holder the right to buy AAPL stock at a given price. This example is taken from Instrument/Option/Test/EuropeanCash.daml , where all the details are available.

You start by defining the terms:

    strike = 50.0
    expiryDate = date 2019 May 15
    referenceAssetId = "AAPL-CLOSE"

Now that the terms have been defined, you can create the option instrument:

    let
      instrument = InstrumentKey with
        issuer
        depository
        id = Id label
        version = "0"
        holdingStandard

    cid <- submitMulti [issuer] [publicParty] do
      exerciseCmd europeanCashOptionFactoryCid EuropeanCashOptionFactory.Create with
        european = EuropeanCashOption.European with
          instrument
          description
          expiryDate
          optionType
          strike
          referenceAssetId
          ownerReceives
          currency
          lastEventTimestamp
        observers = Map.fromList observers

Once this is done, you can create a holding on it using Account.Credit.

If the close price of AAPL on the expiry date is above the strike price, the option holder would profit from exercising the option and buying the stock at the strike price. The value of the option would be spot - strike. Since this option type is cash-settled, this amount would be paid in the option currency after lifecycling.

On the other hand, if the close price of AAPL is below the strike price, the option would expire worthless.

This option instrument is automatically exercised. This means that the decision whether or not to exercise is done automatically by comparing the strike price to an observation of the close price. For this to work, you need to define an Observation as well:

  let observations = Map.fromList [(dateToDateClockTime $ date 2019 May 15, 48.78)]
  observableCid <- toInterfaceContractId <$> submit issuer do
    createCmd Observation with
      provider = issuer; id = Id referenceAssetId; observations; observers = mempty

Barrier Option

The BarrierEuropeanCash instrument models barrier options. They are similar to the EuropeanCash instrument described above, but also contain a barrier that is used to activate (or, alternatively, knock out) the option. The BarrierTypeEnum describes which barrier types are supported.

As an example, consider an option instrument that gives the holder the right to buy AAPL stock at a given price. However, if AAPL ever trades at or below a given barrier level, the option is knocked out (which means that it expires worthless). In other words, this describes a DownAndOut option. This example is taken from Instrument/Option/Test/BarrierEuropeanCash.daml , where all the details are available.

You start by defining the terms:

    barrier = 30.0
    barrierType = DownAndOut
    barrierStartDate = date 2019 Jan 20
    strike = 40.0
    expiryDate = date 2019 May 15
    referenceAssetId = "AAPL-CLOSE"

Now that the terms have been defined, you can create the option instrument:

    let
      instrument = InstrumentKey with
        issuer
        depository
        id = Id label
        version = "0"
        holdingStandard

    cid <- submitMulti [issuer] [publicParty] do
      exerciseCmd barrierOptionFactoryCid BarrierEuropeanCashOptionFactory.Create with
        barrierEuropean = BarrierEuropean with
          instrument
          description
          expiryDate
          optionType
          strike
          barrier
          barrierType
          barrierStartDate
          referenceAssetId
          ownerReceives
          currency
          lastEventTimestamp
        observers = Map.fromList observers

Once this is done, you can create a holding on it using Account.Credit.

Compared to the EuropeanCash option this instrument needs to be lifecycled not only at expiry but also during its lifetime in case of a barrier hit. This is done in the same way as lifecycling at maturity, i.e. an Observation is provided for the reference asset identifier, containing the date and the underlying price.

Dividend Option

The Dividend instrument models physically settled, manually exercised dividend options. For reference, a dividend option gives the holder the right to choose one out of several dividend payouts, on a specific expiry date in the future. The following payout types are supported:

  1. Cash: The dividend is paid in cash. This a mandatory option. In addition, the issue can offer:
  2. Shares: The dividend is paid in shares. To the investor this is similar to a Bonus Issue.
  3. CashFx: The dividend is paid in cash in a foreign currency.

As an example, consider an option instrument that gives the holder the right to choose to receive AAPL dividends either as cash, shares or cash in a foreign currency (EUR). This example is taken from Instrument/Option/Test/Dividend.daml , where all the details are available.

You start by defining the terms:

    expiryDate = date 2019 May 15
    cashQuantity = qty 0.19 cashInstrument
    sharesQuantity = Some $ qty 0.0041 aaplInstrument
    fxQuantity = Some $ qty 0.17 eurInstrument

Now that the terms have been defined, you can create the option instrument:

    let
      instrument = InstrumentKey with
        issuer
        depository
        id = Id label
        version = "0"
        holdingStandard

    cid <- submitMulti [issuer] [publicParty] do
      exerciseCmd dividendOptionFactoryCid DividendOption.Create with
        dividend = Dividend with
          instrument
          description
          expiryDate
          cashQuantity
          sharesQuantity
          fxQuantity
          lastEventTimestamp
          prevEvents = []
        observers = Map.fromList observers

Once this is done, you can create a holding on it using Account.Credit.

On the expiry date, the option holder will make an Election out of the available choices. The lifecycling of this option works in the same way as for physically settled European options.

Frequently Asked Questions

How do I transfer or trade an option?

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

In order to trade an option (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.

How do I calculate settlement payments for an option?

On the expiry date, the issuer will need to lifecycle the European option. This will result in a lifecycle effect for the payoff, which can be cash settled. This is described in detail in the Lifecycling and the Intermediated Lifecycling tutorials.