@solana-mobile/mobile-wallet-adapter-protocol 2.1.4 → 2.2.0-new-arch-beta

package/src/transact.ts

@@ -0,0 +1,499 @@
+import createHelloReq from './createHelloReq.js';
+import createMobileWalletProxy from './createMobileWalletProxy.js';
+import { SEQUENCE_NUMBER_BYTES } from './createSequenceNumberVector.js';
+import { ENCODED_PUBLIC_KEY_LENGTH_BYTES } from './encryptedMessage.js';
+import {
+    SolanaMobileWalletAdapterError,
+    SolanaMobileWalletAdapterErrorCode,
+    SolanaMobileWalletAdapterProtocolError,
+} from './errors.js';
+import generateAssociationKeypair from './generateAssociationKeypair.js';
+import generateECDHKeypair from './generateECDHKeypair.js';
+import { decryptJsonRpcMessage, encryptJsonRpcMessage } from './jsonRpcMessage.js';
+import parseHelloRsp, { SharedSecret } from './parseHelloRsp.js';
+import parseSessionProps from './parseSessionProps.js';
+import { startSession, startRemoteSession, getRemoteSessionUrl } from './startSession.js';
+import { AssociationKeypair, MobileWallet, RemoteMobileWallet, RemoteWalletAssociationConfig, SessionProperties, WalletAssociationConfig } from './types.js';
+
+const WEBSOCKET_CONNECTION_CONFIG = {
+    /**
+     * 300 milliseconds is a generally accepted threshold for what someone
+     * would consider an acceptable response time for a user interface
+     * after having performed a low-attention tapping task. We set the initial
+     * interval at which we wait for the wallet to set up the websocket at
+     * half this, as per the Nyquist frequency, with a progressive backoff
+     * sequence from there. The total wait time is 30s, which allows for the
+     * user to be presented with a disambiguation dialog, select a wallet, and
+     * for the wallet app to subsequently start.
+     */
+    retryDelayScheduleMs: [150, 150, 200, 500, 500, 750, 750, 1000],
+    timeoutMs: 30000,
+} as const;
+const WEBSOCKET_PROTOCOL = 'com.solana.mobilewalletadapter.v1';
+
+type JsonResponsePromises<T> = Record<
+    number,
+    Readonly<{ resolve: (value?: T | PromiseLike<T>) => void; reject: (reason?: unknown) => void }>
+>;
+
+type State =
+    | { __type: 'connected'; sharedSecret: SharedSecret; sessionProperties: SessionProperties }
+    | { __type: 'connecting'; associationKeypair: AssociationKeypair }
+    | { __type: 'disconnected' }
+    | { __type: 'hello_req_sent'; associationPublicKey: CryptoKey; ecdhPrivateKey: CryptoKey };
+
+function assertSecureContext() {
+    if (typeof window === 'undefined' || window.isSecureContext !== true) {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_SECURE_CONTEXT_REQUIRED,
+            'The mobile wallet adapter protocol must be used in a secure context (`https`).',
+        );
+    }
+}
+
+function assertSecureEndpointSpecificURI(walletUriBase: string) {
+    let url: URL;
+    try {
+        url = new URL(walletUriBase);
+    } catch {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL,
+            'Invalid base URL supplied by wallet',
+        );
+    }
+    if (url.protocol !== 'https:') {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL,
+            'Base URLs supplied by wallets must be valid `https` URLs',
+        );
+    }
+}
+
+function getSequenceNumberFromByteArray(byteArray: ArrayBuffer): number {
+    const view = new DataView(byteArray);
+    return view.getUint32(0, /* littleEndian */ false);
+}
+
+export async function transact<TReturn>(
+    callback: (wallet: MobileWallet) => TReturn,
+    config?: WalletAssociationConfig,
+): Promise<TReturn> {
+    assertSecureContext();
+    const associationKeypair = await generateAssociationKeypair();
+    const sessionPort = await startSession(associationKeypair.publicKey, config?.baseUri);
+    const websocketURL = `ws://localhost:${sessionPort}/solana-wallet`;
+    let connectionStartTime: number;
+    const getNextRetryDelayMs = (() => {
+        const schedule = [...WEBSOCKET_CONNECTION_CONFIG.retryDelayScheduleMs];
+        return () => (schedule.length > 1 ? (schedule.shift() as number) : schedule[0]);
+    })();
+    let nextJsonRpcMessageId = 1;
+    let lastKnownInboundSequenceNumber = 0;
+    let state: State = { __type: 'disconnected' };
+    return new Promise((resolve, reject) => {
+        let socket: WebSocket;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const jsonRpcResponsePromises: JsonResponsePromises<any> = {};
+        const handleOpen = async () => {
+            if (state.__type !== 'connecting') {
+                console.warn(
+                    'Expected adapter state to be `connecting` at the moment the websocket opens. ' +
+                        `Got \`${state.__type}\`.`,
+                );
+                return;
+            }
+            socket.removeEventListener('open', handleOpen);
+
+            // previous versions of this library and walletlib incorrectly implemented the MWA session 
+            // establishment protocol for local connections. The dapp is supposed to wait for the 
+            // APP_PING message before sending the HELLO_REQ. Instead, the dapp was sending the HELLO_REQ 
+            // immediately upon connection to the websocket server regardless of wether or not an 
+            // APP_PING was sent by the wallet/websocket server. We must continue to support this behavior 
+            // in case the user is using a wallet that has not updated their walletlib implementation. 
+            const { associationKeypair } = state;
+            const ecdhKeypair = await generateECDHKeypair();
+            socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+            state = {
+                __type: 'hello_req_sent',
+                associationPublicKey: associationKeypair.publicKey,
+                ecdhPrivateKey: ecdhKeypair.privateKey,
+            };
+        };
+        const handleClose = (evt: CloseEvent) => {
+            if (evt.wasClean) {
+                state = { __type: 'disconnected' };
+            } else {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_CLOSED,
+                        `The wallet session dropped unexpectedly (${evt.code}: ${evt.reason}).`,
+                        { closeEvent: evt },
+                    ),
+                );
+            }
+            disposeSocket();
+        };
+        const handleError = async (_evt: Event) => {
+            disposeSocket();
+            if (Date.now() - connectionStartTime >= WEBSOCKET_CONNECTION_CONFIG.timeoutMs) {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_TIMEOUT,
+                        `Failed to connect to the wallet websocket at ${websocketURL}.`,
+                    ),
+                );
+            } else {
+                await new Promise((resolve) => {
+                    const retryDelayMs = getNextRetryDelayMs();
+                    retryWaitTimeoutId = window.setTimeout(resolve, retryDelayMs);
+                });
+                attemptSocketConnection();
+            }
+        };
+        const handleMessage = async (evt: MessageEvent<Blob>) => {
+            const responseBuffer = await evt.data.arrayBuffer();
+            switch (state.__type) {
+                case 'connecting':
+                    if (responseBuffer.byteLength !== 0) {
+                        throw new Error('Encountered unexpected message while connecting');
+                    }
+                    const ecdhKeypair = await generateECDHKeypair();
+                    socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                    state = {
+                        __type: 'hello_req_sent',
+                        associationPublicKey: associationKeypair.publicKey,
+                        ecdhPrivateKey: ecdhKeypair.privateKey,
+                    };
+                    break;
+                case 'connected':
+                    try {
+                        const sequenceNumberVector = responseBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                        const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                        if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                            throw new Error('Encrypted message has invalid sequence number');
+                        }
+                        lastKnownInboundSequenceNumber = sequenceNumber;
+                        const jsonRpcMessage = await decryptJsonRpcMessage(responseBuffer, state.sharedSecret);
+                        const responsePromise = jsonRpcResponsePromises[jsonRpcMessage.id];
+                        delete jsonRpcResponsePromises[jsonRpcMessage.id];
+                        responsePromise.resolve(jsonRpcMessage.result);
+                    } catch (e) {
+                        if (e instanceof SolanaMobileWalletAdapterProtocolError) {
+                            const responsePromise = jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            delete jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            responsePromise.reject(e);
+                        } else {
+                            throw e;
+                        }
+                    }
+                    break;
+                case 'hello_req_sent': {
+                    // if we receive an APP_PING message (empty message), resend the HELLO_REQ (see above)
+                    if (responseBuffer.byteLength === 0) {
+                        const ecdhKeypair = await generateECDHKeypair();
+                        socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                        state = {
+                            __type: 'hello_req_sent',
+                            associationPublicKey: associationKeypair.publicKey,
+                            ecdhPrivateKey: ecdhKeypair.privateKey,
+                        };
+                        break;
+                    }
+                    const sharedSecret = await parseHelloRsp(
+                        responseBuffer,
+                        state.associationPublicKey,
+                        state.ecdhPrivateKey,
+                    );
+                    const sessionPropertiesBuffer = responseBuffer.slice(ENCODED_PUBLIC_KEY_LENGTH_BYTES);
+                    const sessionProperties = sessionPropertiesBuffer.byteLength !== 0 
+                        ? await (async () => {
+                            const sequenceNumberVector = sessionPropertiesBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                            const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                            if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                                throw new Error('Encrypted message has invalid sequence number');
+                            }
+                            lastKnownInboundSequenceNumber = sequenceNumber;
+                            return parseSessionProps(sessionPropertiesBuffer, sharedSecret);
+                        })() : <SessionProperties> { protocol_version: 'legacy' };
+                    state = { __type: 'connected', sharedSecret, sessionProperties };
+                    const wallet = createMobileWalletProxy(sessionProperties.protocol_version,
+                        async (method, params) => {
+                            const id = nextJsonRpcMessageId++;
+                            socket.send(
+                                await encryptJsonRpcMessage(
+                                    {
+                                        id,
+                                        jsonrpc: '2.0' as const,
+                                        method,
+                                        params: params ?? {},
+                                    }, 
+                                    sharedSecret,
+                                ),
+                            );
+                            return new Promise((resolve, reject) => {
+                                jsonRpcResponsePromises[id] = {
+                                    resolve(result) {
+                                        switch (method) {
+                                            case 'authorize':
+                                            case 'reauthorize': {
+                                                const { wallet_uri_base } = result as Awaited<
+                                                    ReturnType<MobileWallet['authorize' | 'reauthorize']>
+                                                >;
+                                                if (wallet_uri_base != null) {
+                                                    try {
+                                                        assertSecureEndpointSpecificURI(wallet_uri_base);
+                                                    } catch (e) {
+                                                        reject(e);
+                                                        return;
+                                                    }
+                                                }
+                                                break;
+                                            }
+                                        }
+                                        resolve(result);
+                                    },
+                                    reject,
+                                };
+                            });
+                        })
+                    try {
+                        resolve(await callback(wallet));
+                    } catch (e) {
+                        reject(e);
+                    } finally {
+                        disposeSocket();
+                        socket.close();
+                    }
+                    break;
+                }
+            }
+        };
+        let disposeSocket: () => void;
+        let retryWaitTimeoutId: number;
+        const attemptSocketConnection = () => {
+            if (disposeSocket) {
+                disposeSocket();
+            }
+            state = { __type: 'connecting', associationKeypair };
+            if (connectionStartTime === undefined) {
+                connectionStartTime = Date.now();
+            }
+            socket = new WebSocket(websocketURL, [WEBSOCKET_PROTOCOL]);
+            socket.addEventListener('open', handleOpen);
+            socket.addEventListener('close', handleClose);
+            socket.addEventListener('error', handleError);
+            socket.addEventListener('message', handleMessage);
+            disposeSocket = () => {
+                window.clearTimeout(retryWaitTimeoutId);
+                socket.removeEventListener('open', handleOpen);
+                socket.removeEventListener('close', handleClose);
+                socket.removeEventListener('error', handleError);
+                socket.removeEventListener('message', handleMessage);
+            };
+        };
+        attemptSocketConnection();
+    });
+}
+
+export async function transactRemote<TReturn>(
+    callback: (wallet: RemoteMobileWallet) => TReturn,
+    config: RemoteWalletAssociationConfig,
+): Promise<{associationUrl: URL, result: Promise<TReturn>}> {
+    assertSecureContext();
+    const associationKeypair = await generateAssociationKeypair();
+    const { associationUrl, reflectorId } = await getRemoteSessionUrl(associationKeypair.publicKey, config.remoteHostAuthority, config?.baseUri);
+    const websocketURL = `wss://${config?.remoteHostAuthority}/reflect?id=${reflectorId}`;
+
+    let connectionStartTime: number;
+    const getNextRetryDelayMs = (() => {
+        const schedule = [...WEBSOCKET_CONNECTION_CONFIG.retryDelayScheduleMs];
+        return () => (schedule.length > 1 ? (schedule.shift() as number) : schedule[0]);
+    })();
+    let nextJsonRpcMessageId = 1;
+    let lastKnownInboundSequenceNumber = 0;
+    let state: State = { __type: 'disconnected' };
+    return { associationUrl, result: new Promise((resolve, reject) => {
+        let socket: WebSocket;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const jsonRpcResponsePromises: JsonResponsePromises<any> = {};
+        const handleOpen = async () => {
+            if (state.__type !== 'connecting') {
+                console.warn(
+                    'Expected adapter state to be `connecting` at the moment the websocket opens. ' +
+                        `Got \`${state.__type}\`.`,
+                );
+                return;
+            }
+            socket.removeEventListener('open', handleOpen);
+        };
+        const handleClose = (evt: CloseEvent) => {
+            if (evt.wasClean) {
+                state = { __type: 'disconnected' };
+            } else {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_CLOSED,
+                        `The wallet session dropped unexpectedly (${evt.code}: ${evt.reason}).`,
+                        { closeEvent: evt },
+                    ),
+                );
+            }
+            disposeSocket();
+        };
+        const handleError = async (_evt: Event) => {
+            disposeSocket();
+            if (Date.now() - connectionStartTime >= WEBSOCKET_CONNECTION_CONFIG.timeoutMs) {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_TIMEOUT,
+                        `Failed to connect to the wallet websocket at ${websocketURL}.`,
+                    ),
+                );
+            } else {
+                await new Promise((resolve) => {
+                    const retryDelayMs = getNextRetryDelayMs();
+                    retryWaitTimeoutId = window.setTimeout(resolve, retryDelayMs);
+                });
+                attemptSocketConnection();
+            }
+        };
+        const handleMessage = async (evt: MessageEvent<Blob>) => {
+            const responseBuffer = await evt.data.arrayBuffer();
+            switch (state.__type) {
+                case 'connecting':
+                    if (responseBuffer.byteLength !== 0) {
+                        throw new Error('Encountered unexpected message while connecting');
+                    }
+                    const ecdhKeypair = await generateECDHKeypair();
+                    socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                    state = {
+                        __type: 'hello_req_sent',
+                        associationPublicKey: associationKeypair.publicKey,
+                        ecdhPrivateKey: ecdhKeypair.privateKey,
+                    };
+                    break;
+                case 'connected':
+                    try {
+                        const sequenceNumberVector = responseBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                        const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                        if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                            throw new Error('Encrypted message has invalid sequence number');
+                        }
+                        lastKnownInboundSequenceNumber = sequenceNumber;
+                        const jsonRpcMessage = await decryptJsonRpcMessage(responseBuffer, state.sharedSecret);
+                        const responsePromise = jsonRpcResponsePromises[jsonRpcMessage.id];
+                        delete jsonRpcResponsePromises[jsonRpcMessage.id];
+                        responsePromise.resolve(jsonRpcMessage.result);
+                    } catch (e) {
+                        if (e instanceof SolanaMobileWalletAdapterProtocolError) {
+                            const responsePromise = jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            delete jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            responsePromise.reject(e);
+                        } else {
+                            throw e;
+                        }
+                    }
+                    break;
+                case 'hello_req_sent': {
+                    const sharedSecret = await parseHelloRsp(
+                        responseBuffer,
+                        state.associationPublicKey,
+                        state.ecdhPrivateKey,
+                    );
+                    const sessionPropertiesBuffer = responseBuffer.slice(ENCODED_PUBLIC_KEY_LENGTH_BYTES);
+                    const sessionProperties = sessionPropertiesBuffer.byteLength !== 0 
+                        ? await (async () => {
+                            const sequenceNumberVector = sessionPropertiesBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                            const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                            if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                                throw new Error('Encrypted message has invalid sequence number');
+                            }
+                            lastKnownInboundSequenceNumber = sequenceNumber;
+                            return parseSessionProps(sessionPropertiesBuffer, sharedSecret);
+                        })() : <SessionProperties> { protocol_version: 'legacy' };
+                    state = { __type: 'connected', sharedSecret, sessionProperties };
+                    const wallet = createMobileWalletProxy(sessionProperties.protocol_version,
+                        async (method, params) => {
+                            const id = nextJsonRpcMessageId++;
+                            socket.send(
+                                await encryptJsonRpcMessage(
+                                    {
+                                        id,
+                                        jsonrpc: '2.0' as const,
+                                        method,
+                                        params: params ?? {},
+                                    }, 
+                                    sharedSecret,
+                                ),
+                            );
+                            return new Promise((resolve, reject) => {
+                                jsonRpcResponsePromises[id] = {
+                                    resolve(result) {
+                                        switch (method) {
+                                            case 'authorize':
+                                            case 'reauthorize': {
+                                                const { wallet_uri_base } = result as Awaited<
+                                                    ReturnType<MobileWallet['authorize' | 'reauthorize']>
+                                                >;
+                                                if (wallet_uri_base != null) {
+                                                    try {
+                                                        assertSecureEndpointSpecificURI(wallet_uri_base);
+                                                    } catch (e) {
+                                                        reject(e);
+                                                        return;
+                                                    }
+                                                }
+                                                break;
+                                            }
+                                        }
+                                        resolve(result);
+                                    },
+                                    reject,
+                                };
+                            });
+                        })
+                    try {
+                        resolve(await callback(new Proxy(wallet as RemoteMobileWallet, {
+                            get<TMethodName extends keyof RemoteMobileWallet>(target: RemoteMobileWallet, p: TMethodName) {
+                                if (p == 'terminateSession') {
+                                    return async function () {
+                                        disposeSocket();
+                                        socket.close();
+                                        return;
+                                    };
+                                } else return target[p];
+                            },
+                        })))
+                    } catch (e) {
+                        reject(e);
+                    }
+                    break;
+                }
+            }
+        };
+        let disposeSocket: () => void;
+        let retryWaitTimeoutId: number;
+        const attemptSocketConnection = () => {
+            if (disposeSocket) {
+                disposeSocket();
+            }
+            state = { __type: 'connecting', associationKeypair };
+            if (connectionStartTime === undefined) {
+                connectionStartTime = Date.now();
+            }
+            socket = new WebSocket(websocketURL, [WEBSOCKET_PROTOCOL]);
+            socket.addEventListener('open', handleOpen);
+            socket.addEventListener('close', handleClose);
+            socket.addEventListener('error', handleError);
+            socket.addEventListener('message', handleMessage);
+            disposeSocket = () => {
+                window.clearTimeout(retryWaitTimeoutId);
+                socket.removeEventListener('open', handleOpen);
+                socket.removeEventListener('close', handleClose);
+                socket.removeEventListener('error', handleError);
+                socket.removeEventListener('message', handleMessage);
+            };
+        };
+        attemptSocketConnection();
+    })};
+}

