dazl.ledger.config — connection configuration

This module contains configuration objects for a Connection.

Normally you don’t need to construct these objects directly; instead, simply call dazl.connect(), which contains the same options exposed by the Config.create() function, which in turn includes the options exposed by the subobjects of Config.

Generally you should not modify a Config object (or subobjects) that have already been passed to a Connection. There are some exceptions to this rule, though; for example, when using tokens, you can simply assign Config.access.token to a new value.

Configuration options are broken up into three subobjects:

• Access configuration: settings commonly found in Daml JWT tokens (party settings, ledger ID, application name)

• SSL/TLS configuration: settings for configuring TLS connections

• URL Configuration: settings that determine the location of gRPC Ledger API or HTTP JSON API implementation

class dazl.ledger.config.Config(access: dazl.ledger.config.access.AccessConfig, ssl: dazl.ledger.config.ssl.SSLConfig, url: dazl.ledger.config.url.URLConfig, logger: logging.Logger, lookup: Optional[dazl.damlast.lookup.MultiPackageLookup] = None)

Stores configuration for a Connection.

classmethod create(url: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, scheme: Optional[str] = None, read_as: Union[None, dazl.prim.party.Party, Collection[dazl.prim.party.Party]] = None, act_as: Union[None, dazl.prim.party.Party, Collection[dazl.prim.party.Party]] = None, admin: Optional[bool] = False, ledger_id: Optional[str] = None, application_name: Optional[str] = None, oauth_token: Optional[str] = None, oauth_token_file: Optional[str] = None, ca: Optional[bytes] = None, ca_file: Optional[os.PathLike] = None, cert: Optional[bytes] = None, cert_file: Optional[os.PathLike] = None, cert_key: Optional[bytes] = None, cert_key_file: Optional[os.PathLike] = None, connect_timeout: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None, retry_timeout: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None, use_http_proxy: bool = True, logger: Optional[logging.Logger] = None, logger_name: Optional[str] = None, log_level: Optional[str] = None, lookup: Optional[dazl.damlast.lookup.MultiPackageLookup] = None) → dazl.ledger.config.Config

Create a Config object from the supplied parameters.

The remote can be configured either by supplying a URL or by supplying a host (and optional port and scheme). If none of url, host, port, or scheme are supplied, then environment variables are consulted; if no environment variables are specified either, then default values are used.

The remote can be configured either by supplying a URL or by supplying a host (and optional port and scheme). If none of url, host, port, or scheme are supplied, then environment variables are consulted; if no environment variables are specified either, then default values are used.

When the URL scheme is http or https, dazl will first attempt to connect assuming the HTTP JSON API; if this fails, gRPC Ledger API is attempted.

If oauth_token is supplied and non-empty, then token-based access is used to connect to the ledger.

If other fields are specified, then property-based access is used. At least one of read_as, act_as, or admin must be supplied. For the HTTP JSON API, ledger_id MUST be supplied.

If _no_ fields are specified, this is an error unless environment variables supply an alternate source of configuration.

function argument	environment variable	default value
url	DAML_LEDGER_URL	localhost:6865
host	DAML_LEDGER_HOST	localhost
port	DAML_LEDGER_PORT	6865, unless scheme is specified: * 80 for http * 443 for https * 6865 for grpc
scheme	DAML_LEDGER_SCHEME	https for port 443 or 8443 http for port 80, 7575 or 8080 grpc for port 6865 https for all other ports

HTTP(s) proxies (gRPC Ledger API only)

