zerowallet-adapter 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @zerowallet/adapter
+
+[![npm version](https://img.shields.io/npm/v/@zerowallet/adapter.svg)](https://www.npmjs.com/package/@zerowallet/adapter)
+
+Zero Wallet Adapter is the official Solana Wallet Adapter SDK for **Zero Wallet**, a self-custody mobile wallet native to Solana. 
+
+This adapter allows any Solana dApp using `@solana/wallet-adapter-react` to instantly connect to the Zero Wallet mobile app, enabling secure mobile transaction signing via deep links.
+
+---
+
+## What is Zero Wallet?
+Zero Wallet gives users true self-custody mobile access to Solana. Instead of storing private keys in browser extensions or adapter layers, **Zero Wallet keeps your keys safely encrypted on your mobile device**.
+
+When a user connects a dApp or signs a transaction, the `@zerowallet/adapter` passes the request to the Zero Wallet app via secure OS-level deep links (`zerowallet://`), entirely offloading the private key operations to the mobile application.
+
+## Installation
+
+Add the package via your preferred package manager:
+
+```bash
+npm install @zerowallet/adapter @solana/wallet-adapter-base @solana/web3.js
+# or
+yarn add @zerowallet/adapter @solana/wallet-adapter-base @solana/web3.js
+# or
+pnpm add @zerowallet/adapter @solana/wallet-adapter-base @solana/web3.js
+```
+
+## Quick Start
+
+Integrating Zero Wallet works exactly like integrating Phantom or Solflare in the standard Solana wallet adapter ecosystem.
+
+```tsx
+import React, { useMemo } from 'react';
+import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react';
+import { WalletModalProvider, WalletMultiButton } from '@solana/wallet-adapter-react-ui';
+import { ZeroWalletAdapter } from '@zerowallet/adapter';
+import '@solana/wallet-adapter-react-ui/styles.css';
+
+export const Wallet = ({ children }) => {
+    // Determine your network
+    const endpoint = 'https://api.mainnet-beta.solana.com';
+
+    const wallets = useMemo(
+        () => [
+            new ZeroWalletAdapter({
+                network: 'mainnet-beta', // or 'devnet', 'testnet'
+                // Optional: Hardcode the callback URL if you are not running in a browser environment
+                // callbackUrl: 'https://my-dapp.com/callback'
+            }),
+            // ... other wallets like new PhantomWalletAdapter()
+        ],
+        []
+    );
+
+    return (
+        <ConnectionProvider endpoint={endpoint}>
+            <WalletProvider wallets={wallets} autoConnect>
+                <WalletModalProvider>
+                    <WalletMultiButton />
+                    {children}
+                </WalletModalProvider>
+            </WalletProvider>
+        </ConnectionProvider>
+    );
+};
+```
+
+## Deep Link Flow
+
+When a user initiates an action from your dApp, the flow is as follows:
+
+1. **Adapter serializes payload**: The adapter encodes the payload (e.g., connection request, serialized transaction) into Base64.
+2. **Deep link dispatched**: The adapter calls `window.location.href = 'zerowallet://...'`.
+3. **OS opens Zero Wallet**: The mobile device triggers the Zero Wallet app and passes the payload.
+4. **User approves in app**: The user sees the transaction UI in Zero Wallet and taps "Approve" (signing securely with local keys).
+5. **App redirects back**: Zero Wallet constructs the callback URL passed by the dApp, appending the signed data or public key, and opens it.
+6. **Adapter resolves**: The adapter code waiting for the callback completes the Promise and hands the signed data back to the dApp.
+
+## Deep Link URL Scheme (For App Developers)
+
+If you are developing the mobile app side of Zero Wallet, you must intercept the `zerowallet://` scheme and handle these routes:
+
+### Connect
+```
+zerowallet://connect?callback=<callback_url>&id=<unique_id>
+```
+**Response Format (Appended to Callback URL):**
+* Success: `<callback_url>?id=<id>&status=approved&publicKey=<base58>`
+* Failure: `<callback_url>?id=<id>&status=rejected&error=User%20Cancelled`
+
+### Sign Transaction
+```
+zerowallet://sign?tx=<base64_serialized_tx>&callback=<callback_url>&id=<id>&network=<mainnet-beta|devnet>
+```
+**Response Format:**
+* Success: `<callback_url>?id=<id>&status=approved&signedTx=<base64_signed_tx>`
+
+### Sign All Transactions
+```
+zerowallet://signAll?txs=<base64_array_of_txs>&callback=<callback_url>&id=<id>
+```
+**Response Format:**
+* Success: `<callback_url>?id=<id>&status=approved&signedTxs=<base64_array_of_signed_txs>`
+
+### Sign Message
+```
+zerowallet://signMessage?msg=<base64_message>&callback=<callback_url>&id=<id>
+```
+**Response Format:**
+* Success: `<callback_url>?id=<id>&status=approved&signature=<base64_signature>`
+
+## Troubleshooting
+
+### Deep Links are not opening
+* Ensure you are testing on a mobile device where Zero Wallet is installed. Desktop browsers without an extension wrapper will trigger a timeout.
+* Check that your dApp's callback URL is valid and does not drop URL parameters on reload (often happens with heavily cached SPAs).
+
+### Callback times out
+* The default timeout is 120 seconds. If the user takes longer to approve within the app, the adapter will throw a `WalletTimeoutError`. Catch this error and prompt the user to try again.
+
+## License
+
+MIT

package/jest.config.js

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/tests/**/*.test.ts'],
+    moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "zerowallet-adapter",
+    "version": "1.0.0",
+    "description": "Zero Wallet Adapter SDK for Solana dApps",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "test": "jest",
+        "lint": "eslint src --ext .ts",
+        "clean": "rm -rf dist"
+    },
+    "keywords": [
+        "solana",
+        "wallet",
+        "adapter",
+        "zero",
+        "zerowallet"
+    ],
+    "author": "Zero Wallet",
+    "license": "MIT",
+    "peerDependencies": {
+        "@solana/wallet-adapter-base": "^0.9.23",
+        "@solana/web3.js": "^1.87.6"
+    },
+    "dependencies": {
+        "@solana/wallet-standard-features": "^1.1.0",
+        "@wallet-standard/core": "^1.0.3",
+        "@wallet-standard/features": "^1.0.3",
+        "@wallet-standard/wallet": "^1.0.1",
+        "bs58": "^5.0.0"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.12",
+        "@types/node": "^20.12.7",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.1.2",
+        "tsup": "^8.0.2",
+        "typescript": "^5.4.5"
+    }
+}

