Scala bindings¶

The Scala bindings are deprecated as of 2020-10-14.

This page provides a basic Scala programmer’s introduction to working with Daml Ledgers, using the Scala programming language and the Ledger API.

Introduction¶

The Scala bindings is a client implementation of the Ledger API. The Scala bindings library lets you write applications that connect to a Daml Ledger using the Scala programming language.

There are two main components:

Scala codegen

Daml to Scala code generator. Use this to generate Scala classes from Daml models. The generated Scala code provides a type safe way of creating contracts (CreateCommand) and exercising contract choices (ExerciseCommand).
Akka Streams-based API

The API that you use to send commands to the ledger and receive transactions back.

In order to use the Scala bindings, you should be familiar with:

Getting started¶

If this is your first experience with the Scala bindings library, we recommend that you start by looking at the quickstart-scala example.

To use the Scala bindings, set up the following dependencies in your project:

lazy val codeGenDependencies = Seq(
  "com.daml" %% "bindings-scala" % damlSdkVersion
)

lazy val applicationDependencies = Seq(
  "com.daml" %% "bindings-akka" % damlSdkVersion
)

We recommend separating generated code and application code into different modules. There are two modules in the quickstart-scala example:

scala-codegen

This module will contain only generated Scala classes.
application

This is the application code that makes use of the generated Scala classes.

lazy val `scala-codegen` = project
  .in(file("scala-codegen"))
  .settings(
    name := "scala-codegen",
    commonSettings,
    libraryDependencies ++= codeGenDependencies,
  )

lazy val `application` = project
  .in(file("application"))
  .settings(
    name := "application",
    commonSettings,
    libraryDependencies ++= codeGenDependencies ++ applicationDependencies,
  )
  .dependsOn(`scala-codegen`)

Generating Scala code¶

Install the latest version of the SDK.
Build a DAR file from a Daml model. Refer to Building Daml projects for more instructions.
Configure codegen in the daml.yaml (for more details see Daml codegen documentation).

codegen:
  scala:
    package-prefix: com.daml.quickstart.iou.model
    output-directory: scala-codegen/src/main/scala
    verbosity: 2

Run Scala codegen:
```
$ daml codegen scala
```

If the command is successful, it should print:

Scala codegen
Reading configuration from project configuration file
[INFO ] Scala Codegen verbosity: INFO
[INFO ] decoding archive with Package ID: 5c96aa21d5f38386833ff47fe1a7562afb5b3fe5be520f289c42892dfb0ef42b
[INFO ] decoding archive with Package ID: 748d55be531976e941076a44fe8c06ad4a7bdb36160711dd0204b5ab8dc77e44
[INFO ] decoding archive with Package ID: d841a5e45897aea965ab7699f3e51613c9d00b9fbd1bb09658d7fb00486f5b57
[INFO ] Scala Codegen result:
Number of generated templates: 3
Number of not generated templates: 0
Details:

The output above tells that Scala codegen read configuration from daml.yaml and produced Scala classes for 3 templates without errors (empty Details: line).

Example code¶

In this section we will demonstrate how to use the Scala bindings library.

This section refers to the IOU Daml example from the Quickstart guide and quickstart-scala example that we already mentioned above.

Please keep in mind that quickstart-scala example compiles with -Xsource:2.13 scalac option, this is to activate the fix for a Scala bug that forced users to add extra imports for implicits that should not be needed.

Create a contract and send a CreateCommand¶

To create a Scala class representing an IOU contract, you need the following imports:

import com.daml.ledger.client.binding.{Primitive => P}
import com.daml.quickstart.iou.model.{Iou => M}

the definition of the issuer Party:

  private val issuer = P.Party("Alice")

and the following code to create an instance of the M.Iou class:

  val iou = M.Iou(
    issuer = issuer,
    owner = issuer,
    currency = "USD",
    amount = BigDecimal("1000.00"),
    observers = List(),
  )

To send a CreateCommand (keep in mind the following code snippet is part of the Scala for comprehension expression):

    createCmd = iou.create
    _ <- clientUtil.submitCommand(issuer, issuerWorkflowId, createCmd)
    _ = logger.info(s"$issuer created IOU: $iou")
    _ = logger.info(s"$issuer sent create command: $createCmd")

For more details on how to submit a command, please refer to the implementation of com.daml.quickstart.iou.ClientUtil#submitCommand.

Receive a transaction, exercise a choice and send an ExerciseCommand¶

To receive a transaction as a newOwner and decode a CreatedEvent for IouTransfer contract, you need the definition of the newOwner Party:

  private val newOwner = P.Party("Bob")

and the following code that handles subscription and decoding:

    _ <- clientUtil.subscribe(newOwner, offset0, None) { tx =>
      logger.info(s"$newOwner received transaction: $tx")
      decodeCreated[M.IouTransfer](tx).foreach { contract: Contract[M.IouTransfer] =>
        logger.info(s"$newOwner received contract: $contract")

To exercise IouTransfer_Accept choice on the IouTransfer contract that you received and send a corresponding ExerciseCommand:

        val exerciseCmd = contract.contractId.exerciseIouTransfer_Accept(actor = newOwner)
        clientUtil.submitCommand(newOwner, newOwnerWorkflowId, exerciseCmd) onComplete {
          case Success(_) =>
            logger.info(s"$newOwner sent exercise command: $exerciseCmd")
            logger.info(s"$newOwner accepted IOU Transfer: $contract")
          case Failure(e) =>
            logger.error(s"$newOwner failed to send exercise command: $exerciseCmd", e)
        }

Fore more details on how to subscribe to receive events for a particular party, please refer to the implementation of com.daml.quickstart.iou.IouMain#newOwnerAcceptsAllTransfers.

Authorization¶

Some ledgers will require you to send an access token along with each request. To learn more about authorization, read the Authorization overview.

To use the same token for all ledger API requests, use the token field of LedgerClientConfiguration:

  private val clientConfig = LedgerClientConfiguration(
    applicationId = ApplicationId.unwrap(applicationId),
    ledgerIdRequirement = LedgerIdRequirement.none,
    commandClient = CommandClientConfiguration.default,
    sslContext = None,
    token = None,
  )

To specify the token for an individual call, use the token parameter:

transactionClient.getLedgerEnd() // Uses the token specified in LedgerClientConfiguration
transactionClient.getLedgerEnd(token = acessToken) // Uses the given token

Note that if your tokens can change at run time (e.g., because they expire or because you switch users), you will need to specify them on a per-call basis as shown above.