Note

This page is a work in progress. It may contain incomplete or incorrect information.

API Configuration

Participant nodes expose the Admin API, the gRPC Ledger API, and optionally the JSON Ledger API.

This page explains how to configure general options that apply to both the Admin API and the gRPC Ledger API. For the configuration options that apply only to specific APIs, please refer to the Administration API, the gRPC Ledger API, and the JSON Ledger API pages.

Ports

Canton assigns ports automatically for all the APIs of all the configured nodes if the port has not been configured explicitly. The ports are allocated according to the following scheme:

/** Participant node default ports */
val ledgerApiPort = defaultPortStart(4001)
val participantAdminApiPort = defaultPortStart(4002)

To explicitly set the port for an API, set the port option in the configuration section for that API.

The following is an example that demonstrates how to configure the port for the various APIs:

participant1 {
  storage.type = memory
  admin-api.port = 5012
  ledger-api.port = 5011
}

Keep Alive

Canton enables keep-alive by default on all gRPC connections in order to prevent load-balancers or firewalls from terminating long-running RPC calls in the event of some silence on the connection.

To tweak the keep-alive configuration of a connection, adjust the following parameters:

• time

• timeout

• permit-keep-alive-time

• permit-keep-alive-without-calls

You can adjust the first two parameters for either the Synchronizer Public API client in the keep-alive-client section, or for the server side of the Admin API and the gRPC Ledger API in the keep-alive-server section. The last two parameters are server only, and you can therefore adjust them only in the keep-alive-server section of the Admin API and the gRPC Ledger API.

The gRPC documentation further describes these parameters and their effect.

Note

permit-keep-alive-time specifies the most aggressive keep-alive time that a client is permitted to use. If a client uses a keep-alive time that is more aggressive than the server’s permit-keep-alive-time, the connection is terminated with a GOAWAY error with “too_many_pings” as the debug data.

Note

Setting permit-keep-alive-without-calls to true allows clients to send ping messages outside of any ongoing gRPC call. Such a ping otherwise results in a GOAWAY error.

Canton sets different default values for these parameters depending on the API:

API	Admin API	Ledger API
time	40s	10min
timeout	20s	20s
permit-keep-alive-time	20s	10s
permit-keep-alive-without-calls	false	false

The following is an example that demonstrates how to configure the keep-alive for the various APIs:

sequencer-client {
    keep-alive-client {
        time = 60s
        timeout = 30s
    }
}

admin-api {
    keep-alive-server {
        time = 40s
        timeout = 20s
        permit-keep-alive-time = 20s
    }
}

ledger-api {
    keep-alive-server {
        time = 40s
        timeout = 20s
        permit-keep-alive-time = 20s
        permit-keep-alive-without-calls = true
    }
}

Native libraries usage by Netty

Canton ships with native libraries (for some processor architectures: x86_64, ARM64, S390_64) so that the Netty network access library can take advantage of the epoll system call on Linux. This generally leads to improved performance and less pressure on the JVM garbage collector.

The system automatically picks the native library if available for the current operating system and architecture, or falls back to the standard NIO library if the native library is not available.

To switch off using the native library, set the following when running Canton:

-Dio.netty.transport.noNative=true

Even when this is expected, falling back to NIO might lead to a warning being emitted at DEBUG level on your log.