@claritydao/midnight-agora-sdk 0.1.0

package/src/governor-api.ts

@@ -0,0 +1,948 @@
+import type { GovernorPrivateState } from "./common-types";
+import { type ContractAddress } from "@midnight-ntwrk/compact-runtime";
+import { type Logger } from "pino";
+import {
+  type GovernorContract,
+  type GovernorProviders,
+  type DeployedGovernorContract,
+  GovernorPrivateStateId
+} from "./common-types";
+import * as utils from "./utils/index";
+import {
+  deployContract,
+  findDeployedContract
+} from "@midnight-ntwrk/midnight-js-contracts";
+import { Contract, witnesses } from "@agora-dao-midnight/contract";
+import { type FinalizedTxData } from "@midnight-ntwrk/midnight-js-types";
+import type { DeploymentConfig, ProposalAction } from "./types";
+import { VoteChoice, ConfigPresets } from "./types";
+import {
+  validateDeploymentConfig,
+  validateProposal,
+  validateVoteChoice,
+  validateAddress,
+  validatePositiveBigInt
+} from "./validators";
+import { InvalidParameterError } from "./errors";
+
+/** @internal */
+const governorContractInstance: GovernorContract = new Contract(witnesses);
+
+// Constants to replace magic numbers
+/** @internal */
+const MILLISECONDS_TO_SECONDS = 1000;
+
+/** @internal */
+const INITIAL_EFFECT_ID = BigInt(0);
+
+/** @internal */
+const DEFAULT_BIGINT_VALUE = BigInt(0);
+
+/** @internal */
+const getCurrentUnixTimestamp = (): bigint =>
+  BigInt(Math.floor(Date.now() / MILLISECONDS_TO_SECONDS));
+
+/**
+ * An API for a deployed governor contract.
+ */
+export interface DeployedGovernorAPI {
+  readonly deployedContractAddress: ContractAddress;
+
+  // Proposal operations
+  createProposal: (
+    title: string,
+    description: string,
+    creator: Uint8Array,
+    actions: ProposalAction[]
+  ) => Promise<{ txData: FinalizedTxData; proposalId: bigint }>;
+  castVote: (
+    proposalId: bigint,
+    voter: Uint8Array,
+    choice: VoteChoice
+  ) => Promise<FinalizedTxData>;
+  finalizeProposal: (proposalId: bigint) => Promise<FinalizedTxData>;
+  queueProposal: (proposalId: bigint) => Promise<FinalizedTxData>;
+  executeProposal: (
+    proposalId: bigint,
+    effectId: bigint
+  ) => Promise<FinalizedTxData>;
+
+  // Stake operations
+  registerStake: (
+    userId: Uint8Array,
+    amount: bigint
+  ) => Promise<FinalizedTxData>;
+  getStakeInfo: (userId: Uint8Array) => Promise<any>;
+  getTotalDelegatedPower: (userId: Uint8Array) => Promise<any>;
+  getStakeRecord: (userId: Uint8Array) => Promise<any>;
+  hasProposalThreshold: (userId: Uint8Array) => Promise<any>;
+  hasVotingPower: (userId: Uint8Array) => Promise<any>;
+
+  // Query operations
+  getProposalDetails: (proposalId: bigint) => Promise<any>;
+  getEffectDetails: (effectId: bigint) => Promise<any>;
+  getActiveProposalCount: () => Promise<bigint>;
+  getQueuedProposalCount: () => Promise<bigint>;
+  getProposalVoteCount: (proposalId: bigint) => Promise<any>;
+  getGovernorStatus: () => Promise<any>;
+  getCurrentTime: () => Promise<any>;
+  getCurrentContractTime: () => Promise<bigint>;
+  getTreasuryBalance: () => Promise<bigint>;
+
+  // Utility operations
+  updateTime: (newTime: bigint) => Promise<FinalizedTxData>;
+  displayGovernorValue: () => Promise<{
+    contractAddress: string;
+    activeProposals: bigint;
+    queuedProposals: bigint;
+    treasuryBalance: bigint;
+    isActive: boolean;
+  }>;
+}
+
+/**
+ * Provides an implementation of {@link DeployedGovernorAPI} by adapting a deployed governor
+ * contract.
+ */
+export class GovernorAPI implements DeployedGovernorAPI {
+  /** @internal */
+  private constructor(
+    public readonly deployedContract: DeployedGovernorContract,
+    private readonly providers: GovernorProviders,
+    private readonly logger?: Logger
+  ) {
+    this.deployedContractAddress =
+      deployedContract.deployTxData.public.contractAddress;
+  }
+
+  /**
+   * Gets the address of the current deployed contract.
+   */
+  readonly deployedContractAddress: ContractAddress;
+
+  /**
+   * Creates a governance proposal.
+   *
+   * @param title The proposal title (max 256 characters).
+   * @param description The proposal description (max 10,000 characters).
+   * @param creator The creator's address (32 bytes).
+   * @param actions Array of proposal actions to execute if passed.
+   * @returns Transaction data and proposal ID.
+   *
+   * @throws {InvalidParameterError} If title, description, or creator are invalid.
+   * @throws {InsufficientStakeError} If creator doesn't have sufficient stake.
+   *
+   * @remarks
+   * The creator must have sufficient stake as defined by the governance config's proposalThreshold.
+   * This method will automatically retrieve the creator's current stake from the contract.
+   *
+   * @example
+   * ```typescript
+   * const actions: ProposalAction[] = [{
+   *   typ: 0,
+   *   token: tokenAddress,
+   *   amount: BigInt(10000),
+   *   to: recipientAddress,
+   *   configKey: new Uint8Array(32),
+   *   configValue: new Uint8Array(32),
+   * }];
+   *
+   * const { proposalId, txData } = await governorAPI.createProposal(
+   *   'Fund Community Initiative',
+   *   'Transfer 10,000 tokens to community wallet',
+   *   creatorAddress,
+   *   actions
+   * );
+   * ```
+   */
+  async createProposal(
+    title: string,
+    description: string,
+    creator: Uint8Array,
+    actions: ProposalAction[]
+  ): Promise<{ txData: FinalizedTxData; proposalId: bigint }> {
+    this.logger?.info(`Creating proposal: ${title}`);
+    this.logger?.info(`Description: ${description}`);
+
+    // Validate parameters
+    validateProposal(title, description, creator);
+
+    if (!Array.isArray(actions) || actions.length === 0) {
+      throw new InvalidParameterError(
+        "actions",
+        "must be a non-empty array of ProposalAction"
+      );
+    }
+
+    try {
+      // Get creator's current stake
+      const stakeInfo =
+        await this.deployedContract.callTx.getStakeInfo(creator);
+      const stakeAmount = stakeInfo.private.result.stakedAmount;
+      this.logger?.info(`Creator stake amount: ${stakeAmount}`);
+
+      const stakeWitness = {
+        userId: creator,
+        amount: stakeAmount,
+        nonce: utils.randomBytes(32)
+      };
+
+      const currentTime = getCurrentUnixTimestamp();
+      this.logger?.info(`Current time: ${currentTime}`);
+
+      const createdProposal =
+        await this.deployedContract.callTx.createProposalWithEffect(
+          creator,
+          title,
+          description,
+          actions,
+          stakeWitness,
+          currentTime,
+          currentTime + 300n
+        );
+
+      const proposalId = createdProposal.private.result as bigint;
+
+      this.logger?.info(
+        `Proposal created with ID: ${proposalId}, txHash: ${createdProposal.public.txHash}`
+      );
+      this.logger?.trace({
+        transactionAdded: {
+          circuit: "createProposalWithEffect",
+          txHash: createdProposal.public.txHash,
+          blockHeight: createdProposal.public.blockHeight
+        }
+      });
+
+      return {
+        txData: createdProposal.public,
+        proposalId: proposalId
+      };
+    } catch (error) {
+      this.logger?.error(`Error creating proposal: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Casts a vote on a proposal.
+   *
+   * @param proposalId The proposal ID to vote on (must be > 0).
+   * @param voter The voter's address (32 bytes).
+   * @param choice The vote choice: 0 (For), 1 (Against), or 2 (Abstain). Use VoteChoice enum for type safety.
+   * @returns Transaction data.
+   *
+   * @throws {InvalidParameterError} If proposalId, voter, or choice are invalid.
+   * @throws {InsufficientStakeError} If voter doesn't have sufficient stake.
+   *
+   * @remarks
+   * The voter must have voting power (non-zero stake). This method will automatically retrieve
+   * the voter's current stake from the contract.
+   *
+   * @example
+   * ```typescript
+   * import { VoteChoice } from '@agora-dao-midnight/sdk';
+   *
+   * await governorAPI.castVote(
+   *   proposalId,
+   *   voterAddress,
+   *   VoteChoice.For  // Type-safe vote choice
+   * );
+   * ```
+   */
+  async castVote(
+    proposalId: bigint,
+    voter: Uint8Array,
+    choice: VoteChoice
+  ): Promise<FinalizedTxData> {
+    this.logger?.info(`Casting vote on proposal ${proposalId}`);
+    this.logger?.info(
+      `Vote choice: ${choice === VoteChoice.For ? "For" : choice === VoteChoice.Against ? "Against" : "Abstain"}`
+    );
+
+    // Validate parameters
+    validatePositiveBigInt(proposalId, "proposalId");
+    validateAddress(voter, "voter");
+    validateVoteChoice(choice);
+
+    // Get voter's current stake
+    const stakeInfo = await this.deployedContract.callTx.getStakeInfo(voter);
+    const stakeAmount = stakeInfo.private.result.stakedAmount;
+    this.logger?.info(`Voter stake amount: ${stakeAmount}`);
+
+    const stakeWitness = {
+      userId: voter,
+      amount: stakeAmount,
+      nonce: utils.randomBytes(32)
+    };
+
+    const tx = await this.deployedContract.callTx.castVoteWithValidation(
+      proposalId,
+      voter,
+      choice,
+      stakeWitness
+    );
+
+    this.logger?.info(`Vote cast with txHash: ${tx.public.txHash}`);
+    this.logger?.trace({
+      transactionAdded: {
+        circuit: "castVoteWithValidation",
+        txHash: tx.public.txHash,
+        blockHeight: tx.public.blockHeight
+      }
+    });
+
+    return tx.public;
+  }
+
+  /**
+   * Finalizes a proposal after voting period ends.
+   *
+   * @param proposalId The proposal ID to finalize.
+   * @returns Transaction data.
+   *
+   * @remarks
+   * This should be called after the voting period has ended.
+   */
+  async finalizeProposal(proposalId: bigint): Promise<FinalizedTxData> {
+    this.logger?.info(`Finalizing proposal ${proposalId}`);
+
+    const proofOfGovernorApproval = {
+      proposalId: proposalId,
+      effectId: INITIAL_EFFECT_ID,
+      approvalTime: getCurrentUnixTimestamp(),
+      nonce: utils.randomBytes(32)
+    };
+
+    const tx =
+      await this.deployedContract.callTx.finalizeProposalWithValidation(
+        proposalId,
+        proofOfGovernorApproval
+      );
+
+    this.logger?.info(`Proposal finalized with txHash: ${tx.public.txHash}`);
+    return tx.public;
+  }
+
+  /**
+   * Queues a finalized proposal for execution.
+   *
+   * @param proposalId The proposal ID to queue.
+   * @returns Transaction data.
+   *
+   * @remarks
+   * This should be called after the proposal has been finalized.
+   */
+  async queueProposal(proposalId: bigint): Promise<FinalizedTxData> {
+    this.logger?.info(`Queueing proposal ${proposalId}`);
+
+    const proofOfGovernorApproval = {
+      proposalId: proposalId,
+      effectId: INITIAL_EFFECT_ID,
+      approvalTime: getCurrentUnixTimestamp(),
+      nonce: utils.randomBytes(32)
+    };
+
+    const tx = await this.deployedContract.callTx.queueProposalWithValidation(
+      proposalId,
+      proofOfGovernorApproval
+    );
+
+    this.logger?.info(`Proposal queued with txHash: ${tx.public.txHash}`);
+    return tx.public;
+  }
+
+  /**
+   * Executes a queued proposal.
+   *
+   * @param proposalId The proposal ID to execute.
+   * @param effectId The effect ID to execute.
+   * @returns Transaction data.
+   *
+   * @remarks
+   * This should be called after the execution delay has passed.
+   */
+  async executeProposal(
+    proposalId: bigint,
+    effectId: bigint
+  ): Promise<FinalizedTxData> {
+    this.logger?.info(`Executing proposal ${proposalId}`);
+    this.logger?.info(`Effect ID: ${effectId}`);
+
+    const proofOfGovernorApproval = {
+      proposalId: proposalId,
+      effectId: effectId,
+      approvalTime: getCurrentUnixTimestamp(),
+      nonce: utils.randomBytes(32)
+    };
+
+    const tx = await this.deployedContract.callTx.executeQueuedProposal(
+      proposalId,
+      effectId,
+      proofOfGovernorApproval
+    );
+
+    this.logger?.info(`Proposal executed with txHash: ${tx.public.txHash}`);
+    return tx.public;
+  }
+
+  /**
+   * Registers a stake for a user.
+   *
+   * @param userId The user's address (32 bytes).
+   * @param amount The amount to stake.
+   * @returns Transaction data.
+   */
+  async registerStake(
+    userId: Uint8Array,
+    amount: bigint
+  ): Promise<FinalizedTxData> {
+    this.logger?.info(`Registering stake for user`);
+    this.logger?.info(`Amount: ${amount}`);
+
+    const proofOfStake = {
+      userId: userId,
+      amount: amount,
+      nonce: utils.randomBytes(32)
+    };
+
+    const tx = await this.deployedContract.callTx.registerStakeWithValidation(
+      userId,
+      amount,
+      proofOfStake
+    );
+
+    this.logger?.info(`Stake registered with txHash: ${tx.public.txHash}`);
+    return tx.public;
+  }
+
+  /**
+   * Gets stake information for a user.
+   *
+   * @param userId The user's address (32 bytes).
+   * @returns Stake information.
+   */
+  async getStakeInfo(userId: Uint8Array): Promise<any> {
+    this.logger?.info(`Getting stake info for user`);
+
+    try {
+      const stakeInfo = await this.deployedContract.callTx.getStakeInfo(userId);
+      this.logger?.info({
+        message: "Stake info retrieved",
+        txHash: stakeInfo.public.txHash,
+        blockHeight: stakeInfo.public.blockHeight
+      });
+      return stakeInfo;
+    } catch (error) {
+      this.logger?.error(`Error getting stake info: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets total delegated power for a user.
+   *
+   * @param userId The user's address (32 bytes).
+   * @returns Total delegated power.
+   */
+  async getTotalDelegatedPower(userId: Uint8Array): Promise<any> {
+    this.logger?.info(`Getting total delegated power for user`);
+
+    try {
+      const result =
+        await this.deployedContract.callTx.getTotalDelegatedPower(userId);
+      this.logger?.info({
+        message: "Total delegated power retrieved",
+        txHash: result.public.txHash,
+        blockHeight: result.public.blockHeight
+      });
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error getting total delegated power: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets stake record for a user.
+   *
+   * @param userId The user's address (32 bytes).
+   * @returns Stake record.
+   */
+  async getStakeRecord(userId: Uint8Array): Promise<any> {
+    this.logger?.info(`Getting stake record for user`);
+
+    try {
+      const result = await this.deployedContract.callTx.getStakeRecord(userId);
+      this.logger?.info({
+        message: "Stake record retrieved",
+        txHash: result.public.txHash,
+        blockHeight: result.public.blockHeight
+      });
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error getting stake record: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if user has sufficient stake to create proposals.
+   *
+   * @param userId The user's address (32 bytes).
+   * @returns Result indicating if user meets threshold.
+   */
+  async hasProposalThreshold(userId: Uint8Array): Promise<any> {
+    try {
+      const result =
+        await this.deployedContract.callTx.hasProposalThreshold(userId);
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error checking proposal threshold: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if user has voting power.
+   *
+   * @param userId The user's address (32 bytes).
+   * @returns Result indicating if user has voting power.
+   */
+  async hasVotingPower(userId: Uint8Array): Promise<any> {
+    try {
+      const result = await this.deployedContract.callTx.hasVotingPower(userId);
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error checking voting power: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets proposal details by ID.
+   *
+   * @param proposalId The proposal ID.
+   * @returns Proposal details.
+   */
+  async getProposalDetails(proposalId: bigint): Promise<any> {
+    this.logger?.info(`Getting proposal details for ID: ${proposalId}`);
+
+    try {
+      const result = await this.deployedContract.callTx.getProposal(proposalId);
+      const loggableResult = {
+        message: "Proposal details",
+        id: result.private.result.id?.toString(),
+        status: result.private.result.status,
+        votingStartTime: result.private.result.votingStartTime?.toString(),
+        votingEndTime: result.private.result.votingEndTime?.toString(),
+        creator: result.private.result.creator,
+        votesFor: result.private.result.votesFor?.toString(),
+        votesAgainst: result.private.result.votesAgainst?.toString(),
+        effectId: result.private.result.effectId?.toString()
+      };
+      this.logger?.info(loggableResult);
+      return result.private.result;
+    } catch (error) {
+      this.logger?.error(`Error getting proposal details: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets effect details by ID.
+   *
+   * @param effectId The effect ID.
+   * @returns Effect details.
+   */
+  async getEffectDetails(effectId: bigint): Promise<any> {
+    this.logger?.info(`Getting effect details for ID: ${effectId}`);
+
+    try {
+      const result = await this.deployedContract.callTx.getEffect(effectId);
+      const loggableResult = {
+        message: "Effect details",
+        id: result.private.result.id?.toString(),
+        proposalId: result.private.result.proposalId?.toString(),
+        status: result.private.result.status,
+        executedAt: result.private.result.executedAt?.toString(),
+        actionsCount: result.private.result.actions?.length || 0
+      };
+      this.logger?.info(loggableResult);
+      return result.private.result;
+    } catch (error) {
+      this.logger?.error(`Error getting effect details: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets the count of active proposals.
+   *
+   * @returns Number of active proposals.
+   */
+  async getActiveProposalCount(): Promise<bigint> {
+    this.logger?.info(`Getting active proposal count`);
+
+    try {
+      if (!this.deployedContract?.callTx) {
+        this.logger?.warn("Governor contract or callTx is undefined");
+        return DEFAULT_BIGINT_VALUE;
+      }
+
+      const result =
+        await this.deployedContract.callTx.getActiveProposalCount();
+      this.logger?.info(`Active proposals: ${result.private.result}`);
+      return result.private.result;
+    } catch (error) {
+      this.logger?.warn(`Could not get active proposal count: ${error}`);
+      return DEFAULT_BIGINT_VALUE;
+    }
+  }
+
+  /**
+   * Gets the count of queued proposals.
+   *
+   * @returns Number of queued proposals.
+   */
+  async getQueuedProposalCount(): Promise<bigint> {
+    this.logger?.info(`Getting queued proposal count`);
+
+    try {
+      const result =
+        await this.deployedContract.callTx.getQueuedProposalCount();
+      this.logger?.info(`Queued proposals: ${result.private.result}`);
+      return result.private.result;
+    } catch (error) {
+      this.logger?.warn(`Could not get queued proposal count: ${error}`);
+      return DEFAULT_BIGINT_VALUE;
+    }
+  }
+
+  /**
+   * Gets vote count for a proposal.
+   *
+   * @param proposalId The proposal ID.
+   * @returns Vote count information.
+   */
+  async getProposalVoteCount(proposalId: bigint): Promise<any> {
+    try {
+      const result =
+        await this.deployedContract.callTx.getProposalVoteCount(proposalId);
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error getting proposal vote count: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets the governor contract status.
+   *
+   * @returns Governor status information.
+   */
+  async getGovernorStatus(): Promise<any> {
+    this.logger?.info(`Getting governor status`);
+
+    try {
+      const result = await this.deployedContract.callTx.getGovernorStatus();
+      this.logger?.info(`Governor status retrieved`);
+      return result.private.result;
+    } catch (error) {
+      this.logger?.warn(`Could not get governor status: ${error}`);
+      return null;
+    }
+  }
+
+  /**
+   * Gets the current time from the contract.
+   *
+   * @returns Current time.
+   */
+  async getCurrentTime(): Promise<any> {
+    try {
+      const result = await this.deployedContract.callTx.getCurrentTime();
+      return result;
+    } catch (error) {
+      this.logger?.error(`Error getting current time: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets the current contract time as a bigint.
+   *
+   * @returns Current contract time.
+   */
+  async getCurrentContractTime(): Promise<bigint> {
+    this.logger?.info(`Getting current contract time`);
+
+    try {
+      const status = await this.deployedContract.callTx.getGovernorStatus();
+      const currentTime = status.private.result.currentTime;
+      this.logger?.info(`Current contract time: ${currentTime}`);
+      return currentTime;
+    } catch (error) {
+      this.logger?.error(`Error getting current contract time: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets the treasury balance.
+   *
+   * @returns Treasury balance.
+   *
+   * @remarks
+   * This method queries the contract state to check if the contract exists.
+   * The actual treasury balance would need to be retrieved from the contract's
+   * public state if the contract implements treasury functionality.
+   */
+  async getTreasuryBalance(): Promise<bigint> {
+    this.logger?.info(`Getting treasury balance`);
+
+    try {
+      const state = await this.providers.publicDataProvider.queryContractState(
+        this.deployedContractAddress
+      );
+      if (state != null) {
+        this.logger?.info("Governor contract state found");
+        // Contract exists but doesn't currently expose treasury balance in public state
+        return DEFAULT_BIGINT_VALUE;
+      }
+    } catch (error) {
+      this.logger?.warn(`Could not query contract state: ${error}`);
+    }
+    return DEFAULT_BIGINT_VALUE;
+  }
+
+  /**
+   * Updates the contract time.
+   *
+   * @param newTime The new time to set.
+   * @returns Transaction data.
+   *
+   * @internal
+   * @deprecated This method is for testing purposes only. Do not use in production.
+   *
+   * @remarks
+   * WARNING: This method manipulates contract time and should only be used in testing environments
+   * to simulate time passing. Using this in production can have serious consequences for governance
+   * operations and proposal lifecycles.
+   */
+  async updateTime(newTime: bigint): Promise<FinalizedTxData> {
+    this.logger?.warn(
+      "WARNING: updateTime() is for testing only. Do not use in production!"
+    );
+    this.logger?.info(`Updating contract time to: ${newTime}`);
+
+    const tx = await this.deployedContract.callTx.storeTimestamp(newTime);
+
+    this.logger?.info(`Time updated with txHash: ${tx.public.txHash}`);
+    return tx.public;
+  }
+
+  /**
+   * Displays comprehensive governor status.
+   *
+   * @returns Governor value information.
+   */
+  async displayGovernorValue(): Promise<{
+    contractAddress: string;
+    activeProposals: bigint;
+    queuedProposals: bigint;
+    treasuryBalance: bigint;
+    isActive: boolean;
+  }> {
+    const contractAddress = this.deployedContractAddress;
+    this.logger?.info(`Governor contract deployed at: ${contractAddress}`);
+
+    try {
+      const activeProposals = await this.getActiveProposalCount();
+      const queuedProposals = await this.getQueuedProposalCount();
+      const treasuryBalance = await this.getTreasuryBalance();
+      const status = await this.getGovernorStatus();
+
+      this.logger?.info(`Active proposals: ${Number(activeProposals)}`);
+      this.logger?.info(`Queued proposals: ${Number(queuedProposals)}`);
+      this.logger?.info(`Treasury balance: ${Number(treasuryBalance)}`);
+      this.logger?.info(`Current time: ${Number(status.currentTime)}`);
+
+      return {
+        contractAddress,
+        activeProposals,
+        queuedProposals,
+        treasuryBalance,
+        isActive: true
+      };
+    } catch (error) {
+      this.logger?.error(`Error reading governor state: ${error}`);
+      return {
+        contractAddress,
+        activeProposals: DEFAULT_BIGINT_VALUE,
+        queuedProposals: DEFAULT_BIGINT_VALUE,
+        treasuryBalance: DEFAULT_BIGINT_VALUE,
+        isActive: false
+      };
+    }
+  }
+
+  /**
+   * Deploys a new governor contract to the network.
+   *
+   * @param providers The governor providers.
+   * @param config The deployment configuration including governor, token, and admin settings.
+   * @param logger An optional logger to use for logging.
+   * @returns A `Promise` that resolves with a {@link GovernorAPI} instance that manages the newly deployed
+   * {@link DeployedGovernorContract}; or rejects with a deployment error.
+   *
+   * @example
+   * ```typescript
+   * import { GovernorAPI, ConfigPresets } from '@agora-dao-midnight/sdk';
+   * import { randomBytes } from '@midnight-ntwrk/midnight-js-utils';
+   *
+   * const config = {
+   *   governor: {
+   *     governance: ConfigPresets.production(),
+   *     executionDelay: BigInt(172800),
+   *     gracePeriod: BigInt(604800),
+   *     maxActiveProposals: BigInt(100),
+   *     proposalLifetime: BigInt(2592000),
+   *     emergencyVetoEnabled: true,
+   *     emergencyVetoThreshold: BigInt(75000),
+   *   },
+   *   token: {
+   *     name: 'My DAO Token',
+   *     symbol: 'MDAO',
+   *     decimals: BigInt(18),
+   *   },
+   *   adminKey: randomBytes(32),
+   * };
+   *
+   * const governorAPI = await GovernorAPI.deploy(providers, config, logger);
+   * ```
+   */
+  static async deploy(
+    providers: GovernorProviders,
+    config: DeploymentConfig,
+    logger?: Logger
+  ): Promise<GovernorAPI> {
+    logger?.info("Deploying governor contract");
+
+    // Validate configuration
+    validateDeploymentConfig(config);
+
+    const args = [
+      config.governor,
+      config.token.name,
+      config.token.symbol,
+      config.token.decimals,
+      config.adminKey
+    ] as [typeof config.governor, string, string, bigint, Uint8Array];
+
+    const deployedGovernorContract = await deployContract<
+      typeof governorContractInstance
+    >(providers, {
+      privateStateId: GovernorPrivateStateId,
+      contract: governorContractInstance,
+      initialPrivateState: await GovernorAPI.getPrivateState(providers),
+      args
+    });
+
+    logger?.trace({
+      contractDeployed: {
+        finalizedDeployTxData: deployedGovernorContract.deployTxData.public
+      }
+    });
+
+    return new GovernorAPI(deployedGovernorContract, providers, logger);
+  }
+
+  /**
+   * Finds an already deployed governor contract on the network, and joins it.
+   *
+   * @param providers The governor providers.
+   * @param contractAddress The contract address of the deployed governor contract to search for and join.
+   * @param logger An optional logger to use for logging.
+   * @returns A `Promise` that resolves with a {@link GovernorAPI} instance that manages the joined
+   * {@link DeployedGovernorContract}; or rejects with an error.
+   */
+  static async join(
+    providers: GovernorProviders,
+    contractAddress: ContractAddress,
+    logger?: Logger
+  ): Promise<GovernorAPI> {
+    logger?.info({
+      joinContract: {
+        contractAddress
+      }
+    });
+
+    const deployedGovernorContract =
+      await findDeployedContract<GovernorContract>(providers, {
+        contractAddress,
+        contract: governorContractInstance,
+        privateStateId: GovernorPrivateStateId,
+        initialPrivateState: await GovernorAPI.getPrivateState(providers)
+      });
+
+    logger?.trace({
+      contractJoined: {
+        finalizedDeployTxData: deployedGovernorContract.deployTxData.public
+      }
+    });
+
+    return new GovernorAPI(deployedGovernorContract, providers, logger);
+  }
+
+  /**
+   * Gets or initializes the private state for the governor contract.
+   *
+   * @param providers The governor providers.
+   * @returns The private state.
+   *
+   * @remarks
+   * This method retrieves existing private state from the provider, or creates new private state
+   * if none exists. The governance config in the private state is initialized with testing defaults
+   * and should be updated from the actual contract configuration after joining.
+   */
+  private static async getPrivateState(
+    providers: GovernorProviders
+  ): Promise<GovernorPrivateState> {
+    const existingPrivateState = await providers.privateStateProvider.get(
+      GovernorPrivateStateId
+    );
+    if (existingPrivateState) {
+      return existingPrivateState;
+    }
+
+    const secretKey = utils.randomBytes(32);
+    const currentTime = getCurrentUnixTimestamp();
+
+    // Use testing config as default for private state initialization
+    // The actual governance config should be queried from the contract after joining
+    const defaultConfig = ConfigPresets.testing();
+
+    const newPrivateState: GovernorPrivateState = {
+      secretKey: secretKey,
+      currentTime: currentTime,
+      userStake: {
+        amount: DEFAULT_BIGINT_VALUE,
+        delegatedTo: new Uint8Array(32),
+        stakedAt: currentTime
+      },
+      votingHistory: [],
+      proposalHistory: [],
+      governanceConfig: defaultConfig
+    };
+
+    await providers.privateStateProvider.set(
+      GovernorPrivateStateId,
+      newPrivateState
+    );
+    return newPrivateState;
+  }
+}
+
+export * as utils from "./utils/index";
+export * from "./common-types";