feat: add missing governance and pool apis #120

solidsnakedev · 2025-12-29T19:57:05Z

No description provided.

Copilot

Pull request overview

This PR adds missing governance and pool operation APIs to the Evolution SDK transaction builder, enabling DRep registration/management, Constitutional Committee operations, and stake pool registration/retirement.

Key Changes

New APIs: Added delegateToPool, delegateToDRep, delegateToPoolAndDRep (explicit delegation methods), plus registerDRep, updateDRep, deregisterDRep, authCommitteeHot, resignCommitteeCold, registerPool, and retirePool
Balance Calculation: Implemented proper accounting for certificate deposits/refunds and withdrawals in transaction balance calculations
Protocol Compliance: Added enforcement of Cardano's minimum 1 input requirement to prevent transaction replay attacks

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
`packages/evolution/test/VotingProcedures.CML.test.ts`	Removed debug console.log statements
`packages/evolution/test/ProposalProcedures.CML.test.ts`	Removed debug console.log statements and updated comment
`packages/evolution/src/sdk/builders/phases/utils.ts`	Added utility functions to calculate certificate deposits/refunds and withdrawals
`packages/evolution/src/sdk/builders/phases/Selection.ts`	Enforced minimum 1 input UTxO requirement for protocol compliance
`packages/evolution/src/sdk/builders/phases/ChangeCreation.ts`	Updated balance calculations to include deposits, refunds, and withdrawals
`packages/evolution/src/sdk/builders/phases/Balance.ts`	Updated balance verification to account for deposits, refunds, and withdrawals
`packages/evolution/src/sdk/builders/operations/index.ts`	Exported new Governance, Pool, and Mint operation modules
`packages/evolution/src/sdk/builders/operations/Stake.ts`	Added explicit delegation methods: delegateToPool, delegateToDRep, delegateToPoolAndDRep
`packages/evolution/src/sdk/builders/operations/Pool.ts`	Implemented pool registration and retirement operations
`packages/evolution/src/sdk/builders/operations/Operations.ts`	Added parameter types for new delegation, governance, and committee operations with deprecation marker for delegateTo
`packages/evolution/src/sdk/builders/operations/Governance.ts`	Implemented DRep and Constitutional Committee governance operations
`packages/evolution/src/sdk/builders/TransactionBuilder.ts`	Integrated new operation APIs and added poolDeposits tracking to state
`packages/evolution-devnet/test/TxBuilder.Stake.test.ts`	Added integration tests for new explicit delegation APIs
`packages/evolution-devnet/test/TxBuilder.Pool.test.ts`	Added integration tests for pool registration and retirement
`packages/evolution-devnet/test/TxBuilder.PlutusMint.test.ts`	Removed debug console.log statements
`packages/evolution-devnet/test/TxBuilder.Governance.test.ts`	Added integration tests for DRep and Constitutional Committee operations
`packages/evolution-devnet/src/Genesis.ts`	Added queryCurrentEpoch utility for testing pool retirement

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-29T20:02:03Z

packages/evolution/src/sdk/builders/operations/Pool.ts

+    yield* Ref.update(ctx, (state) => ({
+      ...state,
+      certificates: [...state.certificates, certificate]
+    }))


Missing debug log statement for retirePool operation. For consistency with other operations in the codebase (like registerPool on line 67), this function should log when a PoolRetirement certificate is added.

Suggested change

}))

}))

yield* Effect.logDebug(

`[RetirePool] Added PoolRetirement certificate for pool ${PoolKeyHash.toHex(params.poolKeyHash)} at epoch ${params.epoch}`

)

Copilot · 2025-12-29T20:02:04Z

packages/evolution/src/sdk/builders/operations/Pool.ts

+
+import * as Certificate from "../../../core/Certificate.js"
+import * as PoolKeyHash from "../../../core/PoolKeyHash.js"
+import { TransactionBuilderError,TxBuilderConfigTag, TxContext } from "../TransactionBuilder.js"


Missing space after comma in import statement. Should be "TransactionBuilderError, TxBuilderConfigTag" for consistent code style.

Suggested change

import { TransactionBuilderError,TxBuilderConfigTag, TxContext } from "../TransactionBuilder.js"

import { TransactionBuilderError, TxBuilderConfigTag, TxContext } from "../TransactionBuilder.js"

Copilot · 2025-12-29T20:02:04Z

packages/evolution/src/sdk/builders/operations/Governance.ts

+    yield* Ref.update(ctx, (state) => ({
+      ...state,
+      certificates: [...state.certificates, certificate]
+    }))


