Crate daml

Daml - The smart contract language for building distributed applications on a safe, privacy-aware runtime.

Library Crates

The following library crates are provided for working with Daml in Rust:

crate	description
daml	Daml prelude & common entry point
daml-grpc	Daml Ledger GRPC API bindings
daml-json	Daml Ledger JSON API bindings
daml-codegen	Library for generate Rust GRPC API bindings from Daml archives
daml-derive	Attribute macros for generating Rust GRPC API bindings from Daml archives
daml-macro	Helper macros for working with Daml GRPC values
daml-util	Utilities for working with Daml ledgers
daml-lf	Library for working with Daml-LF archives
daml-bridge	Library for Daml JSON <> GRPC Ledger bridging

Features

The following feature may be enabled:

• grpc - enable the daml-grpc library
• json - enable the daml-json library
• codegen - enable the daml-codegen library
• derive - enable the daml-derive library
• macros - enable the daml-macros library
• util - enable the daml-util library
• lf - enable the daml-lf library (excludes expressions)
• lf-full - enable the daml-lf library (includes expressions)
• prelude - enable the daml prelude
• full - enables: grpc, json, macros, derive, codegen, lf-full, util, prelude
• sandbox - enable sandbox testing features

Usage

Applications should depend on the daml crate directly and specify the appropriate features to enable the required functionality:

[dependencies]
daml = { version = "0.2.2", features = [ "full" ] }

Tour

The following is a brief tour of the facilities these libraries provide.

Working with GRPC

To connect to a Daml ledger via the GRPC API you can use the DamlGrpcClient which can be created using the DamlGrpcClientBuilder. This client exposes all Daml GRPC services such as the DamlCommandService. All GRPC services use the DamlValue type which is generic GRPC representation of Daml types.

The DamlSimpleExecutor which can be created using the DamlSimpleExecutorBuilder provides a higher level API for creating and executing commands against the GRPC Daml ledger API.

A DamlSandboxTokenBuilder is provided for constructing JWT tokens that are suitable for use with the Daml sandbox and other ledgers.

The daml_value! macro can be used to simplify creating a DamlValue and the daml_path! macro can be used to extract data values from a DamlValue.

A sample application which uses many of these facilities is available in the grpc-demo example. See also the integration_tests in the daml-grpc crate for comprehensive usage examples.

Working with JSON

To connect to a Daml ledger via the JSON API you can use the DamlJsonClient which can be created using the DamlJsonClientBuilder. This client exposes the full Daml JSON API service which all make use of the generic JSON Value type.

Conversion between the generic GRPC DamlValue and the generic JSON Value representations is provided by JsonValueEncoder and JsonValueDecoder.

It is also possible to convert A Daml JSON API request to a GRPC API command using JsonToGrpcRequestConverter and A Daml GRPC API event to a JSON API response using GrpcToJsonResponseConverter.

A JsonSchemaEncoder is provided to generate JSON Schema documents from Daml elements and archives.

See the integration_tests in the daml_json crate for comprehensive usage examples.

Working with Daml LF

The DarFile, DamlLfArchive and DamlLfArchivePayload types can be used to load and parse existing .dar & .dalf files and access the various element they contain. The DamlElementVisitor provides a means to traverse these elements.

The DamlPackages type provides the ability to extract Daml LF packages from an existing ledger as a collection of DamlLfArchivePayload, DamlLfArchive or combined into a single DarFile file.

You can use DarFile::apply, DamlLfArchive::apply & DamlLfArchivePayload::apply to apply a function to the DarFile, DamlLfArchive and DamlLfArchivePayload types respectively.

If required you may use DarFile::to_owned_archive to convert a DarFile be owned (bounded by 'static) such that it is suitable to be passed to a thread to async executor.

Code Generation

Rust representations of Daml Archives, Packages, Modules, Data, Templates & Choices can be generated or derived using facilities provided by the daml-codegen and daml-derive crates.

The DamlTemplate, DamlChoices, DamlData, DamlVariant & DamlEnum attribute procedural macros allow for Rust types to be annotated such that these can be used with Daml the GRPC ledger API. The attributes tests of the daml-derive crate provides several examples.

The daml_codegen procedural macro is provided to enable generating Rust modules and types for a complete .dar file. See the codegen tests in the daml-derive crate for examples of using the daml_codegen macro.

The daml_codegen function provides a mechanism to perform code generation from build.rs without using a macro. A sample application which uses the daml_codegen function in a build.rs file is available in the codegen-demo example.

Tools

The following standalone tools make use of the daml library:

crate	description
daml-codegen	Generate Rust GRPC API bindings from Daml archives
daml-bridge	Daml JSON <> GRPC Ledger bridge
daml-oas	Generate OpenAPI and AsyncAPI specifications from Daml dar files
daml-darn	Daml Archive cli tool

Examples

Further examples are available in the examples directory.

Modules

prelude

The Daml prelude.