Skip to main content

Governance actions

Common aspects of all types of governance actions​

A proposal is the process of putting together all the information required to submit a governance action to the chain. A proposal consists of:

  • A deposit
  • The reward account that will receive the deposit return
  • The governance action
  • An anchor

When using the cardano-cli to create a governance action, you will notice that it creates a proposal.

Deposit and stake credentials

Any ada holder can submit a governance action to the chain. They must provide a deposit, which will be returned when the action is finalized (whether it is ratified or has expired). To facilitate this process, the proposer must specify the stake credential that will receive the refunded deposit.

Previous governance action ID

To prevent unintended conflicts between governance actions of the same type, some governance actions must include the governance action ID of the most recently enacted action of its respective type. Notably, this requirement does not apply to treasury withdrawal and info governance actions.

You can get the last enacted governance action IDs with:

cardano-cli conway query gov-state --testnet-magic 4 | jq -r .nextRatifyState.nextEnactState.prevGovActionIds
{
  "Committee": {
    "govActionIx": 0,
    "txId": "fe2c99fe6bc75a9666427163d51ae7dbf5a60df40135361b7bfd53ac6c7912ec"
  },
  "Constitution": {
    "govActionIx": 0,
    "txId": "2bcf2a93cb840d72e6fbbad4d52419fa69a3971dee2e32fab414e32a44ecbaf7"
  },
  "HardFork": null,
  "PParamUpdate": null
}

Please note that both the update committee and motion of no confidence actions share the same space, referred to as 'pgaCommittee,' within the governance state. Consequently, the governance state stores a single value to represent both of these actions. The system also verifies either of these actions against this single stored value.

Anchors

When proposing a governance action, the proposer may employ an anchor, which comprises a URL hosting a document that outlines the rationale for the proposed changes, along with the document's hash.

The document at the URL can be of a free form. It's important that it should communicate to ada holders the what and the why of the proposal. This tutorial mostly uses 'https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld' as an example, see here for more details.

See CIP-100 | Governance Metadata and CIP-0108? | Governance Metadata - Governance Actions for standard. Following CIP-100, we canonize the metadata anchor first, via JSON-LD playground, which we then hash.

You can use cardano-cli to get the hash:

cardano-cli conway governance hash anchor-data --file-text treasury-withdrawal.canonical
931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5

Alternatively, utilize b2sum to hash the document:

b2sum -l 256 treasury-withdrawal.canonical
931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5  treasury-withdrawal.canonical

You will need to supply the hash of the document when creating a governance action.

Update committee actions​

Update committee to add a new CC member:​

Assume you want to add three CC members, who have generated cold keys and have provided their key hashes:

  • 89181f26b47c3d3b6b127df163b15b74b45bba7c3b7a1d185c05c2de
  • ea8738081fca0726f4e781f5e55fda05f8745432a5f8a8d09eb0b34b
  • 7f6721067362d4ae9ca73469fe983ce5572dad9028386100104b0da0

You can create a proposal to add them as new CC members with an expiration epoch (--epoch) for each of them. This is a good time to review the quorum. Let’s assume that 2/3 of the committee needs to accept the proposal:

Create the governance action proposal:

cardano-cli conway governance action update-committee \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --add-cc-cold-verification-key-hash 89181f26b47c3d3b6b127df163b15b74b45bba7c3b7a1d185c05c2de \
  --epoch 100 \
  --add-cc-cold-verification-key-hash ea8738081fca0726f4e781f5e55fda05f8745432a5f8a8d09eb0b34b \
  --epoch 95 \
  --add-cc-cold-verification-key-hash 7f6721067362d4ae9ca73469fe983ce5572dad9028386100104b0da0 \
  --epoch 90 \
  --threshold 2/3 \
  --out-file update-committee.action
  • Note: If there is a previously enacted governance action to update the committee, the proposal must also include --prev-governance-action-tx-id and --prev-governance-action-index.

Update committee to remove an existing CC member:​

Assume that you want to remove the CC member with the key hash 89181f26b47c3d3b6b127df163b15b74b45bba7c3b7a1d185c05c2de. You can do this with:

