@claritydao/midnight-agora-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,51 @@
+export { GovernorAPI, type DeployedGovernorAPI } from "./governor-api";
+export { initializeProviders } from "./browser-providers";
+export {
+  GovernorManager,
+  type DeployedGovernorAPIProvider,
+  type GovernorDeployment,
+  type InProgressGovernorDeployment,
+  type DeployedGovernorDeployment,
+  type FailedGovernorDeployment
+} from "./manager";
+export * from "./common-types";
+export * as utils from "./utils/index";
+
+// Export comprehensive type definitions
+export type {
+  DeploymentConfig,
+  GovernanceConfig,
+  GovernorConfig,
+  TokenConfig,
+  ProposalAction,
+  StakeInfo,
+  ProposalDetails,
+  EffectDetails,
+  VoteCount,
+  GovernorStatus,
+  GovernorValue,
+  StakeRecord
+} from "./types";
+
+// Export enums
+export { VoteChoice, ProposalStatus } from "./types";
+
+// Export configuration presets
+export { ConfigPresets } from "./types";
+
+// Export all error classes
+export {
+  GovernorSDKError,
+  WalletNotConnectedError,
+  InsufficientStakeError,
+  InvalidParameterError,
+  ContractNotFoundError,
+  ProposalNotFoundError,
+  TransactionError,
+  DeploymentError,
+  InvalidConfigurationError,
+  NetworkNotConfiguredError
+} from "./errors";
+
+// Export validators for advanced usage
+export * as validators from "./validators";

package/src/manager.ts

