Add new ledger-state query: governanceProposals.

CHANGELOG.md

@@ -7,11 +7,12 @@ pre: "<b>6. </b>"
 math: true
 ---
 
-### [6.7.1] - 2024-09-21
+### [6.8.0] - 2024-09-21
 
 #### Added
 
-- N/A
+- Integrate `cardano-node==9.2.0` and associated dependencies.
+- Add new ledger-state query: `queryLedgerState/governanceProposals` to retrieve currently active governance proposals and their ratification state (i.e. ongoig votes).
 
 #### Changed
 

README.md

@@ -65,6 +65,7 @@ See our [Ogmios client starter kit](https://github.com/CardanoSolutions/ogmios-t
   `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.
+  `governanceProposals`        | Currently active governance proposals and their ratification state (i.e. votes).
   `liveStakeDistribution`      | Distribution of the stake across all known stake pools, relative to the **total** stake in the network.
   `projectedRewards`           | The projected rewards of an account in a context where the top stake pools are fully saturated. This projection gives, in principle, a ranking of stake pools that maximizes delegator rewards.
   `protocolParameters`         | The current protocol parameters.

clients/TypeScript/packages/client/src/LedgerStateQuery/Client.ts

@@ -5,6 +5,7 @@ import {
   eraStart,
   eraSummaries,
   genesisConfiguration,
+  governanceProposals,
   ledgerTip,
   liveStakeDistribution,
   networkBlockHeight,
@@ -27,6 +28,7 @@ import {
   GenesisByron,
   GenesisConway,
   GenesisShelley,
+  GovernanceProposalReference,
   Origin,
   Point,
   StakePoolId,
@@ -50,6 +52,7 @@ export interface LedgerStateQueryClient {
   epoch(): ReturnType<typeof epoch>
   eraStart(): ReturnType<typeof eraStart>
   eraSummaries: () => ReturnType<typeof eraSummaries>
+  governanceProposals(filter?: GovernanceProposalReference[]): ReturnType<typeof governanceProposals>
   genesisConfiguration(era: 'byron'): Promise<GenesisByron>
   genesisConfiguration(era: 'shelley'): Promise<GenesisShelley>
   genesisConfiguration(era: 'alonzo'): Promise<GenesisAlonzo>
@@ -155,6 +158,9 @@ export async function createLedgerStateQueryClient (
         }
       }
     },
+    governanceProposals (filter) {
+      return governanceProposals(context, filter)
+    },
     ledgerTip () {
       return ledgerTip(context)
     },

clients/TypeScript/packages/client/src/LedgerStateQuery/query/governanceProposals.ts

@@ -0,0 +1,28 @@
+import { InteractionContext, Method } from '../../Connection'
+import {
+  Ogmios,
+  GovernanceProposalReference,
+  GovernanceProposalState
+} from '@cardano-ogmios/schema'
+
+type Request = Ogmios['QueryLedgerStateGovernanceProposals']
+type Response = Ogmios['QueryLedgerStateGovernanceProposalsResponse']
+
+/**
+ * Get currently active {@link GovernanceProposalState}, possibly filtered by {@link GovernanceProposalReference}.
+ *
+ * @category LedgerStateQuery
+ */
+export function governanceProposals (
+  context: InteractionContext,
+  proposals?: GovernanceProposalReference[]
+): Promise<GovernanceProposalState[]> {
+  return Method<Request, Response, GovernanceProposalState[]>(
+    {
+      method: 'queryLedgerState/governanceProposals',
+      ...Array.isArray(proposals) ? { params: { proposals } } : {}
+    },
+    {},
+    context
+  )
+}

clients/TypeScript/packages/client/src/LedgerStateQuery/query/index.ts

@@ -3,6 +3,7 @@ export { epoch } from './epoch'
 export { eraStart } from './eraStart'
 export { eraSummaries } from './eraSummaries'
 export { genesisConfiguration } from './genesisConfiguration'
+export { governanceProposals } from './governanceProposals'
 export { ledgerTip } from './ledgerTip'
 export { liveStakeDistribution } from './liveStakeDistribution'
 export { networkBlockHeight } from './networkBlockHeight'

clients/TypeScript/packages/client/test/LedgerStateQuery.test.ts

@@ -148,6 +148,13 @@ describe('Local state queries', () => {
         ]
       })
       expect(utxoSet[0]).toBeDefined()
+
+      const proposals = await client.governanceProposals()
+      if (proposals.length > 0) {
+        const filteredProposals = await client.governanceProposals([proposals[0].proposal])
+        expect(filteredProposals.length).toBe(1)
+        expect(filteredProposals[0]).toEqual(proposals[0])
+      }
     })
 
     it('can handle concurrent requests ', async () => {
@@ -278,6 +285,16 @@ describe('Local state queries', () => {
         expect(utxoSet[0]).toBeDefined()
       })
     })
+    describe('governance proposals', () => {
+      it('fetches governance proposals, optionally by reference', async () => {
+        const proposals = await LedgerStateQuery.governanceProposals(context)
+        if (proposals.length > 0) {
+          const filteredProposals = await LedgerStateQuery.governanceProposals(context, [proposals[0].proposal])
+          expect(filteredProposals.length).toBe(1)
+          expect(filteredProposals[0]).toEqual(proposals[0])
+        }
+      })
+    })
     describe('rewardsProvenance', () => {
       it('fetches rewards provenance for the ongoing epoch (new)', async () => {
         const provenance = await LedgerStateQuery.rewardsProvenance(context)

clients/TypeScript/packages/repl/src/index.ts

@@ -41,6 +41,9 @@ import {
       era: Schema.EraWithGenesis
     ) => LedgerStateQuery.genesisConfiguration(context, era as 'alonzo'),
     getServerHealth: () => getServerHealth({ connection: createConnectionObject(connection) }),
+    governanceProposals: (
+      filters?: Schema.GovernanceProposalReference[]
+    ) => LedgerStateQuery.governanceProposals(context, filters),
     hasTransaction: (
       id: Schema.TransactionId
     ) => MempoolMonitoring.hasTransaction(context, id),

clients/TypeScript/packages/schema/src/index.ts

@@ -340,6 +340,12 @@ export interface Ogmios {
     | QueryLedgerStateEraMismatch
     | QueryLedgerStateUnavailableInCurrentEra
     | QueryLedgerStateAcquiredExpired;
+  QueryLedgerStateGovernanceProposals: QueryLedgerStateGovernanceProposals;
+  QueryLedgerStateGovernanceProposalsResponse:
+    | QueryLedgerStateGovernanceProposalsResponse
+    | QueryLedgerStateEraMismatch
+    | QueryLedgerStateUnavailableInCurrentEra
+    | QueryLedgerStateAcquiredExpired;
   QueryLedgerStateLiveStakeDistribution: QueryLedgerStateLiveStakeDistribution;
   QueryLedgerStateLiveStakeDistributionResponse:
     | QueryLedgerStateLiveStakeDistributionResponse
@@ -2232,6 +2238,7 @@ export interface QueryLedgerStateEraMismatch {
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
+    | "queryLedgerState/governanceProposals"
     | "queryLedgerState/liveStakeDistribution"
     | "queryLedgerState/projectedRewards"
     | "queryLedgerState/protocolParameters"
@@ -2260,6 +2267,7 @@ export interface QueryLedgerStateUnavailableInCurrentEra {
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
+    | "queryLedgerState/governanceProposals"
     | "queryLedgerState/liveStakeDistribution"
     | "queryLedgerState/projectedRewards"
     | "queryLedgerState/protocolParameters"
@@ -2287,6 +2295,7 @@ export interface QueryLedgerStateAcquiredExpired {
     | "queryLedgerState/epoch"
     | "queryLedgerState/eraStart"
     | "queryLedgerState/eraSummaries"
+    | "queryLedgerState/governanceProposals"
     | "queryLedgerState/liveStakeDistribution"
     | "queryLedgerState/projectedRewards"
     | "queryLedgerState/protocolParameters"
@@ -2452,6 +2461,47 @@ export interface EraParameters {
 export interface SlotLength {
   milliseconds: bigint;
 }
+/**
+ * Query currently active governance proposals, optionally restricted to specific governance proposal references.
+ */
+export interface QueryLedgerStateGovernanceProposals {
+  jsonrpc: "2.0";
+  method: "queryLedgerState/governanceProposals";
+  params?: GovernanceProposalsByReferences | WholeGovernanceProposals;
+  id?: unknown;
+}
+export interface GovernanceProposalsByReferences {
+  proposals: GovernanceProposalReference[];
+}
+export interface WholeGovernanceProposals {}
+export interface QueryLedgerStateGovernanceProposalsResponse {
+  jsonrpc: "2.0";
+  method: "queryLedgerState/governanceProposals";
+  result: GovernanceProposalState[];
+  id?: unknown;
+}
+export interface GovernanceProposalState {
+  proposal: GovernanceProposalReference;
+  deposit: ValueAdaOnly;
+  returnAccount: RewardAccount;
+  metadata: Anchor;
+  action:
+    | GovernanceActionProtocolParametersUpdate
+    | GovernanceActionHardForkInitiation
+    | GovernanceActionTreasuryTransfer
+    | GovernanceActionTreasuryWithdrawals
+    | GovernanceActionConstitutionalCommittee
+    | GovernanceActionConstitution
+    | GovernanceActionNoConfidence
+    | GovernanceActionInformation;
+  since: {
+    epoch: Epoch;
+  };
+  until: {
+    epoch: Epoch;
+  };
+  votes?: GovernanceVote[];
+}
 /**
  * Query the current distribution of the stake across all known stake pools, relative to the TOTAL stake in the network.
  */

docs/content/mini-protocols/local-state-query.md

@@ -105,13 +105,14 @@ queryLedgerState             | Information
 `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.
+`governanceProposals`        | Currently active governance proposals and their ratification state (i.e. votes).
 `liveStakeDistribution`      | Distribution of the stake across all known stake pools, relative to the **total** stake in the network.
 `projectedRewards`           | The projected rewards of an account in a context where the top stake pools are fully saturated. This projection gives, in principle, a ranking of stake pools that maximizes delegator rewards.
 `protocolParameters`         | The current protocol parameters.
 `proposedProtocolParameters` | The last update proposal w.r.t. protocol parameters, if any.
 `rewardAccountSummaries`     | Current delegation settings and rewards of chosen reward accounts.
 `rewardsProvenance`          | Get details about rewards calculation for the ongoing epoch.
-`stakePools`                 | The list of all currently registered and active stake pools with their current parameters. This query can be made with or without specifying list of target `stakePools`. When no stake pools are provided as parameter, the query returns the list of all stake pools and their parameters from the node. 
+`stakePools`                 | The list of all currently registered and active stake pools with their current parameters. This query can be made with or without specifying list of target `stakePools`. When no stake pools are provided as parameter, the query returns the list of all stake pools and their parameters from the node.
 `tip`                        | The current tip the ledger is at. Said differently, the slot number and header hash of the last block that has been processed by the ledger.
 `treasuryAndReserves`        | The Ada value of the treasury and reserves of the protocol.
 `utxo`                       | Current UTXO, possibly filtered by output reference.
@@ -487,6 +488,30 @@ Be aware that it is possible for an acquire request to fail even if (and in part
 }
 ```
 
+#### governanceProposals
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "queryLedgerState/governanceProposals"
+}
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "queryLedgerState/governanceProposals",
+  "params": {
+    "proposals": [
+      {
+        "transaction": { "id": "ee155ace9c40292074cb6aff8c9ccdd273c81648ff1149ef36bcea6ebb8a3e25" },
+        "index": 2
+      }
+    ]
+  }
+}
+```
+
 #### liveStakeDistribution
 
 ```json

docs/static/cardano.json

@@ -160,7 +160,7 @@
         }
       , "era":
         { "type": "string"
-        , "enum": [ "shelley", "allegra", "mary", "alonzo", "babbage" ]
+        , "enum": [ "shelley", "allegra", "mary", "alonzo", "babbage", "conway" ]
         }
       , "id": { "$ref": "cardano.json#/definitions/Digest<Blake2b, 256>" }
       , "ancestor":
@@ -1464,6 +1464,52 @@
       }
     }
 
+  , "GovernanceProposalState":
+    { "title": "GovernanceProposalState"
+    , "type": "object"
+    , "additionalProperties": false
+    , "required": [ "proposal", "action", "deposit", "returnAccount", "metadata", "since", "until", "votes" ]
+    , "properties":
+      { "proposal":
+        { "$ref": "cardano.json#/definitions/GovernanceProposalReference"
+        }
+      , "deposit":
+        { "$ref": "cardano.json#/definitions/Value<AdaOnly>"
+        }
+      , "returnAccount":
+        { "$ref": "cardano.json#/definitions/RewardAccount"
+        }
+      , "metadata":
+        { "$ref": "cardano.json#/definitions/Anchor"
+        }
+      , "action":
+        { "$ref": "cardano.json#/definitions/GovernanceAction"
+        }
+      , "since":
+        { "type": "object"
+        , "additionalProperties": false
+        , "required": ["epoch"]
+        , "properties":
+          { "epoch": { "$ref": "cardano.json#/definitions/Epoch" }
+          }
+        }
+      , "until":
+        { "type": "object"
+        , "additionalProperties": false
+        , "required": ["epoch"]
+        , "properties":
+          { "epoch": { "$ref": "cardano.json#/definitions/Epoch" }
+          }
+        }
+      , "votes":
+        { "type": "array"
+        , "items":
+          { "$ref": "cardano.json#/definitions/GovernanceVote"
+          }
+        }
+      }
+    }
+
   , "GovernanceVote":
     { "title": "GovernanceVote"
     , "description": "A vote on a governance proposal. The 'anchor' is optional and 'proposal' is only present from Conway onwards. Before Conway, a vote would always refer to all proposals part of the same transaction."