@claritydao/midnight-agora-sdk 0.1.0

package/dist/governor-api.d.ts

@@ -0,0 +1,348 @@
+import { type ContractAddress } from "@midnight-ntwrk/compact-runtime";
+import { type Logger } from "pino";
+import { type GovernorProviders, type DeployedGovernorContract } from "./common-types";
+import { type FinalizedTxData } from "@midnight-ntwrk/midnight-js-types";
+import type { DeploymentConfig, ProposalAction } from "./types";
+import { VoteChoice } from "./types";
+/**
+ * An API for a deployed governor contract.
+ */
+export interface DeployedGovernorAPI {
+    readonly deployedContractAddress: ContractAddress;
+    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>;
+    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>;
+    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>;
+    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 declare class GovernorAPI implements DeployedGovernorAPI {
+    readonly deployedContract: DeployedGovernorContract;
+    private readonly providers;
+    private readonly logger?;
+    /** @internal */
+    private constructor();
+    /**
+     * 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
+     * );
+     * ```
+     */
+    createProposal(title: string, description: string, creator: Uint8Array, actions: ProposalAction[]): Promise<{
+        txData: FinalizedTxData;
+        proposalId: bigint;
+    }>;
+    /**
+     * 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
+     * );
+     * ```
+     */
+    castVote(proposalId: bigint, voter: Uint8Array, choice: VoteChoice): Promise<FinalizedTxData>;
+    /**
+     * 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.
+     */
+    finalizeProposal(proposalId: bigint): Promise<FinalizedTxData>;
+    /**
+     * 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.
+     */
+    queueProposal(proposalId: bigint): Promise<FinalizedTxData>;
+    /**
+     * 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.
+     */
+    executeProposal(proposalId: bigint, effectId: bigint): Promise<FinalizedTxData>;
+    /**
+     * Registers a stake for a user.
+     *
+     * @param userId The user's address (32 bytes).
+     * @param amount The amount to stake.
+     * @returns Transaction data.
+     */
+    registerStake(userId: Uint8Array, amount: bigint): Promise<FinalizedTxData>;
+    /**
+     * Gets stake information for a user.
+     *
+     * @param userId The user's address (32 bytes).
+     * @returns Stake information.
+     */
+    getStakeInfo(userId: Uint8Array): Promise<any>;
+    /**
+     * Gets total delegated power for a user.
+     *
+     * @param userId The user's address (32 bytes).
+     * @returns Total delegated power.
+     */
+    getTotalDelegatedPower(userId: Uint8Array): Promise<any>;
+    /**
+     * Gets stake record for a user.
+     *
+     * @param userId The user's address (32 bytes).
+     * @returns Stake record.
+     */
+    getStakeRecord(userId: Uint8Array): Promise<any>;
+    /**
+     * Checks if user has sufficient stake to create proposals.
+     *
+     * @param userId The user's address (32 bytes).
+     * @returns Result indicating if user meets threshold.
+     */
+    hasProposalThreshold(userId: Uint8Array): Promise<any>;
+    /**
+     * Checks if user has voting power.
+     *
+     * @param userId The user's address (32 bytes).
+     * @returns Result indicating if user has voting power.
+     */
+    hasVotingPower(userId: Uint8Array): Promise<any>;
+    /**
+     * Gets proposal details by ID.
+     *
+     * @param proposalId The proposal ID.
+     * @returns Proposal details.
+     */
+    getProposalDetails(proposalId: bigint): Promise<any>;
+    /**
+     * Gets effect details by ID.
+     *
+     * @param effectId The effect ID.
+     * @returns Effect details.
+     */
+    getEffectDetails(effectId: bigint): Promise<any>;
+    /**
+     * Gets the count of active proposals.
+     *
+     * @returns Number of active proposals.
+     */
+    getActiveProposalCount(): Promise<bigint>;
+    /**
+     * Gets the count of queued proposals.
+     *
+     * @returns Number of queued proposals.
+     */
+    getQueuedProposalCount(): Promise<bigint>;
+    /**
+     * Gets vote count for a proposal.
+     *
+     * @param proposalId The proposal ID.
+     * @returns Vote count information.
+     */
+    getProposalVoteCount(proposalId: bigint): Promise<any>;
+    /**
+     * Gets the governor contract status.
+     *
+     * @returns Governor status information.
+     */
+    getGovernorStatus(): Promise<any>;
+    /**
+     * Gets the current time from the contract.
+     *
+     * @returns Current time.
+     */
+    getCurrentTime(): Promise<any>;
+    /**
+     * Gets the current contract time as a bigint.
+     *
+     * @returns Current contract time.
+     */
+    getCurrentContractTime(): Promise<bigint>;
+    /**
+     * 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.
+     */
+    getTreasuryBalance(): Promise<bigint>;
+    /**
+     * 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.
+     */
+    updateTime(newTime: bigint): Promise<FinalizedTxData>;
+    /**
+     * Displays comprehensive governor status.
+     *
+     * @returns Governor value information.
+     */
+    displayGovernorValue(): Promise<{
+        contractAddress: string;
+        activeProposals: bigint;
+        queuedProposals: bigint;
+        treasuryBalance: bigint;
+        isActive: boolean;
+    }>;
+    /**
+     * 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 deploy(providers: GovernorProviders, config: DeploymentConfig, logger?: Logger): Promise<GovernorAPI>;
+    /**
+     * 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 join(providers: GovernorProviders, contractAddress: ContractAddress, logger?: Logger): Promise<GovernorAPI>;
+    /**
+     * 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 getPrivateState;
+}
+export * as utils from "./utils/index";
+export * from "./common-types";
+//# sourceMappingURL=governor-api.d.ts.map

package/dist/governor-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governor-api.d.ts","sourceRoot":"","sources":["../src/governor-api.ts"],"names":[],"mappings":"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"}