Skip to content

Commit fa0ab15

Browse files
hrischuk-dahrischuk-da
authored
Tokenomics in background section (#2076)
Signed-off-by: hrischuk-da <curtis.hrischuk@digitalasset.com>
1 parent 3e90801 commit fa0ab15

File tree

10 files changed

+435
-7
lines changed

10 files changed

+435
-7
lines changed

‎.vscode/settings.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,6 @@
2323
"**/.daml/unpacked-dars/**": true
2424
},
2525
"metals.inlayHints.implicitArguments.enable": true,
26-
"metals.inlayHints.implicitConversions.enable": true
26+
"metals.inlayHints.implicitConversions.enable": true,
27+
"makefile.configureOnOpen": false
2728
}

‎docs/src/app_dev/overview/index.rst‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Use the following documentation to build Canton Network applications and get the
1818

1919
.. TODO(#1156): link to https://docs.digitalasset.com/build/current/ instead of 3.4 when it is available
2020
21+
* Review the summary of the Canton Network tokenomics at :ref:`app_tokenomics`.
2122
* Learn to build Canton Network applications from the tutorials, how-tos, explanations, and reference documentation at
2223
https://docs.digitalasset.com/build/3.3/
2324
* Browse the currently featured apps: https://sync.global/featured-apps/
@@ -59,21 +60,30 @@ See the diagram below to learn about which components serve which APIs and how t
5960
Splice Daml APIs Overview
6061
-------------------------
6162

62-
Splice also defines Daml APIs used in interoperability standards,
63+
Splice implements several decentralized applications whose on-ledger state and workflows are implemented in Daml. An `Interface <https://docs.digitalasset.com/build/3.3/reference/daml/interfaces.html#reference-interfaces>`__
64+
defined in Daml code is a public API that you should develop against because they are stable.
65+
These public APIs are used in interoperability standards,
6366
like the :ref:`Canton Network Token Standard <app_dev_token_standard_overview>`.
64-
Use these Daml APIs to minimize the coupling between your application and your dependencies.
67+
Use these Daml APIs to minimize the coupling between your application's Daml code and the Daml code of your dependencies.
68+
For example, the ``Interfaces`` in the Splice implementaiton loosely
69+
couple an application with the implementation so that a Splice upgrade avoids forcing a corresponding upgrade of an application's Daml code.
6570

6671
See the :ref:`app_dev_daml_api` for an overview of the Daml APIs defined in Splice and their purpose.
6772

6873

6974
Splice Daml Models Overview
7075
---------------------------
7176

72-
Splice implements several decentralized applications whose on-ledger state and workflows are implemented in Daml.
73-
Use the following resources to learn how to interact with this state and workflows.
77+
A Daml model's `Templates <https://docs.digitalasset.com/build/3.3/reference/daml/templates.html>`__ and
78+
`Choices <https://docs.digitalasset.com/build/3.3/reference/daml/choices.html>`__ are considered internal implementation details. For example,
79+
the :ref:`Canton Network Token Standard <app_dev_token_standard_overview>` is the public API for working with tokens, including Canton Coin.
80+
The :ref:`Canton Network Token Standard <app_dev_token_standard_overview>` implementation
81+
operates on top of the :ref:`AmuletRules_Transfer <type-splice-amuletrules-amuletrulestransfer-23235>` choice (this provides backwards compatibility).
82+
It is worthwhile and recommended to study these implementation details because you can learn a lot by examination.
83+
84+
Use the following resources to learn how to interact with the Daml models state and workflows.
7485

7586
* Learn how to read and write Daml code from:
7687
https://docs.digitalasset.com/build/3.3/
7788
* Learn about the Daml packages that are part of Splice and their data models and workflows from
7889
:ref:`app_dev_daml_models`.
79-

‎docs/src/background/tokenomics/cc_transfer_splice_wallet_tokenomics.rst‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
..
2+
Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
3+
..
4+
SPDX-License-Identifier: Apache-2.0
5+
6+
.. _cc_transfer_splice_wallet_tokenomics:
7+
8+
A CC Transfer using the Splice Wallet UI
9+
****************************************
10+
11+
A manual CC transfer using the UI of the Splice wallet (the wallet UI
12+
built into every validator) is an example of a :ref:`AmuletRules_Transfer <type-splice-amuletrules-amuletrulestransfer-23235>`.
13+
There are three types of manual transfers possible with the Splice
14+
wallet UI:
15+
16+
- *Amulet legacy transfer* offer where the receiver has to accept the transfer offer and then automation on the sender’s side completes the transfer. The ``provider`` party on the
17+
:ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>`
18+
is the ``sender``. The ``sender`` is assigned to the :ref:`ValidatorRewardCoupon <type-splice-amulet-validatorrewardcoupon-76808>`
19+
user field. These transfers are never featured.
20+
21+
- A two-step, *CN token standard based*
22+
:ref:`Transfer <type-splice-api-token-transferinstructionv1-transfer-51973>`
23+
offer first locks the desired CC amount; on acceptance, it is
24+
unlocked and the transfer is completed. This does not rely on
25+
automation and works well for external parties. Note that there
26+
the two steps show up in the wallet, with each step having fees
27+
that are rewarded:
28+
29+
- The first step locks the CC as part of creating the transfer
30+
offer. Some additional CC is locked, when compared with the
31+
``Amulet`` legacy transfer offer, to account for possible holding
32+
fees if the request is not accepted quickly. The locking fee
33+
creates both an ``AppRewardCoupon`` and ``ValidatorRewardCoupon`` which
34+
accrue to the ``sender``. These transfers are not featured.
35+
36+
- When the ``receiver`` accepts the transfer, the CC is unlocked, the CC
37+
amount is transferred to the ``receiver``, and any overage change
38+
is returned to the ``sender``. The fees for this step generate both
39+
an ``AppRewardCoupon`` and ``ValidatorRewardCoupon`` which accrue to
40+
the ``sender``. These transfers are not featured.
41+
42+
In both cases, the ``AppRewardCoupon`` reward is small because it results from usage fees.
43+
44+
- *One-step transfer* to a ``receiver`` that has preapproved incoming CC
45+
transfers set up via a
46+
:ref:`TransferPreapproval <type-splice-wallet-transferpreapproval-transferpreapprovalproposal-39002>`
47+
contract. The validator operator of the ``receiver`` is the ``provider``
48+
party on the
49+
``TransferPreapproval``. The
50+
``TransferPreapproval``
51+
contract is only visible to: the ``receiver``, the receiver's
52+
validator operator party, and SuperValidators.
53+
The transfer is featured if the ``provider`` party is a featured application provider.
54+
The reason for this being a featured transfer, is that this ``provider`` party enabled the receipt
55+
of the CC for the external party by creating the ``TransferPreapproval`` and taking care of its regular renewal.
56+
The legacy or token standard based
57+
one-step transfers work the same.
58+
59+
When comparing the ``Amulet`` legacy and token standard two-step transfers,
60+
a difference is that the token standard transfer has additional coupons
61+
for the CC locking fees.
62+
63+

‎docs/src/background/tokenomics/feat_app_act_marker_tokenomics.rst‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
..
2+
Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
3+
..
4+
SPDX-License-Identifier: Apache-2.0
5+
6+
.. _feat_app_act_marker_tokenomics:
7+
8+
Featured Application Activity Marker
9+
************************************
10+
11+
The *featured application activity marker* is specified in
12+
`CIP 47 <https://github.com/global-synchronizer-foundation/cips/blob/main/cip-0047/cip-0047.md>`__. A summary follows.
13+
14+
Featured application activity markers
15+
(:ref:`FeaturedAppActivityMarker <type-splice-amulet-featuredappactivitymarker-16451>`)
16+
can be created for a transaction that adds value
17+
but does not involve a CC Transfer (e.g., a stable coin transfer or the settlement of a trade).
18+
`CIP 47 <https://github.com/global-synchronizer-foundation/cips/blob/main/cip-0047/cip-0047.md>`__ says:
19+
20+
Featured application providers are expected to create featured application activity markers only for transactions that
21+
correspond to a transfer of an asset, or an equivalent transaction, which was enabled by the application provider.
22+
The detailed fair usage policy and enforcement thereof is left up to the Tokenomics Committee of the Global Synchronizer Foundation (GSF).
23+
24+
Generally the guidance is to create a ``FeaturedAppActivityMarker`` for any economically important event, such as:
25+
26+
- Lock or unlock a Real World Asset (RWA).
27+
28+
- Transfer a RWA.
29+
30+
- Mint or burn tokens.
31+
32+
However, it should not be created for any intermediate steps or a `propose step <https://docs.digitalasset.com/build/3.3/sdlc-howtos/smart-contracts/develop/patterns/propose-accept.html>`__.
33+
34+
A ``FeaturedAppActivityMarker`` is immediately converted into an
35+
:ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>` by the automation run by the Super Validators.
36+
The :ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>`
37+
is created with the DSO as the ``signatory`` and the ``provider`` field
38+
as an observer. By default, the ``provider`` can mint CC in the minting
39+
step. The ``featured`` field is set to ``true`` to indicate eligibility to
40+
receive featured application rewards, based on a :ref:`FeaturedAppRight <type-splice-amulet-featuredappright-765>` contract.
41+
42+
There can be several ``FeaturedAppActivityMarkers`` per transaction tree
43+
which increases the total reward. However, this is only allowed for composed transactions (e.g. a settlement transaction) where trading
44+
venue and all the registries of the transferred assets would get featured app rewards. It is also possible for a single
45+
Canton transaction tree to include
46+
:ref:`ValidatorRewardCoupon <type-splice-amulet-validatorrewardcoupon-76808>`,
47+
an
48+
:ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>`
49+
and a
50+
:ref:`FeaturedAppActivityMarker <type-splice-amulet-featuredappactivitymarker-16451>`\ (s)
51+
if there are sub-transcations that create each separately.
52+
53+
54+
A non-featured app cannot accrue a ``FeaturedAppActivityMarker``.
55+
56+
Creating a Featured Application Activity Marker
57+
***********************************************
58+
59+
There are two prerequisites for an application to create a
60+
``FeaturedAppActivityMarker``. The first is to become an approved featured
61+
application which was described in the
62+
:ref:`types_of_activity_records`
63+
section. The second is to update the application code:
64+
65+
1. Find the fully qualified package-id of the interface definition for the
66+
:ref:`FeaturedAppRight <type-splice-api-featuredapprightv1-featuredappright-34177>`
67+
interface which is
68+
``7804375fe5e4c6d5afe067bd314c42fe0b7d005a1300019c73154dd939da4dda:Splice.Api.FeaturedAppRightV1:FeaturedAppRight``
69+
for ``Splice.Api.FeaturedAppRightV1``. The command ``daml damlc
70+
inspect-dar`` can be used to find this.
71+
72+
2. Query the ledger using this ID to retrieve contracts from the Daml
73+
ledger that implement the
74+
:ref:`FeaturedAppRight <type-splice-api-featuredapprightv1-featuredappright-34177>`
75+
interface. The ``curl`` example below illustrates this approach.
76+
77+
.. code-block:: bash
78+
79+
curl "http://$lapiParticipant/v2/state/active-contracts" \
80+
"$jwtToken" "application/json" \
81+
--data-raw '{
82+
"filter": {
83+
"filtersByParty": {
84+
"'$holderPartyId'": {
85+
"cumulative":
86+
[
87+
{
88+
"identifierFilter": {
89+
"InterfaceFilter": {
90+
"value": {
91+
"interfaceId": "'7804375fe5e4c6d5afe067bd314c42fe0b7d005a1300019c73154dd939da4dda:Splice.Api.FeaturedAppRightV1:FeaturedAppRight'",
92+
"includeInterfaceView": true,
93+
"includeCreatedEventBlob": false
94+
}
95+
}
96+
}
97+
}
98+
]}
99+
}
100+
},
101+
"verbose": false,
102+
"activeAtOffset":"'$latestOffset'"
103+
}'
104+
105+
3. The application's Daml code will have to depend on the ``splice-api-featured-app-v1.dar`` and take an argument of type ``ContractId FeaturedAppRight`` on the choice
106+
whose execution should be featured, which allows that choice's body to call the ``FeaturedAppRight_CreateActivityMarker`` in the next step.
107+
108+
3. In the application's Daml code, using the ``FeaturedAppRight`` interface, exercise
109+
the ``FeaturedAppRight_CreateActivityMarker`` choice. Set the
110+
``templateId`` to the fully qualified interface ID above.
111+
112+
4. For testing examples, please review the example DamlScript test
113+
`here <https://github.com/hyperledger-labs/splice/blob/a32995a0df2d447b9e76d81b770a06c296295ab5/daml/splice-dso-governance-test/daml/Splice/Scripts/TestFeaturedAppActivityMarkers.daml#L4>`__.
114+
115+
Consider a single, simple transaction of a RWA which creates a single
116+
``FeaturedAppActivityMarker`` activity record for one ``provider`` and
117+
the ``beneficiary`` is the ``provider``:
118+
119+
1. A :ref:`FeaturedAppActivityMarker <type-splice-amulet-featuredappactivitymarker-16451>` contract is created in the business transaction. The
120+
``provider`` is set to the featured application provider's party. The ``beneficiary`` must be set (unlike an
121+
:ref:`AppRewardCoupon <type-splice-amulet-apprewardcoupon-57229>`) to the party that should be eligible to mint the CC for that activity. The ``provider`` field of the
122+
FeaturedAppActivityMarker is set by calling the interface choice :ref:`FeaturedAppRight_CreateActivityMarker <type-splice-api-featuredapprightv1-featuredapprightcreateactivitymarker-36646>`.
123+
124+
2. No ``ValidatorRewardCoupon`` is created.
125+
126+
127+
It is possible to share the attribution of activity for the ``FeaturedAppActivityMarker``. The
128+
``FeaturedAppRight_CreateActivityMarker`` choice accepts a list of
129+
:ref:`AppRewardBeneficiary <type-splice-api-featuredapprightv1-apprewardbeneficiary-32645>`
130+
contracts. Then a ``FeaturedAppActivityMarker`` is created for each
131+
``beneficiary`` with the ``weight`` field set appropriately.
132+
133+

