Making stateful Scala APIs functional : Understanding the State Monad  – Part 1

Example of a stateful API

Here is an implementation of a generic stack data structure in Scala.

  import scala.reflect.ClassTag

  class Stack[T: ClassTag](capacity: Int) {

    private val items = new Array[T](capacity)
    private var topIndex: Int = 0

    def isEmpty: Boolean = topIndex == 0

    def isFull: Boolean = topIndex == items.length

    def pop(): T = {
      topIndex -= 1

    def push(item: T): Unit = {
      items(topIndex) = item
      topIndex += 1

    def peek(): T = {
      items(topIndex - 1)

    override def toString: String = s"Stack[topIndex = $topIndex, items= ${items.mkString(",")}]"

  object StackTest extends App {
    val stack = new Stack[Int](3)
    println(s"Pushing 90. Result is: ${stack.push(90)}")
    println(s"Pushing 91. Result is: ${stack.push(91)}")
    println(s"Pushing 92. Result is: ${stack.push(92)}")
    println("Should pop 92: " + stack.pop())
    println(s"Pushing 93. Result is: ${stack.push(93)}")
    println("3 items pushed. Stack is full ? " + stack.isFull)
    //stack.push(94) // throws exception

    * Results:
    * Pushing 90. Result is: ()
    * Pushing 91. Result is: ()
    * Pushing 92. Result is: ()
    * Should pop 92: 92
    * Pushing 93. Result is: ()
    * 3 items pushed. Stack is full ? true

This stack follows the object oriented paradigm — we have an object (Stack) that holds some state (items, topIndex) and defines the valid operations that can be carried out on that state — pop, push, peek, isEmpty

Some disadvantages of our stateful stack API. 

There are 2 issues with the above code I would like to highlight.

Problem 1: When given a reference to this stack, I don’t know if its safe to call pop.

Calling pop on an empty stack will throw an exception. Also, calling push on a full stack will throw an exception. So I need to think carefully about the state the stack is in, before I call pop or push. I can think of 2 choices — I can check if the stack is empty (isEmpty) before calling pop, or full (isFull) before calling push. Alternatively, I can call pop or push and handle any resulting exceptions. Put another way, I cannot write client code that uses this stack, without reasoning a bit about its internal state.

Because of this, we say that the pop and push methods have side-effects. That is:

  1. They change the state of the class variable items, which is outside the local scope of those methods.
  2. Even though the API of pop says it should return a value of type T and push should return a value of type Unit, any code calling these methods can actually get a different result — an exception. In other words, they have an interaction with calling code besides returning a value.
Problem 2: Our stack is not thread safe.

If multiple threads call the pop and push methods concurrently, they will try to read or modify the same area in memory. This race-condition means the JVM can not guarantee what results we actually get. There are ways we can guard against this by synchronising access to stack.items and stack.topIndex, but that is outside the scope of this post. The thing to point out here is that when using our Stack in a multi-threaded context, we have to put in extra thought and work to ensure we do so safely.

Lets remove side-effects, and give Stack a stateless API

Here is an implementation using the Cats library

  import cats.Eval

  import scala.reflect.ClassTag
  import scala.util.{Failure, Success, Try}

  case class Stack[A] private(items: Array[A], topIndex: Int) {
    override def toString: String = s"Stack[topIndex = $topIndex, items= ${items.mkString(",")}]"

  object Stack {

    def empty[A: ClassTag](capacity: Int): Stack[A] = new Stack[A](new Array(capacity), 0)

    def isEmpty[A]: State[Stack[A], Boolean] = State(stack => (stack, stack.topIndex == 0))

    def isFull[A]: State[Stack[A], Boolean] = State(stack => (stack, stack.topIndex == stack.items.length))

    def pop[A]: State[Stack[A], Try[A]] = State { stack =>
      val newTopIndex = stack.topIndex - 1
      val item = Try(stack.items(newTopIndex))
      val newStack = Stack(stack.items, newTopIndex)
      (newStack, item)

    def push[A](item: A): State[Stack[A], Try[Unit]] = State { stack =>
      Try {
        val copyItems = stack.items.clone()
        copyItems(stack.topIndex) = item
        val newTopIndex = stack.topIndex + 1
        Stack(copyItems, newTopIndex)
      } match {
        case Success(newStack) => (newStack, Success(()))
        case Failure(e) => (stack, Failure(e))

    def peek[A](): State[Stack[A], Try[A]] = State { stack =>
      (stack, Try(stack.items(stack.topIndex - 1)))

  object StackTest extends App {
    val stack: Stack[Int] = Stack.empty[Int](capacity = 3)
    val stackOperations1 = for {
      s0 <- Stack.push(90)
      _ = println(s"Pushing 90. Result is: $s0")
      s1 <- Stack.push(91)
      _ = println(s"Pushing 91. Result is: $s1")
      s2 <- Stack.push(92)
      _ = println(s"Pushing 92. Result is: $s2")
      s3 <- Stack.pop[Int]
      _ = println(s"Pop stack. Result is: $s3")
      s4 <- Stack.push(93)
      _ = println(s"Pushing 93. Result is: $s4")
      s5 <- Stack.isFull[Int]
      _ = println(s"Is stack full ?. Result is: $s5")
      s6 <- Stack.push(94)
      _ = println(s"Pushing 94. Result is: $s6")
    } yield ()

    val eval: Eval[Stack[Int]] = stackOperations1.runS(stack) //Running the computation and printing the final value of the state

    println("\n Now lets the same operations again, but this time examing the state as we go along... \n")

    val stackOperations2 = for {
      _ <- Stack.push(90).inspect(state => println(s"Pushing 90. Current state is: $state"))
      _ <- Stack.push(91).inspect(state => println(s"Pushing 91. Current state is: $state"))
      _ <- Stack.push(92).inspect(state => println(s"Pushing 92. Current state is: $state"))
      _ <- Stack.pop[Int].inspect(state => println(s"Pop stack. Current state is: $state"))
      _ <- Stack.push(93).inspect(state => println(s"Pushing 93. Current state is: $state"))
      _ <- Stack.isFull[Int].inspect(state => println(s"Is stack full ? Current state is: $state"))
      _ <- Stack.push(94).inspect(state => println(s"Pushing 94. Current state is: $state"))
    } yield ()

    println(stackOperations2.runS(stack).value) //Running the computation and printing the final value of the state


    * Results
    * Pushing 90. Result is: Success(())
    * Pushing 91. Result is: Success(())
    * Pushing 92. Result is: Success(())
    * Pop stack. Result is: Success(92)
    * Pushing 93. Result is: Success(())
    * Is stack full ?. Result is: true
    * Pushing 94. Result is: Failure(java.lang.ArrayIndexOutOfBoundsException: 3)
    * Stack[topIndex = 3, items= 90,91,93]
    * Now lets the same operations again, but this time inspecting the state as we go along...
    * Pushing 90. Current state is: Stack[topIndex = 1, items= 90,0,0]
    * Pushing 91. Current state is: Stack[topIndex = 2, items= 90,91,0]
    * Pushing 92. Current state is: Stack[topIndex = 3, items= 90,91,92]
    * Pop stack. Current state is: Stack[topIndex = 2, items= 90,91,92]
    * Pushing 93. Current state is: Stack[topIndex = 3, items= 90,91,93]
    * Is stack full ? Current state is: Stack[topIndex = 3, items= 90,91,93]
    * Pushing 94. Current state is: Stack[topIndex = 3, items= 90,91,93]
    * Stack[topIndex = 3, items= 90,91,93]

Preparing for the Lagos Scala Meetup Coding Dojos



For those who are new to Scala, and will be joining us at any of our Lagos Scala Meetup events, here is a quick guide on setting up your laptop with Scala for our coding dojos:

  1. Install the Java JDK 
  2.  Install Scala 
  3. Install SBT for Windows , Linux  and Mac
  4.  Install IntelliJ (Or whichever Scala IDE you prefer). You can install the free IntelliJ Community Edition.
  5.  Install the IntelliJ Scala plugin. Here is how to install IntelliJ plugins .

And you are good to go!

Alternatively, you can also follow this handy setup guide prepared by Ikenna Ogbaije.

One last thing you may want to install (and this is really not essential), is the Ammonite REPL – an improved Scala Read Evaluate Print Loop.

Amdahl’s Law

Amdahls’s Law

Amdahl’s law describes the increase in speed that can be gained from parallelizing a computation across multiple processors. It is defined by:
S = 1 / ( 1 – p + p/n)
S= the Speedup gained by running a computation in parallel. This is the time taken to run the computation on a single processor /  time taken to run the computation on n processors.
p = the fraction of the job that can be executed in parallel.
N = the number of processors

The above formula is derived as follows:
Time taken to run a computation on multiple processors = time taken for the parallelizable part of the job + time taken on the non-parallelizable part of the job
Time taken on parallelizable part of the job = Parallelizable fraction of the job / number of processors
= p/n

The sequential part of the job is given by 1-p

Note that part of the non-parallelizable, or sequential part of the computation may involve the overhead of coordinating the multiple processors doing the work.

Thus the ratio of the sequential to the parallelizable part is given by :
S = 1 / (1-p + p/n)

For a perfectly parallelizable job running on 5 processors, the Speedup is
S= 1/ (1-1+ 1/5 ) = 5 times speedup (500%)
For a job that is 80% parallelizable
S= 1/(1-0.8 + 1/0.8) = = 1/1.45 = 45 %  speedup


  1. Maurice Herlihy and Nir Shavit. 2008. The Art of Multiprocessor Programming. Morgan Kaufmann Publishers Inc., San Francisco, CA, USA.

An Introduction to Equity Swaps

What is an Equity Swap?

A swap is a financial contract that involves two counterparties exchanging cash flows over a regular period. An equity swap is a swap in which at least one of the cash flows is based on the performance of a stock or index (Chase, 2004; Cont, 2010; Faboozzi, 2008). One counterparty pays to the other the return or performance of a stock, basket of stocks or an equity index. In return the other counterparty pays a return based on a fixed interest rate, floating interest rate or another stock or index. For an equity swap in which one of the cash flows is based on a floating interest rate, this can be visualized in the diagram below:


The two cash flows in the above diagram are described as legs (Kozul, 2011, p.74). The cash flow based on the equity performance is referred to as the equity leg, and the cash flow based on interest rates is referred to as the financing leg.

From the above, and based on the nature of the cash flows exchanged there can be many variations of equity swaps. For example:

  1. one cash flow can be based of the performance of an equity underlying, while the other cash flow can be based on a floating interest rate. (A floating or variable interest rate is a rate that changes based on the market or some index).
  2. one cash flow can be based of the performance of an equity underlying, while the other cash flow can be based on a fixed interest rate
  3. one cash flow can be based of the performance of a foreign equity underlying denominated in a foreign currency. Depending on how the exchange rate is calculated, they may be termed compo or quanto equity swaps (Ramirez, 2011).
  4. Both cash flows can be based on the performance of different equity underlyings – Rainbow or Blended swaps (Eales and Moorad, 2003)

The cash flows may be exchanged once at the end of the contract, or they may be exchanged periodically during a notional reset.
Consider an equity swap with a financing leg based on a floating rate, as shown in the diagram. The party that pays the financing amount payments or floating amount and receives the equity performance payment (Party A) is called equity amount receiver. The party that pays out the performance of the equity underlying and receives the floating amount payments (Party B) is called the equity amount payer. The equity amount payer can be thought of as ‘carrying the underlying stock’ and is paid the floating amount to finance this holding. Equity swaps thus enable an investor to participate in the performance of an equity index without an initial investment or directly owning the stock. In this light, equity swaps can be viewed as a leveraged trading facility for Party A (Chase, 2004, p. 6).

When Party A and Party B enter into a swap contract, they decide on a currency amount on which the cash flows will be calculated. This amount is called an equity notional principal. (Chase, 2004; Cont, 2010). The notional is the underlying quantity on which payment obligations and interest rates are calculated. The payments are made on regularly scheduled dates over a specified period. At the start of the contract, the notional principal is equivalent to the value of the equity underlying on which the contract is based. To reduce for counterparty risk, the notional amount is recalculated or reset on specified valuation dates.
Equity Swaps are formalized through a confirmation. A confirmation document is an agreement that is legally subject to the ISDA mater agreement signed by the 2 parties.

Example of an Equity Swap Contract

Suppose Acme Ltd and Foo Investment Bank enter into an equity swap contract for £1 million on the stock of Vodafone (VOD:LN) on 24th August 2014. The terms of the swap contract are shown in the table below:

Contract terminology Example value Note
General Terms
Party A Acme Ltd The parties to the contract.
Party B Foo Investment Bank Plc
Trade date 3 Nov 2014 The date the counterparties agree the terms of the equity swap.
Effective date 5 Nov 2014 The date the swap starts. Interest period starts on the effective date.
Termination date 5 Nov 2015 The date on which the swap contract ends
Underlying Vodafone Group plc (Reuters code: VOD.L)  

Details of the underlying stock on which the contract is based.

Underlying currency GBP
Exchange London Stock Exchange
Equity Amounts
Equity Amount payer Party B
Equity Amount receiver Acme Ltd
Number of shares 100,000
Initial price of underlying £226.79 The initial price of the underlying. This is either the initial price of of the stock if the entire quantity is purchased in one block, or the volume-weighted average price per stock if the shares are purchased over several transactions.
Final price of underlying Closing price of the underlying on the Exchange on the Valuation Day at the Valuation Time.
Equity Notional principal  

£22,679,000 (on the Trade Date, the number of shares multiplied by the initial price)

The currency amount equivalent to the value of the number of shares of the underlying.  Equity notional = number of shares x initial price of underlying.
Equity Notional Reset Not Applicable If notional resets apply, the contract notional will be  recalculated on the valuation date.
Type of return Total Return Equity leg payments will include increase in the price of the underlying as well as  dividends
Valuation date(s) 5 November 2015
Valuation Time Closing time of the Exchange
Floating Amounts The section shows details of the finance leg of the swap. The floating amount is paid by the equity amount receiver to the equity amount payer. It reflects the cost of carrying the underlying. It is usually based on a floating interest rate (like Libor) plus a spread.
Equity Amount receiver Party A
Payment Dates 5 Feb 2015, 5 May 2015, 5 Aug 2015, 5 Nov 2015
Floating rate
Calculation agent Foo Investment Bank Plc The calculation agent calculates how much each of the parties owe each other.
Floating rate option LIBOR
– Initial rate fixed on the trade date- Subsequent rates set on the last floating amount payment date
Designated maturity 3 Month
Spread Plus 50 bps (0.5%) The spread covers the dealers costs  (e.g hedging costs) and includes a mark up for the transaction
Floating rate day count fraction Actual / 360
Cash Settlement
Cash settlement Applicable A cash settled equity swap
Settlement Currency GBP
Settlement date 3 Business Days following the Valuation Date. (10 Nov. 2015) On the settlement date, the equity receiver amount receiver gets the equity performance, and the contract terminates.
Dividends The stock on which the equity swap is based may accrue dividends during the term of the contract. The dividend amount is calculated based on the total stock position held. The equity amount receiver may or may not receive this dividend amount depending on if the swap is a total return or price return swap
Dividend period The period commencing on the effective date and ending on the termination date.
Dividend amount 100% of the Ex Div Amount
Dividend payment date The next Payment Date following the date of receipt of the cash dividend by the holders of record of the underlying.



  1. The contract states that the initial LIBOR rate is fixed on the trade date, and subsequent rates are set on the last floating amount payment date. Let’s assume that the rate on the trade date is 0.58563 % and 0.58313 % on 5th 2015, 0.58688% on 5th May 2015, 0.58375% and 5th Aug. 2015.
  2. Assume a dividend of 10p per share is announced on VOD.L on the 6th of July 2015, and is paid on the 12th of October 2015.

Cashflow calculations:

At the start of the swap contract, the value of the contract is zero. During the life of the swap, market conditions will change. As the price of the equity index changes, the 2 legs are valued separately, and the net value is paid/received.

  1. 5th Feb 2015 (1st Payment date)
    Finance leg payment = notional * day count fraction * interest rate
    Day count fraction = (Days between 5th Nov 2014 and 5th Feb 2015) / 360  = 92/ 365 = 0.256
    Interest rate = libor + spread = 0.0058563 + 0.005 = 0.0108563%
    Finance leg payment = £22,679,000 * 0.256 * 0.0108563% =   £62,920.34
    Equity leg payment = 0
  2. 5th May 2015 (2nd Payment Date)
    Finance leg payment = notional * day count fraction * interest rate
    Day count fraction = (Days between 5th Feb 2015 and 5th May 2014) / 360  = 89 / 365 = 0.247
    Interest rate = libor + spread = 0.0058313 + 0.005 =  0.0108313%
    Finance leg payment = £22,679,000 * 0.247 * 0.0108313% =   £60,728.42
    Equity leg payment = 0
  3. 5th August 2015 (3rd Payment Date)
    Similar to the above, the finance leg payment will be  £62,992.79 and the equity leg payment will be £0.
  4. 5th November 2015 (4th Payment Date)
    Similar to the above, the finance leg payment will be  £62,811.38  and the equity leg payment will be £0.
  5. 10th November 2015 (Settlement Date)
    Finance Leg Payment = 0Equity Leg Payment = Capital Gains + Dividend Gains
    Capital Gains = notional * % change in underlying.
    % change in underlying = [(237.70 – 226.70 )/ 226.70 ] * 100% = 4.852%
    Captial Gains  = £22,679,000 * 5.69% = £1,100,436.70
    Dividend Gains = Net Dividend * Number of Shares = 0.09 * 100,000 = £9,000.00
    Equity Leg Payment = £1,100,436.70+ £9,000.00 = £1,109,436.70


During the term of the contract, ACME Ltd has made payments totalling £249,452.93 and received £1,109,436.70 in return based on an increase in Vodafone stock by 4.85%.


 Equity Notional Resets

It is usual for the valuation date of long term equity swaps to coincide with their payment date of the finance leg. In that case, the parties exchange payments and the swap notional is reset for the next period (Ramirez, 2011).

Cash and Physical Settlement

Swaps can be cash-settled or physically settled. Cash settled swaps the equity swap receiver receives the equity appreciation in cash (and pays out the depreciation) (Ramirez, 2011). In physically settled swaps, on the termination date of the contract the equity amount receiver will receive a specified quantity of the equity underlying. In exchange the equity amount receiver will pay the equity amount payer the notional amount.

In return the equity swap receiver agrees to buy the underlying shares at an agreed price (and may receive dividend payments). In return, the equity swap receiver pays out a stream of interest payments to the equity swap payer. (Ramirez, 2011).


Price Return vs Total Return Equity Swaps

In price return equity swaps, the equity amount receiver gets the performance of the equity based only on the reference price – no dividend performance is included. In total return equity swaps, the equity amount receiver gets the performance of the equity, including any dividend payments (Ramirez, 2011).


Advantages of Equity Swaps

  1. Portfolio diversification: For example, an investment fund may wish to diversify by minimising their exposure to a particular stock, but they may not wish to loose ownership of that stock. The fund can enter into a swap contract to pay out the performance of the stock, and in return receive the performance of a different stock or index. (Chase, 2004)
  2. International exposure: A client can use an equity swap to participate in the performance of an international stock without actually purchasing it.
  3. Low cost alternative: An equity swap could be seen as a cheaper alternative to other investment instruments that may achieve the same effect. For example, multiple futures contracts can achieve the same effect, but would attract higher transaction costs and taxes. Directly purchasing a stock or index is another alternative, but it may involve high funding costs, transaction costs, and if a large quantity is involved then availability may be an issue. Equity swaps on the other hand offer lower transaction costs, and involve no custodial costs, or withholding taxes for foreign equities (Chase, 2004; Eales and Moorad, 2003).
  4. Circumnavigate government restrictions: Equity swaps can be used to invest in foreign markets that may not be accessible due to government restrictions on the foreign ownership of stocks. Equity swaps can be used in this was as they allow investors participate in performance of the underlying but not directly own the shares (Merton, 1990; Eales and Moorad, 2003).
  5. Market invisibility: Selling a large quantity of a particular stock on the stock exchange could send a public signal to the market. As an OTC transaction, equity swaps can be used (for a limited time) to decrease a large exposure to a company’s stock without making it visible to the market. (Eales and Moorad, 2003).

5.    Disadvantages of Equity Swaps

  1. Significant cash flows: Involve significant cash flows that must be funded.
  2. Equity swaps cannot be open-ended: Equity swaps must have a termination date. Equity swaps can be used to mimic an equity position, but the contract must be re-established after it terminates to continue participating in the equity. (Chase, 2004).
  3. Credit risk: Equity swaps are subject to credit risk that does not occur when holding an equity directly – the swap dealer can default on their obligation.

Valuation of Equity Swaps

When a swap contract is agreed, there is no cash exchanged up front. The interest rate on the finance leg is calculated so that the present value of the equity payments equals the present value of the interest payments. This means that at the start of the contract, it has zero market value. During the life of the swap contract, as market conditions change its value will no longer be zero. (Chase, 2004).

The ‘pricing of a swap’ refers to the interest rate used to determine the finance leg. However it is a misleading term as no price is determined. The interest rate is picked so that the market value of the swap at the beginning is zero (Chase, 2004).

For fixed rate equity swaps, the price (interest rate) is determined by the formula:

Once the dealer determines the interest rate, the dealer would include a premium into the rate charged the client, to cover the hedging costs and other costs involved in rendering the service. If the dealer is receiving the finance leg payments, the dealer would add a premium to the interest rate. Conversely if the dealer is making the fixed leg payments, the dealer would subtract a premium from the calculated rate (Chase, 2004).



  1. Cont, R. 2010. Encyclopedia of quantitative finance. Chichester: Wiley
  2. Fabozzi, F. J., 2008. Handbook of Finance: Financial Markets and Instruments. New Jersey: John Wiley & Sons.
  3. Kozul, N., 2011. Mastering Investment Banking Securities. Harlow: Pearson Education.
  4. Chance, D. M., 2004. Equity Swaps and Equity Investing. Journal of Alternative Investments. 7 (1), pp. 75 – 97.
  5. Merton, R. C., 1990 The Financial System and Economic Performance. Journal of Financial Services Research, 4 (1990), pp. 263-300.
  6. Eales, B., and Moorad C., 2003. Derivative instruments: a guide to theory and practice. Butterworth-Heinemann.
  7. Ramirez, J. 2011. Handbook of Corporate Equity Derivatives and Equity Capital Markets. John Wiley & Sons