Skip to content
You are reading Codefi Orchestrate development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Configure Orchestrate Transaction Listener

Follow these steps to configure and connect to Orchestrate Transaction Listener dependencies:

  1. Configure Apache Kafka (mandatory)
  2. Configure monitoring (optional). Improve the development experience and debugging.
  3. Configure Multi-tenancy (optional). Use Orchestrate with multiple tenants.

In addition to the dependencies, Orchestrate Transaction Listener needs to be configured to connect to the other microservices and to define how the service should be exposed.


Configure each microservice using microservice-specific environment variables. Command line options are also available and take precedence over environment variables.


Environment Variable Command line option Description Default
TX_LISTENER_PROVIDER_REFRESH_INTERVAL tx-listener-provider-refresh-interval Time interval in seconds for refreshing the configuration of registered chains 5s
API_URL api-url URL of the Gateway API HTTP endpoint localhost:8081
API_METRICS_URL (only ENV var) URL of the Gateway API HTTP metrics endpoint. localhost:8082
TX_SENTRY_REFRESH_INTERVAL tx-sentry-refresh-interval Interval of time in seconds between checks for pending transactions 1s

CLI options

See the complete list of command line options for the Orchestrate Transaction Listener:

  orchestrate tx-listener run [flags]

      --api-url string                                     URL of the API HTTP endpoint. Environment variable: "API_URL" (default "localhost:8081")
  -h, --help                                               help for run
      --kafka-consumer-group-heartbeat-interval duration   The expected time between heartbeats to the consumer coordinator when using Kafka's group management facilities. Heartbeats are used to ensure that the consumer's session stays active and to facilitate rebalancing when new consumers join or leave the group.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_HEARTBEAT_INTERVAL" in ms (default 3s)
      --kafka-consumer-group-rebalance-strategy string     Strategy for allocating topic partitions to members (one of ["Sticky" "Range" "RoundRobin"]).
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_STRATEGY" (default "Range")
      --kafka-consumer-group-rebalance-timeout duration    The maximum allowed time for each worker to join the group once a rebalance has begun. This is basically a limit on the amount of time needed for all tasks to flush any pending data and commit offsets. If the timeout is exceeded, then the worker will be removed from the group, which will cause offset commit failures
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_TIMEOUT" (default 1m0s)
      --kafka-consumer-group-session-timeout duration      The timeout used to detect consumer failures when using Kafka's group management facility. The consumer sends periodic heartbeats to indicate its liveness to the broker. If no heartbeats are received by the broker before the expiration of this session timeout, then the broker will remove this consumer from the group and initiate a rebalance.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_SESSION_TIMEOUT" (default 10s)
      --kafka-consumer-max-processing-time duration        The maximum amount of time the consumer expects a message takes to process for the user. If writing to the Messages channel takes longer than this, that partition will stop fetching more messages until it can proceed again.
                                                           Environment variable: "KAFKA_CONSUMER_MAXPROCESSINGTIME" (default 100ms)
      --kafka-consumer-max-wait-time duration              The maximum amount of time the broker will wait for Consumer.Fetch.Min bytes to become available before it returns fewer than that anyways.
                                                           Environment variable: "KAFKA_CONSUMER_MAX_WAIT_TIME" in ms (default 250ms)
      --kafka-group string                                 Address of Kafka server to connect to.
                                                           Environment variable: "KAFKA_GROUP" (default "group-e2e")
      --kafka-sasl-enabled                                 Whether or not to use SASL authentication when connecting to the broker
                                                           Environment variable: "KAFKA_SASL_ENABLED"
      --kafka-sasl-handshake                               Whether or not to send the Kafka SASL handshake first if enabled (defaults to true). You should only set this to false if you're using a non-Kafka SASL proxy.
                                                           Environment variable: "KAFKA_SASL_HANDSHAKE" (default true)
      --kafka-sasl-mechanism string                        SASLMechanism is the name of the enabled SASL mechanism. Possible values: OAUTHBEARER, PLAIN (defaults to PLAIN).
                                                           Environment variable: "KAFKA_SASL_MECHANISM"
      --kafka-sasl-password string                         Password for SASL/PLAIN or SASL/SCRAM auth.
                                                           Environment variable: "KAFKA_SASL_PASSWORD"
      --kafka-sasl-scramauthzid string                     Authz id used for SASL/SCRAM authentication
                                                           Environment variable: "KAFKA_SASL_SCRAMAUTHZID"
      --kafka-sasl-user string                             Username for SASL/PLAIN or SASL/SCRAM auth.
                                                           Environment variable: "KAFKA_SASL_USER"
      --kafka-tls-ca-cert-file string                      CA cert file Path.
                                                           Environment variable: "KAFKA_TLS_CA_CERT_FILE"
      --kafka-tls-client-cert-file string                  Client Cert File Path.
                                                           Environment variable: "KAFKA_TLS_CLIENT_CERT_FILE"
      --kafka-tls-client-key-file string                   Client key file Path.
                                                           Environment variable: "KAFKA_TLS_CLIENT_KEY_FILE"
      --kafka-tls-enabled                                  Whether or not to use TLS when connecting to the broker (defaults to false).
                                                           Environment variable: "KAFKA_TLS_ENABLED"
      --kafka-tls-insecure-skip-verify                     Controls whether a client verifies the server's certificate chain and host name. If InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.
                                                           Environment variable: "KAFKA_TLS_INSECURE_SKIP_VERIFY"
      --kafka-url strings                                  URL (addresses) of Kafka server(s) to connect to.
                                                           Environment variable: "KAFKA_URL" (default [localhost:9092])
      --kafka-version string                               The version of Kafka that Sarama will assume it is running against. Defaults to the oldest supported stable version. Since Kafka provides backwards-compatibility, setting it to a version older than you have will not break anything, although it may prevent you from using the latest features. Setting it to a version greater than you are actually running may lead to random breakage.
                                                           Environment variable: "KAFKA_CONSUMER_GROUP_REBALANCE_TIMEOUT" (default "1.0.0")
      --metrics-modules strings                            List of metrics modules to exposed by prometheus endpoint. Available metric modules are ["tcp" "go" "process" "healthz"], to enable all use ENABLED or to disable all DISABLED.
                                                           Environment variable: "METRICS_MODULES" (default [ENABLED])
      --tx-listener-provider-refresh-interval duration     Time interval for refreshing the configuration from the chain-registry
                                                           Environment variable: "TX_LISTENER_PROVIDER_REFRESH_INTERVAL" (default 5s)
      --tx-sentry-refresh-interval duration                Interval of time between checks for pending transactions. Environment variable: "TX_SENTRY_REFRESH_INTERVAL" (default 1s
ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can obtain paid professional support by Consensys at