package/src/adapter.ts

@@ -0,0 +1,272 @@
+import {
+    BaseMessageSignerWalletAdapter,
+    EventEmitter,
+    WalletName,
+    WalletReadyState,
+    WalletSignTransactionError,
+    WalletSignMessageError,
+    WalletConnectionError,
+    WalletDisconnectedError,
+    WalletTimeoutError
+} from '@solana/wallet-adapter-base';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+import {
+    ZeroWalletAdapterConfig,
+    ConnectCallbackParams,
+    SignCallbackParams
+} from './types';
+import {
+    ZeroWalletNotInstalledError,
+    ZeroWalletConnectionError,
+    ZeroWalletUserRejectionError,
+    ZeroWalletSignTransactionError,
+    ZeroWalletSignMessageError,
+    ZeroWalletTimeoutError
+} from './errors';
+import {
+    buildConnectUrl,
+    buildSignMessageUrl,
+    buildSignTransactionUrl,
+    buildSignAllUrl,
+    isMobile,
+    isZeroWalletInstalled,
+    openDeepLink,
+    waitForCallback,
+    parseCallbackParams
+} from './deeplink';
+import {
+    generateCallbackId,
+    serializeTransaction,
+    deserializeTransaction,
+    serializeMessage,
+    deserializeSignature
+} from './utils';
+import bs58 from 'bs58';
+
+export const ZeroWalletName = 'Zero Wallet' as WalletName<'Zero Wallet'>;
+
+// Simple clean SVG icon base64 encoded
+export const ZeroWalletIcon = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJibGFjayIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PHBhdGggZD0iTTE2LjUgNy41QzE2Ljc1IDcuNSA5IDIwIDkuNSAyMEw3LjUgMTYuNUM3LjI1IDE2LjUgMTUgNCAxNC41IDRMMTYuNSA3LjVaIiBmaWxsPSJibGFjayIvPjwvc3ZnPg==';
+
+export interface ZeroWalletAdapterEvents {
+    connect(publicKey: PublicKey): void;
+    disconnect(): void;
+    error(error: any): void;
+}
+
+export class ZeroWalletAdapter extends BaseMessageSignerWalletAdapter {
+    name = ZeroWalletName;
+    url = 'https://zerowallet.app';
+    icon = ZeroWalletIcon;
+    supportedTransactionVersions = new Set(['legacy', 0] as const);
+
+    private _connecting: boolean;
+    private _wallet: any | null; // For standard injected wallet if applicable
+    private _publicKey: PublicKey | null;
+    private _readyState: WalletReadyState;
+    private _config: ZeroWalletAdapterConfig;
+
+    constructor(config: ZeroWalletAdapterConfig = {}) {
+        super();
+        this._config = {
+            network: config.network || 'mainnet-beta',
+            timeoutMs: config.timeoutMs || 120000,
+            callbackUrl: config.callbackUrl || (typeof window !== 'undefined' ? window.location.href : '')
+        };
+        this._connecting = false;
+        this._wallet = null;
+        this._publicKey = null;
+        this._readyState = WalletReadyState.Unsupported;
+
+        // Determine ready state
+        if (typeof window !== 'undefined') {
+            if (isMobile()) {
+                // On mobile we consider it installed/loadable via deep links
+                this._readyState = isZeroWalletInstalled() ? WalletReadyState.Installed : WalletReadyState.Loadable;
+            } else if (isZeroWalletInstalled()) {
+                this._readyState = WalletReadyState.Installed;
+            } else {
+                this._readyState = WalletReadyState.Loadable; // Fallback to QR / WalletConnect eventually
+            }
+        }
+
+        // Try to recover session from local storage
+        if (typeof window !== 'undefined') {
+            try {
+                const storedKey = localStorage.getItem('zerowallet_pubkey');
+                if (storedKey) {
+                    this._publicKey = new PublicKey(storedKey);
+                    // Emit connect on next tick so listeners have time to attach
+                    setTimeout(() => {
+                        if (this._publicKey) this.emit('connect', this._publicKey);
+                    }, 0);
+                }
+            } catch (e) {
+                // Ignore storage errors
+            }
+        }
+    }
+
+    get publicKey(): PublicKey | null {
+        return this._publicKey;
+    }
+
+    get connecting(): boolean {
+        return this._connecting;
+    }
+
+    get readyState(): WalletReadyState {
+        return this._readyState;
+    }
+
+    async connect(): Promise<void> {
+        try {
+            if (this.connected || this.connecting) return;
+
+            if (this._readyState !== WalletReadyState.Installed && this._readyState !== WalletReadyState.Loadable) {
+                throw new ZeroWalletNotInstalledError();
+            }
+
+            this._connecting = true;
+
+            const id = generateCallbackId();
+            const deepLinkUrl = buildConnectUrl(this._config.callbackUrl!, id);
+
+            openDeepLink(deepLinkUrl);
+
+            try {
+                // Wait for the app to redirect back with the params
+                const params = await waitForCallback(id, this._config.timeoutMs);
+                const parsed = parseCallbackParams(params) as ConnectCallbackParams;
+
+                if (parsed.status === 'rejected') {
+                    throw new ZeroWalletUserRejectionError(parsed.error || 'User rejected the connection request.');
+                }
+
+                if (!parsed.publicKey) {
+                    throw new ZeroWalletConnectionError('No public key returned from wallet.');
+                }
+
+                this._publicKey = new PublicKey(parsed.publicKey);
+
+                // Save session
+                if (typeof window !== 'undefined') {
+                    localStorage.setItem('zerowallet_pubkey', this._publicKey.toBase58());
+                }
+
+                this.emit('connect', this._publicKey);
+            } catch (e: any) {
+                if (e instanceof ZeroWalletTimeoutError) {
+                    throw new WalletTimeoutError(e?.message, e);
+                }
+                throw e; // rethrow mapping error
+            }
+        } catch (error: any) {
+            this.emit('error', error);
+            throw error;
+        } finally {
+            this._connecting = false;
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        this._publicKey = null;
+        if (typeof window !== 'undefined') {
+            localStorage.removeItem('zerowallet_pubkey');
+        }
+        this.emit('disconnect');
+    }
+
+    async signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T> {
+        try {
+            if (!this.connected) throw new WalletDisconnectedError();
+
+            const id = generateCallbackId();
+            const serialized = serializeTransaction(transaction);
+            const url = buildSignTransactionUrl(serialized, this._config.callbackUrl!, id, this._config.network);
+
+            openDeepLink(url);
+
+            const params = await waitForCallback(id, this._config.timeoutMs);
+            const parsed = parseCallbackParams(params) as SignCallbackParams;
+
+            if (parsed.status === 'rejected') {
+                throw new ZeroWalletUserRejectionError(parsed.error || 'User rejected signature.');
+            }
+
+            if (!parsed.signedTx) {
+                throw new ZeroWalletSignTransactionError('No signed transaction returned.');
+            }
+
+            return deserializeTransaction(parsed.signedTx) as T;
+        } catch (error: any) {
+            this.emit('error', error);
+            if (error instanceof ZeroWalletTimeoutError) {
+                throw new WalletTimeoutError(error?.message, error);
+            }
+            throw new WalletSignTransactionError(error?.message, error);
+        }
+    }
+
+    async signAllTransactions<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]> {
+        try {
+            if (!this.connected) throw new WalletDisconnectedError();
+
+            const id = generateCallbackId();
+            const serializedTxs = transactions.map((t: T) => serializeTransaction(t));
+            const url = buildSignAllUrl(serializedTxs, this._config.callbackUrl!, id, this._config.network);
+
+            openDeepLink(url);
+
+            const params = await waitForCallback(id, this._config.timeoutMs);
+            const parsed = parseCallbackParams(params) as SignCallbackParams;
+
+            if (parsed.status === 'rejected') {
+                throw new ZeroWalletUserRejectionError(parsed.error || 'User rejected signature.');
+            }
+
+            if (!parsed.signedTxs || parsed.signedTxs.length !== transactions.length) {
+                throw new ZeroWalletSignTransactionError('Invalid number of signed transactions returned.');
+            }
+
+            return parsed.signedTxs.map(t => deserializeTransaction(t) as T);
+        } catch (error: any) {
+            this.emit('error', error);
+            if (error instanceof ZeroWalletTimeoutError) {
+                throw new WalletTimeoutError(error?.message, error);
+            }
+            throw new WalletSignTransactionError(error?.message, error);
+        }
+    }
+
+    async signMessage(message: Uint8Array): Promise<Uint8Array> {
+        try {
+            if (!this.connected || !this.publicKey) throw new WalletDisconnectedError();
+
+            const id = generateCallbackId();
+            const serializedMessage = serializeMessage(message);
+            const url = buildSignMessageUrl(serializedMessage, this._config.callbackUrl!, id);
+
+            openDeepLink(url);
+
+            const params = await waitForCallback(id, this._config.timeoutMs);
+            const parsed = parseCallbackParams(params) as SignCallbackParams;
+
+            if (parsed.status === 'rejected') {
+                throw new ZeroWalletUserRejectionError(parsed.error || 'User rejected signature.');
+            }
+
+            if (!parsed.signature) {
+                throw new ZeroWalletSignMessageError('No signature returned.');
+            }
+
+            return deserializeSignature(parsed.signature);
+        } catch (error: any) {
+            this.emit('error', error);
+            if (error instanceof ZeroWalletTimeoutError) {
+                throw new WalletTimeoutError(error?.message, error);
+            }
+            throw new WalletSignMessageError(error?.message, error);
+        }
+    }
+}

