# SDK library for mobile proving on Mina

Mina Wallet SDK should enable developers to connect their zkApps running on the browser with the mobile wallets.

## Supported platforms

- Phase 1: iOS (Safari), Android (Chrome)
- Phase 2: iOS, Android mobile apps

## Features

- Deep links to connect to the mobile wallet on mobile
- Connecting to the mobile wallet in the internal wallet browser
- Establishing and maintaining a connection with the wallet
- Injecting window.mina object to the browser

## Connection flow - mobile

flowchart TD
    A([zkApp Execution Environment on Mobile])
    A -->|Mobile Wallet| H([Mobile Wallet Installed?])
    H -->|Yes| J([Connect via Mobile Wallet])
    H -->|No| I([iOS App Store / Android Google Play]) -->|Deep Link to zkApp| J

## Connection flow - future stages with Desktop

flowchart TD
    A([zkApp Execution Environment])
    A -->|Desktop| C([Modal: Connect via Extension or Mobile]) -->|Extension Wallet| E([Extension Installed?])
    E -->|No| F([Chrome Store]) --> |Deep Link to zkApp| G([Connect via Extension])
    E -->|Yes| G
    C -->|Mobile Wallet| H([Mobile Wallet Installed?])
    H -->|Yes| J([Connect via Mobile Wallet])
    H -->|No| I([iOS App Store / Android Google Play]) -->|Deep Link to zkApp| J
    A -->|Mobile iOS/Android| K([Deep Link to Mobile Wallet]) --> H

## API

### MinaWalletProvider

MinaWalletProvider will be used as a provider in React next.js apps.

The `MinaWalletProvider` is a React context provider component that integrates the Mina Wallet SDK into React applications. It manages the connection state with the Mina wallet and provides the necessary context for child components to interact with the wallet and the Mina network. By using the `MinaWalletProvider`, developers can integrate Mina wallet functionalities into React applications with ease, allowing components to access and react to wallet state changes seamlessly.

#### Key Features

- **State Management**: Manages the connection state, including whether the wallet is connected or connecting, and provides access to the user's account and balance.
- **Event Handling**: Listens to and handles various events from the SDK and the provider, such as account changes and chain changes.
- **Context Provider**: Supplies the SDK instance and related state to child components via React context.
- **Read-Only Calls**: Supports read-only interactions with the Mina network when the wallet is not connected using GraphQL or BlockBerry API.
- **Debugging**: Offers optional debug logging to assist with development and troubleshooting.

#### Usage Example

To utilize the `MinaWalletProvider`, application or specific component tree should be wrapped with it:

import React from "react";
import { MinaWalletProvider } from "mina-wallet-sdk";

const App = () => {
  return (
    <MinaWalletProvider
      sdkOptions={{
        injectProvider: true, // Injects window.mina into the browser
        zkAppMetadata: {
          name: "My zkApp",
          url: "https://my-zkapp.example.com",
          iconUrl: "https://my-zkapp.example.com/favicon.ico",
        },
        // Additional SDK options...
      }}
    >
      {/* Your app components go here */}
    </MinaWalletProvider>
  );
};

export default App;

In this example, the `MinaWalletProvider` is initialized with custom SDK options and wraps the main application components, making the SDK and wallet context available throughout the app.

#### Context Usage

Child components can access the SDK and wallet state using the `useContext` hook:

import React, { useContext, useEffect } from "react";
import { useMinaWalletContext } from "mina-wallet-sdk";

const MyComponent = () => {
  const {
    sdk,
    connected,
    connecting,
    account,
    chainId, // mina:testnet, mina:mainnet
    balance,
    error,
    provider,
  } = useMinaWalletContext();

  useEffect(async () => {
    if (sdk && !connected && !connecting) {
      await sdk.connect();
    }
  }, [sdk, connected, connecting]);

  return (
    <div>
      {connected ? (
        <div>
          <p>Connected account: {account}</p>
          <p>Chain ID: {chainId}</p>
          <p>Balance: {balance}</p>
        </div>
      ) : (
        <p>Connecting to Mina wallet...</p>
      )}
    </div>
  );
};

export default MyComponent;

#### MinaWalletProvider Props

The `MinaWalletProvider` accepts the following props:

- `sdkOptions: MinaWalletSDKOptions`: Configuration options for initializing the Mina Wallet SDK.
- `children: React.ReactNode`: The child components that will have access to the wallet context.

#### MinaWalletContext

The context provided by `MinaWalletProvider` includes the following state and functions:

