Glossary of concepts¶

Daml¶

Daml is a programming language for writing smart contracts, that you can use to build an application based on a ledger. You can run Daml contracts on many different ledgers.

Contract¶

A contract is an item on a ledger. They are created from blueprints called templates, and include:

data (parameters)
roles (signatory, observer)
choices (and controllers)

Contracts are immutable: once they are created on the ledger, the information in the contract cannot be changed. The only thing that can happen to it is that the contract can be archived.

Active contract, archived contract¶

When a contract is created on a ledger, it becomes active. But that doesn’t mean it will stay active forever: it can be archived. This can happen:

if the signatories of the contract decide to archive it
if a consuming choice is exercised on the contract

Once the contract is archived, it is no longer valid, and choices on the contract can no longer be exercised.

Template¶

A template is a blueprint for creating a contract. This is the Daml code you write.

For full documentation on what can be in a template, see Reference: templates.

Choice¶

A choice is something that a party can exercise on a contract. You write code in the choice body that specifies what happens when the choice is exercised: for example, it could create a new contract.

Choices give you a way to transform the data in a contract: while the contract itself is immutable, you can write a choice that archives the contract and creates a new version of it with updated data.

A choice can only be exercised by its controller. Within the choice body, you have the authorization of all of the contract’s signatories.

For full documentation on choices, see Reference: choices.

Consuming choice¶

A consuming choice means that, when the choices is exercised, the contract it is on will be archived. The alternative is a nonconsuming choice.

Consuming choices can be preconsuming or postconsuming.

Preconsuming choice¶

A choice marked preconsuming will be archived at the start of that exercise.

Postconsuming choice¶

A choice marked postconsuming will not be archived until the end of the exercise choice body.

Nonconsuming choice¶

A nonconsuming choice does NOT archive the contract it is on when exercised. This means the choice can be exercised more than once on the same contract.

Disjunction choice, flexible controllers¶

A disjunction choice has more than one controller.

If a contract uses flexible controllers, this means you don’t specify the controller of the choice at creation time of the contract, but at exercise time.

Party¶

A party represents a person or legal entity. Parties can create contracts and exercise choices.

Signatories, observers, controllers, and maintainers all must be parties, represented by the Party data type in Daml.

Signatory¶

A signatory is a party on a contract. The signatories MUST consent to the creation of the contract by authorizing it: if they don’t, contract creation will fail.

For documentation on signatories, see Reference: templates.

Observer¶

An observer is a party on a contract. Being an observer allows them to see that instance and all the information about it. They do NOT have to consent to the creation.

For documentation on observers, see Reference: templates.

Controller¶

A controller is a party that is able to exercise a particular choice on a particular contract.

Controllers must be at least an observer, otherwise they can’t see the contract to exercise it on. But they don’t have to be a signatory. this enables the propose-accept pattern.

Choice Observer¶

A choice observer is a party on a choice. Choice observers are guaranteed to see the choice being exercised and all its consequences with it.

Stakeholder¶

Stakeholder is not a term used within the Daml language, but the concept refers to the signatories and observers collectively. That is, it means all of the parties that are interested in a contract.

Maintainer¶

The maintainer is a party that is part of a contract key. They must always be a signatory on the contract that they maintain the key for.

It’s not possible for keys to be globally unique, because there is no party that will necessarily know about every contract. However, by including a party as part of the key, this ensures that the maintainer will know about all of the contracts, and so can guarantee the uniqueness of the keys that they know about.

For documentation on contract keys, see Contract keys.

Authorization, signing¶

The Daml runtime checks that every submitted transaction is well-authorized, according to the authorization rules of the ledger model, which guarantee the integrity of the underlying ledger.

A Daml update is the composition of update actions created with one of the items in the table below. A Daml update is well-authorized when all its contained update actions are well-authorized. Each operation has an associated set of parties that need to authorize it:

Updates and required authorization¶
Update action	Type	Authorization
`create`	`(Template c) => c -> Update (ContractId c)`	All signatories of the created contract
`exercise`	`ContractId c -> e -> Update r`	All controllers of the choice
`fetch`	`ContractId c -> e -> Update r`	One of the union of signatories and observers of the fetched contract
`fetchByKey`	`k -> Update (ContractId c, c)`	Same as `fetch`
`lookupByKey`	`k -> Update (Optional (ContractId c))`	All key maintainers

At runtime, the Daml execution engine computes the required authorizing parties from this mapping. It also computes which parties have given authorization to the update in question. A party is giving authorization to an update in one of two ways:

It is the signatory of the contract that contains the update action.
It is element of the controllers executing the choice containing the update action.

Only if all required parties have given their authorization to an update action, the update action is well-authorized and therefore executed. A missing authorization leads to the abortion of the update action and the failure of the containing transaction.

It is noteworthy, that authorizing parties are always determined only from the local context of a choice in question, that is, its controllers and the contract’s signatories. Authorization is never inherited from earlier execution contexts.

Standard library¶

The Daml standard library is a set of Daml functions, classes and more that make developing with Daml easier.

For documentation, see The standard library.

Agreement¶

An agreement is part of a contract. It is text that explains what the contract represents.

It can be used to clarify the legal intent of a contract, but this text isn’t evaluated programmatically.

See Reference: templates.

Create¶

A create is an update that creates a contract on the ledger.

Contract creation requires authorization from all its signatories, or the create will fail. For how to get authorization, see the propose-accept and multi-party agreement patterns.

A party submits a create command.

See Reference: updates.

Exercise¶

An exercise is an action that exercises a choice on a contract on the ledger. If the choice is consuming, the exercise will archive the contract; if it is nonconsuming, the contract will stay active.

Exercising a choice requires authorization from all of the controllers of the choice.

A party submits an exercise command.

See Reference: updates.