package/src/deeplink.ts

@@ -0,0 +1,131 @@
+import { ZeroWalletTimeoutError } from './errors';
+import { ConnectCallbackParams, SignCallbackParams } from './types';
+import { generateCallbackId, isMobileDevice } from './utils';
+
+const ZERO_WALLET_SCHEME = 'zerowallet://';
+
+/**
+ * Builds the URL to connect to the Zero Wallet mobile app deep link.
+ */
+export function buildConnectUrl(callbackUrl: string, id: string): string {
+    return `${ZERO_WALLET_SCHEME}connect?callback=${encodeURIComponent(callbackUrl)}&id=${id}`;
+}
+
+/**
+ * Builds the deep link URL to request signing a single transaction.
+ */
+export function buildSignTransactionUrl(serializedTxBase64: string, callbackUrl: string, id: string, network: string = 'mainnet-beta'): string {
+    return `${ZERO_WALLET_SCHEME}sign?tx=${encodeURIComponent(serializedTxBase64)}&callback=${encodeURIComponent(callbackUrl)}&id=${id}&network=${network}`;
+}
+
+/**
+ * Builds the deep link URL to request signing multiple transactions.
+ */
+export function buildSignAllUrl(serializedTxsBase64: string[], callbackUrl: string, id: string, network: string = 'mainnet-beta'): string {
+    const serializedPayload = JSON.stringify(serializedTxsBase64); // JSON array of base64 strings
+    return `${ZERO_WALLET_SCHEME}signAll?txs=${encodeURIComponent(serializedPayload)}&callback=${encodeURIComponent(callbackUrl)}&id=${id}&network=${network}`;
+}
+
+/**
+ * Builds the deep link URL to request signing a raw message.
+ */
+export function buildSignMessageUrl(messageBase64: string, callbackUrl: string, id: string): string {
+    return `${ZERO_WALLET_SCHEME}signMessage?msg=${encodeURIComponent(messageBase64)}&callback=${encodeURIComponent(callbackUrl)}&id=${id}`;
+}
+
+/**
+ * Attempts to open the deep link using window.location.href.
+ */
+export function openDeepLink(url: string): void {
+    if (typeof window !== 'undefined') {
+        window.location.href = url;
+    }
+}
+
+/**
+ * Detects if the current user agent is mobile.
+ */
+export function isMobile(): boolean {
+    return isMobileDevice();
+}
+
+/**
+ * Checks for the presence of the Zero Wallet browser extension (or injected provider wrapper if present).
+ * Currently always returns false conceptually via deep links, but standardizes the check.
+ */
+export function isZeroWalletInstalled(): boolean {
+    if (typeof window === 'undefined') return false;
+    return !!(window as any).zerowallet?.isZeroWallet;
+}
+
+/**
+ * Waits for a callback matching the provided request ID.
+ * Since redirect callbacks typically reload the page, if you are a SPA you must register this listener
+ * or catch it on boot in the adapter itself.
+ * 
+ * For in-app browser or local state preservation, we listen to the hashchange/search params.
+ */
+export function waitForCallback(
+    expectedId: string,
+    timeoutMs: number = 120000
+): Promise<URLSearchParams> {
+    return new Promise((resolve, reject) => {
+        let timeoutId: NodeJS.Timeout;
+
+        // Note: For deep links, true "waiting" like this only works if the dApp is in a container
+        // that handles the URL return without reloading, or uses a specific communication bridge.
+        // For external browsers, the return callback will act as a page navigation to the dApp's callback URL.
+        const checkUrl = () => {
+            if (typeof window === 'undefined') return;
+            const params = new URLSearchParams(window.location.search);
+            if (params.get('id') === expectedId) {
+                clearTimeout(timeoutId);
+                clearInterval(intervalId);
+                resolve(params);
+            }
+        };
+
+        const intervalId = setInterval(checkUrl, 1000); // Check every second
+        checkUrl(); // check initially
+
+        timeoutId = setTimeout(() => {
+            clearInterval(intervalId);
+            reject(new ZeroWalletTimeoutError('Deep link response timed out.'));
+        }, timeoutMs);
+    });
+}
+
+/**
+ * Parses callback URL SearchParams into typed parameters.
+ */
+export function parseCallbackParams(params: URLSearchParams): ConnectCallbackParams | SignCallbackParams {
+    const id = params.get('id') || '';
+    const status = (params.get('status') as 'approved' | 'rejected') || 'rejected';
+    const error = params.get('error') || undefined;
+
+    // Connect Params
+    const publicKey = params.get('publicKey') || undefined;
+
+    // Sign Params
+    const signedTx = params.get('signedTx') || undefined;
+    let signedTxs: string[] | undefined;
+    try {
+        const rawTxs = params.get('signedTxs');
+        if (rawTxs) {
+            signedTxs = JSON.parse(decodeURIComponent(rawTxs));
+        }
+    } catch (e) {
+        console.error('Failed to parse signedTxs array', e);
+    }
+    const signature = params.get('signature') || undefined;
+
+    return {
+        id,
+        status,
+        error,
+        publicKey,
+        signedTx,
+        signedTxs,
+        signature
+    };
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import { WalletError } from '@solana/wallet-adapter-base';
+
+export class ZeroWalletNotInstalledError extends WalletError {
+    name = 'ZeroWalletNotInstalledError';
+}
+
+export class ZeroWalletConnectionError extends WalletError {
+    name = 'ZeroWalletConnectionError';
+}
+
+export class ZeroWalletUserRejectionError extends WalletError {
+    name = 'ZeroWalletUserRejectionError';
+}
+
+export class ZeroWalletSignTransactionError extends WalletError {
+    name = 'ZeroWalletSignTransactionError';
+}
+
+export class ZeroWalletSignMessageError extends WalletError {
+    name = 'ZeroWalletSignMessageError';
+}
+
+export class ZeroWalletTimeoutError extends WalletError {
+    name = 'ZeroWalletTimeoutError';
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './adapter';
+export * from './deeplink';
+export * from './errors';
+export * from './types';
+export * from './utils';
+export * from './standard';

package/src/standard.ts

@@ -0,0 +1,172 @@
+import { SolanaSignAndSendTransactionFeature, SolanaSignAndSendTransactionMethod, SolanaSignMessageFeature, SolanaSignMessageMethod, SolanaSignTransactionFeature, SolanaSignTransactionMethod } from '@solana/wallet-standard-features';
+import { Wallet, WalletAccount, WalletIcon } from '@wallet-standard/core';
+import { ZeroWalletAdapter, ZeroWalletIcon, ZeroWalletName } from './adapter';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { StandardConnectFeature, StandardConnectMethod, StandardDisconnectFeature, StandardDisconnectMethod, StandardEventsFeature, StandardEventsListeners, StandardEventsNames, StandardEventsOnMethod } from '@wallet-standard/features';
+
+export interface ZeroWalletWindowStandard extends Window {
+    zerowallet?: {
+        isZeroWallet?: boolean;
+    };
+}
+
+export type ZeroWalletFeature = StandardConnectFeature &
+    StandardDisconnectFeature &
+    StandardEventsFeature &
+    SolanaSignTransactionFeature &
+    SolanaSignAndSendTransactionFeature &
+    SolanaSignMessageFeature;
+
+export class ZeroWalletStandardWallet implements Wallet {
+    readonly #adapter: ZeroWalletAdapter;
+    readonly #listeners: { [E in StandardEventsNames]?: StandardEventsListeners[E][] } = {};
+    readonly #version = '1.0.0' as const;
+
+    get version() {
+        return this.#version;
+    }
+
+    get name() {
+        return ZeroWalletName;
+    }
+
+    get icon(): WalletIcon {
+        return ZeroWalletIcon as WalletIcon;
+    }
+
+    get chains() {
+        return ['solana:mainnet', 'solana:devnet', 'solana:testnet'] as const;
+    }
+
+    get features(): ZeroWalletFeature {
+        return {
+            'standard:connect': {
+                version: '1.0.0',
+                connect: this.#connect,
+            },
+            'standard:disconnect': {
+                version: '1.0.0',
+                disconnect: this.#disconnect,
+            },
+            'standard:events': {
+                version: '1.0.0',
+                on: this.#on,
+            },
+            'solana:signTransaction': {
+                version: '1.0.0',
+                supportedTransactionVersions: ['legacy', 0],
+                signTransaction: this.#signTransaction,
+            },
+            'solana:signAndSendTransaction': {
+                version: '1.0.0',
+                supportedTransactionVersions: ['legacy', 0],
+                signAndSendTransaction: this.#signAndSendTransaction,
+            },
+            'solana:signMessage': {
+                version: '1.0.0',
+                signMessage: this.#signMessage,
+            },
+        };
+    }
+
+    get accounts() {
+        return this.#adapter.publicKey ? [new ZeroWalletStandardAccount(this.#adapter.publicKey)] : [];
+    }
+
+    constructor(adapter: ZeroWalletAdapter) {
+        this.#adapter = adapter;
+        this.#adapter.on('connect', this.#emit.bind(this, 'change', { accounts: this.accounts }));
+        this.#adapter.on('disconnect', this.#emit.bind(this, 'change', { accounts: this.accounts }));
+    }
+
+    #connect: StandardConnectMethod = async ({ silent } = {}) => {
+        if (!this.#adapter.connected) {
+            await this.#adapter.connect();
+        }
+        return { accounts: this.accounts };
+    };
+
+    #disconnect: StandardDisconnectMethod = async () => {
+        await this.#adapter.disconnect();
+    };
+
+    #on: StandardEventsOnMethod = (event, listener) => {
+        this.#listeners[event]?.push(listener) || (this.#listeners[event] = [listener]);
+        return (): void => this.#off(event, listener);
+    };
+
+    #emit<E extends StandardEventsNames>(event: E, ...args: Parameters<StandardEventsListeners[E]>): void {
+        // eslint-disable-next-line prefer-spread
+        this.#listeners[event]?.forEach((listener) => listener.apply(null, args));
+    }
+
+    #off<E extends StandardEventsNames>(event: E, listener: StandardEventsListeners[E]): void {
+        this.#listeners[event] = this.#listeners[event]?.filter((existingListener) => listener !== existingListener);
+    }
+
+    #signTransaction: SolanaSignTransactionMethod = async (...inputs) => {
+        if (!this.#adapter.connected) throw new Error('Not connected');
+        const signedTxs = [];
+        for (const input of inputs) {
+            const tx = Transaction.from(input.transaction); // Using legacy for simplicity in standard adapter interface as fallback
+            const signed = await this.#adapter.signTransaction(tx);
+            signedTxs.push({ signedTransaction: signed.serialize() });
+        }
+        return signedTxs;
+    };
+
+    #signAndSendTransaction: SolanaSignAndSendTransactionMethod = async (...inputs) => {
+        if (!this.#adapter.connected) throw new Error('Not connected');
+        throw new Error('signAndSendTransaction not fully implemented in standard adapter wrapper for Zero Wallet deep link yet.');
+    };
+
+    #signMessage: SolanaSignMessageMethod = async (...inputs) => {
+        if (!this.#adapter.connected) throw new Error('Not connected');
+        const signatures = [];
+        for (const input of inputs) {
+            const signature = await this.#adapter.signMessage(input.message);
+            signatures.push({ signedMessage: input.message, signature });
+        }
+        return signatures;
+    };
+}
+
+export class ZeroWalletStandardAccount implements WalletAccount {
+    readonly #publicKey: PublicKey;
+
+    get address() {
+        return this.#publicKey.toBase58();
+    }
+
+    get publicKey() {
+        return this.#publicKey.toBytes();
+    }
+
+    get chains() {
+        return ['solana:mainnet', 'solana:devnet', 'solana:testnet'] as const;
+    }
+
+    get features() {
+        return ['solana:signTransaction', 'solana:signAndSendTransaction', 'solana:signMessage'] as const;
+    }
+
+    constructor(publicKey: PublicKey) {
+        this.#publicKey = publicKey;
+    }
+}
+
+/**
+ * Registers the ZeroWallet in the Wallet Standard modal ecosystem.
+ */
+export function registerWalletStandard(adapter: ZeroWalletAdapter): void {
+    if (typeof window === 'undefined') return;
+
+    try {
+        const wallet = new ZeroWalletStandardWallet(adapter);
+        const { registerWallet } = require('@wallet-standard/wallet') as typeof import('@wallet-standard/wallet');
+        registerWallet(wallet);
+    } catch (error) {
+        console.error('ZeroWallet: Failed to register wallet standard', error);
+    }
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+export interface ZeroWalletWindow extends Window {
+    zerowallet?: {
+        isZeroWallet?: boolean;
+    };
+}
+
+export interface ConnectResponse {
+    publicKey: string;
+}
+
+export interface SignTransactionResponse {
+    signedTransaction: string;
+}
+
+export interface SignAllTransactionsResponse {
+    signedTransactions: string[];
+}
+
+export interface SignMessageResponse {
+    signature: string;
+}
+
+// Params attached to the callback URL by the mobile app
+export interface DeepLinkCallbackParams {
+    id: string;
+    status: 'approved' | 'rejected';
+    error?: string; // Set when status is rejected
+}
+
+export interface ConnectCallbackParams extends DeepLinkCallbackParams {
+    publicKey?: string; // Base58 encoded pulic key string (on success)
+}
+
+export interface SignCallbackParams extends DeepLinkCallbackParams {
+    signedTx?: string; // Base64 encoded signed transaction
+    signedTxs?: string[]; // Array of base64 encoded signed transactions
+    signature?: string; // Base64 encoded signature
+}
+
+export interface ZeroWalletAdapterConfig {
+    /**
+     * Network cluster.
+     */
+    network?: 'mainnet-beta' | 'devnet' | 'testnet';
+    /**
+     * Timeout for deep link callbacks in milliseconds. Defaults to 120000 (2 minutes).
+     */
+    timeoutMs?: number;
+    /**
+     * The callback scheme/host your dApp is listening on. e.g., "my-dapp://callback"
+     */
+    callbackUrl?: string;
+}

package/src/utils.ts

@@ -0,0 +1,92 @@
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+/**
+ * Serializes a transaction (legacy or versioned) to a base64 encoded string.
+ */
+export function serializeTransaction(tx: Transaction | VersionedTransaction): string {
+    if ('version' in tx) {
+        // Versioned transaction
+        return encodeBase64(tx.serialize());
+    } else {
+        // Legacy transaction.
+        // Needs recentBlockhash and feePayer before serialize, but typically dApp provides this
+        // Use requireAllSignatures: false if the wallet still needs to add signatures
+        return encodeBase64(tx.serialize({ requireAllSignatures: false }));
+    }
+}
+
+/**
+ * Deserializes a base64 encoded transaction back into a Transaction or VersionedTransaction.
+ */
+export function deserializeTransaction(serializedTxBase64: string): Transaction | VersionedTransaction {
+    const buffer = decodeBase64(serializedTxBase64);
+    try {
+        // Attempt versioned transaction parsing
+        return VersionedTransaction.deserialize(buffer);
+    } catch (e) {
+        // Fallback to legacy
+        return Transaction.from(buffer);
+    }
+}
+
+/**
+ * Serializes a raw message Uint8Array to base64.
+ */
+export function serializeMessage(message: Uint8Array): string {
+    return encodeBase64(message);
+}
+
+/**
+ * Deserializes a base64 signature back to Uint8Array.
+ */
+export function deserializeSignature(signatureBase64: string): Uint8Array {
+    return decodeBase64(signatureBase64);
+}
+
+/**
+ * Converts a Uint8Array to a base64 string.
+ */
+export function encodeBase64(data: Uint8Array): string {
+    if (typeof btoa !== 'undefined') {
+        const binString = Array.from(data, (byte) => String.fromCharCode(byte)).join('');
+        return btoa(binString);
+    }
+    return Buffer.from(data).toString('base64');
+}
+
+/**
+ * Converts a base64 string to a Uint8Array.
+ */
+export function decodeBase64(data: string): Uint8Array {
+    if (typeof atob !== 'undefined') {
+        const binString = atob(data);
+        return new Uint8Array(binString.split('').map((char) => char.charCodeAt(0)));
+    }
+    return new Uint8Array(Buffer.from(data, 'base64'));
+}
+
+/**
+ * Generates a unique 16 character hex string for tracking deep link requests.
+ */
+export function generateCallbackId(): string {
+    return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+}
+
+/**
+ * Detects if the current environment is a mobile device via User-Agent.
+ */
+export function isMobileDevice(): boolean {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) return false;
+    return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+}
+
+export function isIOS(): boolean {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) return false;
+    return /iPhone|iPad|iPod/i.test(navigator.userAgent);
+}
+
+export function isAndroid(): boolean {
+    if (typeof navigator === 'undefined' || !navigator.userAgent) return false;
+    return /Android/i.test(navigator.userAgent);
+}

