Glossary of concepts¶
Contract, contract instance¶
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.
They’re sometimes referred to as a contract instance to make clear that this is an instantiated contract, as opposed to a template.
Active contract, archived contract¶
- 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.
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.
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.
For full documentation on choices, see Reference: choices.
For documentation on signatories, see Reference: templates.
For documentation on observers, see Reference: templates.
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 instance.
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.
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.
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.
See Reference: updates.
An exercise is an action that exercises a choice on a contract instance on the ledger. If the choice is consuming, the exercise will archive the contract instance; if it is nonconsuming, the contract instance will stay active.
See Reference: updates.
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
Scenarios emulate a real 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 scenario fails) what caused it to fail.
A contract key requires a maintainer: a simple key would be something like a tuple of text and maintainer, like
See Contract keys.
DAR file, DALF file¶
.dar file is the result of compiling DAML using the Assistant.
.dar files to a ledger in order to be able to create contracts from the templates in that file.
.dar contains multiple
.dalf files. A
.dalf file is the output of a compiled DAML package or library. Its underlying format is DAML-LF.
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 SDK tools, and download new SDK versions.
DAML Studio is a plugin for Visual Studio Code, and is the IDE for writing DAML code.
See DAML Studio.
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.
Application, ledger client, integration¶
There’s a lot of information available about application development, starting with the Writing applications using the Ledger API page.
Command submission service¶
Command completion service¶
Active contract service¶
Ledger identity service¶
Ledger API libraries¶
The following libraries wrap the ledger API for more native experience applications development.
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.
This is echoed in scenarios, where you can mock an application by having parties submit transactions/updates to the ledger. You can use
submitMustFail to express what should succeed and what shouldn’t.
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 inside the DAML SDK, 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”)
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 DA Ledger Model page.
When you’re developing, you’ll use Sandbox as your ledger.
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.