Skip to content
BitSafeBitSafeBitSafe
Go to websiteTalk to BitSafe

Use cases

Module selection and custom Daml

Each use case on this page gives the problem, the packages and workflows that it uses, and the pages that hold the procedures. The package names are the names in each daml.yaml.

Common setup

Section titled “Common setup”

Every use case starts with the same setup. Each step below has its own procedure page.

Step Tool Procedure
1. Create the Decentralized Party Onboarding workflow Create a Decentralized Party
2. Configure the party credentials PUT /party-config on each node Create a Decentralized Party
3. Grant the Ledger API rights for the party Grant Rights in the UI, or POST /auth/grant-rights on each node Create a Decentralized Party
4. Distribute the DARs DARs workflow, POST /dars/distribute Package and contract operations
5. Deploy GovernanceRules Contracts workflow, POST /contracts Package and contract operations

The contracts workflow does not upload DARs. POST /contracts takes no DAR files. Distribute every package with the DARs workflow before step 5.

After the setup, each governed operation follows the same lifecycle: propose, confirm and execute. See Governance lifecycle.

Section titled “Featured app rewards”

Problem. A featured application earns rewards for the Decentralized Party. The members must decide together who receives the rewards. Reward coupons also expire when nobody uses them in time.

Packages and workflows.

Task Package Action or workflow
Set the provider app reward beneficiaries and their weights governance-utility-onboarding-v1 SetProviderAppRewardBeneficiaries
Get a featured app right on DevNet governance-utility-onboarding-v1 RequestDevNetFeaturedAppRight
Let a validator mint the reward coupons governance-rewards-automation-v1 SetupMintingDelegation and AcceptExternalPartySetup
Assign the reward coupons to a fixed split without a vote per round governance-rewards-automation-v1 SetupCouponReassignmentDelegation, then the reward automation loop on each node

The beneficiary weights must add up to exactly 1.0. RequestDevNetFeaturedAppRight works only on DevNet. On other networks, the DSO grants a featured app right through its own governance.

Use the minting delegation or the coupon reassignment for a party, not both. The two modes compete for the same coupons.

Procedures. Reward automation and Architecture overview.

Utility services

Section titled “Utility services”

Problem. A Decentralized Party wants to act as a utility registry provider or registrar under shared control. The party issues an instrument, manages the instrument issuers and issues credentials. No single member may act alone.

Packages and workflows.

Task Package Actions
Create the provider service and the user service governance-utility-onboarding-v1 ProvisionProviderService, CreateProviderServiceRequest and CreateUserServiceRequest
Run the full onboarding in one vote governance-utility-onboarding-v1 SetupUtility
Split the provider role and the registrar role across two Decentralized Parties governance-utility-onboarding-v1 CreateProviderConfiguration, CreateRegistrarServiceRequest, OnboardRegistrar and ProvisionInstrument
Manage the instrument issuers governance-utility-onboarding-v1 OnboardInstrumentIssuers and OffboardInstrumentIssuers
Mint and burn the instrument governance-utility-onboarding-v1 Mint, Burn, AcceptMintRequest and AcceptBurnRequest
Issue and accept credentials governance-utility-credential-v1 OfferFreeCredential, OfferPaidCredential and AcceptFreeCredential

Each action is a domain proposal on POST /governance/propose. In the split layout, each Decentralized Party has its own GovernanceRules contract and its own members.

Use ProvisionProviderService to create the provider service. POST /contracts cannot create the provider service. The provider service has two signatories. The Decentralized Party signs externally.

Procedures. Governance lifecycle and API and workflow reference. The repository has the request bodies in its utility services walkthrough.

Token custody

Section titled “Token custody”

Problem. A Decentralized Party holds tokens for several organizations. No single member may move the tokens or accept a transfer alone.

Packages and workflows.

Task Package Action
Receive Canton Coin without an approval per transfer governance-token-custody-v1 SetupCcPreapproval. A provider must accept the resulting proposal.
Receive utility tokens without an approval per transfer governance-token-custody-v1 SetupTokenPreapproval. The preapproval takes effect at execution.
Send tokens governance-token-custody-v1 Transfer
Accept an incoming transfer governance-token-custody-v1 AcceptTransfer

A transfer proposal names the holdings that fund it. Another action can spend those holdings before the vote completes. The execution then fails. Use dedicated holdings and a short confirmation timeout.

A transfer offer stays valid for 24 hours by default. The validity_window_hours field of the proposal changes this window. A sender can also withdraw an incoming transfer before the members accept it.

Procedures. Governance lifecycle and API and workflow reference. The repository has the request bodies in its token custody walkthrough.

Multi-signature wallet

Section titled “Multi-signature wallet”

Problem. A wallet product needs approval from several signers for each transaction. The signers must change over time without a new wallet identity.

Packages and workflows. A Decentralized Party gives the wallet one party ID. The governance-core-v1 rules give the approval policy. Each signer runs a Decentralization Manager node. The wallet application calls the API of these nodes.

Wallet concept Decentralized Party equivalent
N of M signers threshold and members in GovernanceRules
Transaction proposal A domain proposal, for example Transfer
Signature collection Confirmations on POST /governance/confirm
Quorum reached can_execute: true in the confirmations response
Transaction execution POST /governance/execute
Add a signer The governance action governance_add_member, and the add-party workflow for the topology
Remove a signer The governance action governance_remove_member, and the kick workflow for the topology
Change the quorum The governance action governance_set_threshold

The governance threshold and the namespace threshold are separate settings. The change-threshold workflow changes the namespace threshold. Change each threshold on purpose.

A different model suits one key holder with several validating hosts. That model uses an external party with co-validation. See Decentralize an external party.

Procedures. Membership and governance changes, Add a member to a Decentralized Party and Governance lifecycle.

Generic voting

Section titled “Generic voting”

Problem. The members make a decision outside the ledger, for example a policy change. They want a permanent on-ledger record of the approval.

Packages and workflows. The governance-core-v1 package has the GenericVoteProposal template, with the action label GenericVote. The vote has no other effect on the ledger. Execution creates a GovernanceExecutionResult with the description, the executor, the confirmers and the execution time.

Procedures. Complete your first governance action and Governance lifecycle.

Technical sources

Section titled “Technical sources”
Section titled “Related pages”

Next step

Section titled “Next step”

Prepare the packages: Package and contract operations.