package/tests/adapter.test.ts

@@ -0,0 +1,142 @@
+import { ZeroWalletAdapter } from '../src/adapter';
+import { WalletReadyState, WalletTimeoutError, WalletDisconnectedError } from '@solana/wallet-adapter-base';
+import * as deeplink from '../src/deeplink';
+import { ZeroWalletTimeoutError, ZeroWalletUserRejectionError, ZeroWalletNotInstalledError } from '../src/errors';
+import { Transaction, PublicKey, SystemProgram } from '@solana/web3.js';
+
+// Mock the openDeepLink function
+jest.mock('../src/deeplink', () => ({
+    ...jest.requireActual('../src/deeplink'),
+    openDeepLink: jest.fn(),
+    waitForCallback: jest.fn(),
+    isMobile: jest.fn(),
+    isZeroWalletInstalled: jest.fn()
+}));
+
+describe('ZeroWalletAdapter', () => {
+    let adapter: ZeroWalletAdapter;
+    const mockCallbackUrl = 'https://tester.com/callback';
+
+    beforeEach(() => {
+        // Reset mocks
+        jest.clearAllMocks();
+
+        // Default to mobile environment for testing deep links
+        (deeplink.isMobile as jest.Mock).mockReturnValue(true);
+        (deeplink.isZeroWalletInstalled as jest.Mock).mockReturnValue(true);
+
+        adapter = new ZeroWalletAdapter({ callbackUrl: mockCallbackUrl, timeoutMs: 1000 });
+    });
+
+    describe('readyState', () => {
+        it('returns Installed on mobile if zero wallet is detected', () => {
+            expect(adapter.readyState).toBe(WalletReadyState.Installed);
+        });
+
+        it('returns Loadable on desktop if not explicitly installed', () => {
+            (deeplink.isMobile as jest.Mock).mockReturnValue(false);
+            (deeplink.isZeroWalletInstalled as jest.Mock).mockReturnValue(false);
+
+            // Re-instantiate to pickup mocked values
+            adapter = new ZeroWalletAdapter();
+            expect(adapter.readyState).toBe(WalletReadyState.Loadable);
+        });
+    });
+
+    describe('connect()', () => {
+        it('opens deep link and resolves with public key on approval', async () => {
+            const pubKeyString = '11111111111111111111111111111111';
+
+            // Mock waiting for callback returning approved status
+            const params = new URLSearchParams(`?id=mockid&status=approved&publicKey=${pubKeyString}`);
+            (deeplink.waitForCallback as jest.Mock).mockResolvedValueOnce(params);
+
+            const connectPromise = adapter.connect();
+
+            expect(adapter.connecting).toBe(true);
+            expect(deeplink.openDeepLink).toHaveBeenCalled();
+
+            await connectPromise;
+
+            expect(adapter.connecting).toBe(false);
+            expect(adapter.connected).toBe(true);
+            expect(adapter.publicKey?.toBase58()).toBe(pubKeyString);
+        });
+
+        it('rejects when user cancels', async () => {
+            const params = new URLSearchParams(`?id=mockid&status=rejected&error=User%20cancelled`);
+            (deeplink.waitForCallback as jest.Mock).mockResolvedValueOnce(params);
+
+            await expect(adapter.connect()).rejects.toThrow(ZeroWalletUserRejectionError);
+            expect(adapter.connected).toBe(false);
+        });
+
+        it('throws WalletTimeoutError on timeout', async () => {
+            (deeplink.waitForCallback as jest.Mock).mockRejectedValueOnce(new ZeroWalletTimeoutError());
+
+            await expect(adapter.connect()).rejects.toThrow(WalletTimeoutError);
+        });
+    });
+
+    describe('signTransaction()', () => {
+        let tx: Transaction;
+
+        beforeEach(async () => {
+            // Must be connected to sign
+            (deeplink.waitForCallback as jest.Mock).mockResolvedValueOnce(
+                new URLSearchParams(`?status=approved&publicKey=11111111111111111111111111111111`)
+            );
+            await adapter.connect();
+
+            tx = new Transaction();
+            tx.add(SystemProgram.transfer({
+                fromPubkey: adapter.publicKey!,
+                toPubkey: new PublicKey('22222222222222222222222222222222'),
+                lamports: 1000,
+            }));
+            tx.recentBlockhash = '33333333333333333333333333333333';
+            tx.feePayer = adapter.publicKey!;
+        });
+
+        it('serializes tx, sends deep link, returns signed tx', async () => {
+            // Mock signing response
+            const signedSerialized = (() => {
+                const signedTx = new Transaction();
+                // Just use same tx for mocking
+                signedTx.add(SystemProgram.transfer({
+                    fromPubkey: adapter.publicKey!,
+                    toPubkey: new PublicKey('22222222222222222222222222222222'),
+                    lamports: 1000,
+                }));
+                signedTx.recentBlockhash = '33333333333333333333333333333333';
+                signedTx.feePayer = adapter.publicKey!;
+                // Requires signatures array fake
+                signedTx.signatures.push({ publicKey: adapter.publicKey!, signature: Buffer.alloc(64) });
+                return signedTx.serialize({ requireAllSignatures: false, verifySignatures: false }).toString('base64');
+            })();
+
+            const params = new URLSearchParams(`?status=approved&signedTx=${encodeURIComponent(signedSerialized)}`);
+            (deeplink.waitForCallback as jest.Mock).mockResolvedValueOnce(params);
+
+            const result = await adapter.signTransaction(tx);
+
+            expect(result).toBeInstanceOf(Transaction);
+            expect(deeplink.openDeepLink).toHaveBeenCalledTimes(2); // once for connect, once for sign
+        });
+    });
+
+    describe('disconnect()', () => {
+        it('clears state and emits event', async () => {
+            (deeplink.waitForCallback as jest.Mock).mockResolvedValueOnce(
+                new URLSearchParams(`?status=approved&publicKey=11111111111111111111111111111111`)
+            );
+            await adapter.connect();
+            expect(adapter.connected).toBe(true);
+
+            await adapter.disconnect();
+
+            expect(adapter.connected).toBe(false);
+            expect(adapter.publicKey).toBeNull();
+        });
+    });
+});