‎docs/src/background/tokenomics/index.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
..
2+
Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
3+
..
4+
SPDX-License-Identifier: Apache-2.0
5+
6+
.. _app_tokenomics:
7+
8+
Tokenomics
9+
==========
10+
11+
Following is an overview of the Canton Network tokenomics for
12+
application developers or validator operators. It builds on the "`Canton
13+
Coin: A Canton-Network-native payment
14+
application <https://www.digitalasset.com/hubfs/Canton%20Network%20Files/Documents%20(whitepapers%2c%20etc...)/Canton%20Coin_%20A%20Canton-Network-native%20payment%20application.pdf?__hstc=169870847.16854726061d8b28be85af48c17588c4.1750870506327.1750870506327.1750870506327.1&__hssc=169870847.1.1750870506328&__hsfp=1243925796&_gl=1*1fkzmuj*_gcl_au*MTkyOTE1NjAyNC4xNzUwODcwNTA2*_ga*NDU1NzM2NzgyLjE3NTA4NzA1MDY.*_ga_GVK9ZHZSMR*czE3NTA4NzA1MDUkbzEkZzAkdDE3NTA4NzA1MDUkajYwJGwwJGgw>`__"
15+
whitepaper and assumes you have read the whitepaper.
16+
17+
.. toctree::
18+
19+
overview_tokenomics.rst
20+
feat_app_act_marker_tokenomics.rst
21+
cc_transfer_splice_wallet_tokenomics.rst
22+
traffic_tokenomics.rst
23+
val_live_tokenomics.rst
24+
sv_live_tokenomics.rst

0 commit comments

Comments
 (0)