Connect to the Ledger

Code fragments are provided for illustration purposes only. They do not comprise a complete, working example.

Creating a Project

Prior to connecting to the ledger, developers should familiarise themselves with the DAML SDK documentation on Ledger API services.

Developers need to establish a development environment. The documentation follows examples using Maven and IntelliJ IDEA. 

Connecting via ledger API connectivity requires files available from the ASX FTP. Details on how to access these files will be provided directly to organisations who have selected to connect by Direct access.

The server contains 2 files - a CertChain file and a zip file containing the Java Classes ( and a Read Me.

The first step is to create a project and add the following dependencies: 

  • Java Bindings
  • Java Classes 

Java Bindings

To use Java Bindings, the following dependencies need to be added to the new Maven Project within the pom.xml file: 

Code fragment
        <version>${bindings-rx-java-version}</version> -- Refer to version provided in the sample code provided by ASX
        <version>${csp-java-stubs-version}</version> -- The corresponding release version published per the code drop release notes
        <version>5.0.4</version> -- Refer to version provided in the sample code provided by ASX

For further information on Java Bindings, please refer to the Java Bindings Tutorial.

Java Classes

The Java Classes are sourced via the FTP download. The Java Classes file ( can be copied to an internal repository (e.g. Nexus or equivalent) or included as a dependency.

The Java Classes are used to support the development of commands and specific to CSP.

Establishing a Secure Connection to the Ledger

The first step is to establish a mutual TLS secured connection to the ledger.

ITE1 Update

The below code sample has been updated to include accessToken. 

The following code fragment example demonstrates how to establish a secure connection to the ledger:

Code fragment
// Initialises a secure gRPC channel with a large maximum size (max message size is 128 MiB in this example)
// If the message size is larger that what is specified a RESOURCE_EXHAUSTED error will be returned when fetching packages
private NettyChannelBuilder getChannelBuilder(String host, int port) throws SSLException {
    int MAX_MESSAGE_SIZE = 128 * 1024 * 1024;
    return NettyChannelBuilder.forAddress(host, port)
        // Sets the periodic HTTP2 ping is sent over the transport as 30 seconds.
        .keepAliveTime(30, TimeUnit.SECONDS)
        // If the ping response does not arrive within a 20 second time out window, the transport will be disconnected. This is intentionally set to a time less than keepAliveTime.
        .keepAliveTimeout(20, TimeUnit.SECONDS)
// Create a client instance
DamlLedgerClient client = DamlLedgerClient.newBuilder(getChannelBuilder(host,port))
                .trustManager(new File(trustCertCollectionFilePath))
                .keyManager(new File(clientCertChainFilePath), new File(clientPrivateKeyFilePath)).build())
// Connects to the ledger and runs initial validation

In the above code fragment:

  • The ManagedChannel class is used to construct a channel that is later used by the DamlLedgerClient constructor. It uses a builder pattern with the following parameters:
    • Host: The hostname of the ledger server.
    • Port: The port number exposed by the ledger server for API communication.
      • In CDE, by default, this is 8080, however this will be provided to the participant via email. Similarly, the port will take the format of 3XXX, where XXX is the CDE instance number allocated.
      • In ITE1, the specified port is provided in the Connectivity Guide (refer to Section 04 - Networking Details for ITEs). The port will be 3000.
    • The file referenced as clientCertChainFilePath, is the .cer format signed certificate returned by ASX. 
    • The file referenced as trustCertCollectionFilePath:
      • In CDE, this is the .pem format certificate chain downloaded from the ASX FTP;
      • In ITE1, this is generated in CSAM and provided by CTS.
    • The clientPrivateKeyFilePath is the .key file created as part of the CSR.
  • trustManager, keyManager, File(privateKey) are a requirements for mutual TLS.
  • MaxInboundMessageSize: Specifies the permitted message size. The Ledger API is configured to use a default message size of 4MiB. 

    .maxInboundMessageSize() within ManagedChannel (previously described) is used to set a new upper threshold when the default message size is insufficient for tasks such as fetching large messaging tasks. 

  • accessToken is the Ledger API token obtained from the Obtaining a Ledger API Token section.
  • The client.connect method is used to establish the connection.

This establishes a secure connection to the CSP environment.

Related Pages:

There are no related labels.

Browse Popular Pages:

No labels match these criteria.

This document provides general information only. ASX Limited (ABN 98 008 624 691) and its related bodies corporate (“ASX”) makes no representation or warranty with respect to the accuracy, reliability or completeness of the information. To the extent permitted by law, ASX and its employees, officers and contractors shall not be liable for any loss or damage arising in any way (including by way of negligence) from or in connection with any information provided or omitted or from anyone acting or refraining to act in reliance on this information.

© 2022 ASX Limited ABN 98 008 624 691