cardano-cli conway governance action update-committee \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --remove-cc-cold-verification-key-hash 89181f26b47c3d3b6b127df163b15b74b45bba7c3b7a1d185c05c2de \
  --threshold 1/2 \
  --prev-governance-action-tx-id fe2c99fe6bc75a9666427163d51ae7dbf5a60df40135361b7bfd53ac6c7912ec \
  --prev-governance-action-index 0 \
  --out-file update-committee.action

Update committee to only change the threshold:​

cardano-cli conway governance action update-committee \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --threshold 60/100 \
  --prev-governance-action-tx-id fe2c99fe6bc75a9666427163d51ae7dbf5a60df40135361b7bfd53ac6c7912ec \
  --prev-governance-action-index 0 \
  --out-file update-committee.action

Updating the constitution​

Should you decide to propose an update to the SanchoNet constitution, please note that all rules and principles outlined for SanchoNet should be fictional and unrelated to the actual rules on the Cardano blockchain. Quotes directly from Don Quixote are encouraged, as well as rules in a similar spirit that aren't directly extracted from the book. SanchoNet is not the space for serious discussions about the future governance of Cardano. For substantial conversations, please visit the dedicated forum to explore the weighty matters of Cardano's constitution with the depth they deserve. Cardano Forum

  • Find the last enacted governance action of this type:
cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.nextRatifyState.nextEnactState.prevGovActionIds.Constitution'
{
  "govActionIx": 0,
  "txId": "00caeb6c2db4575acc43be3e8f87b881dccb86283daf16aa2707275cbe7f3451"
}
  • Write a constitution update and save it to constitution.txt
  • Upload the constitution.txt file to a URL so that everyone can read it, for example, https://tinyurl.com/mr3ferf9
  • Check the hash of the constitution.txt file using b2sum.
wget https://tinyurl.com/mr3ferf9 -O constitution.txt
cardano-cli conway governance hash anchor-data --file-text constitution.txt
5d372dca1a4cc90d7d16d966c48270e33e3aa0abcb0e78f0d5ca7ff330d2245d

or

b2sum -l 256 constitution.txt
5d372dca1a4cc90d7d16d966c48270e33e3aa0abcb0e78f0d5ca7ff330d2245d  constitution.txt

Create the proposal to update the constitution:​

cardano-cli conway governance action create-constitution \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash "931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5" \
  --constitution-url https://tinyurl.com/mr3ferf9  \
  --constitution-hash "5d372dca1a4cc90d7d16d966c48270e33e3aa0abcb0e78f0d5ca7ff330d2245d" \
  --prev-governance-action-tx-id "00caeb6c2db4575acc43be3e8f87b881dccb86283daf16aa2707275cbe7f3451" \
  --prev-governance-action-index 0 \
  --out-file constitution.action

Motion of no confidence​

  • Find the last governance action enacted of this type:
cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.nextRatifyState.nextEnactState.prevGovActionIds.Committee'
{
  "govActionIx": 0,
  "txId": "fe2c99fe6bc75a9666427163d51ae7dbf5a60df40135361b7bfd53ac6c7912ec"
}

Create a no-confidence governance action:​

cardano-cli conway governance action create-no-confidence \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --prev-governance-action-tx-id fe2c99fe6bc75a9666427163d51ae7dbf5a60df40135361b7bfd53ac6c7912ec \
  --prev-governance-action-index 0 \
  --out-file no-confidence.action

Treasury withdrawal​

In addition to the stake credential required to obtain a deposit refund, the proposer must also furnish stake credentials for receiving funds from the treasury in the event that the governance action is approved.

Create the treasury withdrawal proposal:​

cardano-cli conway governance action create-treasury-withdrawal \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --funds-receiving-stake-verification-key-file stake.vkey \
  --transfer 50000000000 \
  --out-file treasury.action
  • Note that you do not need to provide any previous governance action ID on treasury withdrawals.

Info​

Create the 'info' governance action:​

cardano-cli conway governance action create-info --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url  https://tinyurl.com/yc74fxx4 \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --out-file info.action

Update protocol parameters to change the --key-reg-deposit-amt​

