Provider Interface

interface ProviderInterface extends ProviderEventEmitter {
  /** Send JSON-RPC request to the wallet */
  request(args: RequestArguments): Promise<unknown>;
  /** Disconnect from the wallet and clear session */
  disconnect(): Promise<void>;
  /** Emit provider events */
  emit<K extends keyof ProviderEventMap>(
    event: K, 
    ...args: [ProviderEventMap[K]]
  ): boolean;
  /** Listen for provider events */
  on<K extends keyof ProviderEventMap>(
    event: K, 
    listener: (_: ProviderEventMap[K]) => void
  ): this;
  /** Identifier property for Coinbase Wallet */
  readonly isCoinbaseWallet: true;
}

interface RequestArguments {
  /** JSON-RPC method name */
  readonly method: string;
  /** Optional method parameters */
  readonly params?: readonly unknown[] | object;
}

/**
 * Request account access from the wallet
 * @returns Promise resolving to array of account addresses
 */
await provider.request({ 
  method: "eth_requestAccounts" 
}): Promise<string[]>;

/**
 * Disconnect from the wallet and clear all session data
 * @returns Promise that resolves when disconnection is complete
 */
await provider.disconnect(): Promise<void>;

import { createCoinbaseWalletSDK } from "@coinbase/wallet-sdk";

const sdk = createCoinbaseWalletSDK({
  appName: "Connection Example"
});
const provider = sdk.getProvider();

// Connect to wallet
try {
  const accounts = await provider.request({
    method: "eth_requestAccounts"
  });
  console.log("Connected accounts:", accounts);
} catch (error) {
  console.error("Connection failed:", error);
}

// Disconnect from wallet
await provider.disconnect();

/**
 * Send a transaction
 * @param params - Transaction parameters
 * @returns Transaction hash
 */
await provider.request({
  method: "eth_sendTransaction",
  params: [TransactionRequest]
}): Promise<string>;

/**
 * Send batch calls (Smart Wallet only)
 * @param params - Batch call parameters
 * @returns Batch call identifier
 */
await provider.request({
  method: "wallet_sendCalls",
  params: [SendCallsParams]
}): Promise<string>;

/**
 * Get batch calls status
 * @param params - Status request parameters
 * @returns Call status information
 */
await provider.request({
  method: "wallet_getCallsStatus",
  params: [GetCallsStatusParams]
}): Promise<CallsStatus>;

interface TransactionRequest {
  from: string;
  to?: string;
  value?: string;
  data?: string;
  gas?: string;
  gasPrice?: string;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
  nonce?: string;
}

interface SendCallsParams {
  /** Array of calls to execute in a batch */
  calls: Array<{
    /** Target contract address */
    to: string;
    /** Optional contract call data */
    data?: string;
    /** Optional ETH value to send with call */
    value?: string;
  }>;
  /** Address sending the batch calls */
  from: string;
}

interface GetCallsStatusParams {
  /** Batch identifier returned from wallet_sendCalls */
  batchId: string;
}

interface CallsStatus {
  /** Current status of the batch calls */
  status: 'PENDING' | 'CONFIRMED' | 'FAILED';
  /** Optional transaction hash when confirmed */
  transactionHash?: string;
  /** Optional error information when failed */
  error?: string;
}

// Send ETH transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [{
    from: accounts[0],
    to: "0x742d35Cc6634C0532925a3b8D186dFaedD9B6E3C",
    value: "0x38d7ea4c68000", // 0.001 ETH in wei
  }]
});

// Smart Wallet batch call
const batchId = await provider.request({
  method: "wallet_sendCalls",
  params: [{
    calls: [
      {
        to: "0x...",
        data: "0x...",
        value: "0x0"
      }
    ],
    from: accounts[0]
  }]
});

/**
 * Sign a message with personal_sign
 * @param params - [message, address]
 * @returns Signature string
 */
await provider.request({
  method: "personal_sign",
  params: [string, string]
}): Promise<string>;

/**
 * Sign typed data (EIP-712)
 * @param params - [address, typedData]
 * @returns Signature string
 */
await provider.request({
  method: "eth_signTypedData_v4",
  params: [string, TypedData]
}): Promise<string>;

// Sign a message
const message = "Hello from my dapp!";
const signature = await provider.request({
  method: "personal_sign",
  params: [message, accounts[0]]
});

