@dynamic-labs/aleo 4.79.2 → 4.80.0

package/src/connectors/DynamicWaasAleoConnector/DynamicWaasAleoConnector.d.ts

@@ -0,0 +1,409 @@
+import type { LogoutReason } from '@dynamic-labs-sdk/client';
+import { JwtVerifiedCredential, SignMessageContext } 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 { WaasAleoWalletConnector, type WaasAleoWalletConnectorProps } from '../WaasAleoWalletConnector';
+import { AleoWallet } from '../../wallet/AleoWallet';
+import { AleoOwnedRecord } from '../../utils/aleoSendableTokens';
+export type DynamicWaasAleoConnectorProps = WaasAleoWalletConnectorProps & {
+    walletUiUtils: WalletUiUtils<InternalWalletConnector>;
+};
+type JoinProgramResult = {
+    programId: string;
+    rounds: number;
+    finalRecordPlaintext?: string;
+    skipped?: 'insufficient_records' | 'unsupported';
+    error?: string;
+};
+declare const DynamicWaasAleoConnector_base: (abstract new (...args: any[]) => {
+    [x: string]: any;
+    name: string;
+    overrideKey: string;
+    isEmbeddedWallet: boolean;
+    getSignedSessionId?: (() => Promise<string>) | undefined;
+    getMfaToken?: ((props?: {
+        mfaAction?: import("@dynamic-labs/sdk-api-core").MFAAction | undefined;
+    } | undefined) => Promise<string | undefined>) | undefined;
+    getWalletPassword?: import("@dynamic-labs/wallet-connector-core").GetWalletPasswordFn | undefined;
+    getAuthToken?: (() => string) | undefined;
+    getElevatedAccessToken?: ((props: {
+        scope: import("@dynamic-labs/sdk-api-core").TokenScope;
+    }) => Promise<string | undefined>) | 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;
+    setWaasAuthMode(authMode: "cookie" | "header"): void;
+    setGetMfaTokenFunction(getMfaToken: (props?: {
+        mfaAction?: import("@dynamic-labs/sdk-api-core").MFAAction | undefined;
+    } | undefined) => Promise<string | undefined>): void;
+    setGetElevatedAccessTokenFunction(getElevatedAccessToken: (params: {
+        scope: import("@dynamic-labs/sdk-api-core").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;
+    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): Promise<import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient>;
+    createWalletAccount({ thresholdSignatureScheme, password, bitcoinConfig, }?: {
+        thresholdSignatureScheme?: string | undefined;
+        password?: string | undefined;
+        bitcoinConfig?: import("@dynamic-labs-wallet/core").BitcoinConfig | undefined;
+    } | undefined): Promise<{
+        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;
+        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, }: {
+        accountAddress: string;
+        password?: 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;
+        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/core").GetWalletResponse>;
+    getWalletRecoveryState({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<import("@dynamic-labs-wallet/core").WalletRecoveryState>;
+    endSession(reason?: LogoutReason | undefined): Promise<void>;
+    getActiveAccountAddress(): Promise<string | undefined>;
+    getConnectedAccounts(): Promise<string[]>;
+    generateTraceId(): string;
+    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>;
+}) & typeof WaasAleoWalletConnector;
+/**
+ * Dynamic WaaS connector for Aleo.
+ * Phase 1: supports wallet creation (MPC keygen → aleo1... address) and
+ * retrieval of the active WaaS wallet. signMessage and signTransaction
+ * throw NotSupported until Sodot adds `EdBls12377.sign(bytes)` and we wire up
+ * the Aleo `signRequest` ceremony.
+ */
+export declare class DynamicWaasAleoConnector extends DynamicWaasAleoConnector_base implements IDynamicWaasConnector {
+    ChainWallet: typeof AleoWallet;
+    name: string;
+    overrideKey: string;
+    isEmbeddedWallet: boolean;
+    logger: Logger;
+    activeAccountAddress: string | undefined;
+    verifiedCredentials: JwtVerifiedCredential[] | undefined;
+    protected walletUiUtils: WalletUiUtils<InternalWalletConnector>;
+    constructor(props: DynamicWaasAleoConnectorProps);
+    setVerifiedCredentials(verifiedCredentials: JwtVerifiedCredential[]): void;
+    getWalletClientByAddress({ accountAddress, }: {
+        accountAddress: string;
+    }): Promise<import("@dynamic-labs-wallet/browser-wallet-client").DynamicWalletClient>;
+    getActiveAccountAddress(): Promise<string | undefined>;
+    private setActiveAccountAddress;
+    afterWalletSelectHook(walletAddress: string): void;
+    private requireSignedSessionId;
+    validateActiveWallet(expectedAddress: string): Promise<void>;
+    private ensureActiveAccountFromVerifiedCredentials;
+    getAddress(): Promise<string>;
+    connect(): Promise<void>;
+    getConnectedAccounts(): Promise<string[]>;
+    signMessage(message: string): Promise<string>;
+    signMessageWithContext({ message, context, }: {
+        message: string | {
+            raw: string;
+        };
+        context: SignMessageContext;
+    }): Promise<string>;
+    signTransaction(_transaction: unknown): Promise<string>;
+    /**
+     * Aleo full transaction flow: view key → MPC sign → prove + broadcast via DPS.
+     * Delegates to the iframe's DynamicAleoWalletClient.proveTransaction.
+     */
+    proveTransaction(params: {
+        programId: string;
+        functionName: string;
+        inputs: string[];
+        inputTypes: string[];
+        broadcast?: boolean;
+    }): Promise<{
+        txId?: string;
+        provingResponse?: unknown;
+    }>;
+    /**
+     * List this wallet's Aleo records across all programs (credits + custom
+     * tokens). Delegates into the iframe's DynamicAleoWalletClient.
+     * findOwnedRecords, which uses Provable's hosted RecordScanner. View key
+     * never leaves the iframe.
+     *
+     * Each returned record carries `program_name` + `record_name` so callers
+     * can group/display by token. Credits records additionally get a parsed
+     * `microcredits` field. Other tokens are returned raw — caller parses the
+     * plaintext per program schema.
+     *
+     * First call per wallet registers the view key with Provable (one-time,
+     * cached UUID in iframe IndexedDB). Subsequent calls reuse the UUID.
+     */
+    listOwnedRecords(): Promise<{
+        records: unknown[];
+    }>;
+    /**
+     * Merge the wallet's owned records down — one final record per Aleo
+     * program — by recursively running `<program>/join` two-at-a-time.
+     * Mirrors the basic pairwise strategy from Provable's `example-autojoin`:
+     * at each round we pair records, run joins concurrently, wait for the
+     * outputs to surface from Provable's RecordScanner, and recurse until one
+     * record remains for that program. Odd-one-out is carried forward.
+     *
+     * Cross-program records can't combine on-chain (a `credits.aleo/credits`
+     * record and a `test_usad_stablecoin.aleo/Token` record have different
+     * record types), so the result is always one record per program.
+     *
+     * Fees are sponsored by ANF's Feemaster when its policy covers the
+     * `(programId, 'join')` pair (today: `credits.aleo`). Programs not in
+     * the policy fall through to the user-paid path inside `proveTransaction`.
+     *
+     * Today: only `credits.aleo` is allowed end-to-end. Stablecoin / ARC-21
+     * joins are blocked on snarkVM's `Stack::authorize_request` credits-only
+     * check — Provable is tracking the relaxation. Until then non-credits
+     * programs are reported as `skipped: 'unsupported'` rather than thrown,
+     * so callers can iterate the result and surface what merged vs. what
+     * didn't without try/catch noise.
+     *
+     * @param opts.programIds  Programs to merge. Omit (default) to merge
+     *   every owned program with ≥2 records. Programs with <2 records are
+     *   reported as `skipped: 'insufficient_records'`.
+     * @param opts.filterRecord  Optional per-record predicate that narrows
+     *   the candidate set BEFORE pairing. Used by ARC-21 where one program
+     *   (`token_registry.aleo`) hosts many tokens — the on-chain `join`
+     *   refuses to combine records with different `token_id` fields, so we
+     *   filter by token_id first and never broadcast a doomed merge.
+     */
+    joinRecords(opts?: {
+        programIds?: string[];
+        filterRecord?: (record: AleoOwnedRecord) => boolean;
+    }): Promise<{
+        results: JoinProgramResult[];
+    }>;
+    /**
+     * Pre-fork: only `credits.aleo` made it past `Stack::authorize_request`.
+     * Post-fork (Roy's snarkVM @32ad6c4 + the file:-overrides in
+     * dynamic-waas-sdk's pnpm workspace), stablecoin joins authorize too.
+     * Programs that *aren't* credits and aren't a known stablecoin still
+     * 404 on shape — we'd hit `record name doesn't match` or similar
+     * mid-MPC, which is wasteful, so we keep an allowlist.
+     */
+    private processProgramJoin;
+    /**
+     * Reads the wallet's owned records, applies the optional caller predicate,
+     * and groups by program. The `filterRecord` predicate runs first so callers
+     * can scope the merge to a sub-set within a program (ARC-21 token_id filter).
+     */
+    private fetchAndGroupOwnedRecords;
+    /**
+     * Pairwise-merges `records` (all from `programId`) until one remains.
+     * Each round runs every pair's join concurrently, then polls the
+     * RecordScanner until the round's output records have surfaced.
+     * Caller validates the list shape and ≥2 length.
+     *
+     * We track every plaintext we've consumed across the entire call in
+     * `consumedAcrossCall` and exclude them from each poll result. Provable's
+     * RecordScanner indexes a transaction's new outputs and its spent inputs
+     * separately — outputs typically surface 5–15 s after broadcast, but the
+     * spend index for the consumed inputs can lag much longer (we've seen
+     * 30 s+). Without local consumed-tracking, polling either (a) waits for
+     * the laggy spend index, slowing every round to its slowest piece, or
+     * (b) lets a stale consumed record leak into the next round's polling
+     * and mis-count it as a fresh output.
+     *
+     * Per-program shape (record name + input types) comes from
+     * `joinShapeForProgram(programId)`. Today that supports `credits.aleo`
+     * and the four Sealance-compliant stablecoin program ids; extending
+     * to ARC-21 / token_registry would be another entry there.
+     */
+    private joinProgramRecords;
+    /**
+     * Polls `listOwnedRecords` until `expectedNewCount` previously-unseen
+     * records of the right program/record-name have surfaced. We do NOT
+     * wait for the scanner to mark consumed inputs as spent — that index
+     * is independently delayed, and waiting on it stalls rounds whose
+     * outputs are already visible. `consumedAcrossCall` is the local-spent
+     * set tracked in `joinProgramRecords`; we filter against it explicitly.
+     */
+    private waitForJoinRoundOutputs;
+    /**
+     * Returns the IUITransaction the widget's Send flow drives. Implementing
+     * this method is the *only* signal the widget needs to render the "Send"
+     * button next to "Deposit" — `isSendBalanceWalletConnector` is duck-typed
+     * on the presence of `createUiTransaction`.
+     *
+     * The widget's send view picks one token from the per-network registry
+     * (credits + USAD/USDCx always; mainnet additionally exposes 5 ARC-21
+     * hyp_warp tokens). At submit time the picked token's `programKind`
+     * drives the transition signature:
+     *
+     *  - `credits`     → `credits.aleo/transfer_private(_to_public)`,
+     *                    inputs `[record, recipient, amount]` (u64).
+     *  - `stablecoin`  → `<token>.aleo/transfer_private(_to_public)`,
+     *                    inputs `[recipient, amount, record]` (u128). The
+     *                    iframe appends a Sealance freeze-list exclusion
+     *                    proof + its `[MerkleProof; 2u32].private` type
+     *                    automatically.
+     *  - `arc21`       → `token_registry.aleo/transfer_private(_to_public)`,
+     *                    inputs `[recipient, amount, record]` (u128). The
+     *                    token_id is encoded inside the record plaintext;
+     *                    the transition signature does NOT take it as an
+     *                    explicit argument.
+     *
+     * Submission path: AleoUiTransaction.submit → onSubmit closure below →
+     * this.proveTransaction → iframe (Sodot MPC sign + optional Sealance
+     * proof injection) → Feemaster (when policy covers it) → Provable DPS
+     * (proves + broadcasts) → returns txId.
+     */
+    createUiTransaction(from: string): Promise<IUITransaction>;
+    /**
+     * True when the given token is registered as shieldable on the
+     * currently-selected Aleo network. The widget's Unshielded tab uses this
+     * to gate the "Shield Manually" CTA — unregistered tokens (e.g. random
+     * third-party Aleo programs surfaced by the redcoast public-balance feed)
+     * don't get a CTA they couldn't successfully act on.
+     *
+     * Native ALEO doesn't have a contract address in redcoast's public-balance
+     * feed (it surfaces as `isNative: true` with a sentinel like `'0x0'`),
+     * so we recognise it via `isNative` and fall back to the registry's
+     * `credits.aleo` entry when the literal address misses.
+     */
+    canShieldToken(token: {
+        address?: string;
+        isNative?: boolean;
+    }): boolean;
+    /**
+     * True when the Feemaster currently sponsors a shield (
+     * `transfer_public_to_private`) of the given token. Wraps the generic
+     * `isFeemasterSponsored` and looks up the token's `programId` from the
+     * shieldable registry. Used by the widget to decide whether the
+     * "Shield Manually" CTA can dispatch silently or needs a user-paid fee
+     * confirmation modal first.
+     */
+    isShieldSponsored(token: {
+        address?: string;
+        isNative?: boolean;
+    }): Promise<boolean>;
+    /**
+     * True when ANF's Feemaster policy currently sponsors `(programId,
+     * functionName)` on the connector-selected network. Used by the widget
+     * to decide whether to show a user-paid confirmation modal before a
+     * shield/send/join. Generic — applies to any (program, function) pair,
+     * not shield-specific. Never throws — returns `false` on any failure so
+     * callers default to "show modal" rather than silently dispatching.
+     */
+    isFeemasterSponsored(args: {
+        programId: string;
+        functionName: string;
+    }): Promise<boolean>;
+    private resolveShieldableToken;
+    /**
+     * Shield (`transfer_public_to_private`) `amount` of the given token from
+     * the wallet's public balance into a fresh private record owned by self.
+     * Drives the widget's "Shield Manually" CTA on the Unshielded tab.
+     *
+     * `amount` is in the token's atomic units (microcredits for credits;
+     * `10^decimals` for stablecoin / ARC-21). The connector resolves the
+     * shield-shape registry by `tokenAddress` (matching the unshielded
+     * `TokenBalance.address` redcoast surfaces). Recipient is always self.
+     *
+     * Throws `DynamicError` if the token has no shield shape registered for
+     * the current network — those tokens shouldn't have rendered the CTA in
+     * the first place, but the throw is a safety net against a stale UI
+     * state slipping a doomed transaction past us.
+     */
+    shieldToken(args: {
+        tokenAddress: string;
+        isNative?: boolean;
+        amount: bigint;
+    }): Promise<string>;
+    endSession(reason?: LogoutReason): Promise<void>;
+    getProvider(): undefined;
+}
+export {};