cardano-cli conway governance action create-protocol-parameters-update \
  --testnet \
  --governance-action-deposit $(cardano-cli conway query gov-state --testnet-magic 4 | jq -r '.currentPParams.govActionDeposit') \
  --deposit-return-stake-verification-key-file stake.vkey \
  --anchor-url https://raw.githubusercontent.com/Ryun1/metadata/main/cip108/treasury-withdrawal.jsonld \
  --anchor-data-hash 931f1d8cdfdc82050bd2baadfe384df8bf99b00e36cb12bfb8795beab3ac7fe5 \
  --key-reg-deposit-amt 1000000 \
  --out-file pp-update.action
  • Note: If there is a previously enacted governance action to update the protocol parameters, the proposal must also include --prev-governance-action-tx-id and --prev-governance-action-index.

Submitting the *.action action file in a transaction​

Submitting the *.action file to the blockchain is the essential step in bringing your proposal to life and making it accessible for the community to participate in the voting process. This process essentially transforms your proposal from a conceptual idea into an actionable item. Once submitted, it becomes part of the public ledger, while also allowing members of the governance bodies to review, discuss, and ultimately cast their votes on its approval or rejection.

  • Note that you can also use build-raw and calculate-min-fee to build transactions in an off-line settting. The example below uses the convenient build:
cardano-cli conway transaction build \
  --testnet-magic 4 \
  --tx-in "$(cardano-cli query utxo --address "$(cat payment.addr)" --testnet-magic 4 --out-file /dev/stdout | jq -r 'keys[0]')" \
  --change-address $(cat payment.addr) \
  --proposal-file info.action \
  --out-file tx.raw
cardano-cli conway transaction sign \
  --testnet-magic 4 \
  --tx-body-file tx.raw \
  --signing-key-file payment.skey \
  --out-file tx.signed
cardano-cli conway transaction submit \
  --testnet-magic 4 \
  --tx-file tx.signed

Finding the governance action ID of your proposal​

You may want to find your governance action ID to share it with others on Discord1 and seek their support. The transaction ID and the index of the transaction that submitted the proposal serve as the action ID. An effective way to find your governance action ID is by querying the governance state and filtering by (the proposer) stake key hash.

First, find your key hash with:

cardano-cli conway stake-address key-hash --stake-verification-key-file stake.vkey

8e0debc9fdc6c616ac40d98bf3950b436895eea9cccf0396a6e5e12b

Use jq to filter the gov-state output by the stake key hash. The output contains all the relevant information about your governance actions, including actionId:

cardano-cli conway query gov-state --testnet-magic 4 \
| jq -r --arg keyHash "8e0debc9fdc6c616ac40d98bf3950b436895eea9cccf0396a6e5e12b" '.proposals | to_entries[] | select(.value.returnAddr.credential.keyHash | contains($keyHash)) | .value'
{
  "action": {
    "contents": [
      [
        {
          "credential": {
            "keyHash": "7249a71391f08399f06b492eae7892a33191699625cff50b7dee55c6"
          },
          "network": "Testnet"
        },
        20388738581
      ]
    ],
    "tag": "TreasuryWithdrawals"
  },
  "actionId": {
    "govActionIx": 0,
    "txId": "4fcd92abf2ce3d6796c5fae51ea83d563ca8611359c9624fd1cecd7fa1ce71cc"
  },
  "committeeVotes": {
    "keyHash-23e05ad2b71317a6348ce4b68dae37aa1c0e545cdea740b23c21742e": "VoteNo",
    "keyHash-540bedcd4bdcbf523e899c3ef43f2b96ecec4f6303af58d15a413ed1": "VoteYes",
    "keyHash-6c1d098a366f2274651943a7f778b3b5459c129f0407a0db2902253a": "VoteYes"
  },
  "dRepVotes": {
    "keyHash-13797df5308dfebf2348fa58b312a177cf97939f5f7d21168e1a54db": "VoteYes",
    "keyHash-9853551d8b99884f51608822e012bbf0d444eb7bea2807ee664f1241": "Abstain",
    "keyHash-cf09b59e134fa14e48da39b552c02299a054d7c8b895b3d827453672": "VoteNo"
  },
  "deposit": 1000000000,
  "expiresAfter": 34,
  "proposedIn": 33,
  "returnAddr": {
    "credential": {
      "keyHash": "8e0debc9fdc6c616ac40d98bf3950b436895eea9cccf0396a6e5e12b"
    },
    "network": "Testnet"
  },
  "stakePoolVotes": {}
}