Implement new ledger state query: constitutionalCommittee

This 'required' a small breaking change in one of the new Conway certificate, to better reflect on the relationship there is between those certificates and the new query.
CardanoSolutions · Apr 28, 2024 · 5c89f25 · 5c89f25
1 parent 12889c3
commit 5c89f25
Show file tree

Hide file tree

Showing 13 changed files with 627 additions and 39 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,16 +11,58 @@ pre: "<b>5. </b>"
 #### Added
 
 - Integrated with `cardano-node==8.10.1-pre`.
+
+- A new ledger state query [`queryLedgerState/constitutionalCommittee`](https://ogmios.dev/api/#operation-publish-/?QueryLedgerStateConstitutionalCommittee).
+
 - A new transaction submission error: [ConflictingInputsAndReferences](https://ogmios.dev/mini-protocols/local-tx-submission#schema-3164/ConflictingInputsAndReferences) (`code=3164`).
 
 #### Changed
 
+- > [!WARNING]
+  > Adjusted the schema of constitutional committee certificates in order to harmonize responses between certificates and the new `constitutionalCommittee` ledger query.
+  >
+  > <table>
+  > <tr><th>before</th><th>after</th></tr>
+  > <tr>
+  > <td>
+  > ```json
+  > {
+  >   "type": "constitutionalCommitteeHotKeyRegistration",
+  >   "member": {
+  >     "id": "0000",
+  >   },
+  >   "hotKey": "0000"
+  > }
+  > ```
+  > </td>
+  > <td>
+  > ```json
+  > {
+  >   "type": "constitutionalCommitteeDelegation",
+  >   "member": {
+  >     "id": "0000",
+  >   },
+  >   "delegate": {
+  >     "status": "authorized",
+  >     "id": "000"
+  >   }
+  > }
+  > ```
+  > </td>
+  > </tr>
+  > </table>
+
 - Fixed integer overflow happening when encoding relative time bounds in era summary, causing times to be shown as negative values.
 
+- Fixed parsing of the `constitution` ledger query which now resolves properly.
+
 #### Removed
 
 - N/A
 
+---
+---
+
 ### [6.2.0] - 2024-03-22
 
 #### Added
@@ -37,6 +79,9 @@ pre: "<b>5. </b>"
 
 - N/A
 
+---
+---
+
 ### [6.1.0] - 2024-02-21
 
 #### Added
@@ -65,6 +110,9 @@ pre: "<b>5. </b>"
 
 - `InternalLedgerTypeConversionError` which can no longer occur.
 
+---
+---
+
 ### [6.0.3] - 2024-02-02
 
 #### Added

diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ See our [Ogmios client starter kit](https://github.com/CardanoSolutions/ogmios-t
   queryLedgerState             | Information
   ---                          | ---
   `constitution`               | The current on-chain constitution.
+  `constitutionalCommittee`    | A complete summary of the constitutional committee.
   `epoch`                      | The current epoch of the ledger.
   `eraStart`                   | The information regarding the beginning of the current ledger era.
   `eraSummaries`               | Era bounds and slot parameters details, required for proper slotting arithmetic.

diff --git a/clients/TypeScript/packages/schema/src/index.ts b/clients/TypeScript/packages/schema/src/index.ts
@@ -54,7 +54,7 @@ export type Certificate =
   | StakePoolRegistration
   | StakePoolRetirement
   | GenesisDelegation
-  | ConstitutionalCommitteeHotKeyRegistration
+  | ConstitutionalCommitteeDelegation
   | ConstitutionalCommitteeRetirement
   | DelegateRepresentativeRegistration
   | DelegateRepresentativeUpdate
@@ -84,6 +84,18 @@ export type Relay = RelayByAddress | RelayByName;
  * An epoch number or length.
  */
 export type Epoch = number;
+export type ConstitutionalCommitteeDelegate =
+  | {
+      status: "authorized";
+      id: DigestBlake2B224;
+    }
+  | {
+      status: "resigned";
+      metadata?: Anchor;
+    }
+  | {
+      status: "none";
+    };
 export type None = null;
 /**
  * A network target, as defined since the Shelley era.
@@ -298,6 +310,12 @@ export interface Ogmios {
     | QueryLedgerStateEraMismatch
     | QueryLedgerStateUnavailableInCurrentEra
     | QueryLedgerStateAcquiredExpired;
+  QueryLedgerStateConstitutionalCommittee: QueryLedgerStateConstitutionalCommittee;
+  QueryLedgerStateConstitutionalCommitteeResponse:
+    | QueryLedgerStateConstitutionalCommitteeResponse
+    | QueryLedgerStateEraMismatch
+    | QueryLedgerStateUnavailableInCurrentEra
+    | QueryLedgerStateAcquiredExpired;
   QueryLedgerStateEpoch: QueryLedgerStateEpoch;
   QueryLedgerStateEpochResponse:
     | QueryLedgerStateEpochResponse
@@ -705,14 +723,14 @@ export interface GenesisDelegate {
   vrfVerificationKeyHash: DigestBlake2B256;
 }
 /**
- * A constitutional committee member registers a hot key for voting on-chain. Constitutional committee members do not vote with their cold key directly. New registrations supersedes any preceding ones.
+ * A constitutional committee member delegates a hot credential for voting on-chain. Constitutional committee members do not vote with their cold key directly. New registrations supersedes any preceding ones.
  */
-export interface ConstitutionalCommitteeHotKeyRegistration {
-  type: "constitutionalCommitteeHotKeyRegistration";
+export interface ConstitutionalCommitteeDelegation {
+  type: "constitutionalCommitteeDelegation";
   member: {
     id: DigestBlake2B224;
   };
-  hotKey: DigestBlake2B224;
+  delegate: ConstitutionalCommitteeDelegate;
 }
 /**
  * A constitutional committee member resigns from the committee.
@@ -902,18 +920,19 @@ export interface ValueDelta {
 export interface GovernanceActionConstitutionalCommittee {
   type: "constitutionalCommittee";
   members: {
-    added: ConstitutionalCommitteeMember[];
+    added: ConstitutionalCommitteeMemberSummary[];
     removed: {
       id: DigestBlake2B224;
     }[];
   };
   quorum: Ratio;
 }
-export interface ConstitutionalCommitteeMember {
+export interface ConstitutionalCommitteeMemberSummary {
   id: DigestBlake2B224;
-  mandate: {
-    epoch: Epoch;
-  };
+  mandate?: Mandate;
+}
+export interface Mandate {
+  epoch: Epoch;
 }
 /**
  * A change in the constitution. Only its hash is recorded on-chain.
@@ -2122,6 +2141,8 @@ export interface ReleaseLedgerStateResponse {
 export interface QueryLedgerStateEraMismatch {
   jsonrpc: "2.0";
   method:
+    | "queryLedgerState/constitution"
+    | "queryLedgerState/constitutionalCommittee"
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
@@ -2147,6 +2168,8 @@ export interface QueryLedgerStateEraMismatch {
 export interface QueryLedgerStateUnavailableInCurrentEra {
   jsonrpc: "2.0";
   method:
+    | "queryLedgerState/constitution"
+    | "queryLedgerState/constitutionalCommittee"
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
@@ -2171,6 +2194,8 @@ export interface QueryLedgerStateUnavailableInCurrentEra {
 export interface QueryLedgerStateAcquiredExpired {
   jsonrpc: "2.0";
   method:
+    | "queryLedgerState/constitution"
+    | "queryLedgerState/constitutionalCommittee"
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
@@ -2216,6 +2241,49 @@ export interface Constitution {
   };
   metadata: Anchor;
 }
+/**
+ * Get the state of the constitutional committee (only available from Conway onwards).
+ */
+export interface QueryLedgerStateConstitutionalCommittee {
+  jsonrpc: "2.0";
+  method: "queryLedgerState/constitutionalCommittee";
+  id?: unknown;
+}
+export interface QueryLedgerStateConstitutionalCommitteeResponse {
+  jsonrpc: "2.0";
+  method: "queryLedgerState/constitutionalCommittee";
+  result: null | {
+    members: ConstitutionalCommitteeMember[];
+    quorum: null | Ratio;
+  };
+  id?: unknown;
+}
+/**
+ * A constitutional committee member as seen in the context of a specific epoch. Statuses and next states are to be seen from this specific epoch. The field 'next', when present, refers to any change happening to this member in the following epoch.
+ */
+export interface ConstitutionalCommitteeMember {
+  id: DigestBlake2B224;
+  /**
+   * A member status. 'active' indicates that this member vote will count during the ratification of the ongoing epoch. 'unrecognized' means that some hot credential currently points to a non-existing (or no longer existing) member.
+   */
+  status: "active" | "expired" | "unrecognized";
+  delegate: ConstitutionalCommitteeDelegate;
+  mandate?: Mandate;
+  next?:
+    | {
+        change: "toBeEnacted";
+      }
+    | {
+        change: "toBeRemoved";
+      }
+    | {
+        change: "expiring";
+      }
+    | {
+        change: "adjustingMandate";
+        mandate: Mandate;
+      };
+}
 /**
  * Query the current epoch number the ledger is at.
  */
@@ -2660,7 +2728,7 @@ export interface GenesisConway {
   era: "conway";
   constitution: Constitution;
   constitutionalCommittee: {
-    members: ConstitutionalCommitteeMember[];
+    members: ConstitutionalCommitteeMemberSummary[];
     quorum: Ratio;
   };
   updatableParameters: {

diff --git a/docs/content/mini-protocols/local-state-query.md b/docs/content/mini-protocols/local-state-query.md
@@ -101,6 +101,7 @@ queryNetwork                 | Information
 queryLedgerState             | Information
 ---                          | ---
 `constitution`               | The on-chain constitution.
+`constitutionalCommittee`    | A complete summary of the constitutional committee.
 `epoch`                      | The current epoch of the ledger.
 `eraStart`                   | The information regarding the beginning of the current ledger era.
 `eraSummaries`               | Era bounds and slot parameters details, required for proper slotting arithmetic.
@@ -333,6 +334,70 @@ Be aware that it is possible for an acquire request to fail even if (and in part
 
 ### Network
 
+#### constitution
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "queryLedgerState/constitution",
+  "result": {
+    "metadata": {
+      "url": "",
+      "hash": "0000000000000000000000000000000000000000000000000000000000000000"
+    },
+    "guardrails": null
+  },
+  "id": null
+}
+```
+
+#### constitutionalCommittee
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "queryLedgerState/constitutionalCommittee",
+  "result": {
+    "members": [
+      {
+        "id": "5f1b4429fe3bda963a7b70ab81135112a785afcf55ccd695b122e794",
+        "delegate": {
+          "status": "authorized",
+          "credential": "5aa349227e4068c85c03400396bcea13c7fd57d0ec78c604bc768fc5"
+        },
+        "status": "active",
+        "mandate": {
+          "epoch": 379
+        }
+      },
+      {
+        "id": "9393c87a66b1f7dd4f9b486a49232de92e39e18b3b20ac4a539b4df2",
+        "delegate": {
+          "status": "authorized",
+          "credential": "670994283668cea40218e0ef33c51aff39ca00a74f68ed428cf305ce"
+        },
+        "status": "active",
+        "mandate": {
+          "epoch": 379
+        }
+      },
+      {
+        "id": "b7bfc26ddc6718133a204af6872149b69de83dd3350f60b257e55773",
+        "delegate": {
+          "status": "none"
+        },
+        "status": "active",
+        "mandate": {
+          "epoch": 379
+        }
+      }
+    ],
+    "quorum": "2/3"
+  },
+  "id": null
+}
+```
+
 #### blockHeight
 
 ```json