Missing debug log statement for registerDRep operation. For consistency with similar operations in the codebase (like registerPool which logs the deposit), this function should log when a RegDrepCert certificate is added.

Suggested change

}))

}))

yield* Effect.logDebug(

`Added RegDrepCert for DRep ${credentialToKey(params.drepCredential)} with deposit ${drepDeposit}`

)

Copilot · 2025-12-29T20:02:04Z

packages/evolution/src/sdk/builders/phases/Selection.ts

+    // This handles cases where refunds/withdrawals cover all costs, but no UTxO inputs exist
+    const stateAfterSelection = yield* Ref.get(ctx)
+    if (stateAfterSelection.selectedUtxos.length === 0) {
+      //TODO: double check if this is a good approach, it seems that this condition is only needed when refunds/withdrawals cover all costs


The TODO comment should be removed or addressed. This logic appears correct - enforcing minimum 1 input is required by Cardano protocol even when refunds/withdrawals cover all costs. The condition properly checks if no UTxOs are selected and adds the smallest available one. Consider either removing the TODO or providing more specific concerns if this approach needs review.

Suggested change

//TODO: double check if this is a good approach, it seems that this condition is only needed when refunds/withdrawals cover all costs

// At this point refunds/withdrawals may have covered all costs, leaving no selected inputs;

// however, Cardano still requires at least one input UTxO, so we pick the smallest available one

Copilot · 2025-12-29T20:02:05Z

packages/evolution/src/sdk/builders/phases/utils.ts

+ * Certificates with refunds (money IN):
+ * - UnregCert: Stake deregistration refund
+ * - UnregDrepCert: DRep deregistration refund
+ * - RetirePoolCert: Pool retirement refund (PoolRetirement)


Inaccurate documentation comment: The comment on line 25 states "RetirePoolCert: Pool retirement refund (PoolRetirement)" suggesting it provides a refund, but the code correctly implements no refund (lines 66-70). The documentation on line 25 should be corrected to indicate that pool retirement does NOT provide a refund in the Conway era, matching the implementation.

Suggested change

* - RetirePoolCert: Pool retirement refund (PoolRetirement)

* - RetirePoolCert: Pool retirement (no refund in Conway era; pool deposits are burned)

Copilot · 2025-12-29T20:02:06Z

packages/evolution/src/sdk/builders/operations/Governance.ts

+      return {
+        ...state,
+        certificates: [...state.certificates, certificate],
+        redeemers: newRedeemers,
+        deferredRedeemers: newDeferredRedeemers
+      }


Missing debug log statement for authCommitteeHot operation. For consistency with similar operations in the codebase, this function should log when an AuthCommitteeHotCert certificate is added.

Suggested change

return {

...state,

certificates: [...state.certificates, certificate],

redeemers: newRedeemers,

deferredRedeemers: newDeferredRedeemers

}

const updatedState = {

...state,

certificates: [...state.certificates, certificate],

redeemers: newRedeemers,

deferredRedeemers: newDeferredRedeemers

}

console.debug("[Governance] Added AuthCommitteeHotCert", {

coldCredential: credentialToKey(params.coldCredential),

hotCredential: credentialToKey(params.hotCredential)

})

return updatedState

Copilot · 2025-12-29T20:02:06Z

packages/evolution/src/sdk/builders/operations/Governance.ts

+        redeemers: newRedeemers,
+        deferredRedeemers: newDeferredRedeemers
+      }
+    })


Missing debug log statement for resignCommitteeCold operation. For consistency with similar operations in the codebase, this function should log when a ResignCommitteeColdCert certificate is added.

Suggested change

})

})

yield* Effect.logDebug(

`Added ResignCommitteeColdCert certificate for cold credential ${credentialToKey(params.coldCredential)}`

)

Copilot · 2025-12-29T20:02:06Z

packages/evolution-devnet/src/Genesis.ts

 */
 export const queryUtxos = (cluster: Cluster) => Effect.runPromise(queryUtxosEffect(cluster))
+
+//TODO: this function does not belong here


The TODO comment indicates this function might be misplaced. The queryCurrentEpoch function appears to be a devnet testing utility but is placed in Genesis.ts. Consider moving this to a more appropriate module (perhaps a separate Query.ts or TestUtils.ts) or removing the TODO if this location is acceptable.

Suggested change

//TODO: this function does not belong here

Copilot · 2025-12-29T20:02:07Z

packages/evolution/src/sdk/builders/operations/Pool.ts

+    // TODO: protocol param should be resolved earlier in builder phases, not here
+    // protocol param can come from the provider or the build options directly


