@claritydao/midnight-agora-sdk 0.1.0

package/src/browser-providers.ts

@@ -0,0 +1,274 @@
+import { type GovernorProviders, type GovernorCircuits } from "./common-types";
+import {
+  concatMap,
+  filter,
+  firstValueFrom,
+  interval,
+  map,
+  of,
+  take,
+  tap,
+  throwError,
+  timeout,
+  catchError
+} from "rxjs";
+import { pipe as fnPipe } from "fp-ts/function";
+import { type Logger } from "pino";
+import {
+  type InitialAPI,
+  type ConnectedAPI,
+  type Configuration
+} from "@midnight-ntwrk/dapp-connector-api";
+import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
+import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
+import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
+import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
+import {
+  type BalancedProvingRecipe,
+  type WalletProvider
+} from "@midnight-ntwrk/midnight-js-types";
+import type {
+  ShieldedCoinInfo,
+  UnprovenTransaction,
+  TransactionId,
+  FinalizedTransaction,
+  CoinPublicKey,
+  EncPublicKey
+} from "@midnight-ntwrk/ledger-v6";
+import semver from "semver";
+import {
+  getNetworkId,
+  setNetworkId
+} from "@midnight-ntwrk/midnight-js-network-id";
+
+// Helper functions for hex encoding/decoding
+const toHexString = (bytes: Uint8Array): string =>
+  Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+const _fromHexString = (hex: string): Uint8Array =>
+  new Uint8Array(hex.match(/.{1,2}/g)!.map((byte) => parseInt(byte, 16)));
+
+/**
+ * Initializes and returns the providers required for Governor contract interactions in a browser environment.
+ *
+ * @param logger The logger instance for logging.
+ * @param networkId The network ID to connect to (e.g., 'testnet', 'mainnet').
+ * @returns A promise that resolves to configured GovernorProviders.
+ *
+ * @remarks
+ * This function connects to the Midnight Lace wallet extension and retrieves network configuration
+ * from the wallet. The network ID is specified by the caller.
+ */
+export const initializeProviders = async (
+  logger: Logger,
+  networkId: string = "testnet"
+): Promise<GovernorProviders> => {
+  const { wallet, config } = await connectToWallet(logger, networkId);
+  const zkConfigPath = window.location.origin;
+
+  logger.info(`Connecting to wallet with network ID: ${getNetworkId()}`);
+
+  // Get wallet addresses
+  const addresses = await wallet.getShieldedAddresses();
+
+  return {
+    privateStateProvider: levelPrivateStateProvider({
+      privateStateStoreName: "governor-private-state"
+    }),
+    zkConfigProvider: new FetchZkConfigProvider<GovernorCircuits>(
+      zkConfigPath,
+      fetch.bind(window)
+    ),
+    proofProvider: config.proverServerUri
+      ? httpClientProofProvider(config.proverServerUri)
+      : httpClientProofProvider(""), // Fallback - proving may be done by wallet
+    publicDataProvider: indexerPublicDataProvider(
+      config.indexerUri,
+      config.indexerWsUri
+    ),
+    walletProvider: createWalletProvider(wallet, addresses),
+    midnightProvider: {
+      async submitTx(tx: FinalizedTransaction): Promise<TransactionId> {
+        // Convert transaction to hex string for the connector API
+        const serialized = tx.serialize();
+        const hexString = toHexString(serialized);
+        await wallet.submitTransaction(hexString);
+        // Return the transaction hash as the ID
+        return tx.transactionHash() as TransactionId;
+      }
+    }
+  };
+};
+
+/**
+ * Creates a WalletProvider from the connected wallet API.
+ */
+const createWalletProvider = (
+  wallet: ConnectedAPI,
+  addresses: {
+    shieldedCoinPublicKey: string;
+    shieldedEncryptionPublicKey: string;
+  }
+): WalletProvider => {
+  // Note: The bech32m addresses need to be converted to the expected key types
+  // This conversion may need adjustment based on the actual key format expected
+  const coinPublicKey =
+    addresses.shieldedCoinPublicKey as unknown as CoinPublicKey;
+  const encryptionPublicKey =
+    addresses.shieldedEncryptionPublicKey as unknown as EncPublicKey;
+
+  return {
+    getCoinPublicKey(): CoinPublicKey {
+      return coinPublicKey;
+    },
+    getEncryptionPublicKey(): EncPublicKey {
+      return encryptionPublicKey;
+    },
+    async balanceTx(
+      tx: UnprovenTransaction,
+      _newCoins?: ShieldedCoinInfo[],
+      _ttl?: Date
+    ): Promise<BalancedProvingRecipe> {
+      // Use the wallet's balancing capability
+      // Convert Uint8Array to hex string for the connector API
+      const serialized = tx.serialize();
+      const hexString = toHexString(serialized);
+      const _result = await wallet.balanceUnsealedTransaction(hexString);
+
+      // The wallet returns a balanced transaction as a hex string
+      // We need to convert it back and return as NothingToProve
+      // Note: The actual deserialization may need the Transaction.deserialize with proper markers
+      // For now, we return the original transaction as the wallet handles proving internally
+      return {
+        type: "NothingToProve" as const,
+        transaction: tx // The wallet should have balanced this
+      };
+    }
+  };
+};
+
+/**
+ * Connects to the Midnight Lace wallet extension.
+ *
+ * @param logger The logger instance for logging.
+ * @param networkId The network ID to connect to.
+ * @returns A promise that resolves to the wallet API and configuration.
+ */
+const connectToWallet = (
+  logger: Logger,
+  networkId: string
+): Promise<{ wallet: ConnectedAPI; config: Configuration }> => {
+  const COMPATIBLE_CONNECTOR_API_VERSION = "4.x";
+
+  return firstValueFrom(
+    fnPipe(
+      interval(100),
+      map(() => {
+        // Find wallet in window.midnight
+        const midnight = window.midnight;
+        if (!midnight) return undefined;
+
+        // The new API uses rdns keys instead of named keys like mnLace
+        // Look for any available wallet
+        const walletKeys = Object.keys(midnight).filter(
+          (key) => key !== "addEventListener"
+        );
+        if (walletKeys.length === 0) return undefined;
+
+        return midnight[walletKeys[0]] as InitialAPI | undefined;
+      }),
+      tap((connectorAPI) => {
+        logger.info(connectorAPI, "Check for wallet connector API");
+      }),
+      filter((connectorAPI): connectorAPI is InitialAPI => !!connectorAPI),
+      concatMap((connectorAPI) =>
+        semver.satisfies(
+          connectorAPI.apiVersion,
+          COMPATIBLE_CONNECTOR_API_VERSION
+        )
+          ? of(connectorAPI)
+          : throwError(() => {
+              logger.error(
+                {
+                  expected: COMPATIBLE_CONNECTOR_API_VERSION,
+                  actual: connectorAPI.apiVersion
+                },
+                "Incompatible version of wallet connector API"
+              );
+
+              return new Error(
+                `Incompatible version of Midnight Lace wallet found. Require '${COMPATIBLE_CONNECTOR_API_VERSION}', got '${connectorAPI.apiVersion}'.`
+              );
+            })
+      ),
+      tap((connectorAPI) => {
+        logger.info(
+          connectorAPI,
+          "Compatible wallet connector API found. Connecting."
+        );
+      }),
+      take(1),
+      timeout({
+        first: 1_000,
+        with: () =>
+          throwError(() => {
+            logger.error("Could not find wallet connector API");
+
+            return new Error(
+              "Could not find Midnight Lace wallet. Extension installed?"
+            );
+          })
+      }),
+      concatMap(async (connectorAPI) => {
+        // Connect to the wallet with the specified network ID
+        const connectedAPI = await connectorAPI.connect(networkId);
+
+        // Set the network ID globally
+        setNetworkId(networkId);
+
+        logger.info("Connected to wallet");
+
+        return { walletConnectorAPI: connectedAPI, connectorAPI };
+      }),
+      timeout({
+        first: 30_000, // Increased timeout for user approval
+        with: () =>
+          throwError(() => {
+            logger.error("Wallet connector API has failed to respond");
+
+            return new Error(
+              "Midnight Lace wallet has failed to respond. Extension enabled?"
+            );
+          })
+      }),
+      catchError((error, apis) =>
+        error
+          ? throwError(() => {
+              logger.error("Unable to connect to wallet");
+              return new Error(
+                "Application is not authorized or connection failed"
+              );
+            })
+          : apis
+      ),
+      concatMap(async ({ walletConnectorAPI }) => {
+        const config = await walletConnectorAPI.getConfiguration();
+
+        logger.info(
+          "Connected to wallet connector API and retrieved service configuration"
+        );
+
+        return { wallet: walletConnectorAPI, config };
+      })
+    )
+  );
+};
+
+// Extend Window interface for TypeScript
+declare global {
+  interface Window {
+    midnight?: Record<string, InitialAPI>;
+  }
+}

