@dynamic-labs/midnight 4.90.0 → 4.91.1

package/src/waas/connector/DynamicWaasMidnightConnector.d.ts

@@ -0,0 +1,470 @@
+import type { ConnectedAPI, TokenType } from '@midnight-ntwrk/dapp-connector-api';
+import { JwtVerifiedCredential, MFAAction, SignMessageContext, TokenScope } from '@dynamic-labs/sdk-api-core';
+import { IUITransaction, WalletUiUtils } from '@dynamic-labs/types';
+import { IDynamicWaasConnector, InternalWalletConnector } from '@dynamic-labs/wallet-connector-core';
+import { Logger } from '@dynamic-labs/logger';
+import type { DynamicWaasMidnightConnectorProps } from '../../types';
+import { MidnightWallet } from '../../wallet/MidnightWallet';
+import { WaasMidnightWalletConnector } from '../WaasMidnightWalletConnector';
+declare const DynamicWaasMidnightConnector_base: (abstract new (...args: any[]) => {
+    [x: string]: any;
+    name: string;
+    overrideKey: string;
+    isEmbeddedWallet: boolean;
+    getSignedSessionId?: (() => Promise<string>) | undefined;
+    getSessionPublicKey?: (() => Promise<string | undefined>) | undefined;
+    getMfaToken?: ((props?: {
+        mfaAction?: MFAAction | undefined;
+    } | undefined) => Promise<string | undefined>) | undefined;
+    getWalletPassword?: import("@dynamic-labs/wallet-connector-core").GetWalletPasswordFn | undefined;
+    getAuthToken?: (() => string) | undefined;
+    getElevatedAccessToken?: ((props: {
+        scope: TokenScope;
+    }) => Promise<string | undefined>) | undefined;
+    onUnauthorized?: (() => void | Promise<void>) | undefined;
+    environmentId?: string | undefined;
+    baseApiUrl?: string | undefined;
+    relayUrl?: string | undefined;
+    baseClientKeysharesRelayApiUrl?: string | undefined;
+    dynamicWaasClient: import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient | undefined;
+    chainName: string;
+    authMode: "cookie" | "header";
+    logger: Logger;
+    __exportHandler: import("@dynamic-labs/waas").WaasExportHandler;
+    validateActiveWallet(expectedAddress: string): Promise<void>;
+    setGetAuthTokenFunction(getAuthToken: () => string): void;
+    setOnUnauthorizedFunction(onUnauthorized: () => void | Promise<void>): void;
+    setWaasAuthMode(authMode: "cookie" | "header"): void;
+    setGetMfaTokenFunction(getMfaToken: (props?: {
+        mfaAction?: MFAAction | undefined;
+    } | undefined) => Promise<string | undefined>): void;
+    setGetElevatedAccessTokenFunction(getElevatedAccessToken: (params: {
+        scope: TokenScope;
+    }) => Promise<string | undefined>): void;
+    setGetWalletPasswordFunction(getWalletPassword: import("@dynamic-labs/wallet-connector-core").GetWalletPasswordFn): void;
+    getPasswordIfNeeded({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<string | undefined>;
+    getPassword({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<string | undefined>;
+    setEnvironmentId(environmentId: string): void;
+    setBaseApiUrl(baseApiUrl: string): void;
+    setBaseClientKeysharesRelayApiUrl(baseClientKeysharesRelayApiUrl?: string | undefined): void;
+    setRelayUrl(relayUrl: string): void;
+    setGetSignedSessionIdFunction(getSignedSessionId: () => Promise<string>): void;
+    setGetSessionPublicKeyFunction(getSessionPublicKey: () => Promise<string | undefined>): void;
+    delegateKeyShares({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    createDynamicWaasClient(traceContext?: import("dist/packages/waas/utils/instrumentation").TraceContext | undefined): Promise<import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient>;
+    getWaasWalletClient(traceContext?: import("dist/packages/waas/utils/instrumentation").TraceContext | undefined, { forceRebuild }?: {
+        forceRebuild?: boolean | undefined;
+    } | undefined): Promise<import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient>;
+    createWalletAccount({ thresholdSignatureScheme, password, bitcoinConfig, }?: {
+        thresholdSignatureScheme?: string | undefined;
+        password?: string | undefined;
+        bitcoinConfig?: import("@dynamic-labs-wallet/browser-wallet-client").BitcoinConfig | undefined;
+    } | undefined): Promise<{
+        /**
+         * Requires and returns the signed session ID
+         * @returns The signed session ID
+         * @throws {DynamicError} If signed session ID is not available
+         */
+        chainName: string;
+        accountAddress: string;
+        publicKeyHex: string;
+        rawPublicKey: string | Uint8Array | undefined;
+    }>;
+    importPrivateKey({ privateKey, thresholdSignatureScheme, publicAddressCheck, addressType, legacyWalletId, password, }: {
+        privateKey: string;
+        thresholdSignatureScheme?: string | undefined;
+        publicAddressCheck?: string | undefined;
+        addressType?: string | undefined;
+        /**
+         * Validates that the expected wallet address matches the active wallet
+         * Updates the active account address if it doesn't match
+         * @param expectedAddress - The expected wallet address to validate
+         * @throws {DynamicError} If signed session ID is not available or account is not found
+         */
+        legacyWalletId?: string | undefined;
+        password?: string | undefined;
+    }): Promise<void>;
+    exportPrivateKey({ accountAddress, displayContainer, password, }?: {
+        accountAddress?: string | undefined;
+        displayContainer?: HTMLIFrameElement | undefined;
+        password?: string | undefined;
+    } | undefined): Promise<void>;
+    getExportHandler(): {
+        clear: () => void;
+    };
+    exportClientKeyshares({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    backupKeySharesToGoogleDrive({ accountAddress, password, googleDriveAccessToken, }: {
+        accountAddress: string;
+        password?: string | undefined;
+        googleDriveAccessToken?: string | undefined;
+    }): Promise<void>;
+    exportClientKeysharesFromGoogleDrive({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    backupKeySharesToICloud({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    displayICloudSignIn({ displayContainer, }: {
+        displayContainer: HTMLElement;
+    }): Promise<void>;
+    hideICloudSignIn(): Promise<void>;
+    isICloudAuthenticated(): Promise<boolean>;
+    refreshWalletAccountShares({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    reshareWalletAccountShares({ accountAddress, thresholdSignatureScheme, password, }: {
+        accountAddress: string;
+        thresholdSignatureScheme: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    revokeDelegation({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<void>;
+    updatePassword({ accountAddress, existingPassword, newPassword, }: {
+        accountAddress: string; /**
+         * Connects to the WaaS wallet client
+         */
+        existingPassword?: string | undefined;
+        newPassword: string;
+    }): Promise<void>;
+    setPassword({ accountAddress, newPassword, }: {
+        accountAddress: string;
+        newPassword: string;
+    }): Promise<void>;
+    signRawMessage({ accountAddress, message, password, }: {
+        accountAddress: string;
+        message: string;
+        password?: string | undefined;
+    }): Promise<string>;
+    unlockWallet({ accountAddress, password, }: {
+        accountAddress: string;
+        password?: string | undefined;
+    }): Promise<import("@dynamic-labs-wallet/browser-wallet-client").GetWalletResponse>;
+    getWalletRecoveryState({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<import("@dynamic-labs-wallet/browser-wallet-client").WalletRecoveryState>;
+    endSession(reason?: import("@dynamic-labs-sdk/client").LogoutReason | undefined): Promise<void>;
+    getActiveAccountAddress(): Promise<string | undefined>;
+    getConnectedAccounts(): Promise<string[]>;
+    generateTraceId(): string;
+    buildErrorInstrumentContext(error: unknown): {
+        errorCode: string | import("@dynamic-labs/utils").ErrorCode;
+        errorMessage: string;
+        errorType: string | undefined;
+    } | {
+        errorCode: string;
+        errorMessage?: undefined;
+        errorType?: undefined;
+    };
+    instrument(message: string, context: import("@dynamic-labs/logger").InstrumentOptions & import("dist/packages/waas/utils/instrumentation").InstrumentContext & Record<string, any>): void;
+    instrumentAsync<T_1>({ operation, resource, fn, context, }: {
+        operation: string;
+        resource: string;
+        fn: (timing: import("dist/packages/waas/utils/instrumentation").InstrumentationTimer) => Promise<T_1>;
+        context?: Record<string, any> | undefined;
+    }): Promise<T_1>;
+    getPrivateBalance(): Promise<{
+        unshielded: Record<string, string>;
+        shielded: Record<string, string>;
+        dust: {
+            balance: string;
+            cap: string;
+        };
+        address: string;
+        dustSynced: boolean;
+    }>;
+}) & typeof WaasMidnightWalletConnector;
+/**
+ * WaaS (Wallet-as-a-Service) connector for Midnight blockchain.
+ * Extends the WaaS-specific Midnight base with MPC wallet functionality.
+ */
+export declare class DynamicWaasMidnightConnector extends DynamicWaasMidnightConnector_base implements IDynamicWaasConnector {
+    ChainWallet: typeof MidnightWallet;
+    name: string;
+    overrideKey: string;
+    isEmbeddedWallet: boolean;
+    logger: Logger;
+    activeAccountAddress: string | undefined;
+    verifiedCredentials: JwtVerifiedCredential[] | undefined;
+    protected walletUiUtils: WalletUiUtils<InternalWalletConnector>;
+    constructor(props: DynamicWaasMidnightConnectorProps);
+    /**
+     * Signs a message with additional context information
+     * @param message - The message to sign (string or object with raw property)
+     * @param context - Additional context for the message signing
+     * @returns The signed message as a string
+     * @throws {Error} Method not implemented for Midnight
+     */
+    signMessageWithContext({ message, context, }: {
+        message: string | {
+            raw: string;
+        };
+        context: SignMessageContext;
+    }): Promise<string>;
+    /**
+     * Override setVerifiedCredentials to filter and set Midnight WaaS credentials
+     * Filters for credentials with walletName === 'dynamicwaas' and chain === 'midnight'
+     */
+    setVerifiedCredentials(verifiedCredentials: JwtVerifiedCredential[]): void;
+    /**
+     * Override setEnvironmentId to ensure it's set on the logger
+     */
+    setEnvironmentId(environmentId: string): void;
+    /**
+     * Gets the wallet client for a specific account address and sets it as active
+     * @param accountAddress - The Midnight account address
+     * @returns The WaaS wallet client instance
+     */
+    getWalletClientByAddress({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient>;
+    /**
+     * Gets the currently active account address
+     * @returns The active account address or undefined if not set
+     */
+    getActiveAccountAddress(): Promise<string | undefined>;
+    /**
+     * Sets the active account address for this connector
+     * @param accountAddress - The Midnight account address to set as active
+     */
+    private setActiveAccountAddress;
+    /**
+     * Called when the user selects this wallet in the modal.
+     * Sets the active account so getAddress/getNetwork work correctly during network validation.
+     */
+    afterWalletSelectHook(walletAddress: string): void;
+    /**
+     * Requires and returns the signed session ID
+     * @returns The signed session ID
+     * @throws {DynamicError} If signed session ID is not available
+     */
+    private requireSignedSessionId;
+    /**
+     * Validates that the expected wallet address matches the active wallet
+     * Updates the active account address if it doesn't match
+     * @param expectedAddress - The expected wallet address to validate
+     * @throws {DynamicError} If signed session ID is not available or account is not found
+     */
+    validateActiveWallet(expectedAddress: string): Promise<void>;
+    /**
+     * When active account is not set (e.g. primary wallet restored from session),
+     * fall back to the first Midnight verified credential so signing and getAddress work.
+     */
+    private ensureActiveAccountFromVerifiedCredentials;
+    /**
+     * Gets the active wallet address
+     * Falls back to verified credential address if no active account is set
+     * @returns The wallet address or empty string if not found
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Connects to the WaaS wallet client
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the wallet (no-op for WaaS)
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Signs a message using the wallet UI utils for user interaction
+     * @param message - The message to sign
+     * @returns The signed message as a string
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Internal method to sign a message with MFA token
+     * @param message - The message to sign
+     * @returns The signed message as a string
+     * @throws {DynamicError} If active account address is not set
+     * @throws {DynamicError} If signed session ID is not available
+     */
+    internalSignMessage(message: string): Promise<string>;
+    /**
+     * Ends the current session and clears the active account address
+     */
+    endSession(): Promise<void>;
+    /**
+     * Signs and finalizes (ZK proves) a Midnight transaction via MPC.
+     * Step 2 of the 3-step flow: createTransferTransaction → signTransaction → submitTransaction.
+     *
+     * @param serializedTransaction - Base64-encoded unsigned UnprovenTransaction
+     * @returns Base64-encoded FinalizedTransaction, ready for submitTransaction
+     */
+    signTransaction(serializedTransaction: string): Promise<string>;
+    /**
+     * Creates a UI transaction for the send balance flow
+     * @param from - The sender's address
+     * @returns A new IUITransaction instance
+     */
+    createUiTransaction(from: string): Promise<IUITransaction>;
+    /**
+     * Returns the provider.
+     * For WaaS, there is no traditional browser provider.
+     */
+    getProvider(): undefined;
+    /**
+     * Creates a new Midnight wallet account.
+     * Midnight wallets automatically create multiple address types:
+     * - Primary: unshielded address (for public transfers)
+     * - Additional: dust address (for gas/fee management) and shielded address (for private transfers)
+     *
+     * All address types are derived from a single keygen using different BIP-44 derivation paths.
+     *
+     * @param thresholdSignatureScheme - The threshold signature scheme (default: 'TWO_OF_TWO')
+     * @param password - Optional password for the wallet
+     * @returns The created wallet account information with primary (unshielded) address
+     */
+    createWalletAccount({ thresholdSignatureScheme, password, }?: {
+        thresholdSignatureScheme?: string;
+        password?: string;
+    }): Promise<{
+        chainName: string;
+        accountAddress: string;
+        publicKeyHex: string;
+        rawPublicKey: string | Uint8Array | undefined;
+    }>;
+    getPrivateBalance(): Promise<{
+        unshielded: Record<string, string>;
+        shielded: Record<string, string>;
+        dust: {
+            balance: string;
+            cap: string;
+        };
+        address: string;
+        dustSynced: boolean;
+    }>;
+    /**
+     * Exposes the same `ConnectedAPI` surface injected Midnight wallets provide,
+     * adapted from WaaS MPC state. This is what lets the shared
+     * `MidnightWalletConnector` balance methods (`getShieldedBalances`,
+     * `getUnshieldedBalances`, `getDustBalance`) work for WaaS wallets — they all
+     * delegate to `getConnectedAPI()`, which throws (returns undefined) by
+     * default. Address lookups and transfers stay on the WaaS-specific paths.
+     */
+    protected getConnectedAPI(): Promise<ConnectedAPI | undefined>;
+    /**
+     * Adapts the WaaS MPC `getPrivateBalance()` result to the shape
+     * `MidnightWallet.getFormattedBalances()` expects. The base
+     * `MidnightWalletConnector.getBalances()` throws unconditionally (it does not
+     * route through `getConnectedAPI`), so WaaS still overrides it directly —
+     * here in a single `getPrivateBalance()` call.
+     *
+     * Cap-tolerant: `dust.cap` is 0n on browser-wallet-client <= 1.0.16 and the
+     * real cap once the wallet-SDK-v4 change is published (no code change needed).
+     */
+    getBalances(): Promise<{
+        shielded: Record<TokenType, bigint>;
+        unshielded: Record<TokenType, bigint>;
+        dust: {
+            cap: bigint;
+            balance: bigint;
+        };
+        dustSyncing?: boolean;
+    }>;
+    registerDust(): Promise<{
+        dustBalance: string;
+        txId?: string;
+        status: 'registered' | 'already_registered' | 'already_has_dust' | 'no_utxos';
+        message: string;
+        registeredCount: number;
+    }>;
+    /**
+     * One-call transfer: runs the full build → sign (ZK prove) → submit flow and
+     * returns the broadcast tx hash. This is what backs `wallet.sendBalance` for
+     * embedded Midnight wallets; use the individual steps
+     * (`createTransferTransaction` / `signTransaction` / `submitTransaction`) when
+     * you need to inspect or persist the transaction between stages.
+     */
+    createTransfer(params: {
+        transfers: Array<{
+            type: 'unshielded' | 'shielded';
+            recipientAddress: string;
+            amount: string;
+            tokenType?: string;
+        }>;
+        /** Optional TTL in minutes. Defaults to 5. */
+        ttlMinutes?: number;
+    }): Promise<string>;
+    /**
+     * Step 1 of the Midnight transfer flow.
+     * Builds an unsigned UnprovenTransaction from one or more transfer specs.
+     * Accepts any combination of unshielded / shielded transfers in a single tx.
+     * No MPC, no proof server, no broadcast.
+     */
+    createTransferTransaction(params: {
+        transfers: Array<{
+            type: 'unshielded' | 'shielded';
+            recipientAddress: string;
+            amount: string;
+            tokenType?: string;
+        }>;
+        /** Optional TTL in minutes. Defaults to 5. */
+        ttlMinutes?: number;
+    }): Promise<{
+        serializedTransaction: string;
+    }>;
+    /**
+     * Release UTXOs reserved by an abandoned draft or signed-but-never-submitted
+     * transaction. Accepts either an unsigned (Step 1 output) or finalized
+     * (Step 2 output) serialized transaction.
+     */
+    revertTransaction(serializedTransaction: string): Promise<{
+        reverted: boolean;
+        count: number;
+        cacheCleared: boolean;
+        message: string;
+    }>;
+    /**
+     * Revert every finalized-but-unsubmitted transaction the SDK knows about
+     * (`state.pending.all`). Does not cover unfinalized Step-1-only drafts —
+     * those are never registered with the pending-tx service by design. If
+     * UTXOs are still stuck after this, use `resetWalletCache()`.
+     */
+    revertAllPending(): Promise<{
+        reverted: boolean;
+        count: number;
+        cacheCleared: boolean;
+        message: string;
+    }>;
+    /**
+     * Nuclear reset. Stops the cached wallet, clears its persisted IndexedDB
+     * entry, and forces the next operation to cold-sync from chain. Midnight's
+     * officially recommended workaround when UTXOs get stuck in pending state
+     * that can't be reverted through the normal API.
+     */
+    resetWalletCache(): Promise<{
+        reverted: boolean;
+        count: number;
+        cacheCleared: boolean;
+        message: string;
+    }>;
+    private callRevertTransaction;
+    /**
+     * Step 3 of the unshielded public transfer flow.
+     * Broadcasts a finalized transaction via the wallet's NodeClient.
+     * Optionally waits for the unshielded balance to stabilize.
+     */
+    submitTransaction(serializedFinalizedTransaction: string, options?: {
+        waitForBalance?: boolean;
+        tokenType?: string;
+        balanceBefore?: string;
+    }): Promise<{
+        txHash: string;
+        balanceAfter?: string;
+    }>;
+}
+export {};