@megaeth-labs/wallet-sdk 0.1.8 → 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

@@ -40,19 +40,19 @@ interface GetFromContractRequest {
     args: any[];
 }
 interface TransactionReceiptLog {
-    address: string;
-    data: string;
+    address: `0x${string}`;
+    data: `0x${string}`;
     topics: string[];
 }
 interface TransactionReceipt {
-    hash: string;
+    hash: `0x${string}`;
     blockHash: string;
     blockNumber: number;
     chainId: number;
     gasUsed: number;
     logs: TransactionReceiptLog[];
     status: string;
-    transactionHash: string;
+    transactionHash: `0x${string}`;
 }
 interface TransactionResult {
     status: 'approved' | 'cancelled' | 'error';

package/dist/index.d.ts

@@ -40,19 +40,19 @@ interface GetFromContractRequest {
     args: any[];
 }
 interface TransactionReceiptLog {
-    address: string;
-    data: string;
+    address: `0x${string}`;
+    data: `0x${string}`;
     topics: string[];
 }
 interface TransactionReceipt {
-    hash: string;
+    hash: `0x${string}`;
     blockHash: string;
     blockNumber: number;
     chainId: number;
     gasUsed: number;
     logs: TransactionReceiptLog[];
     status: string;
-    transactionHash: string;
+    transactionHash: `0x${string}`;
 }
 interface TransactionResult {
     status: 'approved' | 'cancelled' | 'error';

package/package.json

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