update tokenomics

docs/src/app_dev/overview/index.rst

@@ -8,6 +8,9 @@
 Overview
 ========
 
+If you are a new Canton Network developer, please check out the
+`TL;DR for new Canton Network developers <https://docs.digitalasset.com/build/3.4/overview/tldr.html>`__.
+
 Canton Network Applications
 ---------------------------
 

docs/src/background/tokenomics/overview_tokenomics.rst

@@ -10,14 +10,14 @@ Steps in a Round
 
 Canton Network tokenomics is based on an *Activity Record* which
 identifies a party that performed an action which provides value to the
-network. An activity record has a *weight* which is the the relative share of CC minting
+network. An activity record has a *weight* which is the relative share of CC minting
 associated with this activity record.
 
 Creating an activity record and minting the associated Canton
 Coin (CC) are two distinct steps. The creation and minting steps are
 performed in a cycle that is called a *round* which has five phases. In
 the first phase, any fee values for that round are written to the ledger
-(the fees can be obtained from the :ref:`Scan State API <scan_current_state_api>`.
+(the fees can be obtained from the :ref:`Scan State API <scan_current_state_api>`).
 The second phase is called the *activity recording* and it is when
 activity records are created; records created in this phase belong to that round. The next phase calculates
 a `CC-issuance-per-activity-weight <https://github.com/hyperledger-labs/splice/blob/332e06a7ae9e13fde5bba0bf7dcb059aa36f979e/daml/splice-amulet/daml/Splice/Issuance.daml#L67>`__
@@ -28,20 +28,19 @@ a *minting phase* where the owners of an activity record can mint CC proportiona
 
 There are several rounds active
 concurrently with each round being in a different phase. A round starts
-every 10 minutes, which is configuration parameter that the Super Validators may change in the future via a governance vote. See the CC
+every 10 minutes, which is a configuration parameter that the Super Validators may change in the future via a governance vote. See the CC
 whitepaper for the details.
 
-There is no difference in activity record creation for an `external
-party <https://docs.digitalasset.com/build/3.3/tutorials/app-dev/external_signing_onboarding.html#tutorial-onboard-external-party>`__
-or local party but there is a difference in the automation support used
-in the minting phase. For local parties onboarded to a validator, the
-validator application runs background automation to mint all activity
-records automatically. An external party signs transactions using a key
-they control. As a consequence, the validator automation is not able to
-perform minting for external parties. For external parties, automation needs
-to be developed to call :ref:`AmuletRules_Transfer <type-splice-amuletrules-amuletrulestransfer-23235>` at least once per round
-with all activity records as inputs.  An accepted CIP, called `Weighted Validator Liveness Rewards for SV-Determined Parties <https://github.com/global-synchronizer-foundation/cips/blob/main/cip-0073/cip-0073.md>`__,
-is available for comment soon which describes providing this support.
+There is no difference in activity record creation for an `external party
+<https://docs.digitalasset.com/build/3.3/tutorials/app-dev/external_signing_onboarding.html#tutorial-onboard-external-party>`__ or a
+local party, but there is a difference in the automation support used in the minting phase. For local parties onboarded to a
+validator, the validator application runs background automation to mint all activity records automatically. An external party signs
+transactions using a key they control. As a consequence, the validator automation is not able to perform minting for external
+parties. For external parties, automation needs to be developed to call :ref:`AmuletRules_Transfer
+<type-splice-amuletrules-amuletrulestransfer-23235>` at least once per round with all activity records as inputs.  An accepted CIP,
+called `Weighted Validator Liveness Rewards for SV-Determined Parties
+<https://github.com/global-synchronizer-foundation/cips/blob/main/cip-0073/cip-0073.md>`__, is available for comment soon which
+describes providing this support.
 
 As an aside, some interesting templates are important to the tokenomics are:
 
@@ -73,22 +72,19 @@ There are five key templates involved in the accounting for network activity:
       - :ref:`SvRewardCoupon <type-splice-amulet-svrewardcoupon-68580>`
 
 The last four are activity records while a ``FeaturedAppActivityMarker`` is not considered an activity record. As discussed later, a
-``FeaturedAppActivityMarker`` is converted into an ``AppRewardCoupon`` via
-automation run by the Super Validators.
+``FeaturedAppActivityMarker`` is converted into an ``AppRewardCoupon`` via automation run by the Super Validators.  After CIP-0078,
+the featured CC transfer and `FeaturedAppActivityMarker`` both generate the same reward. The ``FeaturedAppActivityMarker`` is the
+preferred way to generate app activity records.
 
 The ``FeaturedAppActivityMarker``,
 ``AppRewardCoupon``, and ``ValidatorRewardCoupon`` contracts are created when an
 application's transaction succeeds. In general, an application receives rewards when its Daml code directly creates ``FeaturedAppActivityMarker`` contracts
 or interacts with Daml models that feature the application provider's party.  A ``ValidatorRewardCoupon`` is created for every call to ``AmuletRules_Transfer``
 (e.g., a CC Transfer using the Splice Wallet UI) or when CC is burned.
 
-Aside from the minting weight, an application's reward also depends on
-whether it is designated as *featured* or *unfeatured* (the default
-state). An unfeatured application receives a smaller reward and has a
-lower cap on the amount it can mint. A featured application receives
-larger rewards and has a higher cap. A *featured application* also
-receives an additional minting weight with a total equivalent value of about
-$1 US (the SuperValidators may adjust this in the future).
+Aside from the minting weight, an application's reward also depends on whether it is designated as *featured* or *unfeatured* (the
+default state). An unfeatured application does not receive any reward. A featured application receives a minting weight with a total
+equivalent value of about $1 US (the SuperValidators may adjust this in the future).
 
 .. _how_to_become_a_featured_application:
 
@@ -101,7 +97,7 @@ is an input to the application. That process starts by filling in `this
 form <https://sync.global/featured-app-request/>`__. The request goes to
 the tokenomics committee who reviews the application and responds to it.
 This `webpage <https://lists.sync.global/g/tokenomics/topics>`__ lists
-the tokenomics committees topics for tracking. Here’s an `example of a
+the tokenomics committee's topics for tracking. Here is an `example of a
 successful
 submission <https://lists.sync.global/g/tokenomics/topic/new_featured_app_request/112787885>`__.
 Note that, for testing purposes, you can self-feature your application
@@ -111,33 +107,18 @@ For some of the templates, the attribution of activity can be shared with multip
 be shared between the application provider and application user, based
 on a given ``weight`` for each. The general pattern for this is:
 
--  A list of beneficiaries, each with a ``weight``, is provided. The weights  sum up to ``1.0``.
+-  A list of beneficiaries, each with a ``weight``, is provided. The weights sum up to ``1.0``.
 
 -  Later processing creates a separate contract for each beneficiary and weight pair,
    setting the contract's ``beneficiary`` and ``weight`` fields accordingly.
 
 Beneficiaries are discussed further in the following sections.
 
-Fees
-****
+`CIP-0078 <https://github.com/global-synchronizer-foundation/cips/blob/main/cip-0078/cip-0078.md>`__ eliminated
+almost all fees for Canton Coin transfers and locks so unfeatured applications no longer receive any reward.
+The holding fee remains but its behavior changed so that no holding fees are charged when using a coin as an input to a transfer.
 
-The weight on a ``ValidatorRewardCoupon`` and ``AppRewardCoupon`` is the sum of the create, lock and transfer fees,
-excluding the base transfer fees for the “change”.  These fees eligible for reward are:
-
--  The *percentage transfer fee* which is proportional to the total amount of CC burnt in the transaction.
-
--  A *base transfer fee* that is a fixed cost for each new CC contract created for the receivers or the sender.
-
--  A coin *locking fee* for when CC is locked during a transfer.
-
-See the CC whitepaper for the details. Relevant fee values for a round
-can be obtained from the :ref:`Scan State API <scan_current_state_api>`.
-
-A holding fee is paid by a CC holder but is not eligible for rewards.  This is a fixed fee, per separate coin contract (UTXO) per unit
-of time, that is independent of the coin amount.  It promotes merging of CC to reduce network storage use. The holding
-fee is tallied per round since creation
-and is paid on the next transaction involving that record. So if
-you earned or created the CC activity record in round 1000 and you
-spent it in round 1010 then you pay 10 rounds of holding fees.
-
-Please note that the reward from usage fees are very small in comparison to the reward for being a featured application.  To simplify the tokenomics and implementation, usages fees and their corresponding rewards may be dropped as part of a future CIP.
+The holding fees is a fixed fee, per separate coin contract (UTXO) per unit
+of time, that is independent of the coin amount.  It promotes merging of CC to reduce network storage use by incentivizing merging or removal of dust coins.
+Holding fees are not charged when transferring coins but only explicitly on expired coin contracts via the ``Amulet_Expire`` choice,
+This makes accounting for holding fees simple as the value of the coin contract is charged as a holding fee.