@megaeth-labs/wallet-sdk 0.1.9-beta.2 → 0.1.9

package/README.md

@@ -1,444 +1,42 @@
-# MOSS Wallet SDK
+# MegaETH Wallet SDK
 
-## Contents
+Distributed to partners to work with the MegaETH wallet. Is responsible for loading the wallet inside an iFrame and
+communicating with it.
 
-- [Install](#install)
-- [Initialize](#initialize)
-- [Connection Management](#connection-management)
-  - [Connect Wallet](#connect-wallet)
-  - [Check Status](#check-status)
-  - [Disconnect](#disconnect)
-- [Authentication](#authentication)
-  - [Authenticate with SIWE](#authenticate-with-siwe)
-- [Transfers](#transfers)
-  - [Native Token Transfer (ETH)](#native-token-transfer-eth)
-  - [ERC20 Token Transfer](#erc20-token-transfer)
-  - [ERC721 NFT Transfer](#erc721-nft-transfer)
-  - [ERC1155 Token Transfer](#erc1155-token-transfer)
-- [Smart Contract Interactions](#smart-contract-interactions)
-  - [Call Contract Method](#call-contract-method)
-  - [Silent Contract Call (Session Keys)](#silent-contract-call-session-keys)
-  - [Batch Contract Calls](#batch-contract-calls)
-  - [Call Contract with Raw Data](#call-contract-with-raw-data)
-  - [Read from Contract (No Gas)](#read-from-contract-no-gas)
-- [Session Keys & Permissions](#session-keys--permissions)
-  - [Grant Permissions](#grant-permissions)
-  - [Get Current Permissions](#get-current-permissions)
-  - [Revoke Permissions](#revoke-permissions)
-- [Message Signing](#message-signing)
-  - [Sign Message](#sign-message)
-  - [Sign Structured Data (EIP-712)](#sign-structured-data-eip-712)
-- [Wallet Information](#wallet-information)
-  - [Get Token Balances](#get-token-balances)
-  - [Open Wallet UI](#open-wallet-ui)
-  - [Deposit Funds](#deposit-funds)
-- [Event Handling](#event-handling)
+## Setup
 
-## Install
+Install dependencies: `pnpm i`
 
-`npm install @megaeth-labs/wallet-sdk`
+Link package locally so other packages can use it: `pnpm dev:link`
 
-A React Hooks version is also availale as `@megaeth-labs/wallet-sdk-react`
+Auto build during dev: `pnpm dev`
 
-Types for all requests and responses can be found at [`src/types.ts`](src/types.ts)
+Build once: `pnpm build`
 
-## Initialize
-Sets up the iFrame-based wallet. Resolves when the wallet is ready.
+## How It Works
 
-```typescript
-import { mega } from '@megaeth-labs/wallet-sdk';
-
-await mega.initialise({
-    network: 'mainnet', // or 'testnet'
-    logging: 'error', // Optional: 'debug' | 'info' | 'warn' | 'error'
-    debug: false, // Optional: Enable internal verbose debug logging
-    sponsorUrl: 'https://your-sponsor-url.com', // Optional: Custom sponsor URL - see Sponsoring
-    sponsorMode: 'app-only', // Optional: 'everything' | 'app-only' | 'explicit'
-    sponsorToken: 'native', // Optional: 'native' | 'usdm'
-});
-```
-
-## Connection Management
-
-### Connect Wallet
-Shows the connection UI and resolves when the user connects or cancels.
-
-```typescript
-const { status, address } = await mega.connect();
-
-if (status === 'connected') {
-    console.log('Wallet connected:', address);
-}
-```
-
-### Check Status
-Get the current connection status without prompting the user.
-
-```typescript
-const { status, address } = await mega.status();
-```
-
-### Disconnect
-Disconnect the current wallet session.
-
-```typescript
-const result = await mega.disconnect();
-console.log('Disconnected:', result.status);
-```
-
-## Authentication
-
-### Authenticate with SIWE
-Shows the built-in Sign-In with Ethereum (SIWE) UI. Returns a JWT that can be verified at `https://wallet-api.megaeth.com/v1/partner-auth/verify?origin=YOUR_ORIGIN&jwt=JWT_TOKEN`
-
-```typescript
-const auth = await mega.authenticate();
-
-if (auth.status === 'success' && auth.jwt) {
-    const response = await fetch(
-        `https://wallet-api.megaeth.com/v1/partner-auth/verify?origin=${window.location.host}&jwt=${auth.jwt}`
-    );
-    const { walletAddress } = await response.json();
-}
-```
-
-## Transfers
-
-### Native Token Transfer (ETH)
-Transfer native tokens from the connected wallet.
-
-```typescript
-import { parseEther } from 'viem';
-
-const result = await mega.transfer({
-    type: 'native',
-    to: '0xRecipientAddress',
-    amount: parseEther('0.1').toString(),
-    sponsor: false, // Optional: Use sponsored transactions when sponsor mode is explict
-});
-
-if (result.status === 'approved') {
-    console.log('Transaction hash:', result.receipt.hash);
-}
-```
+The bulk of the logic can be found in the `src/wallet.ts` file. It handles the initialization of the wallet,
+communication with the iframe, and event handling. It exposes a object `mega` which contains all the methods to initialise and communicate with the iFrame.
 
-### ERC20 Token Transfer
-Transfer ERC20 tokens.
+Communication is handled using the `penpal` library which ensures that messages are sent and received securely and reliably between the parent window and the iframe.
 
-```typescript
-import { parseUnits } from 'viem';
-
-const result = await mega.transfer({
-    type: 'erc20',
-    to: '0xRecipientAddress',
-    amount: parseUnits('100', 18).toString(), // 100 tokens with 18 decimals
-    contractAddress: '0xTokenContractAddress',
-});
-```
-
-### ERC721 NFT Transfer
-Transfer an ERC721 NFT.
-
-```typescript
-const result = await mega.transfer({
-    type: 'erc721',
-    to: '0xRecipientAddress',
-    contractAddress: '0xNFTContractAddress',
-    tokenId: 1234,
-    amount: '0',
-});
-```
-
-### ERC1155 Token Transfer
-Transfer ERC1155 tokens.
-
-```typescript
-const result = await mega.transfer({
-    type: 'erc1155',
-    to: '0xRecipientAddress',
-    contractAddress: '0xTokenContractAddress',
-    tokenId: 1,
-    amount: '5', // Number of tokens to transfer
-});
-```
-
-## Smart Contract Interactions
-
-### Call Contract Method
-Execute a contract method with user approval.
-
-```typescript
-const result = await mega.callContract({
-    address: '0xContractAddress',
-    abi: contractABI,
-    functionName: 'mint',
-    args: [parseEther('1')],
-    value: parseEther('0.1'), // Optional: ETH value to send
-    sponsor: false, // Optional: Use sponsored transactions when sponsor mode is explict
-});
+**Initialisation Flow**
+Calling `mega.initialise()` triggers the following steps:
+1. iFrame is created and loaded
+2. Penpal is initialised to handle communication with the iFrame
+3. A method `ready` is exposed to the iFrame
+4. The iFrame loads and checks wallet status and then calls `ready` in the parent window
 
-if (result.status === 'approved') {
-    console.log('Transaction hash:', result.receipt.hash);
-}
-```
-
-### Silent Contract Call (Session Keys)
-Execute a contract method silently using session key permissions (no user approval required).
-
-```typescript
-const result = await mega.callContract({
-    address: '0xContractAddress',
-    abi: contractABI,
-    functionName: 'claim',
-    args: [],
-    silent: true, // Uses session key with pre-approved permissions
-});
-```
-
-### Batch Contract Calls
-Execute multiple contract calls in a single transaction.
+**Methods**
+Each of the available methods can be found in the `src/outbound-methods` folder and follow the same pattern:
+1. Validate the request
+2. Use `Remote.remote.methodName` to call the method in the iFrame
+3. The promise remains open until the iFrame responds
+4. Result is returned
 
+For example:
 ```typescript
-const result = await mega.callContract([
-    {
-        address: '0xContract1',
-        abi: abi1,
-        functionName: 'approve',
-        args: ['0xSpender', parseEther('100')],
-    },
-    {
-        address: '0xContract2',
-        abi: abi2,
-        functionName: 'swap',
-        args: [parseEther('100')],
-    },
-]);
-```
-
-### Call Contract with Raw Data
-Execute a contract call using raw calldata instead of ABI.
-
-```typescript
-const result = await mega.callContract({
-    address: '0xContractAddress',
-    data: '0x...' as `0x${string}`,
-    value: parseEther('0.1'),
-});
-```
-
-### Read from Contract (No Gas)
-Read data from a contract without creating a transaction.
-
-```typescript
-const balance = await mega.getFromContract<bigint>({
-    address: '0xTokenContract',
-    abi: erc20ABI,
-    functionName: 'balanceOf',
-    args: ['0xUserAddress'],
-});
-
-console.log('Balance:', balance.toString());
+const {signature, status} = await mega.signMessage('Hello World');
 ```
 
-## Session Keys & Permissions
-
-### Grant Permissions
-Grant session key permissions for silent transactions. Users approve once, then your app can execute permitted transactions without additional prompts.
-
-```typescript
-import { parseEther } from 'viem';
-
-const result = await mega.grantPermissions({
-    permissions: {
-        expiry: 86400, // Expiry in seconds (24 hours)
-        feeToken: {
-            limit: parseEther('0.01').toString(), // Max fee allowed per transaction
-            symbol: 'ETH', // Optional: Fee token symbol
-        },
-        permissions: {
-            // Specific contract calls allowed
-            calls: [
-                {
-                    to: '0xContractAddress',
-                    signature: 'mint(uint256)', // Function signature
-                },
-                {
-                    to: '0xAnotherContract',
-                    signature: 'claim()',
-                },
-            ],
-            // Spending limits for tokens
-            spend: [
-                {
-                    limit: parseEther('100'), // 100 ETH
-                    period: 'day', // 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'
-                    token: undefined, // undefined for native ETH
-                },
-                {
-                    limit: parseEther('1000'), // 1000 tokens
-                    period: 'week',
-                    token: '0xTokenAddress' as `0x${string}`,
-                },
-            ],
-        },
-    },
-    externalAddress: '0xYourAppAddress', // Optional: External address for permissions if sending from another wallet (e.g. from your API)
-    sponsor: false, // Optional: Sponsor the permission grant transaction when sponsor mode is explicit
-});
-
-if (result.status === 'approved') {
-    console.log('Permissions granted');
-}
-```
-
-### Get Current Permissions
-Check what permissions are currently active for an address.
-
-```typescript
-const perms = await mega.getPermissions('0xUserAddress'); // Optional: address parameter
-
-if (perms?.permissions) {
-    console.log('Expiry:', new Date(perms.permissions.expiry * 1000));
-    console.log('Allowed calls:', perms.permissions.permissions.calls);
-    console.log('Spending limits:', perms.permissions.permissions.spend);
-}
-```
-
-### Revoke Permissions
-Revoke all active session key permissions.
-
-```typescript
-await mega.revokePermissions();
-console.log('All permissions revoked');
-```
-
-## Message Signing
-
-### Sign Message
-Request the user to sign a message.
-
-```typescript
-const result = await mega.signMessage('Hello, World!');
-
-if (result.status === 'success' && result.signature) {
-    console.log('Signature:', result.signature);
-}
-```
-
-### Sign Structured Data (EIP-712)
-Sign typed structured data.
-
-```typescript
-const domain = {
-    name: 'MyApp',
-    version: '1',
-    chainId: 1,
-    verifyingContract: '0xContract',
-};
-
-const types = {
-    Person: [
-        { name: 'name', type: 'string' },
-        { name: 'wallet', type: 'address' },
-    ],
-};
-
-const value = {
-    name: 'Alice',
-    wallet: '0x...',
-};
-
-const result = await mega.signData({
-    data: { domain, types, value },
-});
-
-if (result.status === 'success' && result.signature) {
-    console.log('Signature:', result.signature);
-}
-```
-
-### Verifying Messages
-For SIWE messages, the `@megaeth-labss/wallet-server-verify` package can be used to verify the signature.
-
-For other messages or for more control, the following code can be used:
-
-```typescript
-import { PersonalMessage } from 'ox'; 
-import { Porto, RelayActions } from 'porto';
-import { RelayClient } from 'porto/viem';
-import { http, toBytes } from 'viem';
-import { megaeth, megaethTestnet } from 'viem/chains';
-
-const message = 'Hello';
-const address = '0x...';
-const signature = '0x...';
-const chainId = 4326;
-
-const porto = Porto.create({
-    relay: http('https://wallet-relay.megaeth.com'),
-    chains: [megaeth, megaethTestnet],
-});
-
-const client = RelayClient.fromPorto(porto, {
-    chainId
-});
-
-const result = await RelayActions.verifySignature(client, {
-    address,
-    digest: PersonalMessage.getSignPayload(toBytes(message)),
-    signature
-});
-
-if(!result.valid) { 
-    throw new Error('Invalid Signature');
-}
-```
-
-## Wallet Information
-
-### Get Token Balances
-Retrieve the user's token balances.
-
-```typescript
-// Get all tokens
-const allBalances = await mega.balances({});
-
-// Get specific tokens
-const specificBalances = await mega.balances({
-    tokens: ['0xTokenAddress1', '0xTokenAddress2'],
-});
-
-specificBalances.forEach(token => {
-    console.log(`${token.symbol}: ${token.displayBalance}`);
-    console.log(`USD Value: $${token.usdBalance}`);
-});
-```
-
-### Open Wallet UI
-Open the wallet interface for the user.
-
-```typescript
-await mega.open();
-```
-
-### Deposit Funds
-Show the deposit UI to help users fund their wallet.
-
-```typescript
-await mega.deposit();
-```
-
-## Event Handling
-
-Listen to wallet events for real-time updates.
-
-```typescript
-// Listen for status changes
-mega.events.on('statusChange', ({ status, address }) => {
-    console.log('Status changed:', status, address);
-});
-
-// Stop listening
-const unsubscribe = mega.events.on('statusChange', handler);
-unsubscribe(); // Call to remove listener
-```
+All request and return types are defined in the `src/types.ts` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@megaeth-labs/wallet-sdk",
-  "version": "0.1.9-beta.2",
+  "version": "0.1.9",
   "description": "MegaETH Wallet SDK for web applications",
   "type": "module",
   "main": "./dist/index.cjs",