@@ -0,0 +1,203 @@
+import {
+  type DeployedGovernorAPI,
+  GovernorAPI,
+  type GovernorProviders
+} from "./governor-api";
+import { initializeProviders } from "./browser-providers";
+import { type ContractAddress } from "@midnight-ntwrk/compact-runtime";
+import { BehaviorSubject, type Observable } from "rxjs";
+import { type Logger } from "pino";
+import type { DeploymentConfig } from "./types";
+
+/**
+ * An in-progress governor deployment.
+ */
+export interface InProgressGovernorDeployment {
+  readonly status: "in-progress";
+}
+
+/**
+ * A deployed governor deployment.
+ */
+export interface DeployedGovernorDeployment {
+  readonly status: "deployed";
+
+  /**
+   * The {@link DeployedGovernorAPI} instance when connected to an on network governor contract.
+   */
+  readonly api: DeployedGovernorAPI;
+}
+
+/**
+ * A failed governor deployment.
+ */
+export interface FailedGovernorDeployment {
+  readonly status: "failed";
+
+  /**
+   * The error that caused the deployment to fail.
+   */
+  readonly error: Error;
+}
+
+/**
+ * A governor deployment.
+ */
+export type GovernorDeployment =
+  | InProgressGovernorDeployment
+  | DeployedGovernorDeployment
+  | FailedGovernorDeployment;
+
+/**
+ * Provides access to governor deployments.
+ */
+export interface DeployedGovernorAPIProvider {
+  /**
+   * Gets the observable set of governor deployments.
+   *
+   * @remarks
+   * This property represents an observable array of {@link GovernorDeployment}, each also an
+   * observable. Changes to the array will be emitted as governors are resolved (deployed or joined),
+   * while changes to each underlying governor can be observed via each item in the array.
+   */
+  readonly governorDeployments$: Observable<
+    Array<Observable<GovernorDeployment>>
+  >;
+
+  /**
+   * Joins or deploys a governor contract.
+   *
+   * @param contractAddress An optional contract address to use when resolving.
+   * @returns An observable governor deployment.
+   *
+   * @remarks
+   * For a given `contractAddress`, the method will attempt to find and join the identified governor
+   * contract; otherwise it will attempt to deploy a new one.
+   */
+  readonly resolve: (
+    contractAddress?: ContractAddress
+  ) => Observable<GovernorDeployment>;
+}
+
+/**
+ * A {@link DeployedGovernorAPIProvider} that manages governor deployments in a browser setting.
+ *
+ * @remarks
+ * {@link GovernorManager} configures and manages a connection to the Midnight Lace
+ * wallet, along with a collection of additional providers that work in a web-browser setting.
+ */
+export class GovernorManager implements DeployedGovernorAPIProvider {
+  readonly #governorDeploymentsSubject: BehaviorSubject<
+    Array<BehaviorSubject<GovernorDeployment>>
+  >;
+  #initializedProviders: Promise<GovernorProviders> | undefined;
+
+  /**
+   * Initializes a new {@link GovernorManager} instance.
+   *
+   * @param deploymentConfig The deployment configuration for the governor contract.
+   * @param logger The `pino` logger to for logging.
+   */
+  constructor(
+    private readonly deploymentConfig: DeploymentConfig,
+    private readonly logger: Logger
+  ) {
+    this.#governorDeploymentsSubject = new BehaviorSubject<
+      Array<BehaviorSubject<GovernorDeployment>>
+    >([]);
+    this.governorDeployments$ = this.#governorDeploymentsSubject;
+  }
+
+  /** @inheritdoc */
+  readonly governorDeployments$: Observable<
+    Array<Observable<GovernorDeployment>>
+  >;
+
+  /** @inheritdoc */
+  resolve(contractAddress?: ContractAddress): Observable<GovernorDeployment> {
+    const deployments = this.#governorDeploymentsSubject.value;
+    let deployment = deployments.find(
+      (deployment) =>
+        deployment.value.status === "deployed" &&
+        deployment.value.api.deployedContractAddress === contractAddress
+    );
+
+    if (deployment) {
+      return deployment;
+    }
+
+    deployment = new BehaviorSubject<GovernorDeployment>({
+      status: "in-progress"
+    });
+
+    if (contractAddress) {
+      void this.joinDeployment(deployment, contractAddress);
+    } else {
+      void this.deployDeployment(deployment);
+    }
+
+    this.#governorDeploymentsSubject.next([...deployments, deployment]);
+
+    return deployment;
+  }
+
+  private getProviders(): Promise<GovernorProviders> {
+    // We use a cached `Promise` to hold the providers. This will:
+    //
+    // 1. Cache and re-use the providers (including the configured connector API), and
+    // 2. Act as a synchronization point if multiple contract deploys or joins run concurrently.
+    //    Concurrent calls to `getProviders()` will receive, and ultimately await, the same
+    //    `Promise`.
+    return (
+      this.#initializedProviders ??
+      (this.#initializedProviders = initializeProviders(this.logger))
+    );
+  }
+
+  private async deployDeployment(
+    deployment: BehaviorSubject<GovernorDeployment>
+  ): Promise<void> {
+    try {
+      const providers = await this.getProviders();
+      const api = await GovernorAPI.deploy(
+        providers,
+        this.deploymentConfig,
+        this.logger
+      );
+
+      deployment.next({
+        status: "deployed",
+        api
+      });
+    } catch (error: unknown) {
+      deployment.next({
+        status: "failed",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+
+  private async joinDeployment(
+    deployment: BehaviorSubject<GovernorDeployment>,
+    contractAddress: ContractAddress
+  ): Promise<void> {
+    try {
+      const providers = await this.getProviders();
+      const api = await GovernorAPI.join(
+        providers,
+        contractAddress,
+        this.logger
+      );
+
+      deployment.next({
+        status: "deployed",
+        api
+      });
+    } catch (error: unknown) {
+      deployment.next({
+        status: "failed",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,403 @@
+/**
+ * Type definitions for the Agora DAO Governor SDK.
+ *
+ * @module types
+ */
+
+/**
+ * Governance configuration parameters.
+ */
+export interface GovernanceConfig {
+  /**
+   * Duration of the voting period in seconds.
+   * @example BigInt(604800) // 7 days for production
+   * @example BigInt(300) // 5 minutes for testing
+   */
+  votingPeriod: bigint;
+
+  /**
+   * Minimum number of votes required for a proposal to pass (quorum).
+   * @example BigInt(100000) // 100K tokens for production
+   * @example BigInt(100) // 100 tokens for testing
+   */
+  quorumThreshold: bigint;
+
+  /**
+   * Minimum stake required to create a proposal.
+   * @example BigInt(50000) // 50K tokens for production
+   * @example BigInt(100) // 100 tokens for testing
+   */
+  proposalThreshold: bigint;
+
+  /**
+   * Maximum lifetime of a proposal in seconds.
+   * @example BigInt(2592000) // 30 days for production
+   * @example BigInt(86400) // 1 day for testing
+   */
+  proposalLifetime: bigint;
+
+  /**
+   * Delay before a passed proposal can be executed, in seconds.
+   * @example BigInt(172800) // 2 days for production
+   * @example BigInt(60) // 1 minute for testing
+   */
+  executionDelay: bigint;
+
+  /**
+   * Grace period after execution delay before proposal expires, in seconds.
+   * @example BigInt(604800) // 7 days for production
+   * @example BigInt(300) // 5 minutes for testing
+   */
+  gracePeriod: bigint;
+
+  /**
+   * Minimum amount that can be staked.
+   * @example BigInt(1000) // 1K tokens for production
+   * @example BigInt(10) // 10 tokens for testing
+   */
+  minStakeAmount: bigint;
+
+  /**
+   * Minimum staking period in seconds before tokens can be unstaked.
+   * @example BigInt(604800) // 7 days for production
+   * @example BigInt(60) // 1 minute for testing
+   */
+  stakingPeriod: bigint;
+}
+
+/**
+ * Complete governor contract configuration.
+ */
+export interface GovernorConfig {
+  /** Governance-specific parameters */
+  governance: GovernanceConfig;
+
+  /** Delay before execution (should match governance.executionDelay) */
+  executionDelay: bigint;
+
+  /** Grace period for execution (should match governance.gracePeriod) */
+  gracePeriod: bigint;
+
+  /** Maximum number of active proposals allowed */
+  maxActiveProposals: bigint;
+
+  /** Proposal lifetime (should match governance.proposalLifetime) */
+  proposalLifetime: bigint;
+
+  /** Whether emergency veto is enabled */
+  emergencyVetoEnabled: boolean;
+
+  /**
+   * Stake threshold required for emergency veto.
+   * @example BigInt(75000) // 75K tokens for production
+   * @example BigInt(500) // 500 tokens for testing
+   */
+  emergencyVetoThreshold: bigint;
+}
+
+/**
+ * Token configuration for governor deployment.
+ */
+export interface TokenConfig {
+  /**
+   * Token name.
+   * @example "Agora DAO Token"
+   */
+  name: string;
+
+  /**
+   * Token symbol.
+   * @example "AGORA"
+   */
+  symbol: string;
+
+  /**
+   * Number of decimal places for token.
+   * @example BigInt(18) // Standard ERC20
+   * @example BigInt(6) // USDC-like
+   */
+  decimals: bigint;
+}
+
+/**
+ * Complete deployment configuration for governor contract.
+ */
+export interface DeploymentConfig {
+  /** Governor configuration */
+  governor: GovernorConfig;
+
+  /** Token configuration */
+  token: TokenConfig;
+
+  /**
+   * Admin key for the contract (32 bytes).
+   *
+   * @remarks
+   * SECURITY: This should be generated securely and stored safely.
+   * Never use predictable or hardcoded admin keys in production.
+   *
+   * @example
+   * ```typescript
+   * import { randomBytes } from '@midnight-ntwrk/midnight-js-utils';
+   * const adminKey = randomBytes(32);
+   * ```
+   */
+  adminKey: Uint8Array;
+}
+
+/**
+ * Vote choice enumeration.
+ */
+export enum VoteChoice {
+  /** Vote in favor of the proposal */
+  For = 0,
+
+  /** Vote against the proposal */
+  Against = 1,
+
+  /** Abstain from voting */
+  Abstain = 2
+}
+
+/**
+ * Proposal action type.
+ */
+export interface ProposalAction {
+  /** Action type identifier */
+  typ: number;
+
+  /** Token address for transfer actions */
+  token: Uint8Array;
+
+  /** Amount for transfer actions */
+  amount: bigint;
+
+  /** Recipient address for transfer actions */
+  to: Uint8Array;
+
+  /** Configuration key for config update actions */
+  configKey: Uint8Array;
+
+  /** Configuration value for config update actions */
+  configValue: Uint8Array;
+}
+
+/**
+ * Stake information for a user.
+ */
+export interface StakeInfo {
+  /** Amount of tokens staked */
+  stakedAmount: bigint;
+
+  /** Address to which stake is delegated */
+  delegatedTo: Uint8Array;
+
+  /** Timestamp when stake was registered */
+  stakedAt: bigint;
+}
+
+/**
+ * Proposal status enumeration.
+ */
+export enum ProposalStatus {
+  /** Proposal is pending and not yet active */
+  Pending = 0,
+
+  /** Proposal is active and accepting votes */
+  Active = 1,
+
+  /** Proposal voting period has ended, needs finalization */
+  Succeeded = 2,
+
+  /** Proposal was defeated */
+  Defeated = 3,
+
+  /** Proposal is queued for execution */
+  Queued = 4,
+
+  /** Proposal has been executed */
+  Executed = 5,
+
+  /** Proposal has expired */
+  Expired = 6,
+
+  /** Proposal was canceled */
+  Canceled = 7
+}
+
+/**
+ * Detailed proposal information.
+ */
+export interface ProposalDetails {
+  /** Unique proposal identifier */
+  id: bigint;
+
+  /** Current proposal status */
+  status: ProposalStatus;
+
+  /** Timestamp when voting started */
+  votingStartTime: bigint;
+
+  /** Timestamp when voting ends */
+  votingEndTime: bigint;
+
+  /** Address of proposal creator */
+  creator: Uint8Array;
+
+  /** Number of votes in favor */
+  votesFor: bigint;
+
+  /** Number of votes against */
+  votesAgainst: bigint;
+
+  /** Number of abstain votes */
+  votesAbstain: bigint;
+
+  /** Associated effect ID */
+  effectId: bigint;
+
+  /** Proposal title */
+  title: string;
+
+  /** Proposal description */
+  description: string;
+}
+
+/**
+ * Effect details for a proposal.
+ */
+export interface EffectDetails {
+  /** Effect identifier */
+  id: bigint;
+
+  /** Associated proposal ID */
+  proposalId: bigint;
+
+  /** Effect status */
+  status: number;
+
+  /** Actions to be executed */
+  actions: ProposalAction[];
+
+  /** Timestamp when effect was created */
+  createdAt: bigint;
+
+  /** Timestamp when effect can be executed */
+  executableAt: bigint;
+}
+
+/**
+ * Vote count information for a proposal.
+ */
+export interface VoteCount {
+  /** Number of votes in favor */
+  votesFor: bigint;
+
+  /** Number of votes against */
+  votesAgainst: bigint;
+
+  /** Number of abstain votes */
+  votesAbstain: bigint;
+
+  /** Total number of votes cast */
+  totalVotes: bigint;
+}
+
+/**
+ * Governor contract status.
+ */
+export interface GovernorStatus {
+  /** Whether the governor is active */
+  isActive: boolean;
+
+  /** Number of active proposals */
+  activeProposalCount: bigint;
+
+  /** Number of queued proposals */
+  queuedProposalCount: bigint;
+
+  /** Current contract time */
+  currentTime: bigint;
+
+  /** Treasury balance */
+  treasuryBalance: bigint;
+}
+
+/**
+ * Governor value display information.
+ */
+export interface GovernorValue {
+  /** Contract address */
+  contractAddress: string;
+
+  /** Number of active proposals */
+  activeProposals: bigint;
+
+  /** Number of queued proposals */
+  queuedProposals: bigint;
+
+  /** Treasury balance */
+  treasuryBalance: bigint;
+
+  /** Whether governor is active */
+  isActive: boolean;
+}
+
+/**
+ * Stake record information.
+ */
+export interface StakeRecord {
+  /** User address */
+  userId: Uint8Array;
+
+  /** Staked amount */
+  amount: bigint;
+
+  /** Delegated to address */
+  delegatedTo: Uint8Array;
+
+  /** Stake timestamp */
+  stakedAt: bigint;
+
+  /** Whether stake is locked */
+  isLocked: boolean;
+}
+
+/**
+ * Helper functions for creating production and testing configurations.
+ */
+export const ConfigPresets = {
+  /**
+   * Creates a production-ready governance configuration.
+   *
+   * @remarks
+   * Suitable for mainnet deployment with secure parameters.
+   */
+  production: (): GovernanceConfig => ({
+    votingPeriod: BigInt(604800), // 7 days
+    quorumThreshold: BigInt(100000), // 100K tokens
+    proposalThreshold: BigInt(50000), // 50K tokens
+    proposalLifetime: BigInt(2592000), // 30 days
+    executionDelay: BigInt(172800), // 2 days
+    gracePeriod: BigInt(604800), // 7 days
+    minStakeAmount: BigInt(1000), // 1K tokens
+    stakingPeriod: BigInt(604800) // 7 days
+  }),
+
+  /**
+   * Creates a testing governance configuration.
+   *
+   * @remarks
+   * Suitable for testnet/development with shorter periods.
+   */
+  testing: (): GovernanceConfig => ({
+    votingPeriod: BigInt(300), // 5 minutes
+    quorumThreshold: BigInt(100), // 100 tokens
+    proposalThreshold: BigInt(100), // 100 tokens
+    proposalLifetime: BigInt(86400), // 1 day
+    executionDelay: BigInt(60), // 1 minute
+    gracePeriod: BigInt(300), // 5 minutes
+    minStakeAmount: BigInt(10), // 10 tokens
+    stakingPeriod: BigInt(60) // 1 minute
+  })
+};

package/src/utils/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Provides utility functions.
+ *
+ * @module
+ */
+
+/**
+ * Generates a buffer containing a series of randomly generated bytes.
+ *
+ * @param length The number of bytes to generate.
+ * @returns A `Uint8Array` representing `length` randomly generated bytes.
+ */
+export const randomBytes = (length: number): Uint8Array => {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+};
+
+/**
+ * Converts a wallet address string to a Uint8Array (32 bytes).
+ *
+ * @param address The wallet address string.
+ * @returns A 32-byte Uint8Array representation of the address.
+ */
+export const addressToBytes = (address: string): Uint8Array => {
+  const addressBytes = new Uint8Array(32);
+  const addressStr = address.replace(/[^0-9a-f]/gi, "");
+  const addressHex = addressStr.slice(-64);
+  for (let i = 0; i < Math.min(32, addressHex.length / 2); i++) {
+    addressBytes[i] = parseInt(addressHex.substr(i * 2, 2), 16);
+  }
+  return addressBytes;
+};
+
+/**
+ * Converts a Uint8Array to a hex string.
+ *
+ * @param bytes The bytes to convert.
+ * @returns Hex string representation.
+ */
+export const bytesToHex = (bytes: Uint8Array): string => {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+/**
+ * Converts a hex string to a Uint8Array.
+ *
+ * @param hex The hex string to convert.
+ * @returns Uint8Array representation.
+ */
+export const hexToBytes = (hex: string): Uint8Array => {
+  const cleanHex = hex.replace(/^0x/, "");
+  const bytes = new Uint8Array(cleanHex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
+  }
+  return bytes;
+};