package/src/common-types.ts

@@ -0,0 +1,51 @@
+import type {
+  ImpureCircuitId,
+  MidnightProviders,
+  Contract
+} from "@midnight-ntwrk/midnight-js-types";
+import type {
+  DeployedContract,
+  FoundContract
+} from "@midnight-ntwrk/midnight-js-contracts";
+
+// Use Contract type from midnight-js-types to avoid importing the actual Contract class
+// This prevents eager loading of the contract CJS module which requires WASM
+export type GovernorContract = Contract;
+
+export type GovernorCircuits = ImpureCircuitId<GovernorContract>;
+
+export const GovernorPrivateStateId = "governorPrivateState";
+
+// Define GovernorPrivateState type locally to avoid importing from contract module
+// which would trigger WASM initialization
+export type GovernorPrivateState = {
+  secretKey: Uint8Array | null;
+  currentTime: bigint;
+  userStake: {
+    amount: bigint;
+    delegatedTo: Uint8Array;
+    stakedAt: bigint;
+  };
+  votingHistory: any[];
+  proposalHistory: any[];
+  governanceConfig: {
+    votingPeriod: bigint;
+    quorumThreshold: bigint;
+    proposalThreshold: bigint;
+    proposalLifetime: bigint;
+    executionDelay: bigint;
+    gracePeriod: bigint;
+    minStakeAmount: bigint;
+    stakingPeriod: bigint;
+  };
+};
+
+export type GovernorProviders = MidnightProviders<
+  GovernorCircuits,
+  typeof GovernorPrivateStateId,
+  GovernorPrivateState
+>;
+
+export type DeployedGovernorContract =
+  | DeployedContract<GovernorContract>
+  | FoundContract<GovernorContract>;

