@dynamic-labs/ton 4.62.0 → 4.63.1

package/src/connectors/TonConnectConnector/TonConnectConnector.d.ts

@@ -1,32 +1,31 @@
-import { TonConnect, type SendTransactionRequest } from '@tonconnect/sdk';
-import { TonClient } from '@ton/ton';
-import { Chain, WalletConnectorBase } from '@dynamic-labs/wallet-connector-core';
-import type { GenericNetwork, IUITransaction } from '@dynamic-labs/types';
-import { TonWallet } from '../../wallet/TonWallet';
-import { type SendJettonOptions, type TonConnectConnectorOpts, type TonConnectProof, type TonTransactionResult } from '../../types';
+import { TonConnectUI } from '@tonconnect/ui';
+import type { IUITransaction } from '@dynamic-labs/types';
+import { TonWalletConnector } from '../../TonWalletConnector';
+import { type SendTransactionRequest, type TonConnectConnectorOpts, type TonConnectProof } from '../../types';
+export declare const resetSharedTonConnectUI: () => void;
 /**
  * TON Connect connector implementation
  *
- * Uses the TON Connect SDK to connect with TON wallets that support
- * the TON Connect protocol (Tonkeeper, MyTonWallet, etc.)
+ * Uses @tonconnect/ui to present a wallet selection modal and handle
+ * QR codes, deep links, and bridge connections automatically.
+ * All TON connector instances share a single TonConnectUI to avoid
+ * DOM conflicts and localStorage key collisions.
  */