package/tests/deeplink.test.ts

@@ -0,0 +1,103 @@
+import {
+    buildConnectUrl,
+    buildSignTransactionUrl,
+    buildSignAllUrl,
+    buildSignMessageUrl,
+    waitForCallback,
+    isMobile,
+    parseCallbackParams
+} from '../src/deeplink';
+import { ZeroWalletTimeoutError } from '../src/errors';
+
+describe('deeplink', () => {
+    const callbackUrl = 'https://my-dapp.com/callback';
+    const id = '1234567890abcdef';
+
+    describe('URL Builders', () => {
+        it('buildConnectUrl returns correct URL format', () => {
+            const url = buildConnectUrl(callbackUrl, id);
+            expect(url).toBe(`zerowallet://connect?callback=https%3A%2F%2Fmy-dapp.com%2Fcallback&id=${id}`);
+        });
+
+        it('buildSignTransactionUrl encodes transaction correctly', () => {
+            const txBase64 = 'aGVsbG8='; // hello
+            const url = buildSignTransactionUrl(txBase64, callbackUrl, id, 'devnet');
+            expect(url).toBe(`zerowallet://sign?tx=aGVsbG8%3D&callback=https%3A%2F%2Fmy-dapp.com%2Fcallback&id=${id}&network=devnet`);
+        });
+
+        it('buildSignAllUrl encodes array correctly', () => {
+            const txs = ['tx1', 'tx2'];
+            const url = buildSignAllUrl(txs, callbackUrl, id);
+            const expectedPayload = encodeURIComponent(JSON.stringify(txs));
+            expect(url).toBe(`zerowallet://signAll?txs=${expectedPayload}&callback=https%3A%2F%2Fmy-dapp.com%2Fcallback&id=${id}&network=mainnet-beta`);
+        });
+
+        it('buildSignMessageUrl encodes message correctly', () => {
+            const url = buildSignMessageUrl('bXNn', callbackUrl, id);
+            expect(url).toBe(`zerowallet://signMessage?msg=bXNn&callback=https%3A%2F%2Fmy-dapp.com%2Fcallback&id=${id}`);
+        });
+    });
+
+    describe('waitForCallback', () => {
+        let originalWindow: any;
+
+        beforeEach(() => {
+            jest.useFakeTimers();
+            originalWindow = global.window;
+            global.window = {
+                location: {
+                    search: ''
+                }
+            } as any;
+        });
+
+        afterEach(() => {
+            jest.useRealTimers();
+            global.window = originalWindow;
+        });
+
+        it('resolves when callback received', async () => {
+            const waitPromise = waitForCallback(id, 5000);
+
+            // Advance time a bit and set the window search
+            jest.advanceTimersByTime(1500);
+            global.window.location.search = `?id=${id}&status=approved`;
+
+            // trigger next check
+            jest.advanceTimersByTime(1000);
+
+            const params = await waitPromise;
+            expect(params.get('id')).toBe(id);
+            expect(params.get('status')).toBe('approved');
+        });
+
+        it('rejects on timeout', async () => {
+            const waitPromise = waitForCallback(id, 2000);
+
+            // Advance time past timeout without ever setting window search
+            jest.advanceTimersByTime(2500);
+
+            await expect(waitPromise).rejects.toThrow(ZeroWalletTimeoutError);
+        });
+    });
+
+    describe('parseCallbackParams', () => {
+        it('parses connect approved', () => {
+            const params = new URLSearchParams(`?id=${id}&status=approved&publicKey=1111`);
+            const parsed = parseCallbackParams(params);
+
+            expect(parsed.id).toBe(id);
+            expect(parsed.status).toBe('approved');
+            expect(parsed.publicKey).toBe('1111');
+        });
+
+        it('parses rejection', () => {
+            const params = new URLSearchParams(`?id=${id}&status=rejected&error=User%20cancelled`);
+            const parsed = parseCallbackParams(params);
+
+            expect(parsed.id).toBe(id);
+            expect(parsed.status).toBe('rejected');
+            expect(parsed.error).toBe('User cancelled');
+        });
+    });
+});