package/src/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * Custom error classes for the Agora DAO Governor SDK.
+ *
+ * @module errors
+ */
+
+/**
+ * Base error class for all SDK errors.
+ */
+export class GovernorSDKError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GovernorSDKError";
+    Object.setPrototypeOf(this, GovernorSDKError.prototype);
+  }
+}
+
+/**
+ * Thrown when wallet is not connected.
+ */
+export class WalletNotConnectedError extends GovernorSDKError {
+  constructor() {
+    super(
+      "Wallet not connected. Please ensure Lace wallet is installed and connected."
+    );
+    this.name = "WalletNotConnectedError";
+    Object.setPrototypeOf(this, WalletNotConnectedError.prototype);
+  }
+}
+
+/**
+ * Thrown when user has insufficient stake for an operation.
+ */
+export class InsufficientStakeError extends GovernorSDKError {
+  constructor(required: bigint, actual: bigint) {
+    super(`Insufficient stake. Required: ${required}, Actual: ${actual}`);
+    this.name = "InsufficientStakeError";
+    Object.setPrototypeOf(this, InsufficientStakeError.prototype);
+  }
+}
+
+/**
+ * Thrown when a parameter is invalid.
+ */
+export class InvalidParameterError extends GovernorSDKError {
+  constructor(parameterName: string, reason: string) {
+    super(`Invalid parameter '${parameterName}': ${reason}`);
+    this.name = "InvalidParameterError";
+    Object.setPrototypeOf(this, InvalidParameterError.prototype);
+  }
+}
+
+/**
+ * Thrown when a contract is not found at the specified address.
+ */
+export class ContractNotFoundError extends GovernorSDKError {
+  constructor(address: string) {
+    super(`Contract not found at address: ${address}`);
+    this.name = "ContractNotFoundError";
+    Object.setPrototypeOf(this, ContractNotFoundError.prototype);
+  }
+}
+
+/**
+ * Thrown when a proposal is not found.
+ */
+export class ProposalNotFoundError extends GovernorSDKError {
+  constructor(proposalId: bigint) {
+    super(`Proposal not found with ID: ${proposalId}`);
+    this.name = "ProposalNotFoundError";
+    Object.setPrototypeOf(this, ProposalNotFoundError.prototype);
+  }
+}
+
+/**
+ * Thrown when a transaction fails.
+ */
+export class TransactionError extends GovernorSDKError {
+  constructor(
+    message: string,
+    public readonly txHash?: string
+  ) {
+    super(
+      `Transaction failed: ${message}${txHash ? ` (txHash: ${txHash})` : ""}`
+    );
+    this.name = "TransactionError";
+    Object.setPrototypeOf(this, TransactionError.prototype);
+  }
+}
+
+/**
+ * Thrown when contract deployment fails.
+ */
+export class DeploymentError extends GovernorSDKError {
+  constructor(message: string) {
+    super(`Contract deployment failed: ${message}`);
+    this.name = "DeploymentError";
+    Object.setPrototypeOf(this, DeploymentError.prototype);
+  }
+}
+
+/**
+ * Thrown when configuration is invalid.
+ */
+export class InvalidConfigurationError extends GovernorSDKError {
+  constructor(message: string) {
+    super(`Invalid configuration: ${message}`);
+    this.name = "InvalidConfigurationError";
+    Object.setPrototypeOf(this, InvalidConfigurationError.prototype);
+  }
+}
+
+/**
+ * Thrown when network ID is not set.
+ */
+export class NetworkNotConfiguredError extends GovernorSDKError {
+  constructor() {
+    super(
+      "Network ID not configured. Set window.midnight.mnLace.networkId before initializing providers."
+    );
+    this.name = "NetworkNotConfiguredError";
+    Object.setPrototypeOf(this, NetworkNotConfiguredError.prototype);
+  }
+}