When connecting to the gRPC Ledger API, note that gRPC environment variables are always also respected; you can set https_proxy/http_proxy` (note the lowercase environment variable name). dazl, by default, will _also_ disable usage of a proxy server for a localhost host or a 127.0.0.1 host; this can be overridden by passing a value of use_http_proxy to True.

Parameters

• url – The URL to connect to. Can be used as an alternative to supplying host, port, and scheme as individual values. Can alternatively be supplied via the environment variable DAML_LEDGER_URL.

• host – The host to connect to. Can be used as an alternative to supplying url as a combined value. Can alternatively be supplied via the environment variable DAML_LEDGER_HOST.

• port – The port to connect to. Can be used as an alternative to supplying url as a combined value. Can alternatively be supplied via the environment variable DAML_LEDGER_PORT.

• scheme – The scheme to connect to. Can be used as an alternative to supplying url as a combined value. Can alternatively be supplied via the environment variable DAML_LEDGER_SCHEME.

• connect_timeout – Length of time to wait before giving up connecting to the remote and declaring an error. The default value is 30 seconds.

• retry_timeout – Length of time to wait while attempting to retry retryable errors before giving up and declaring an error. The default value is 30 seconds.

• use_http_proxy – True to use an HTTP(S) proxy server if configured; False to avoid using any configured server. If unspecified and the host is localhost, the proxy server is avoided; otherwise the proxy server is used.

• ca – A certificate authority to use to validate the server’s certificate. If not supplied, the operating system’s default trust store is used. Cannot be specified with ca_file.

• ca_file – A file containing the certificate authority to use to validate the server’s certificate. If not supplied, the operating system’s default trust store is used. Cannot be specified with ca.

• cert – A client-side certificate to be used when connecting to a server that requires mutual TLS. Cannot be specified with cert_file.

• cert_file – A file containing the client-side certificate to be used when connecting to a server that requires mutual TLS. Cannot be specified with cert.

• cert_key – A client-side private key to be used when connecting to a server that requires mutual TLS. Cannot be specified with cert_key_file.

• cert_key_file – A client-side private key to be used when connecting to a server that requires mutual TLS. Cannot be specified with cert_key.

• read_as – A party or set of parties on whose behalf (in addition to all parties listed in act_as) contracts can be retrieved. Cannot be specified if oauth_token or oauth_token_file is specified.

• act_as – A party or set of parties on whose behalf commands should be executed. Parties here are also implicitly granted read_as access as well. Cannot be specified if oauth_token or oauth_token_file is specified.

• admin – HTTP JSON API only: allow admin endpoints to be used. This flag is ignored when connecting to gRPC Ledger API implementations. Cannot be specified if oauth_token or oauth_token_file is specified.

• ledger_id – The ledger ID to connect to. For the HTTP JSON API, this value is required. For the gRPC Ledger API, if this value is _not_ supplied, its value will be retrieved from the server. Cannot be specified if oauth_token or oauth_token_file is specified.

• application_name – A string that identifies this application. This is used for tracing purposes on the server-side. Cannot be specified if oauth_token or oauth_token_file is specified.

• oauth_token – The OAuth bearer token to be used on all requests. If specified, no other access parameters can be specified.

• oauth_token_file – A file that contains the OAuth bearer token to be used on all requests. If specified, no other access parameters can be specified.

• logger – The logger to use for connections created from this configuration. If not supplied, a logger will be created.

• logger_name – The name of the logger. Only used if logger is not provided.

• log_level – The logging level for the logger. The default is warn. Only used if logger is not provided.

• lookup – An alternate symbol table to use to store package information. You should not normally need to set this value.

Access configuration

The AccessConfig protocol specifies how dazl identifies itself to a ledger. There are two built-in mechanisms for this: property-based access, which is traditionally used with ledgers that do NOT require authorization/authentication (typical in a local development scenario, for example coding against a local sandbox), and token-based access, which is required for ledgers that DO require authorization/authentication (typical in a production scenario and/or hosted ledgers).

In property-based access (PropertyBasedAccessConfig), the behavior differs depending on whether you are connecting over the gRPC Ledger API or the HTTP JSON API:

• For the gRPC Ledger API, read_as and act_as are used as-is. ledger_id is defaulted to the value requested from the ledger (but only if not initially specified). The admin property is ignored and unused.

• For the HTTP JSON API, read_as, act_as, admin, ledger_id, and application_name are all used to generate an unsigned JWT locally. ledger_id MUST be supplied.

In token-based access (TokenBasedAccessConfig), the value of the token completely determines the parties that can be used, the ledger ID to connect to, and the name of the application. AccessConfig.token can be overwritten at any time, and that value will be used for all subsequent calls to the ledger. If your ledger requires authorization/authentication using tokens, you _must_ use token-based access.

Although dazl does not currently refresh tokens automatically, you can update the token yourself at any time:

async def main():
    async with dazl.connect(token=MY_INITIAL_TOKEN) as conn:
        task1 = asyncio.create_task(do_ledger_stuff(conn))
        task2 = asyncio.create_task(refresh_token(conn))

        await task1
        task2.cancel()

async def do_ledger_stuff(conn):
    # use the connection normally to make ledger calls
    ...

async def refresh(conn):
    while True:
        # sleep for one hour
        await asyncio.sleep(3600)
        conn.config.access.token = NEW_REFRESHED_TOKEN

Deeper support for token refreshing may be added in a future release.

class dazl.ledger.config.AccessConfig

Configuration parameters for providing access to a ledger.

To create an instance of this protocol, call create_access() and provide either oauth_token or the other fields you wish to set (such as act_as). You cannot specify both an access token and other fields.

You may implement this protocol using your own custom type if you have very specialized access needs.

property act_as: AbstractSet[dazl.prim.party.Party]

The set of parties that can be used to write data to the ledger.

Type

AbstractSet[Party]

property admin: bool

True if the token grants “admin” access.

Type

bool

property application_name: Optional[str]

The application name.

Type

Optional[str]

property ledger_id: Optional[str]

The ledger ID. For non-token based access methods, this can be queried from the ledger.

Type

Optional[str]

property read_as: AbstractSet[dazl.prim.party.Party]

The set of parties that can be used to read data from the ledger. This also includes the set of parties that can be used to write data to the ledger.

Type

AbstractSet[Party]

property read_only_as: AbstractSet[dazl.prim.party.Party]

The set of parties that have read-only access to the underlying ledger.

Type

AbstractSet[Party]

property token: str

The bearer token that provides authorization and authentication to a ledger.

Type

str

property token_version: Optional[Literal[1, 2]]

The version of the token supplied at configuration time, as provided by a signing authority that is trusted by the server.

This parameter is used at connection initialization in order to bootstrap local state.

If access parameters are supplied instead of a token, then the version of the token is None.

Type

int | None

dazl.ledger.config.create_access(*, read_as: Union[None, dazl.prim.party.Party, Collection[dazl.prim.party.Party]] = None, act_as: Union[None, dazl.prim.party.Party, Collection[dazl.prim.party.Party]] = None, admin: Optional[bool] = None, ledger_id: Optional[str] = None, application_name: Optional[str] = None, oauth_token: Optional[str] = None, oauth_token_file: Optional[str] = None, logger: Optional[logging.Logger] = None) → dazl.ledger.config.access.AccessConfig

Create an appropriate instance of AccessConfig.

See Config.create() for a more detailed description of these parameters.

class dazl.ledger.config.PropertyBasedAccessConfig

Access configuration that is manually specified outside of an authentication/authorization framework. Suitable for local testing or when no auth server is available, and the Ledger API inherently trusts any caller to provide its own authentication and authorization.

property act_as: MutableSet[dazl.prim.party.Party]

The set of parties for which act-as rights are granted. This collection can be modified. Adding a party to this set _removes_ it from read_only_as().

Type

MutableSet[Party]

property admin: bool

Whether or not the token sent to HTTP JSON API contains the admin: true flag that signals a token bearer with admin access.

property application_name: str

The application name.

Type

Optional[str]

property ledger_id: Optional[str]

The ledger ID. When connecting to the gRPC Ledger API, this can be inferred and does not need to be supplied. When connecting to the HTTP JSON API, it must be supplied.

Type

Optional[str]

property read_as: AbstractSet[dazl.prim.party.Party]

The set of parties for which read rights are granted. This collection is read-only. If you want to add a party with read-only access, add it to read_only_as(); if you want to add a party with act-as access as well as read-only access, add it to act_as().

This set always includes the act_as parties. For the set of parties that can be read as but NOT acted as, use read_only_as().

Type

AbstractSet[Party]

property read_only_as: MutableSet[dazl.prim.party.Party]

The set of parties for which read-as rights are granted, but act-as rights are NOT granted. This collection can be modified.

Type

MutableSet[Party]

property token: str

Produces a token without signing, utilizing our parameters.

property token_version: None

Return None, because any token that we are supplying is purely for identification purposes and not really a valid server-side issued token.

class dazl.ledger.config.TokenBasedAccessConfig

Access configuration that is inherently token-based. The token can be changed at any time, and party rights, the application name, and ledger ID are all derived off of the token.

property act_as: AbstractSet[dazl.prim.party.Party]

The set of parties that can be used to write data to the ledger.

Type

AbstractSet[Party]

property admin: bool

True if the token grants “admin” access.

Type

bool

property application_name: Optional[str]

The application name.

Type

Optional[str]

property ledger_id: Optional[str]

The ledger ID. For non-token based access methods, this can be queried from the ledger.

Type

Optional[str]

property read_as: AbstractSet[dazl.prim.party.Party]

The set of parties that can be used to read data from the ledger. This also includes the set of parties that can be used to write data to the ledger.

Type

AbstractSet[Party]

property read_only_as: AbstractSet[dazl.prim.party.Party]

The set of parties that have read-only access to the underlying ledger.

Type

AbstractSet[Party]

property token: str

The bearer token that provides authorization and authentication to a ledger. This value can be replaced on a live connection in order to support use cases such as token refreshing.

property token_version: Literal[1, 2]

The version of the token supplied at configuration time, as provided by a signing authority that is trusted by the server.

This parameter is used at connection initialization in order to bootstrap local state.

If access parameters are supplied instead of a token, then the version of the token is None.

Type

int | None

SSL/TLS configuration

class dazl.ledger.config.SSLConfig(ca: Optional[bytes] = None, ca_file: Optional[os.PathLike] = None, cert: Optional[bytes] = None, cert_file: Optional[os.PathLike] = None, cert_key: Optional[bytes] = None, cert_key_file: Optional[os.PathLike] = None, logger: Optional[logging.Logger] = None)

Configuration parameters that affect SSL connections.

See Config.create() for a more detailed description of these parameters.

property ca: Optional[bytes]

Server certificate authority file.

property cert: Optional[bytes]

Client certificate file.

property cert_key: Optional[bytes]

Client certificate and key file.

URL configuration

The URLConfig protocol specifies the ledger implementation that dazl connects to (either gRPC Ledger API or HTTP JSON API).

dazl.ledger.config.create_url(*, url: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, scheme: Optional[str] = None, connect_timeout: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None, retry_timeout: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None, use_http_proxy: Optional[bool] = None, logger: Optional[logging.Logger] = None)

Create an instance of URLConfig, possibly with values taken from environment variables, or defaulted if otherwise unspecified.

See Config.create() for a more detailed description of these parameters.

class dazl.ledger.config.URLConfig

Configuration parameters for the remote host, including basic connection parameters that do not belong in AccessConfig.

property connect_timeout: datetime.timedelta

How long to wait for a connection before giving up.

The default is 30 seconds.

property retry_timeout: datetime.timedelta

How long to keep retrying retryable operations before giving up.

The default is 30 seconds.

property url: str

The full URL to connect to, including a protocol (scheme), host, and port.

property use_http_proxy: bool

Whether to allow the use of HTTP proxies.