- `sdk?: MinaWalletSDK`: The initialized instance of the Mina Wallet SDK.
- `connected: boolean`: Indicates whether the wallet is connected.
- `connecting: boolean`: Indicates whether a connection attempt is in progress.
- `readOnlyCalls: boolean`: Allows querying the network without a wallet connection using GraphQL or BlockBerry API.
- `provider?: SDKProvider`: The SDK provider instance for interacting with the wallet (or window.mina if `injectProvider` is true)
- `account?: string`: The connected user's account address.
- `chainId?: string`: The current chain ID.
- `balance?: string`: The user's account balance in MINA.
- `error?: Error`: Any error encountered during connection or interaction.
- `syncing?: boolean`: Indicates if the SDK is syncing data.

#### Event Handling

The `MinaWalletProvider` internally handles various events emitted by the SDK and provider, such as:

- `connecting`: Triggered when a connection attempt starts.
- `connect`: Triggered when the wallet is successfully connected.
- `disconnect`: Triggered when the wallet is disconnected.
- `accountsChanged`: Triggered when the user's account changes.
- `chainChanged`: Triggered when the connected chain changes.
- `error`: Triggered when an error occurs.

By managing these events, the provider ensures the application's UI stays in sync with the wallet's state.

### MinaWalletSDK

The `sdk` object in the Mina Wallet SDK provides a comprehensive set of functionalities for interacting with the Mina network and the user's Mina wallet. It allows developers to initialize the SDK, manage wallet connections, and handle various wallet-related operations and events.

By utilizing the `sdk` object provided by the Mina Wallet SDK, developers can seamlessly integrate Mina wallet functionalities into their applications, enhancing the user experience through secure and efficient interactions with the Mina blockchain.

#### Key Features

- **Wallet Connection**: Establish and maintain connections with the Mina wallet extension or mobile wallets.
- **Transactions and Messages Signing**: Facilitates signing of transactions and messages through the connected wallet.
- **Account and Network Management**: Provides methods to access user account information such as addresses, chainId and balances.
- **SDK Configuration**: Allows configuration of RPC/GraphQL endpoints, network settings, and other SDK options.

#### Methods

- `connect()`: Initiates a connection request to the user's Mina wallet.
- `disconnect()`: Terminates the connection with the wallet.
- `isConnected()`: Returns a boolean indicating if the SDK is connected to a wallet.
- `getProvider()`: Retrieves the provider instance
- `on(event, listener)`: Subscribes to SDK or wallet events.
- `off(event, listener)`: Unsubscribes from events.

#### Events

- `connected`: Emitted when a connection to the wallet is successfully established.
- `disconnected`: Emitted when the connection to the wallet is terminated.
- `accountsChanged`: Emitted when the user's wallet account changes.
- `networkChanged`: Emitted when the wallet's connected network changes.

#### Usage Example

import { MinaWalletSDK } from 'mina-wallet-sdk';

const sdk = new MinaWalletSDK({
    zkAppMetadata: {
        name: 'My Mina zkApp',
        url: 'https://my-mina-zkapp.example.com',
        iconUrl: 'https://my-mina-zkapp.example.com/favicon.ico',
    },
});

sdk.on('connected', () => {
    console.log('Mina wallet connected');
});

sdk.on('accountsChanged', (accounts: string[]) => {
    console.log('Accounts changed:', accounts);
});

await sdk.connect();
const provider = sdk.getProvider();
if (provider) {
    // Interact with the Mina provider
    const accounts = await provider.request(
        { method: 'mina_accounts' }
    );
    console.log('Accounts:', accounts);
    const result = await provider.request(
        { method: 'mina_sendTransaction', 
          params: {
            onlySign: true,
            transaction: tx.toJSON(),
            feePayer: {
                fee,
                memo,
            },
          }
        });
    console.log('Signed transaction:', result.signedData);
}

In this example, we:

- Create an instance of `MinaWalletSDK` with custom options.
- Listen for the `connected` and `accountsChanged` events.
- Connect to the user's Mina wallet using `sdk.connect()`.
- Retrieve the injected provider and interact with the wallet.

#### SDK Options (`MinaWalletSDKOptions`)

The `MinaWalletSDK` constructor accepts an options object to configure the SDK:

interface MinaWalletSDKOptions {
  zkAppMetadata?: ZkAppMetadata; 
  connectionMethods?: ConnectionMethods; 
  // Additional configuration options...
}

#### zkApp Metadata (`ZkAppMetadata`)

Provide information about your zkApp to enhance user trust and experience:

interface ZkAppMetadata {
  name: string; // The name of your zkApp
  url?: string; // The URL where your zkApp is hosted
  iconUrl?: string; // A URL pointing to your zkApp's icon
}