> 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/get-started/complete-your-first-governance-action.md). # Complete your first governance action [Overview](/decentralization-manager/overview.md) · [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md) ### Why start with a generic vote? A generic vote runs the full propose, confirm, and execute flow. It pauses no service, moves no token, and changes no membership or threshold. Execution records the vote in a `GovernanceExecutionResult` contract. The vote has no other effect on the ledger. ### Before you start * A Decentralized Party exists, and every member node hosts it. * Each node stores party credentials for the party, and **Test Auth** succeeds. See [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md). * The party has an active `GovernanceRules` contract. The party page then shows a **Governance** section and a **Gov Threshold** card. To deploy the contract, see [Package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md). * On each node, the **Authentication** section shows the member party as **Member**. * On each node, the operator holds the admin role when `DECPM_ADMIN_ROLE` is set. Propose, confirm, execute, expire, and cancel-proposal require that role. See [Authentication and operator roles](/decentralization-manager/operations-and-reference/authentication-and-operator-roles.md). * The **Action Timeout** card shows enough time for every member to confirm. ### Two thresholds The party page shows two thresholds: * **Threshold** is the topology threshold. It counts the namespace owners that must sign a topology change. You set it when you create the party. * **Gov Threshold** is the governance threshold from the `GovernanceRules` contract. It counts the member confirmations that an action needs before execution. A governance action needs **Gov Threshold** confirmations. {% hint style="info" %} The active `GovernanceRules` contract sets the required confirmations. Do not rely on a threshold copied from another Decentralized Party. {% endhint %} ### 1. Define the decision Write a short, clear statement that the members can approve or reject as written. Include no secrets, no personal data, no contract IDs that can change, and no promises that the vote cannot keep. Example development decision: > Approve the documentation workflow test for this development Decentralized Party. ### 2. Create the proposal Create the first proposal from a member node. On that node: 1. Open **Parties** and click the party. 2. Click **New Proposal**. The **New Proposal** dialog opens. 3. In **Proposal Type**, select **Generic Vote**. 4. Enter the decision in **Vote Description**. 5. Click **Submit Proposal**. Decentralization Manager creates a `GenericVoteProposal` contract. It then submits a confirmation for the member party of the proposer. The proposal therefore starts with one confirmation. To use the API, send an operator access token. First, read the ID of the rules contract: ```bash curl -sS "http://localhost:8080/governance/state?party_id=my-party::1220..." \ -H "Authorization: Bearer $TOKEN" ``` The response holds `state.contract_id`, `state.members`, and `state.threshold`. Then create the proposal: ```bash curl -sS -X POST http://localhost:8080/governance/propose \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "party_id": "my-party::1220...", "rules_contract_id": "", "proposal": { "type": "generic_vote", "description": "Approve the documentation workflow test for this development Decentralized Party." } }' ``` A successful call returns `{"message": "Proposal created and confirmed"}`. ### 3. Review the proposal On each member node: 1. Open **Approvals**. On the other member nodes, the **GenericVote** card is under **Needs your action**. On the node of the proposer, the card is under **In progress** and shows **Awaiting others**. 2. Click **Review ▾** on the card. 3. Check the description and the proposal contract ID. 4. Read the **Full payload** JSON. It holds the `contract_id`, the `template_id`, and every create argument of the proposal under `create_arguments`. Match the proposal by its contract ID, label, description, and proposer. Do not confirm a proposal based on its description alone. {% hint style="warning" %} When `DECPM_ADMIN_ROLE` names a role, a caller without that role does not receive the full payload. The **Review** panel then does not show it. When `DECPM_ADMIN_ROLE` is unset, every authenticated caller counts as an admin and receives the full payload. Do not rely on this rule to keep proposal fields confidential unless the node sets `DECPM_ADMIN_ROLE`. {% endhint %} With the API, `GET /governance/confirmations` returns the open proposals under `domain_actions`: ```bash curl -sS "http://localhost:8080/governance/confirmations?party_id=my-party::1220..." \ -H "Authorization: Bearer $TOKEN" ``` Each entry holds `proposal_cid`, `action_label`, `description`, `proposer`, `confirmations`, `confirmation_count`, `executable_confirmation_cids`, and `can_execute`. The entry also holds `proposal_template_id` and `proposal_payload` under the same role rule as the **Full payload** JSON. ### 4. Confirm the proposal On each other member node, click **Confirm** on the card. The ring on the card shows the confirmation count against **Gov Threshold**. Stop when the count reaches the threshold. With the API: ```bash curl -sS -X POST http://localhost:8080/governance/confirm \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "party_id": "my-party::1220...", "rules_contract_id": "", "action": { "type": "governance_set_threshold", "new_threshold": 0 }, "governance_type": "core_domain", "proposal_cid": "" }' ``` The request schema requires `action`. A `core_domain` confirmation does not use it. The `proposal_cid` identifies the proposal. ### 5. Execute the approved action When the count reaches **Gov Threshold**, the card shows **Execute** on each member node. One member clicks **Execute**. With the API: ```bash curl -sS -X POST http://localhost:8080/governance/execute \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "party_id": "my-party::1220...", "rules_contract_id": "", "action": { "type": "governance_set_threshold", "new_threshold": 0 }, "confirmation_cids": ["", ""], "disclosed_contracts": [], "governance_type": "core_domain", "proposal_cid": "" }' ``` Take the `confirmation_cids` from `executable_confirmation_cids` in the confirmations response. Execution archives the proposal and consumes the confirmations. ### 6. Verify the result Confirm that: * The proposal no longer appears under **Needs your action** or **In progress**, or in `domain_actions`. * A `GovernanceExecutionResult` contract exists. It records `actionLabel` (`GenericVote`), `description`, `executor`, `confirmers`, and `executedAt`. * The **Audit Trail** section of the party page lists the proposal, the confirmations, and the execution in the **Governance** view. The API call is `GET /governance/chain-audit?party_id=`. * No membership, threshold, or application contract changed. * Every member node can see the result. Under **Approvals**, the **Completed** section of the node that executed the proposal shows **Executed**. The other nodes show **You proposed** or **You confirmed**, because each node records only its own actions. ### Cancel or expire Before execution, three separate actions remove governance state: | Action | Who | UI | API | | --------------------- | ------------------------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | Revoke a confirmation | The member that confirmed | **Revoke** on the card | `POST /governance/cancel` with `party_id`, `confirmation_cid`, and `governance_type` | | Cancel the proposal | The proposer only | **Cancel proposal** on the card | `POST /governance/cancel-proposal` with `party_id`, `proposal_cid`, and `confirmation_cid` | | Expire a confirmation | Any member, after the confirmation expires | **Dismiss** on an orphaned card | `POST /governance/expire` with `party_id`, `rules_contract_id`, `confirmation_cid`, and `governance_type` | **Cancel proposal** archives the proposal and the confirmation of the proposer in one transaction. The confirmations of the other members stay on the ledger. Their card then shows **Orphaned**. Each member revokes its own confirmation, or any member expires it after its expiry time. ### If governance changes during the vote Membership, the governance threshold, or the rights of the proposer can change while a proposal is open. The rules contract that is active at execution decides whether the confirmations are enough. When the rules no longer list the proposer as a member or an additional proposer, the card shows **Proposer not authorized**. The ledger then rejects every new confirmation. The UI therefore hides **Confirm**. Only the proposer can cancel that proposal. Keep the first test short. Do not run other governance changes at the same time. ### Troubleshooting | Symptom | Check | Next action | | -------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **New Proposal** opens the **Deploy Contracts** dialog | Whether the party has a `GovernanceRules` contract | Deploy the governance rules first. See [Package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md). | | Propose fails with "No credentials configured for party" | The party credentials on this node | Store the party credentials, then propose again. | | Propose reports that the proposal exists but the confirmation failed | The member party of this node and its user rights | Fix the cause, then click **Confirm** on the card. | | The proposal does not appear on a node | Party credentials, **Test Auth**, and the target network | Find the proposal contract ID before you create a new proposal. | | **Confirm** does not appear | Your own confirmation on the card, or the **Proposer not authorized** pill | Wait for the other members, or ask the proposer to cancel. | | **Execute** does not appear | The confirmation count against **Gov Threshold** | Collect more confirmations from current members. | | Confirmations expire | **Action Timeout** and the ledger time | Expire the old confirmations, then propose again if necessary. | | The result does not appear | Party visibility and the **Audit Trail** view | Refresh the audit trail. Record the sanitized contract and update IDs. | ### Technical sources * [Generic-vote walkthrough](https://github.com/DLC-link/decentralization-manager/blob/main/docs/USE_CASES.md#generic-voting) * [Custom action lifecycle](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CUSTOM_DAML_TEMPLATES.md) * [Governance architecture](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md) * [Governance API handlers](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/server/handlers/governance.rs) * [Governance response types](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/server/types.rs) * [Approvals view](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/frontend/src/components/NotificationsView.tsx) * [Execution result template](https://github.com/DLC-link/decentralization-manager/blob/main/daml/governance-core/daml/Governance/ExecutionResult.daml) ### Related pages * [Governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle.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) ### Next step 👉 **Understand the control flow:** [Governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle.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/get-started/complete-your-first-governance-action.md?ask=&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.