add traffic topup docs for docker-compose (#3040)

Signed-off-by: Itai Segall <itai.segall@digitalasset.com>

Author: isegall-da

docs/src/background/tokenomics/traffic_tokenomics.rst

@@ -20,7 +20,7 @@ purchasing party. There is no application involved so no
 :ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>`
 is created.
 
-To avoid running out of traffic credits, the ability to perform automatic traffic purchases is provided and recommended.   Please see :ref:`helm_validator_topup`.  Alternatively, Daml application code can use :ref:`AmuletRules_BuyMemberTraffic <type-splice-amuletrules-amuletrulesbuymembertraffic-66391>`
+To avoid running out of traffic credits, the ability to perform automatic traffic purchases is provided and recommended.   Please see :ref:`helm_validator_topup` for Kubernetes or :ref:`compose_validator_topup` for Docker-compose.  Alternatively, Daml application code can use :ref:`AmuletRules_BuyMemberTraffic <type-splice-amuletrules-amuletrulesbuymembertraffic-66391>`
 to increase the traffic credit balance.
 
 Note that traffic credits are used whenever a confirmation request for a Daml

docs/src/common/traffic_topups.rst

@@ -0,0 +1,29 @@
+..
+   Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+..
+   SPDX-License-Identifier: Apache-2.0
+
+On each successful top-up, the validator app purchases a `top-up amount` of roughly ``targetThroughput * minTopupInterval`` bytes of traffic
+(specific amount can vary due to rounding-up).
+The ``minTopupInterval`` allows validator operators to control the upper-bound frequency at which automated top-ups happen.
+If the top-up amount is below the synchronizer-wide ``minTopupAmount`` (see :ref:`traffic_parameters`),
+``minTopupInterval`` is automatically stretched so that at least ``minTopupAmount`` bytes of traffic are
+purchased while respecting the configured ``targetThroughput``.
+
+The next top-up gets triggered when all of the following conditions are met:
+
+- The available :ref:`extra traffic balance <traffic_accounting>` drops below the configured top-up amount
+  (i.e., below ``targetThroughput * minTopupInterval``).
+- At least ``minTopupInterval`` has elapsed since the last top-up.
+- The validator has sufficient CC in its wallet to buy the top-up amount worth on traffic
+  (except on DevNet, where the validator app will automatically tap enough coin to purchase traffic).
+
+
+Validators receive a small amount of free traffic from the Super Validators, which suffices for submitting the
+top-up transaction. However, if many other transactions are submitted, you may run into a situation where
+you have exhausted also the free traffic, thus the validator cannot submit the top-up transaction.
+The free traffic grant accumulates gradually and continuously. When no transactions are submitted, it
+takes about twenty minutes for free traffic to accumulate to the maximum possible.
+If you've consumed your traffic balance by submitting too many transactions without purchasing traffic,
+pause your Validator node (validator app and participant) for twenty minutes to allow your free traffic
+balance to accumulate.

docs/src/deployment/traffic.rst

@@ -169,7 +169,8 @@ Additionally, to prevent top-up transactions from failing due to an already depl
 the validator app will
 :ref:`abort ledger submissions if the balance has fallen below a predefined amount<error-below-reserved-traffic-amount>`.
 
-For configuring the built-in top-up automation, please refer to the :ref:`validator deployment guide <helm_validator_topup>`.
+For configuring the built-in top-up automation, please refer to the :ref:`Kubernetes validator deployment guide <helm_validator_topup>`
+or the corresponding :ref:`Docker-compose one<compose_validator_topup>`.
 Configuring alternative methods for buying traffic, e.g., using third-party services, exceeds the scope of this documentation.
 
 .. _traffic_wasted:

docs/src/release_notes.rst

@@ -29,6 +29,7 @@ Upcoming
   - Docs
 
     - Document additional approach for resuming a :ref:`validator disaster recovery <validator_dr>` process that has failed at the step of importing the :term:`ACS`.
+    - Added a section on :ref:`configuring traffic <compose_validator_topup>` topups for Docker-compose deployments
 
 0.4.23
 ------

docs/src/validator_operator/validator_compose.rst

@@ -217,6 +217,21 @@ you wish to migrate, follow the instructions for associating a user with a party
 :ref:`Users, Parties and Wallets in the Splice Wallet section <validator-users>`, but replace
 the admin party ID with the party ID which you wish to associate with each user.
 
+.. _compose_validator_topup:
+
+Configuring Automatic Traffic Purchases
++++++++++++++++++++++++++++++++++++++++
+
+Your node is configured to automatically purchase :ref:`traffic <traffic>` on a pay-as-you-go basis
+(see :ref:`automatically purchase traffic <traffic_topup>`).
+To tune to your needs, you can set environment variables, for example:
+
+.. code-block:: bash
+
+   export TARGET_TRAFFIC_THROUGHPUT=20000 # target throughput in bytes/second
+   export MIN_TRAFFIC_TOPUP_INTERVAL="1m" # minimum interval between top-ups
+
+.. include:: ../common/traffic_topups.rst
 
 Integration with systemd and other init systems
 +++++++++++++++++++++++++++++++++++++++++++++++

docs/src/validator_operator/validator_helm.rst

@@ -632,38 +632,15 @@ Configuring automatic traffic purchases
 ---------------------------------------
 
 By default your node will be configured to automatically purchase :ref:`traffic <traffic>` on a pay-as-you-go basis
-:ref:`automatically purchase traffic <traffic_topup>`.
+(see :ref:`automatically purchase traffic <traffic_topup>`).
 To disable or tune to your needs, edit the following section in the validator-values.yaml file:
 
 .. literalinclude:: ../../../apps/app/src/pack/examples/sv-helm/standalone-validator-values.yaml
     :language: yaml
     :start-after: CONFIGURING_TOPUP_START
     :end-before: CONFIGURING_TOPUP_END
 
-On each successful top-up, the validator app purchases a `top-up amount` of roughly ``targetThroughput * minTopupInterval`` bytes of traffic
-(specific amount can vary due to rounding-up).
-The ``minTopupInterval`` allows validator operators to control the upper-bound frequency at which automated top-ups happen.
-If the top-up amount is below the synchronizer-wide ``minTopupAmount`` (see :ref:`traffic_parameters`),
-``minTopupInterval`` is automatically stretched so that at least ``minTopupAmount`` bytes of traffic are
-purchased while respecting the configured ``targetThroughput``.
-
-The next top-up gets triggered when all of the following conditions are met:
-
-- The available :ref:`extra traffic balance <traffic_accounting>` drops below the configured top-up amount
-  (i.e., below ``targetThroughput * minTopupInterval``).
-- At least ``minTopupInterval`` has elapsed since the last top-up.
-- The validator has sufficient CC in its wallet to buy the top-up amount worth on traffic
-  (except on DevNet, where the validator app will automatically tap enough coin to purchase traffic).
-
-
-Validators receive a small amount of free traffic from the Super Validators, which suffices for submitting the
-top-up transaction. However, if many other transactions are submitted, you may run into a situation where
-you have exhausted also the free traffic, thus the validator cannot submit the top-up transaction.
-The free traffic grant accumulates gradually and continuously. When no transactions are submitted, it
-takes about twenty minutes for free traffic to accumulate to the maximum possible.
-If you've consumed your traffic balance by submitting too many transactions without purchasing traffic,
-pause your Validator node (validator app and participant) for twenty minutes to allow your free traffic
-balance to accumulate.
+.. include:: ../common/traffic_topups.rst
 
 
 .. todo::