@claritydao/midnight-agora-sdk 0.2.0 → 1.2.0

package/src/index.ts

@@ -1,51 +0,0 @@
-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

@@ -1,205 +0,0 @@
-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.
-   * @param networkId The network ID to connect to (e.g., 'testnet', 'undeployed'). Defaults to 'testnet'.
-   */
-  constructor(
-    private readonly deploymentConfig: DeploymentConfig,
-    private readonly logger: Logger,
-    private readonly networkId: string = "testnet"
-  ) {
-    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, this.networkId))
-    );
-  }
-
-  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

@@ -1,403 +0,0 @@
-/**
- * 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

@@ -1,60 +0,0 @@
-/**
- * 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;
-};