-export declare class TonConnectConnector extends WalletConnectorBase<typeof TonWallet> {
-    ChainWallet: typeof TonWallet;
+export declare class TonConnectConnector extends TonWalletConnector {
     name: string;
     overrideKey: string;
-    connectedChain: Chain;
-    supportedChains: Chain[];
     canConnectViaQrCode: boolean;
     canHandleMultipleConnections: boolean;
-    private tonConnect;
-    private tonNetworks;
+    private manifestUrl;
     private connectedWallet;
     private pendingProofPayload;
-    private lastConnectionUrl;
+    private tonConnectAppName;
+    private statusUnsubscribe;
+    private elevateCleanup;
     /**
-     * Get the TonConnect instance (for discovering wallets and advanced usage)
+     * Get the shared TonConnectUI instance
      */
-    getTonConnect(): TonConnect;
+    getTonConnectUI(): TonConnectUI;
     /**
      * Creates a new TON Connect connector
      *
@@ -34,72 +33,54 @@ export declare class TonConnectConnector extends WalletConnectorBase<typeof TonW
      */
     constructor(opts: TonConnectConnectorOpts);
     /**
-     * Setup event listeners for TON Connect
+     * Setup event listeners for TonConnect UI status changes.
+     * Filters events by wallet appName so each connector only reacts
+     * to its own wallet's status changes.
      */
     setupEventListeners(): void;
     /**
-     * Check if the wallet's browser extension is installed
+     * Teardown event listeners
+     */
+    teardownEventListeners(): void;
+    /**
+     * Always return true so the SDK proceeds to connect() instead of
+     * showing an "install extension" prompt.  TonConnect UI handles
+     * wallet discovery and selection internally via its own modal.
      */
     isInstalledOnBrowser(): boolean;
     /**
-     * Retry opening the wallet deep link on mobile
+     * Re-open the TonConnect UI modal for the configured wallet.
+     * Called when the user taps "Open [WalletName]" in the mobile redirect view.
      */
     retryDeeplinkConnection(): void;
     /**
-     * Connect to a TON wallet
+     * Connect to a TON wallet via TonConnect UI modal.
+     * When tonProofPayload is provided, the proof request is bundled into
+     * the connection handshake so the wallet returns address + proof in one shot.
      * @param tonProofPayload - Optional payload for tonProof authentication
      */
     connect(tonProofPayload?: string): Promise<void>;
     /**
-     * Find a wallet matching this connector's overrideKey
-     */
-    private findMatchingWallet;
-    /**
-     * Get the current wallet address in user-friendly format (EQ... or UQ...)
+     * Get the current wallet address in user-friendly format (EQ... or UQ...).
      */
     getAddress(): Promise<string | undefined>;
     /**
-     * Get connected accounts
+     * Get connected accounts.
+     * Awaits session restoration so a persisted session is not missed.
      */
     getConnectedAccounts(): Promise<string[]>;
     /**
-     * Get the current network
-     */
-    getNetwork(): Promise<string | undefined>;
-    /**
-     * Check if current network is testnet
-     */
-    isTestnet(): Promise<boolean>;
-    /**
-     * Sign a message
+     * Sign a message using TonConnect UI
      */
     signMessage(messageToSign: string): Promise<string>;
     /**
-     * Send a transaction
-     */
-    sendTransaction(request: SendTransactionRequest): Promise<TonTransactionResult>;
-    /**
-     * Send Jetton transaction
-     */
-    sendJettonTransaction(_options: SendJettonOptions): Promise<TonTransactionResult>;
-    /**
-     * Get TonClient for the current or specified network.
-     */
-    getTonClient(chainId?: string): TonClient;
-    /**
-     * Get balance of an address
-     */
-    getBalance(address: string): Promise<string | undefined>;
-    /**
-     * Get enabled networks
+     * Send a transaction via TonConnect UI.
+     * Returns the BOC string from the wallet response.
      */
-    getEnabledNetworks(): GenericNetwork[];
+    sendTransaction(request: SendTransactionRequest): Promise<string>;
     /**
-     * Switch network (TON Connect handles this automatically)
-     */
-    switchNetwork(): Promise<void>;
-    /**
-     * Disconnect and cleanup
+     * Disconnect and cleanup.
+     * Only disconnects if this connector owns the current connection.
      */
     endSession(): Promise<void>;
     /**
@@ -112,26 +93,34 @@ export declare class TonConnectConnector extends WalletConnectorBase<typeof TonW
     private internalSendUiTransaction;
     /**
      * Convert TON address from raw format (0:hex) to user-friendly format (UQ...)
-     * TON Connect SDK expects user-friendly format for message addresses
      */
     private convertAddressToUserFriendly;
     /**
-     * Encode a comment as TON message payload
-     *
-     * TON comments are encoded as a Cell with:
-     * - First 32 bits (4 bytes): 0x00000000 (comment opcode)
-     * - Then the UTF-8 bytes of the comment
-     *
-     * For long messages, the comment is split across multiple cells using references.
-     * The Cell is then serialized to base64 BOC format for TON Connect SDK
+     * Encode a comment as TON message payload.
+     * NOTE: TON cells support a maximum of 4 references per cell.
+     * Comments longer than 123 + (4 * 127) = 631 bytes will exceed
+     * this limit. Consider implementing proper snake-cell encoding
+     * for arbitrarily long comments if needed.
      */
     encodeComment(comment: string): string;
     /**
-     * Append a return strategy to a TonConnect universal link.
-     * The `ret` parameter tells the wallet where to redirect after approval.
-     * `back` instructs the wallet to return to the previous app (browser).
+     * Elevate the TonConnect UI above the Dynamic auth modal and prevent
+     * the Dynamic backdrop from intercepting pointer events.
+     * Returns a cleanup function that restores the original state.
+     * Uses a MutationObserver fallback for when #tc-widget-root is created lazily.
+     */
+    private elevateTonConnectUI;
+    /**
+     * Run and clear the elevation cleanup function
+     */
+    private cleanupElevation;
+    /**
+     * Hook called after this wallet is selected as primary.
+     * Reconnects the shared TonConnectUI singleton to this connector's
+     * wallet so that subsequent operations (sign, send) route to the
+     * correct wallet app.
      */
-    private appendReturnStrategy;
+    afterWalletSelectHook(): Promise<void>;
     /**
      * Check if error is a user rejection
      */
@@ -142,40 +131,36 @@ export declare class TonConnectConnector extends WalletConnectorBase<typeof TonW
      * @returns TON Connect proof object
      */
     generateTonConnectProof(payload: string): Promise<TonConnectProof>;
+    /**
+     * Reconnect to a browser extension wallet directly via the JS bridge,
+     * bypassing the TonConnect modal UI. Used during proof reconnection
+     * (where the modal would fail due to internal state not being fully
+     * reset after a disconnect) and during wallet switching.
+     */
+    private connectViaJsBridge;
     /**
      * Override proveOwnership to use tonProof for wallet verification
-     *
-     * For TON wallets, we use the tonProof mechanism during connection
-     * which is the standard way to prove wallet ownership in TON Connect.
-     * The backend expects a specific format with state_init and public_key.
      */
     proveOwnership(address: string, messageToSign: string): Promise<string | undefined>;
     /**
      * proveOwnership using tonProof
-     *
-     * Returns the proof in the format expected by the backend:
-     * {
-     *   address: string,
-     *   proof: { domain, payload, signature, state_init, timestamp },
-     *   public_key: string
-     * }
      */
     private proveOwnershipWithTonProof;
     /**
-     * Extract public key from state_init cell
+     * Detect the wallet contract version from its code cell hash.
+     * Returns the number of bits to skip before the public key in the data cell.
      *
-     * For standard TON wallets, the public key is stored in the data cell:
-     * - First 32 bits: seqno (skipped)
-     * - Next 256 bits (32 bytes): public key
-     *
-     * This matches the extraction logic in the backend.
+     * V3R2 / V4R2: seqno(32) + subwallet_id(32) + pubkey(256) → skip 64 bits
+     * V5R1:        is_signature_allowed(1) + seqno(32) + wallet_id(32) + pubkey(256) → skip 65 bits
+     */
+    private getPublicKeyBitOffset;
+    /**
+     * Extract public key from state_init cell.
+     * Detects wallet contract version to correctly locate the public key.
      */
     private extractPublicKeyFromStateInit;
     /**
      * Extract the nonce from a SIWE-style message
-     *
-     * @param message - The full message to extract nonce from
-     * @returns A short payload suitable for tonProof
      */
     private extractNonceFromMessage;
 }