Daml Script¶

Daml Script provides a way of testing Daml code during development. You can run Daml Script inside Daml Studio, or write them to be executed on Sandbox when it starts up.

They’re useful for:

expressing clearly the intended workflow of your contracts
ensuring that parties can exclusively create contracts, observe contracts, and exercise choices that they are meant to
acting as regression tests to confirm that everything keeps working correctly

In Daml Studio, Daml Script runs in an emulated ledger. You specify a linear sequence of actions that various parties take, and these are evaluated in order, according to the same consistency, authorization, and privacy rules as they would be on a Daml ledger. Daml Studio shows you the resulting transaction graph, and (if a Daml Script fails) what caused it to fail.

See 2 Testing templates using Daml Script.

Contract key¶

A contract key allows you to uniquely identify a contract of a particular template, similarly to a primary key in a database table.

A contract key requires a maintainer: a simple key would be something like a tuple of text and maintainer, like (accountId, bank).

See Contract keys.

DAR file, DALF file¶

A .dar file is the result of compiling Daml using the Assistant.

You upload .dar files to a ledger in order to be able to create contracts from the templates in that file.

A .dar contains multiple .dalf files. A .dalf file is the output of a compiled Daml package or library. Its underlying format is Daml-LF.

Developer tools¶

Assistant¶

Daml Assistant is a command-line tool for many tasks related to Daml. Using it, you can create Daml projects, compile Daml projects into .dar files, launch other developer tools, and download new SDK versions.

See Daml Assistant (daml).

Studio¶

Daml Studio is a plugin for Visual Studio Code, and is the IDE for writing Daml code.

See Daml Studio.

Sandbox¶

Sandbox is a lightweight ledger implementation. In its normal mode, you can use it for testing.

You can also run the Sandbox connected to a PostgreSQL back end, which gives you persistence and a more production-like experience.

See Daml Sandbox.

Navigator¶

Navigator is a tool for exploring what’s on the ledger. You can use it to see what contracts can be seen by different parties, and submit commands on behalf of those parties.

Navigator GUI¶

This is the version of Navigator that runs as a web app.

See Navigator.

Extractor¶

Extractor is a tool for extracting contract data for a single party into a PostgreSQL database.

See Extractor.

Building applications¶

Application, ledger client, integration¶

Application, ledger client and integration are all terms for an application that sits on top of the ledger. These usually read from the ledger, send commands to the ledger, or both.

There’s a lot of information available about application development, starting with the Application architecture page.

Ledger API¶

The Ledger API is an API that’s exposed by any Daml ledger. Alternative names: Daml Ledger API and gRPC Ledger API if disambiguation from other technologies is needed. See The Ledger API page. It includes the following services.

Command submission service¶

Use the command submission service to submit commands - either create commands or exercise commands - to the ledger. See Command submission service.

Command completion service¶

Use the command completion service to find out whether or not commands you have submitted have completed, and what their status was. See Command completion service.

Command service¶

Use the command service when you want to submit a command and wait for it to be executed. See Command service.

Transaction service¶

Use the transaction service to listen to changes in the ledger, reported as a stream of transactions. See Transaction service.

Active contract service¶

Use the active contract service to obtain a party-specific view of all contracts currently active on the ledger. See Active contracts service.

Package service¶

Use the package service to obtain information about Daml packages available on the ledger. See Package service.

Ledger identity service¶

Use the ledger identity service to get the identity string of the ledger that your application is connected to. See Ledger identity service.

Ledger configuration service¶

Use the ledger configuration service to subscribe to changes in ledger configuration. See Ledger configuration service.

Ledger API libraries¶

The following libraries wrap the ledger API for more native experience applications development.

Java bindings¶

An idiomatic Java library for writing ledger applications. See Java bindings.

Scala bindings¶

An idiomatic Scala library for writing ledger applications. See Scala bindings.

Reading from the ledger¶

Applications get information about the ledger by reading from it. You can’t query the ledger, but you can subscribe to the transaction stream to get the events, or the more sophisticated active contract service.

Submitting commands, writing to the ledger¶

Applications make changes to the ledger by submitting commands. You can’t change it directly: an application submits a command of transactions. The command gets evaluated by the runtime, and will only be accepted if it’s valid.

For example, a command might get rejected because the transactions aren’t well-authorized; because the contract isn’t active (perhaps someone else archived it); or for other reasons.

This is echoed in scenarios, where you can mock an application by having parties submit transactions/updates to the ledger. You can use submit or submitMustFail to express what should succeed and what shouldn’t.

Commands¶

A command is an instruction to add a transaction to the ledger.

Daml-LF¶

When you compile Daml source code into a .dar file, the underlying format is Daml-LF. Daml-LF is similar to Daml, but is stripped down to a core set of features. The relationship between the surface Daml syntax and Daml-LF is loosely similar to that between Java and JVM bytecode.

As a user, you don’t need to interact with Daml-LF directly. But internally, it’s used for:

executing Daml code on the Sandbox or on another platform
sending and receiving values via the Ledger API (using a protocol such as gRPC)
generating code in other languages for interacting with Daml models (often called “codegen”)

General concepts¶

Ledger, Daml ledger¶

Ledger can refer to a lot of things, but a ledger is essentially the underlying storage mechanism for a running Daml applications: it’s where the contracts live. A Daml ledger is a ledger that you can store Daml contracts on, because it implements the ledger API.

Daml ledgers provide various guarantees about what you can expect from it, all laid out in the Daml Ledger Model page.

When you’re developing, you’ll use Sandbox as your ledger.

Trust domain¶

A trust domain encompasses a part of the system (in particular, a Daml ledger) operated by a single real-world entity. This subsystem may consist of one or more physical nodes. A single physical machine is always assumed to be controlled by exactly one real-world entity.