> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/decentralization-manager/concepts-and-development/module-selection-and-custom-daml.md).

# Module selection and custom Daml

## Choose a package

Each governed capability is a Daml package. Each package defines proposal templates that implement the `GovernableAction` interface. The names below are the package names in each `daml.yaml`.

| Need                                          | Package                            | Main actions                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The shared interface of every governed action | `governance-action-v1`             | The `GovernableAction` interface. Every package below depends on it.                                                                                                                                                                                                                                                                                                   |
| Governance rules and generic votes            | `governance-core-v1`               | `GovernanceRules`, the confirmation templates, `GovernanceExecutionResult` and `GenericVoteProposal`                                                                                                                                                                                                                                                                   |
| Token custody                                 | `governance-token-custody-v1`      | `Transfer`, `AcceptTransfer`, `SetupCcPreapproval` and `SetupTokenPreapproval`                                                                                                                                                                                                                                                                                         |
| Utility services and token issuance           | `governance-utility-onboarding-v1` | `SetupUtility`, `ProvisionProviderService`, provider and user service requests, registrar and instrument onboarding, instrument issuer onboarding and offboarding, `Mint`, `Burn`, `AcceptMintRequest`, `AcceptBurnRequest`, `SetProviderAppRewardBeneficiaries`, `SetEnableResultContracts`, `CreateDelegatedBatchedMarkersProxy` and `RequestDevNetFeaturedAppRight` |
| Credentials                                   | `governance-utility-credential-v1` | `OfferFreeCredential`, `OfferPaidCredential` and `AcceptFreeCredential`                                                                                                                                                                                                                                                                                                |
| Reward automation                             | `governance-rewards-automation-v1` | `SetupMintingDelegation`, `AcceptExternalPartySetup`, `SetupCouponReassignmentDelegation` and `RevokeCouponReassignmentDelegation`                                                                                                                                                                                                                                     |
| A custom governed action                      | Your own package                   | Any template that implements `GovernableAction`                                                                                                                                                                                                                                                                                                                        |

For the action packages, the names in the table are the action labels. The labels appear on the **Approvals** page and in each `GovernanceExecutionResult`.