package/src/types.ts

@@ -0,0 +1,192 @@
+import type { TransactionVersion } from '@solana/web3.js';
+import type { SolanaSignInInput } from "@solana/wallet-standard";
+import type { IdentifierArray, IdentifierString, WalletAccount, WalletIcon } from '@wallet-standard/core';
+
+export type Account = Readonly<{
+    address: Base64EncodedAddress;
+    label?: string;
+    icon?: WalletIcon;
+    chains?: IdentifierArray;
+    features?: IdentifierArray;
+}> | WalletAccount;
+
+/**
+ * Properties that wallets may present to users when an app
+ * asks for authorization to execute privileged methods (see
+ * {@link PrivilegedMethods}).
+ */
+export type AppIdentity = Readonly<{
+    uri?: string;
+    icon?: string;
+    name?: string;
+}>;
+
+/**
+ * An ephemeral elliptic-curve keypair on the P-256 curve.
+ * This public key is used to create the association token.
+ * The private key is used during session establishment.
+ */
+export type AssociationKeypair = CryptoKeyPair;
+
+export type ProtocolVersion = 'v1' | 'legacy';
+
+export type SessionProperties = Readonly<{
+    protocol_version: ProtocolVersion;
+}>;
+
+/**
+ * The context returned from a wallet after having authorized a given
+ * account for use with a given application. You can cache this and
+ * use it later to invoke privileged methods.
+ */
+export type AuthorizationResult = Readonly<{
+    accounts: Account[];
+    auth_token: AuthToken;
+    wallet_uri_base: string;
+    sign_in_result?: SignInResult;
+}>;
+
+export type AuthToken = string;
+
+export type Base64EncodedAddress = string;
+
+type Base64EncodedSignature = string;
+
+type Base64EncodedMessage = string;
+
+type Base64EncodedSignedMessage = string;
+
+type Base64EncodedSignedTransaction = string;
+
+export type Base64EncodedTransaction = string;
+
+/**
+ * @deprecated Replaced by the 'chain' parameter, which adds multi-chain capability as per MWA 2.0 spec.
+ */
+export type Cluster = 'devnet' | 'testnet' | 'mainnet-beta';
+
+export type Chain = IdentifierString | Cluster;
+
+export type Finality = 'confirmed' | 'finalized' | 'processed';
+
+export type WalletAssociationConfig = Readonly<{
+    baseUri?: string;
+}>;
+
+export type RemoteWalletAssociationConfig = WalletAssociationConfig & Readonly<{
+    remoteHostAuthority: string;
+}>;
+
+export interface AuthorizeAPI {
+    /**
+     * @deprecated Replaced by updated authorize() method, which adds MWA 2.0 spec support.
+     */
+    authorize(params: { cluster: Cluster; identity: AppIdentity }): Promise<AuthorizationResult>;
+
+    authorize(params: { 
+        identity: AppIdentity;
+        chain?: Chain;
+        features?: IdentifierArray; 
+        addresses?: string[]; 
+        auth_token?: AuthToken; 
+        sign_in_payload?: SignInPayload;
+    }): Promise<AuthorizationResult>;
+}
+export interface CloneAuthorizationAPI {
+    cloneAuthorization(params: { auth_token: AuthToken }): Promise<Readonly<{ auth_token: AuthToken }>>;
+}
+export interface DeauthorizeAPI {
+    deauthorize(params: { auth_token: AuthToken }): Promise<Readonly<Record<string, never>>>;
+}
+
+export interface GetCapabilitiesAPI {
+    getCapabilities(): Promise<
+        Readonly<{
+            max_transactions_per_request: number;
+            max_messages_per_request: number;
+            supported_transaction_versions: ReadonlyArray<TransactionVersion>;
+            features: IdentifierArray;
+            /**
+             * @deprecated Replaced by features array.
+             */
+            supports_clone_authorization: boolean;
+            /**
+             * @deprecated Replaced by features array.
+             */
+            supports_sign_and_send_transactions: boolean;
+        }>
+    >;
+}
+export interface ReauthorizeAPI {
+    reauthorize(params: { auth_token: AuthToken; identity: AppIdentity }): Promise<AuthorizationResult>;
+}
+export interface SignMessagesAPI {
+    signMessages(params: {
+        addresses: Base64EncodedAddress[];
+        payloads: Base64EncodedMessage[];
+    }): Promise<Readonly<{ signed_payloads: Base64EncodedSignedMessage[] }>>;
+}
+export interface SignTransactionsAPI {
+    signTransactions(params: {
+        payloads: Base64EncodedTransaction[];
+    }): Promise<Readonly<{ signed_payloads: Base64EncodedSignedTransaction[] }>>;
+}
+export interface SignAndSendTransactionsAPI {
+    signAndSendTransactions(params: {
+        options?: Readonly<{
+            min_context_slot?: number;
+            commitment?: string;
+            skip_preflight?: boolean;
+            max_retries?: number;
+            wait_for_commitment_to_send_next_transaction?: boolean;
+        }>;
+        payloads: Base64EncodedTransaction[];
+    }): Promise<Readonly<{ signatures: Base64EncodedSignature[] }>>;
+}
+
+export interface MobileWallet
+    extends AuthorizeAPI,
+        CloneAuthorizationAPI,
+        DeauthorizeAPI,
+        GetCapabilitiesAPI,
+        ReauthorizeAPI,
+        SignMessagesAPI,
+        SignTransactionsAPI,
+        SignAndSendTransactionsAPI {}
+
+export interface TerminateSessionAPI {
+    terminateSession(): void
+}
+
+export interface RemoteMobileWallet
+    extends MobileWallet, TerminateSessionAPI {}
+
+// optional features
+export const SolanaSignTransactions = 'solana:signTransactions'
+export const SolanaCloneAuthorization = 'solana:cloneAuthorization'
+export const SolanaSignInWithSolana = 'solana:signInWithSolana'
+
+export type SignInPayload = Readonly<{
+    domain?: string;
+    address?: string;
+    statement?: string;
+    uri?: string;
+    version?: string;
+    chainId?: string;
+    nonce?: string;
+    issuedAt?: string;
+    expirationTime?: string;
+    notBefore?: string;
+    requestId?: string;
+    resources?: readonly string[];
+}> | SolanaSignInInput;
+
+export type SignInPayloadWithRequiredFields = Partial<SignInPayload> & 
+    Required<Pick<SignInPayload, 'domain' | 'address'>>
+
+export type SignInResult = Readonly<{
+    address: Base64EncodedAddress;
+    signed_message: Base64EncodedSignedMessage;
+    signature: Base64EncodedAddress;
+    signature_type?: string;
+}>;