Create Your Own Bindings¶
This page gets you started with creating custom bindings for a Daml Ledger.
Bindings for a language consist of two main components:
- Ledger API
- Client “stubs” for the programming language, – the remote API that allows sending ledger commands and receiving ledger transactions. You have to generate Ledger API from the gRPC protobuf definitions in the daml repository on GitHub. Ledger API is documented on this page: Use the Ledger API With gRPC. The gRPC tutorial explains how to generate client “stubs”.
- A code generator is a program that generates classes representing Daml contract templates in the language. These classes incorporate all boilerplate code for constructing: CreateCommand and ExerciseCommand corresponding for each Daml contract template.
Technically codegen is optional. You can construct the commands manually from the auto-generated Ledger API classes. However, it is very tedious and error-prone. If you are creating ad hoc bindings for a project with a few contract templates, writing a proper codegen may be overkill. On the other hand, if you have hundreds of contract templates in your project or are planning to build language bindings that you will share across multiple projects, we recommend including a codegen in your bindings. It will save you and your users time in the long run.
Note that for different reasons we chose codegen, but that is not the only option. There is really a broad category of metaprogramming features that can solve this problem just as well or even better than codegen; they are language-specific, but often much easier to maintain (i.e. no need to add a build step). Some examples are:
Build Ledger Commands¶
No matter what approach you take, either manually building commands or writing a codegen to do this, you need to understand how ledger commands are structured. This section demonstrates how to build create and exercise commands manually and how it can be done using contract classes.
Let’s recall an IOU example from the Quickstart guide, where Iou template is defined like this:
template Iou with issuer : Party owner : Party currency : Text amount : Decimal observers : [Party]
If you do not specify any of the above fields or type their names or values incorrectly, or do not order them exactly as they are in the Daml template, the above code will compile but fail at run-time because you did not structure your create command correctly.
To build ExerciseCommand for Iou_Transfer:
choice Iou_Transfer : ContractId IouTransfer with newOwner : Party controller owner do create IouTransfer with iou = this; newOwner
When creating custom bindings for Daml Ledgers, you will need to:
- generate Ledger API from the gRPC definitions
- decide whether to write a codegen to generate ledger commands or manually build them for all contracts defined in your Daml model.
The above examples should help you get started. If you are creating custom binding or have any questions, see the Getting Help page for how to get in touch with us.
- gRPC documentation: https://grpc.io/docs/
- Documentation for Protobuf “well known types”: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf
- Daml Ledger API gRPC Protobuf definitions
- current main: https://github.com/digital-asset/daml/tree/main/ledger-api/grpc-definitions
- for specific versions: https://github.com/digital-asset/daml/releases