// Sign typed data
const typedData = {
  types: {
    EIP712Domain: [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
      { name: "chainId", type: "uint256" }
    ],
    Person: [
      { name: "name", type: "string" },
      { name: "age", type: "uint256" }
    ]
  },
  primaryType: "Person",
  domain: {
    name: "My Dapp",
    version: "1",
    chainId: 1
  },
  message: {
    name: "Alice",
    age: 25
  }
};

const typedSignature = await provider.request({
  method: "eth_signTypedData_v4",
  params: [accounts[0], JSON.stringify(typedData)]
});

/**
 * Get current chain ID
 * @returns Hex string of chain ID
 */
await provider.request({ 
  method: "eth_chainId" 
}): Promise<string>;

/**
 * Get network version
 * @returns Network version number
 */
await provider.request({ 
  method: "net_version" 
}): Promise<number>;

// Get current chain
const chainId = await provider.request({
  method: "eth_chainId"
});
console.log("Current chain:", parseInt(chainId, 16));

// Get network version
const networkVersion = await provider.request({
  method: "net_version"
});
console.log("Network version:", networkVersion);

/**
 * @deprecated Use provider.request({ method: "eth_requestAccounts" }) instead
 */
await provider.enable(): Promise<string[]>;

interface ProviderRpcError extends Error {
  message: string;
  code: number;
  data?: unknown;
}

// Common error codes:
// 4001: User rejected the request
// 4100: Unauthorized
// 4200: Unsupported method
// -32602: Invalid params

try {
  const accounts = await provider.request({
    method: "eth_requestAccounts"
  });
} catch (error) {
  if (error.code === 4001) {
    console.log("User rejected connection");
  } else if (error.code === 4100) {
    console.log("Not authorized");
  } else {
    console.error("Unexpected error:", error);
  }
}

/**
 * Get injected Coinbase Wallet provider from browser environment
 * @param options - Constructor options with metadata and preferences
 * @returns Injected provider instance or undefined if not available
 */
function getCoinbaseInjectedProvider(
  options: ConstructorOptions
): ProviderInterface | undefined;

interface CBWindow {
  top: CBWindow;
  /** Standard Ethereum provider (may be Coinbase Wallet) */
  ethereum?: CBInjectedProvider;
  /** Legacy Coinbase Wallet extension provider */
  coinbaseWalletExtension?: CBInjectedProvider;
}

interface CBInjectedProvider extends ProviderInterface {
  /** Indicates if running in Coinbase Browser */
  isCoinbaseBrowser?: boolean;
  /** Set application metadata for injected provider */
  setAppInfo?: (
    appName: string,
    appLogoUrl: string | null,
    appChainIds: number[],
    preference: Preference
  ) => unknown;
}

import { getCoinbaseInjectedProvider } from "@coinbase/wallet-sdk";

// Try to get injected provider
const options = {
  metadata: {
    appName: "My Dapp",
    appLogoUrl: "https://example.com/logo.png",
    appChainIds: [1]
  },
  preference: {
    options: "all"
  }
};

const injectedProvider = getCoinbaseInjectedProvider(options);
if (injectedProvider) {
  console.log("Found injected Coinbase Wallet");
  // Use injected provider directly
  const accounts = await injectedProvider.request({
    method: "eth_requestAccounts"
  });
}

// Check if provider is Coinbase Wallet
if (provider.isCoinbaseWallet) {
  console.log("Using Coinbase Wallet");
}

// Check if provider is available in window
if (typeof window !== 'undefined' && window.ethereum?.isCoinbaseWallet) {
  console.log("Coinbase Wallet extension detected");
}

// Check for legacy extension provider
if (typeof window !== 'undefined' && window.coinbaseWalletExtension) {
  console.log("Legacy Coinbase Wallet extension detected");
}

/**
 * Validates request arguments and throws standardized errors for invalid requests
 * @param args - Request arguments to validate
 * @throws ProviderRpcError for invalid arguments or unsupported methods
 */
function checkErrorForInvalidRequestArgs(
  args: unknown
): asserts args is RequestArguments;

// Validate request before processing
try {
  checkErrorForInvalidRequestArgs(userProvidedArgs);
  // Args are valid, proceed with request
  const result = await provider.request(userProvidedArgs);
} catch (error) {
  // Handle validation error
  console.error("Invalid request arguments:", error.message);
}