Skip to content
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/src/app_dev/overview/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------------

Expand Down
75 changes: 28 additions & 47 deletions docs/src/background/tokenomics/overview_tokenomics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__
Expand All @@ -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:

Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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.
2 changes: 0 additions & 2 deletions test-cometbft-full-class-names.log
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think you meant to delete any of these...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@isegall-da I thought the log files were a side effect of my building the docs. Are you suggesting that we are checking in the log files and they shouldn't be deleted? If so, out of curiosity, what is the value of those log files?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are not log files (despite their ending). They define the split of tests for their parallel execution across multiple CI machines.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are produced by logging particular sbt output. That's the reason for the ending.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe I've added the log files back in the latest commit. Appreciate it if someone can confirm and approve.

This file was deleted.

1 change: 0 additions & 1 deletion test-daml-ciupgrade-vote.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-app-upgrade.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-auth0-credentials-preflight.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-bigquery.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-canton-enterprise.log

This file was deleted.

4 changes: 0 additions & 4 deletions test-full-class-names-core-preflight-non-devnet.log

This file was deleted.

3 changes: 0 additions & 3 deletions test-full-class-names-core-preflight.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-disaster-recovery.log

This file was deleted.

2 changes: 0 additions & 2 deletions test-full-class-names-docker-based.log

This file was deleted.

This file was deleted.

4 changes: 0 additions & 4 deletions test-full-class-names-frontend-sim-time.log

This file was deleted.

15 changes: 0 additions & 15 deletions test-full-class-names-frontend.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-local-net-based.log

This file was deleted.

46 changes: 0 additions & 46 deletions test-full-class-names-non-integration.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-offboard-sv-runbook-preflight.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-prepare-reonbaord-sv-preflight.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-re-onboard-sv-runbook-preflight.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-record-time-tolerance.log

This file was deleted.

5 changes: 0 additions & 5 deletions test-full-class-names-resource-intensive.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-signatures.log

This file was deleted.

25 changes: 0 additions & 25 deletions test-full-class-names-sim-time.log

This file was deleted.

1 change: 0 additions & 1 deletion test-full-class-names-sv-preflight-non-devnet.log

This file was deleted.

3 changes: 0 additions & 3 deletions test-full-class-names-sv-preflight.log

This file was deleted.

Loading