The TODO comment indicates protocol parameters should be resolved earlier in builder phases. This is a valid architectural concern - fetching protocol parameters in individual operation programs creates coupling to the provider and may result in redundant fetches. Consider resolving protocol parameters once during an initialization phase and passing them through the context.

Copilot · 2025-12-29T20:02:07Z

packages/evolution/src/sdk/builders/phases/utils.ts

+export function calculateCertificateBalance(
+  certificates: ReadonlyArray<Certificate.Certificate>,
+  poolDeposits: ReadonlyMap<string, bigint>
+): { deposits: bigint; refunds: bigint } {
+  return certificates.reduce(
+    (acc, cert) => {
+      switch (cert._tag) {
+        // Registration certificates with deposits (money goes OUT)
+        case "RegCert":
+        case "RegDrepCert":
+        case "StakeRegDelegCert":
+        case "VoteRegDelegCert":
+        case "StakeVoteRegDelegCert":
+          acc.deposits += cert.coin
+          break
+
+        // Deregistration certificates with refunds (money comes IN)
+        case "UnregCert":
+        case "UnregDrepCert":
+          acc.refunds += cert.coin
+          break
+
+        // Pool registration - deposit tracked in state
+        case "PoolRegistration": {
+          const operatorHex = PoolKeyHash.toHex(cert.poolParams.operator)
+          const deposit = poolDeposits.get(operatorHex)
+          if (deposit !== undefined) {
+            acc.deposits += deposit
+          }
+          break
+        }
+
+        // Pool retirement - no refund in Conway era (deposit is not refunded)
+        // Pool deposits are burned upon retirement
+        case "PoolRetirement":
+          // No refund for pool retirement in Conway
+          break
+
+        // Delegation certificates with no deposit/refund
+        case "StakeRegistration":
+        case "StakeDeregistration":
+        case "StakeDelegation":
+        case "VoteDelegCert":
+        case "StakeVoteDelegCert":
+        case "AuthCommitteeHotCert":
+        case "ResignCommitteeColdCert":
+        case "UpdateDrepCert":
+          // No deposit or refund
+          break
+      }
+      return acc
+    },
+    { deposits: 0n, refunds: 0n }
+  )
+}


Missing unit test coverage for the new calculateCertificateBalance utility function. This function implements critical logic for calculating deposits and refunds from certificates. Given that the repository has extensive test coverage for other utilities and builder functions, this new utility should have comprehensive unit tests to verify correct handling of all certificate types, edge cases (empty certificates, missing pool deposits), and the balance calculations.

feat: add missing governance and pool apis

17bd541

Copilot AI review requested due to automatic review settings December 29, 2025 19:57

Copilot started reviewing on behalf of solidsnakedev December 29, 2025 19:57 View session

refactor: lint

b8c7b2d

Copilot AI reviewed Dec 29, 2025

View reviewed changes

solidsnakedev added 3 commits December 29, 2025 13:02

docs: update docs

ddedf73

refactor: add debug logs

d7bf211

docs: add changeset

ed9bdc0

solidsnakedev merged commit 7989aa7 into main Dec 29, 2025
4 checks passed

github-actions bot mentioned this pull request Dec 29, 2025

ci(changesets): version packages #121

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add missing governance and pool apis #120

feat: add missing governance and pool apis #120

Uh oh!

solidsnakedev commented Dec 29, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Copilot AI Dec 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-    }))
+    }))
+    yield* Effect.logDebug(
+      `[RetirePool] Added PoolRetirement certificate for pool ${PoolKeyHash.toHex(params.poolKeyHash)} at epoch ${params.epoch}`
+    )

	import { TransactionBuilderError,TxBuilderConfigTag, TxContext } from "../TransactionBuilder.js"
	import { TransactionBuilderError, TxBuilderConfigTag, TxContext } from "../TransactionBuilder.js"

	//TODO: double check if this is a good approach, it seems that this condition is only needed when refunds/withdrawals cover all costs
	// At this point refunds/withdrawals may have covered all costs, leaving no selected inputs;
	// however, Cardano still requires at least one input UTxO, so we pick the smallest available one

	* - RetirePoolCert: Pool retirement refund (PoolRetirement)
	* - RetirePoolCert: Pool retirement (no refund in Conway era; pool deposits are burned)

		// TODO: protocol param should be resolved earlier in builder phases, not here
		// protocol param can come from the provider or the build options directly

feat: add missing governance and pool apis #120

feat: add missing governance and pool apis #120

Uh oh!

Conversation

solidsnakedev commented Dec 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants