> 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/governance-lifecycle.md).

# Governance lifecycle

[Complete your first governance action](/decentralization-manager/get-started/complete-your-first-governance-action.md)

## Lifecycle summary

Decentralization Manager runs governance on the ledger as propose, confirm and execute. A `GovernanceRules` contract holds the rules for one Decentralized Party. The rules decide who can propose, who can confirm and execute, and how many confirmations an action needs.

Governance has two paths. A self-management action changes the rules contract itself. A domain action runs the logic of a separate proposal contract. The API field `governance_type` names the path: `core_self` or `core_domain`.

## 1. Governance rules

| Field                       | Meaning                                                 | Rule                                         |
| --------------------------- | ------------------------------------------------------- | -------------------------------------------- |
| `governanceParty`           | The Decentralized Party that the rules govern           | The only signatory of the rules contract     |
| `members`                   | The member parties that can confirm and execute         | Must not be empty                            |
| `threshold`                 | The number of member confirmations that an action needs | At least 1 and at most the number of members |
| `actionConfirmationTimeout` | The time that a confirmation stays valid                | At least 10 seconds                          |
| `additionalProposers`       | Optional non-member parties that can propose            | They cannot confirm or execute               |

The governance members are Daml parties. They are not the namespace owners of the party. See [Decentralized Party and Canton topology](/decentralization-manager/concepts-and-development/decentralized-party-and-canton-topology.md#membership-change).

Read the active rules before you propose or execute. A self-management action replaces the rules contract. The contract ID of the rules therefore changes after each self-management execution.

{% hint style="info" %}
The active rules contract defines the threshold. Do not rely on a count from another Decentralized Party.
{% endhint %}

## 2. Two paths: `core_self` and `core_domain`

|                 | Self-management (`core_self`)                                                                                                             | Domain action (`core_domain`)                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| What it changes | The rules contract: add or remove a member with a new threshold, set the threshold, set the timeout, add or remove an additional proposer | Anything that a `GovernableAction` template does: votes, transfers, utility onboarding, rewards and custom actions |
| Proposal        | No proposal contract. Each confirmation carries the action, and execution matches the confirmations by value                              | A proposal contract that implements `GovernableAction`. Each confirmation names the proposal contract ID           |
| First step      | The first member confirms with `POST /governance/confirm`                                                                                 | `POST /governance/propose` creates the proposal and confirms it as the proposer                                    |
| Confirm         | `POST /governance/confirm` with the same action                                                                                           | `POST /governance/confirm` with the `proposal_cid`                                                                 |
| Execute         | `POST /governance/execute`. The result is a new rules contract                                                                            | `POST /governance/execute`. The action runs, and a `GovernanceExecutionResult` records it                          |

The `governance_type` field defaults to `core_self`. The `core_self` path accepts only the six self-management actions. A confirm or execute request with any other action on that path returns HTTP 400. On the `core_domain` path, the node ignores the `action` field and uses the `proposal_cid`.

## 3. Proposal

A domain proposal is a contract of a template that implements `GovernableAction`. The interface comes from the `governance-action-v1` package. Its view gives the governance party, the proposer, an action label and a description.

`POST /governance/propose` makes two submissions. The first submission creates the proposal. The second submission confirms the proposal as the proposer. When the second submission fails, the proposal still exists. The error names the contract ID of the proposal. Confirm that proposal instead of proposing again.

Any party can create a proposal contract. Confirmations succeed only when the live rules list the proposer as a member or as an additional proposer.

An additional proposer can create a proposal but cannot confirm it. On a node whose member party is an additional proposer, `POST /governance/propose` creates the proposal and then returns an error.

## 4. Confirmation

Each eligible member reviews the proposal and confirms it independently. A domain confirmation names one proposal contract ID. A self-management confirmation carries one exact action value. A confirmation expires `actionConfirmationTimeout` after the member confirms.

The **Review** panel of a proposal card on the **Approvals** page shows the proposal template and every create argument. When `DECPM_ADMIN_ROLE` names a role, a caller without that role does not receive the proposal payload.

The ledger accepts a domain confirmation only when these rules hold:

* The confirmer is a current member.
* The proposal targets the governance party of the rules contract.
* The live rules list the proposer as a member or as an additional proposer.

### Unauthorized proposer

A proposer can leave the member set and the additional proposer set after the proposal exists. The ledger then rejects every new confirmation of that proposal. Decentralization Manager marks such a card **Proposer not authorized** and withholds **Confirm**.

The card still offers **Revoke**, **Cancel proposal** and **Execute** where they apply. These choices do not check the proposer. Only the proposer can cancel the proposal.

## 5. Execution

Any member can execute an action when the confirmations reach the threshold. The confirmations response then shows `can_execute: true`. The executor passes the confirmation contract IDs with the request.

For a domain action, the ledger checks these rules:

* The executor is a current member.
* Every confirmation in the request names this proposal.
* Every confirmation comes from a current member and has not expired.
* No member appears twice.
* The number of confirmations is at least the threshold.

One invalid confirmation in the list stops the whole execution. Leave out an expired confirmation or the confirmation of a removed member.

For a self-management action, every confirmation must carry the same action value. The ledger drops confirmations from non-members before it counts. An expired confirmation stops the execution.

A successful domain execution runs the action with the authority of the governance party. The execution consumes the proposal and the confirmations. A failed action rolls back the whole transaction. The proposal and its confirmations then stay active.

## 6. Result and audit record

A successful domain execution creates one `GovernanceExecutionResult` contract. The governance party is its signatory. The contract has these fields:

| Field             | Content                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `governanceParty` | The governance party that executed the action                    |
| `actionLabel`     | The label of the action, for example `Transfer` or `GenericVote` |
| `description`     | The description from the proposal                                |
| `executor`        | The member who executed the action                               |
| `confirmers`      | The members whose confirmations counted                          |
| `executedAt`      | The ledger time of the execution                                 |

The result has no proposer field and no copy of the proposal payload. The `description` is the permanent record of what the members approved. A self-management execution creates no `GovernanceExecutionResult`. The new rules contract is its result.

Decentralization Manager also keeps two audit views. `GET /governance/audit` lists the governance requests of this node. `GET /governance/chain-audit` reads the governance events of the party from the ledger.

## Cancel, revoke and expire

| Action              | Who                                        | Effect                                                                                                                     | Route and UI                                                |
| ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Revoke confirmation | The confirmer, at any time                 | Archives the confirmation of that member                                                                                   | `POST /governance/cancel`, **Revoke**                       |
| Cancel proposal     | The proposer only, with no vote            | Archives the proposal. The request can include the confirmation of the proposer, and the same transaction then archives it | `POST /governance/cancel-proposal`, **Cancel proposal**     |
| Expire confirmation | Any member, after the confirmation expires | Archives the expired confirmation                                                                                          | `POST /governance/expire`. On an orphaned card, **Dismiss** |
| Retry execution     | Any member                                 | Executes again after a failed attempt                                                                                      | `POST /governance/execute`                                  |

Nobody can remove the live confirmation of another member before it expires. The expiry check prevents one member from removing the vote of another member.

A cancelled proposal can leave the confirmations of other members on the ledger. These confirmations have no effect, because execution needs the proposal. Decentralization Manager marks such a card **Orphaned**. Each member revokes their own confirmation. Any member can expire the remaining confirmations after their timeout ends.

The governance party can also archive a proposal with the `GovernableAction_Cancel` choice. Decentralization Manager has no route for that choice.

## Concurrent governance changes

A pending domain action can overlap a change to the members or the threshold. The ledger checks the confirmations against the rules at execution time:

* Confirmations do not record the rules contract or the member set.
* A lower threshold can make a pending proposal executable at once.
* A removed member's confirmation stops an execution that includes it.
* A new timeout does not change the expiry of existing confirmations.
* A proposal from a removed additional proposer gets no new confirmations.

## Outcome metrics

Each node counts its own governance write attempts in the metric `decman_governance_actions_total`. The `step` label is `propose`, `confirm`, `execute`, `expire`, `cancel_confirmation` or `cancel_proposal`. The `outcome` label is `ok` or `error`.

The metric does not count a request that fails validation before the ledger call. See [Monitoring and logging](/decentralization-manager/operations-and-reference/monitoring-and-logging.md).

## Module-specific actions

The governance core supplies the lifecycle. Application packages define the action that runs after approval: token custody, utility onboarding, credentials, reward automation and custom Daml. A package can add its own validation and authorization rules. See [Module selection and custom Daml](/decentralization-manager/concepts-and-development/module-selection-and-custom-daml.md).

## Operator checklist

* [ ] Confirm the governance party and the rules contract ID.
* [ ] Read the current members, the threshold and the timeout.
* [ ] Check the proposal template and every argument under **Review**.
* [ ] Confirm as the intended member party.
* [ ] Check that `can_execute` is true before you execute.
* [ ] Query the `GovernanceExecutionResult` and the resulting application state.
* [ ] Read the current contract state before you retry a failed execution.

## Technical sources

* [Architecture: Governance System](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md#governance-system)
* [GovernanceRules template](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-core/daml/Governance/Rules.daml)
* [GovernanceExecutionResult template](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-core/daml/Governance/ExecutionResult.daml)
* [GovernanceConfirmation template](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-core/daml/Governance/Confirmation.daml)
* [GovernableAction interface](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-action-v1/daml/Governance/Action.daml)
* [Governance handlers](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/server/handlers/governance.rs)
* [Custom Daml templates](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CUSTOM_DAML_TEMPLATES.md)

## Related pages

* [Complete your first governance action](/decentralization-manager/get-started/complete-your-first-governance-action.md)
* [Module selection and custom Daml](/decentralization-manager/concepts-and-development/module-selection-and-custom-daml.md)
* [Package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md)
* [Membership and governance changes](/decentralization-manager/operations-and-reference/membership-and-governance-changes.md)
* [API and workflow reference](/decentralization-manager/operations-and-reference/api-and-workflow-reference.md)

## Next step

👉 **Choose the governed capability:** [Module selection and custom Daml](/decentralization-manager/concepts-and-development/module-selection-and-custom-daml.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/governance-lifecycle.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.