From 743f99da05cfc6a9c87313c0fa287d79667ad4a2 Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 11 Dec 2024 14:37:09 -0600 Subject: [PATCH] adds v basic mock readme to the sdk for demo purposes --- src/sdk/README.md | 279 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 src/sdk/README.md diff --git a/src/sdk/README.md b/src/sdk/README.md new file mode 100644 index 0000000..c1bf11a --- /dev/null +++ b/src/sdk/README.md @@ -0,0 +1,279 @@ +# MetaMask Multichain SDK + +This SDK provides a way for dapps to connect to the MetaMask wallet via the `externally_connectable` API. It includes a React hook `useSDK` for easy integration in React applications and an `SDK` class for direct usage. + +The MetaMask Multichain SDK simplifies interaction with MetaMask's Multichain API. It allows dApps to: + +- Establish connections with the MetaMask wallet via the `externally_connectable` API. +- Manage sessions across multiple chains using [CAIP-2](https://chainagnostic.org/specs/CAIP-2) identifiers. +- Invoke methods and handle notifications from the wallet. + +## Installation + +Copy the `sdk` folder into your project's `src` directory or another preferred location. + +## Usage + +### Using the `useSDK` Hook (React) + +The `useSDK` hook manages the connection state, sessions, and method invocations, making it easy to integrate into React applications. + +```typescript +import React, { useEffect } from 'react'; +import { useSDK } from '@metamask/sdk'; + +function App() { + const { + isConnected, + currentSession, + extensionId, + connect, + disconnect, + createSession, + getSession, + revokeSession, + invokeMethod, + onNotification, + } = useSDK({ + onSessionChanged: (notification) => { + console.log('Session changed:', notification); + }, + onWalletNotify: (notification) => { + console.log('Wallet notification:', notification); + }, + }); + + // Connect to MetaMask + const handleConnect = async () => { + try { + await connect('your-extension-id'); // Replace with your MetaMask extension ID + console.log('Connected to MetaMask'); + } catch (error) { + console.error('Connection error:', error); + } + }; + + // Create a session with specified chain IDs (e.g., Ethereum Mainnet and Polygon) + const handleCreateSession = async () => { + try { + const scopes = ['eip155:1', 'eip155:137']; + const session = await createSession(scopes); + console.log('Session created:', session); + } catch (error) { + console.error('Error creating session:', error); + } + }; + + // Invoke a method on a specific chain + const handleInvokeMethod = async () => { + try { + const result = await invokeMethod('eip155:1', { + method: 'eth_blockNumber', + params: [], + }); + console.log('Block number:', result); + } catch (error) { + console.error('Error invoking method:', error); + } + }; + + // Handle incoming notifications + useEffect(() => { + onNotification((notification) => { + console.log('Received notification:', notification); + }); + }, [onNotification]); + + return ( +
+ + + + +
+ ); +} + +export default App; +``` + +### Using the `SDK` Class Directly + +For non-React applications or if you prefer direct usage, you can interact with the `SDK` class. + +```typescript +import SDK from '@metamask/sdk'; + +async function main() { + const sdk = new SDK(); + + // Connect to MetaMask + try { + const connected = await sdk.setExtensionIdAndConnect('your-extension-id'); // Replace with your MetaMask extension ID + if (connected) { + console.log('Connected to MetaMask'); + } else { + console.error('Failed to connect to MetaMask'); + return; + } + } catch (error) { + console.error('Connection error:', error); + return; + } + + // Create a session + try { + const scopes = ['eip155:1', 'eip155:137']; // Replace with desired chain IDs + const session = await sdk.createSession(scopes); + console.log('Session created:', session); + } catch (error) { + console.error('Error creating session:', error); + return; + } + + // Invoke a method + try { + const result = await sdk.invokeMethod({ + scope: 'eip155:1', + request: { + method: 'eth_blockNumber', + params: [], + }, + }); + console.log('Block number:', result); + } catch (error) { + console.error('Error invoking method:', error); + } + + // Handle notifications + sdk.onNotification((notification) => { + console.log('Received notification:', notification); + }); + + // Disconnect when done + sdk.disconnect(); +} + +main(); +``` + +## API Reference + +### `useSDK` Hook + +The `useSDK` hook provides an easy way to interact with the MetaMask wallet in React applications. + +**Importing the Hook:** + +```typescript +import { useSDK } from '@metamask/sdk'; +``` + +**Hook Usage:** + +```typescript +const { + isConnected, + currentSession, + extensionId, + connect, + disconnect, + createSession, + getSession, + revokeSession, + invokeMethod, + onNotification, +} = useSDK({ + onSessionChanged: (notification) => { + // Handle session changed notifications + }, + onWalletNotify: (notification) => { + // Handle wallet notifications + }, +}); +``` + +**Parameters:** + +- `onSessionChanged: (notification: any) => void` - Callback invoked when the session changes. +- `onWalletNotify: (notification: any) => void` - Callback invoked when a `wallet_notify` event is received. + +**Properties:** + +- `isConnected: boolean` - Indicates if connected to MetaMask. +- `currentSession: any` - Current session information. +- `extensionId: string` - The MetaMask extension ID. + +**Methods:** + +- `connect(extensionId: string): Promise` - Connects to MetaMask using the specified extension ID. +- `disconnect(): void` - Disconnects from MetaMask. +- `createSession(scopes: CaipChainId[]): Promise` - Creates a new session with the specified chain scopes. +- `getSession(): Promise` - Retrieves the current session. +- `revokeSession(): Promise` - Revokes the current session. +- `invokeMethod(scope: CaipChainId, request: { method: string; params: Json[] }): Promise` - Invokes a method on the specified chain. +- `onNotification(callback: (notification: any) => void): void` - Registers a callback for notifications. + +### `SDK` Class + +The `SDK` class allows direct interaction with MetaMask's Multichain API. + +**Importing the SDK:** + +```typescript +import SDK from './sdk/SDK'; // Adjust the import path as needed +``` + +**Class Usage:** + +```typescript +const sdk = new SDK(); +``` + +**Methods:** + +- `setExtensionIdAndConnect(extensionId: string): Promise` - Sets the extension ID and attempts to connect. +- `disconnect(): void` - Disconnects from MetaMask. +- `createSession(scopes: CaipChainId[]): Promise` - Creates a session with the specified chain scopes. +- `getSession(): Promise` - Retrieves the current session. +- `revokeSession(): Promise` - Revokes the current session. +- `invokeMethod({ scope, request }: { scope: CaipChainId; request: { method: string; params: Json[] } }): Promise` - Invokes a method on the specified chain. +- `onNotification(callback: (notification: any) => void): void` - Registers a callback for notifications. + +**Example:** + +```typescript +const sdk = new SDK(); + +// Connect to MetaMask +await sdk.setExtensionIdAndConnect('your-extension-id'); + +// Create a session +const session = await sdk.createSession(['eip155:1']); + +// Invoke a method +const result = await sdk.invokeMethod({ + scope: 'eip155:1', + request: { + method: 'eth_blockNumber', + params: [], + }, +}); +console.log('Block number:', result); + +// Handle notifications +sdk.onNotification((notification) => { + console.log('Received notification:', notification); +}); + +// Disconnect when done +sdk.disconnect(); +``` + +