Canton SDK/Splice Daml APIs

Splice Daml APIs

The APIs below are published by Splice to aid decoupling different Canton Network applications. Consider using them to decouple your code from the upgrading cycles of your dependencies, when building Daml code that interacts with workflows of other apps in the Canton Network.

These APIs are not mandatory to use. Feel free to build your own Daml APIs, potentially using the APIs below as inspiration.

Canton Network Token Standard APIs (CIP-0056)

Refer to the Token Standard documentation section.

Reward Assignment API (CIP-0104)

As part of implementing CIP-0104 the following Daml API was introduced:

The API is meant for apps whose ultimate beneficiaries of rewards are different from the app provider party (e.g., decentralized apps). The API allows them to assign the rewards they receive for their app to their ultimate beneficiaries.

The API is based on a Daml interface, so that apps can use it from their Daml code without incurring a static dependency on splice-amulet and the corresponding upgrading challenges. The reward assignment choice can also be called directly from the Ledger API for apps that don’t use custom Daml code.

Note that the coupons always specify the original app provider party for whose activity the reward coupon was created. Thereby allowing consistent attribution of rewards collected to the app provider party.

Featured App Activity Markers API (CIP-0047)

Important

On networks where traffic-based app rewards as described in CIP-0104 are enabled, the Featured App Activity Markers API will become irrelevant. On such networks, the API is still supported, but no rewards can be earned using it. We recommend apps to stop creating featured app activity markers once CIP-0104 is enabled.

The documentation here is provided for apps that need to integrate with app rewards prior to CIP-0104 being enabled to avoid unnecessary traffic costs.

See the text of the CIP-0047 for its background on its design and its specification.
See the reference docs below for the Daml interfaces that are part of the Featured App Activity Markers API; or read the source code.

or the old API:
The utility package below provides templates that allow to delegate the usage of featured app rights to other parties for the purpose of executing token standard actions. Use these templates to earn app rewards on token standard operations, and to potentially share some of them with your users.

How to earn featured app rewards for wallet user activity

Assuming you are a wallet provider that runs a validator node for your users, then there are two options for you to earn featured app rewards for the activity of your wallet users. They are complementary, so you probably want to implement both of them:

Have your wallet users request your featured wallet provider party to maintain Canton Coin transfer preapproval contracts for them. Whenever such a contract is used to directly transfer CC to one of your wallet users, a featured app coupon is created for your wallet provider party.
Setup your wallet frontend such that the transactions submitted by your users create a featured app activity marker for your wallet provider party.

For token standard interactions, we recommend to use the WalletUserProxy template as explained below. It enables you to earn featured app rewards on sending all CN tokens (including CC) and to earn featured app rewards when your users accept, reject, or withdraw a CN token transfer offer. It further provides the option to execute bulk transfers of CN tokens.

If required, you can also write custom Daml code that creates the featured app activity markers for your wallet provider party on the relevant user actions. Feel free to reuse parts of the WalletUserProxy implementation for that purpose. Make sure to publish your code using a package name under your control to avoid upgrading conflicts.

Earning featured app rewards for direct transfers of non-CC tokens to your wallet users is currently not possible without special support from the app provider of the respective token.

How to use the WalletUserProxy to earn featured app rewards

Assuming you are a wallet provider that runs a validator node for your users, you can use the WalletUserProxy template to get credit for the activity of your wallet users as follows.

Apply for a featured app right for your wallet provider party, as explained on How to become a featured application.
Extract the latest version of the splice-util-featured-app-proxies.dar file from the release bundle (Download Bundle).
Upload the extracted .dar file to your validator node.
Create one WalletUserProxy contract for your featured wallet provider party using the Ledger API of your validator node.
Adjust your wallet frontend as follows:
1. Make the frontend fetch your wallet provider party’s FeaturedAppRight contract and the WalletUserProxy contract.
  
  You can read them from the Ledger API of your validator node using any user that has ReadAs rights for your wallet provider party. We recommend to cache and serve them using your wallet backend for performance reasons.
2. Make the frontend construct the transfer transaction by exercising the WalletUserProxy_TransferFactory_Transfer choice instead of the TransferFactory_Transfer choice of the token standard API. Include the fetched FeaturedAppRight and the WalletUserProxy contracts as disclosed contracts alongside the disclosed contracts received from the registry API when exercising the choice.
  
  See this Daml test script for a complete example of how to construct the choice.

Additional Splice Daml APIs

The app provider of an asset registry is not necessarily the same as the party controlling the minting and burning of tokens. A typical example are tokens that are bridged from another network. The following API targets that use-case; and thus enables to decouple the upgrade cycles of an asset registry from the ones of the bridging app.

The API is built in a similar style as the token standard APIs, but is not part of the token standard. In particular, implementors of the token standard are not required to implement this API.

Nevertheless the API definition is guaranteed to be stable, and can be used by for the purpose explained above. If there were changes to the API, then they would be published as a new version of the API using a fresh package name, so that both the old and the new version can be used in parallel.

Comments

← Back to Documentation