@megaeth-labs/wallet-sdk 0.1.7 → 0.1.9-beta.1

package/README.md

@@ -1,42 +1,410 @@
-# MegaETH Wallet SDK
+# MOSS Wallet SDK
 
-Distributed to partners to work with the MegaETH wallet. Is responsible for loading the wallet inside an iFrame and
-communicating with it.
+## Install
 
-## Setup
+`npm install @megaeth-labs/wallet-sdk`
 
-Install dependencies: `pnpm i`
+A React Hooks version is also availale as `@megaeth-labs/wallet-sdk-react`
 
-Link package locally so other packages can use it: `pnpm dev:link`
+Types for all requests and responses can be found at [`src/types.ts`](src/types.ts)
 
-Auto build during dev: `pnpm dev`
+## Initialize
+Sets up the iFrame-based wallet. Resolves when the wallet is ready.
 
-Build once: `pnpm build`
+```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);
+```
 
-## How It Works
+## Authentication
 
-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.
+### 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();
 
-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.
+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();
+}
+```
 
-**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
+## Transfers
 
-**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
+### Native Token Transfer (ETH)
+Transfer native tokens from the connected wallet.
 
-For example:
 ```typescript
-const {signature, status} = await mega.signMessage('Hello World');
+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);
+}
 ```
 
-All request and return types are defined in the `src/types.ts` file.
+### ERC20 Token Transfer
+Transfer ERC20 tokens.
+
+```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
+});
+
+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.
+
+```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());
+```
+
+## 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
+```

package/dist/index.d.cts

@@ -39,11 +39,25 @@ interface GetFromContractRequest {
     functionName: string;
     args: any[];
 }
+interface TransactionReceiptLog {
+    address: `0x${string}`;
+    data: `0x${string}`;
+    topics: string[];
+}
+interface TransactionReceipt {
+    hash: `0x${string}`;
+    blockHash: string;
+    blockNumber: number;
+    chainId: number;
+    gasUsed: number;
+    logs: TransactionReceiptLog[];
+    status: string;
+    transactionHash: `0x${string}`;
+}
 interface TransactionResult {
     status: 'approved' | 'cancelled' | 'error';
-    receipt?: {
-        hash: string;
-    };
+    receipt?: TransactionReceipt;
+    receipts?: TransactionReceipt[];
     error?: string;
 }
 interface SignMessageResponse {
@@ -169,4 +183,4 @@ declare const mega: {
     };
 };
 
-export { type AuthenticateResponse, type BalancesRequest, type BaseTokenResponse, type CallContractRequest, type Config, type ConnectionStatus, type GetFromContractRequest, type GetPermissionsResponse, type GrantPermissionsRequest, type GrantPermissionsResponse, type LogLevel, type Network, type OwnedTokenResponse, type Permission, type RemoteAPI, type SignDataRequest, type SignDataResponse, type SignMessageResponse, type SponsorMode, type SponsorToken, type TransactionResult, type TransferRequest, mega };
+export { type AuthenticateResponse, type BalancesRequest, type BaseTokenResponse, type CallContractRequest, type Config, type ConnectionStatus, type GetFromContractRequest, type GetPermissionsResponse, type GrantPermissionsRequest, type GrantPermissionsResponse, type LogLevel, type Network, type OwnedTokenResponse, type Permission, type RemoteAPI, type SignDataRequest, type SignDataResponse, type SignMessageResponse, type SponsorMode, type SponsorToken, type TransactionReceipt, type TransactionReceiptLog, type TransactionResult, type TransferRequest, mega };

package/dist/index.d.ts

@@ -39,11 +39,25 @@ interface GetFromContractRequest {
     functionName: string;
     args: any[];
 }
+interface TransactionReceiptLog {
+    address: `0x${string}`;
+    data: `0x${string}`;
+    topics: string[];
+}
+interface TransactionReceipt {
+    hash: `0x${string}`;
+    blockHash: string;
+    blockNumber: number;
+    chainId: number;
+    gasUsed: number;
+    logs: TransactionReceiptLog[];
+    status: string;
+    transactionHash: `0x${string}`;
+}
 interface TransactionResult {
     status: 'approved' | 'cancelled' | 'error';
-    receipt?: {
-        hash: string;
-    };
+    receipt?: TransactionReceipt;
+    receipts?: TransactionReceipt[];
     error?: string;
 }
 interface SignMessageResponse {
@@ -169,4 +183,4 @@ declare const mega: {
     };
 };
 
-export { type AuthenticateResponse, type BalancesRequest, type BaseTokenResponse, type CallContractRequest, type Config, type ConnectionStatus, type GetFromContractRequest, type GetPermissionsResponse, type GrantPermissionsRequest, type GrantPermissionsResponse, type LogLevel, type Network, type OwnedTokenResponse, type Permission, type RemoteAPI, type SignDataRequest, type SignDataResponse, type SignMessageResponse, type SponsorMode, type SponsorToken, type TransactionResult, type TransferRequest, mega };
+export { type AuthenticateResponse, type BalancesRequest, type BaseTokenResponse, type CallContractRequest, type Config, type ConnectionStatus, type GetFromContractRequest, type GetPermissionsResponse, type GrantPermissionsRequest, type GrantPermissionsResponse, type LogLevel, type Network, type OwnedTokenResponse, type Permission, type RemoteAPI, type SignDataRequest, type SignDataResponse, type SignMessageResponse, type SponsorMode, type SponsorToken, type TransactionReceipt, type TransactionReceiptLog, type TransactionResult, type TransferRequest, mega };

package/package.json

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