Several packages also depend on Splice DARs and utility DARs. The repository keeps these dependencies under [`daml/dars/`](https://github.com/DLC-link/decentralization-manager/tree/main/daml/dars).

`governance-rewards-automation-v1` replaces the older `governance-rewards-v1` package. The two packages are not upgrade-compatible.

### Released DARs

The repository keeps the built DARs under [`releases/v1/`](https://github.com/DLC-link/decentralization-manager/tree/main/releases/v1). The newest version of each built-in package is:

| DAR file                                     | Package version |
| -------------------------------------------- | --------------- |
| `governance-action-v1-0.1.0.dar`             | 0.1.0           |
| `governance-core-v1-0.1.0.dar`               | 0.1.0           |
| `governance-token-custody-v1-0.1.0.dar`      | 0.1.0           |
| `governance-utility-onboarding-v1-0.5.0.dar` | 0.5.0           |
| `governance-utility-credential-v1-0.1.0.dar` | 0.1.0           |
| `governance-rewards-automation-v1-0.1.0.dar` | 0.1.0           |

Distribute every package that a party uses to every participant that hosts the party.

### Built-in package names

Decentralization Manager refers to the built-in packages by name, for example `#governance-core-v1`. Canton then selects the highest vetted version with that name.

`GET /party-config` reports these names. `PUT /party-config` configures credentials only. A request with a `packages` field returns HTTP 400.

A fork of a built-in package under a different name needs a change to the built-in names in the Decentralization Manager code and a rebuild.

## Custom Daml actions

A custom template implements the `GovernableAction` interface from `governance-action-v1`. The only governance data-dependency that the package needs is `governance-action-v1`. It does not need `governance-core` at build time.

The interface view has four fields:

| Field             | Meaning                                                    |
| ----------------- | ---------------------------------------------------------- |
| `governanceParty` | The Decentralized Party whose authority the action needs   |
| `proposer`        | The member or additional proposer who created the proposal |
| `actionLabel`     | A short, stable label for the UI and the audit record      |
| `description`     | A description that the execution result keeps              |

One `GovernanceRules` contract governs every custom action of its party. You do not deploy new rules for a new template.

### Template conventions

| Concern           | Convention                                                 | Reason                                                                 |
| ----------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| Signatory         | `proposer` only                                            | One member can create the proposal without a multi-party submission.   |
| Observer          | `governanceParty`                                          | The rules contract must fetch the proposal during confirm and execute. |
| `governanceParty` | Equal to the governance party of the rules contract        | The confirm choice checks it.                                          |
| `proposer`        | A member or an additional proposer                         | The confirm choice checks it against the live rules.                   |
| `actionLabel`     | A distinct label per template, for example `PauseResource` | The UI groups confirmations by label, and the audit records copy it.   |
| `description`     | A self-explanatory text                                    | The text is the permanent on-ledger record of the vote.                |
| Preconditions     | `ensure` clauses on the template                           | Invalid proposals fail at creation, before any vote.                   |

The `executeImpl` of the template runs with the authority of the governance party and of the proposer. It cannot use the authority of any other party. For a third-party signature, use a two-step flow: the action creates an offer, and the other party accepts it.

{% hint style="warning" %}
Every member node stores every contract that the governance party sees. This includes everything that `executeImpl` creates or exercises. Keep data that only some parties may see out of these contracts.
{% endhint %}

## How a custom proposal reaches governance

A custom proposal needs no change to Decentralization Manager. A member creates the proposal in one of two ways:

* **Path A: the contracts workflow.** `POST /contracts` creates contracts from typed field definitions, with signatures from the members. Use this path for infrastructure contracts that the governance party signs, such as `GovernanceRules`.
* **Path B: a direct Ledger API submission.** The proposer is the only signatory. A member creates the proposal with any Ledger API client and its own credentials.

The members then confirm and execute the proposal with `governance_type: "core_domain"` and the proposal contract ID. See [Governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle.md).

`POST /governance/propose` accepts only the built-in proposal types. A new proposal type on that route needs a change to the Decentralization Manager code.

## Deployment approvals

A contracts invitation lists the creates in a fixed order. For each create, the invitation names the resolved package ID, the module, the template and a SHA-256 commitment to the create arguments. Compare these values with the intended deployment before you accept.

Decentralization Manager applies these rules:

* Decentralization Manager resolves a package name to the newest installed version with that exact name. It does this before it stores the workflow run.
* A version with more than one package ID needs an explicit package ID.
* The resolved package ID stays fixed through preparation and retries, even after an upload of another version.
* Each peer computes the hash of the prepared transaction again before it signs.
* Each peer refuses changed arguments, other templates, exercises and extra nodes.

Contracts invitations from before these commitments must start again from an upgraded coordinator. Upgraded peers refuse to sign them. Upgrade every node before a deployment. A node accepts a peer only when the peer uses the same wire version and runs version `0.1.9` or later. All nodes of a Decentralized Party must run the same release. See [Backup, recovery, and upgrades](/decentralization-manager/operations-and-reference/backup-recovery-and-upgrades.md).

A DARs invitation names the file name and the SHA-256 hash of each DAR. On the **Approvals** page, a peer operator can download each DAR before they accept. The node checks the downloaded bytes against the hash in the invitation.

## Design steps

1. Define the application state and the governed action.
2. Decide who can propose and who executes.
3. Define the validation in `ensure` clauses and the failure behavior.
4. Implement the `GovernableAction` interface.
5. Build the DAR and test it with Daml Script tests.
6. Review the authorization and the privacy of every contract.
7. Distribute the DAR to every participant with the DARs workflow.
8. Check that every node has vetted the package.
9. Create one low-risk proposal, then confirm and execute it.
10. Query the `GovernanceExecutionResult` and the resulting application state.

The contracts workflow does not upload DARs. Step 7 therefore comes before any contract deployment. For step 8, use the **Packages** page or `GET /packages/compare-peers`. Any authenticated operator can call `GET /packages/compare-peers`. The admin role is not necessary.

For the routes and request bodies, see [Package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md).

## Versioning

Ship a breaking change as a new package with a new version suffix in its name, for example `-v2`. The old and new packages can then exist together until their pending proposals finish.

Do not change the behavior of a template version that is already in use. Members who confirm a proposal must be able to trust that its `executeImpl` stays the same.

## Boundaries

Custom Daml still needs Daml expertise, package management, testing and node operations. The framework removes repeated governance work. It does not remove application design or security review.

## Technical sources

* [Custom Daml templates](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CUSTOM_DAML_TEMPLATES.md)
* [Architecture: Governance System](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md#governance-system)
* [Daml packages](https://github.com/DLC-link/decentralization-manager/tree/main/daml)
* [Released DARs](https://github.com/DLC-link/decentralization-manager/tree/main/releases/v1)
* [governance-rewards-automation-v1 README](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-rewards-automation/README.md)
* [Built-in package names](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/config.rs)
* [Contract preparation](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/workflow/contracts/steps/prepare.rs)

## Related pages

* [Governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle.md)
* [Use cases](/decentralization-manager/concepts-and-development/use-cases.md)
* [Package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md)
* [API and workflow reference](/decentralization-manager/operations-and-reference/api-and-workflow-reference.md)
* [Complete your first governance action](/decentralization-manager/get-started/complete-your-first-governance-action.md)

## Next step

👉 **See the packages in context:** [Use cases](/decentralization-manager/concepts-and-development/use-cases.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bitsafe.finance/decentralization-manager/concepts-and-development/module-selection-and-custom-daml.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.