package/tests/utils.test.ts

@@ -0,0 +1,68 @@
+import { serializeTransaction, deserializeTransaction, encodeBase64, decodeBase64, isMobileDevice, isIOS, isAndroid } from '../src/utils';
+import { Transaction, PublicKey, SystemProgram } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+describe('utils', () => {
+
+    describe('Base64 Encoding/Decoding', () => {
+        it('encodeBase64 and decodeBase64 are inverse operations', () => {
+            const originalData = new Uint8Array([1, 2, 3, 255, 128, 0, 42]);
+            const encoded = encodeBase64(originalData);
+            expect(typeof encoded).toBe('string');
+
+            const decoded = decodeBase64(encoded);
+            expect(decoded).toEqual(originalData);
+        });
+
+        it('handles strings properly', () => {
+            const str = 'hello world';
+            const bytes = new Uint8Array(Buffer.from(str));
+            const encoded = encodeBase64(bytes);
+            expect(encoded).toBe('aGVsbG8gd29ybGQ=');
+
+            const decoded = decodeBase64(encoded);
+            expect(Buffer.from(decoded).toString()).toBe(str);
+        });
+    });
+
+    describe('Transaction Serialization', () => {
+        it('serializeTransaction generates a base64 string for legacy tx', () => {
+            const tx = new Transaction();
+            tx.add(
+                SystemProgram.transfer({
+                    fromPubkey: new PublicKey('11111111111111111111111111111111'),
+                    toPubkey: new PublicKey('22222222222222222222222222222222'),
+                    lamports: 1000,
+                })
+            );
+            tx.recentBlockhash = '11111111111111111111111111111111';
+            tx.feePayer = new PublicKey('11111111111111111111111111111111');
+
+            const serialized = serializeTransaction(tx);
+            expect(typeof serialized).toBe('string');
+            expect(serialized.length).toBeGreaterThan(0);
+        });
+
+        it('deserializeTransaction round-trips correctly for legacy tx', () => {
+            const tx = new Transaction();
+            tx.add(
+                SystemProgram.transfer({
+                    fromPubkey: new PublicKey('11111111111111111111111111111111'),
+                    toPubkey: new PublicKey('22222222222222222222222222222222'),
+                    lamports: 5000,
+                })
+            );
+            tx.recentBlockhash = '11111111111111111111111111111111';
+            tx.feePayer = new PublicKey('11111111111111111111111111111111');
+
+            const serialized = serializeTransaction(tx);
+            const deserialized = deserializeTransaction(serialized) as Transaction;
+
+            expect(deserialized).toBeInstanceOf(Transaction);
+            expect(deserialized.feePayer?.toBase58()).toBe(tx.feePayer?.toBase58());
+            expect(deserialized.recentBlockhash).toBe(tx.recentBlockhash);
+            expect(deserialized.instructions.length).toBe(1);
+        });
+    });
+
+});

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "ESNext",
+        "lib": [
+            "ES2020",
+            "DOM",
+            "DOM.Iterable"
+        ],
+        "declaration": true,
+        "declarationMap": true,
+        "moduleResolution": "node",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "tests"
+    ]
+}

package/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['cjs', 'esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    treeshake: true,
+    minify: process.env.NODE_ENV === 'production',
+    external: [
+        '@solana/wallet-adapter-base',
+        '@solana/web3.js',
+        '@solana/wallet-standard-features',
+        '@wallet-standard/core',
+        '@wallet-standard/features',
+        '@wallet-standard/wallet'
+    ],
+});