@megaflow-labs/sdk 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.2] – 2026-02-28
+
+### Improvements — Developer Experience
+
+#### Added `connectWithPrivateKey` convenience method
+- You can now connect the `MegaFlowBuilder` and `MegaFlowClient` directly with a private key hex string, without needing to manually import `privateKeyToAccount` or create account objects.
+
+#### Expanded viem re-exports
+- Re-exported `parseAbi`, `parseAbiItem`, `parseAbiParameters` (ABI helpers)
+- Re-exported `createPublicClient`, `createWalletClient`, `http`, `webSocket` (Client factories)
+- Re-exported `Chain`, `decodeAbiParameters` (Types and Encoding)
+- This allows developers to rely **entirely** on the SDK imports for script and dapp building, eliminating duplicate `viem` dependencies.
+
+---
+
 ## [0.1.1] – 2026-02-26
 
 ### Improvements — Developer Experience

package/README.md

@@ -26,25 +26,21 @@ On standard EVM chains, sending multiple transactions requires multiple wallet c
 npm install @megaflow-labs/sdk
 ```
 
-> Requires `viem ^2.0.0` (peer dependency) and Node.js ≥ 18.
+> **Node.js ≥ 18** required. `viem` is a peer dependency — but all commonly used viem utilities are **re-exported from the SDK** so you rarely need to install it separately.
 
 ---
 
 ## Quick Start
 
 ```typescript
-import { MegaFlowClient, MEGAETH_TOKENS } from '@megaflow-labs/sdk';
-import { privateKeyToAccount } from 'viem/accounts';
-import { parseUnits, parseEther } from 'viem';
+import { MegaFlowClient, MEGAETH_TOKENS, parseUnits, parseEther } from '@megaflow-labs/sdk';
 
-const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
-
-// Zero-config: connects to MegaETH Mainnet automatically
-const client = new MegaFlowClient().connectWithAccount(account);
+// fromPrivateKey() creates a fully connected client in one line
+const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
 
 // Read on-chain state
-const balance = await client.getTokenBalance(MEGAETH_TOKENS.WETH, account.address);
-const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+const balance = await client.getTokenBalance(MEGAETH_TOKENS.WETH, client.address!);
+const allowance = await client.getAllowance(USDC, client.address!, DEX_ROUTER);
 
 // Build, simulate, and execute — all in one chain
 const result = await client
@@ -55,7 +51,7 @@ const result = await client
     amountIn: parseUnits('100', 6),
     amountOutMin: parseEther('0.03'),
     path: [USDC, MEGAETH_TOKENS.WETH],
-    to: account.address,
+    to: client.address!,
   })
   .executeSync(); // instant receipt on MegaETH (~10ms)
 
@@ -63,6 +59,13 @@ console.log(`Tx hash: ${result.receipt.transactionHash}`);
 console.log(`Gas used: ${result.gasUsed}`);
 ```
 
+> **Using an existing viem account or WalletClient?** Both still work:
+> ```typescript
+> import { MegaFlowClient, privateKeyToAccount } from '@megaflow-labs/sdk';
+> const client = new MegaFlowClient().connectWithAccount(privateKeyToAccount('0x...'));
+> // or: .connect(myExistingWalletClient)
+> ```
+
 ---
 
 ## Core Concepts
@@ -94,15 +97,16 @@ const result = await builder.execute();
 
 Stateful high-level client. Extends MegaFlowBuilder with token reads, nonce management, and WebSocket support.
 
+**Factory methods (v0.1.1+):**
+
 ```typescript
-import { MegaFlowClient } from '@megaflow-labs/sdk';
+import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
 
-const client = new MegaFlowClient({ debug: true });
-client.connectWithAccount(account);
+// From private key
+const client = MegaFlowClient.fromPrivateKey('0xYOUR_KEY');
 
-// Read token state
-const bal = await client.getTokenBalance(token, address);
-const allowance = await client.getAllowance(token, address, spender);
+// From mnemonic
+const client2 = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
 
 // Batch transfers to multiple recipients in one tx
 const result = await client
@@ -116,6 +120,22 @@ const result = await client
 
 ---
 
+## What's re-exported from viem
+
+You can import all of these directly from `@megaflow-labs/sdk` — **no separate `viem` install needed**:
+
+| Category | Exports |
+|---|---|
+| **Account factories** | `privateKeyToAccount`, `mnemonicToAccount`, `hdKeyToAccount` |
+| **Unit helpers** | `parseUnits`, `parseEther`, `formatUnits`, `formatEther` |
+| **ABI helpers** | `parseAbi`, `parseAbiItem`, `parseAbiParameters` |
+| **Client factories** | `createPublicClient`, `createWalletClient`, `http`, `webSocket` |
+| **Address utilities** | `isAddress`, `getAddress`, `zeroAddress` |
+| **Encoding** | `encodeFunctionData`, `decodeFunctionData`, `encodeAbiParameters`, `decodeAbiParameters` |
+| **Types** | `Address`, `Hash`, `Hex`, `Chain`, `PublicClient`, `WalletClient`, `Account`, `TransactionReceipt` |
+
+---
+
 ## API Reference
 
 ### Execution Methods
@@ -246,11 +266,41 @@ const client = new MegaFlowClient({ rpcUrl: 'https://your-rpc.example.com' });
 
 ---
 
+## Examples
+
+See the **[megaflow-labs/examples](https://github.com/megaflow-labs/examples)** repository for 14 working TypeScript scripts covering real DeFi patterns:
+
+| Script | Pattern |
+|---|---|
+| `04-yield-optimizer` | Wrap + Approve + Supply to Aave in one tx |
+| `05-leverage-loop` | Flashloan-style leverage loop without smart contracts |
+| `06-nft-sweep-and-stake` | Buy NFT + stake atomically |
+| `07-token-snipe-and-protect` | Snipe + stop-loss authorization |
+| `08-bridge-intent` | Swap + bridge to L1 in one signature |
+| `09-flash-arbitrage` | Zero-risk EOA arbitrage across two DEXes |
+| `10-debt-repayment` | Liquidation rescue (swap illiquid → repay) |
+| `11-airdrop-claim-and-sell` | Claim + sell before price collapses |
+| `12-payroll-batch` | Treasury swap + pay 50 contributors |
+| `13-portfolio-rebalance` | Multi-sell → single target buy |
+| `14-options-payoff` | Conditional options exercise |
+
+**Clone and run:**
+```bash
+git clone https://github.com/megaflow-labs/examples
+cd examples && npm install
+cp .env.example .env   # add your PRIVATE_KEY
+npm run 04-yield
+```
+
+---
+
 ## Links
 
 - **Website:** [megaflow.space](https://megaflow.space)
+- **Examples:** [github.com/megaflow-labs/examples](https://github.com/megaflow-labs/examples)
 - **GitHub:** [github.com/megaflow-labs](https://github.com/megaflow-labs)
 - **NPM:** [@megaflow-labs/sdk](https://www.npmjs.com/package/@megaflow-labs/sdk)
+- **AI Context:** [llms.txt](https://github.com/megaflow-labs/sdk/blob/main/llms.txt)
 
 ---
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Chain, Address, Hex, Hash, TransactionReceipt, PublicClient, WalletClient, Account } from 'viem';
-export { Account, Address, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, isAddress, numberToHex, parseEther, parseUnits, zeroAddress } from 'viem';
+export { Account, Address, Chain, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, http, isAddress, numberToHex, parseAbi, parseAbiItem, parseAbiParameters, parseEther, parseUnits, webSocket, zeroAddress } from 'viem';
 export { hdKeyToAccount, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
 /**
@@ -1290,8 +1290,13 @@ declare class MegaFlowBuilder {
      */
     connectWithAccount(account: Account, rpcUrl?: string): this;
     /**
-     * Disconnect the wallet (for cleanup).
+     * Connect using a raw private key hex string.
+     * The most convenient way to connect in scripts — no viem import needed.
+     *
+     * @example
+     * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
      */
+    connectWithPrivateKey(privateKey: `0x${string}`, rpcUrl?: string): this;
     disconnect(): this;
     /**
      * Add a raw call (pre-encoded calldata).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Chain, Address, Hex, Hash, TransactionReceipt, PublicClient, WalletClient, Account } from 'viem';
-export { Account, Address, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, isAddress, numberToHex, parseEther, parseUnits, zeroAddress } from 'viem';
+export { Account, Address, Chain, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, http, isAddress, numberToHex, parseAbi, parseAbiItem, parseAbiParameters, parseEther, parseUnits, webSocket, zeroAddress } from 'viem';
 export { hdKeyToAccount, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
 /**
@@ -1290,8 +1290,13 @@ declare class MegaFlowBuilder {
      */
     connectWithAccount(account: Account, rpcUrl?: string): this;
     /**
-     * Disconnect the wallet (for cleanup).
+     * Connect using a raw private key hex string.
+     * The most convenient way to connect in scripts — no viem import needed.
+     *
+     * @example
+     * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
      */
+    connectWithPrivateKey(privateKey: `0x${string}`, rpcUrl?: string): this;
     disconnect(): this;
     /**
      * Add a raw call (pre-encoded calldata).

package/dist/index.js

@@ -45,33 +45,40 @@ __export(index_exports, {
   createMegaFlowClientTestnet: () => createMegaFlowClientTestnet,
   createMegaFlowMainnet: () => createMegaFlowMainnet,
   createMegaFlowTestnet: () => createMegaFlowTestnet,
+  createPublicClient: () => import_viem8.createPublicClient,
+  createWalletClient: () => import_viem8.createWalletClient,
   deadlineInMinutes: () => deadlineInMinutes,
-  decodeAbiParameters: () => import_viem7.decodeAbiParameters,
-  decodeFunctionData: () => import_viem7.decodeFunctionData,
-  encodeAbiParameters: () => import_viem7.encodeAbiParameters,
-  encodeFunctionData: () => import_viem7.encodeFunctionData,
+  decodeAbiParameters: () => import_viem9.decodeAbiParameters,
+  decodeFunctionData: () => import_viem9.decodeFunctionData,
+  encodeAbiParameters: () => import_viem9.encodeAbiParameters,
+  encodeFunctionData: () => import_viem9.encodeFunctionData,
   formatEther: () => import_viem5.formatEther,
   formatUnits: () => import_viem5.formatUnits,
-  getAddress: () => import_viem6.getAddress,
+  getAddress: () => import_viem7.getAddress,
   getKyberQuote: () => getKyberQuote,
-  hdKeyToAccount: () => import_accounts2.hdKeyToAccount,
+  hdKeyToAccount: () => import_accounts3.hdKeyToAccount,
   hexToBigInt: () => import_viem5.hexToBigInt,
-  isAddress: () => import_viem6.isAddress,
+  http: () => import_viem8.http,
+  isAddress: () => import_viem7.isAddress,
   isUserRejection: () => isUserRejection,
   isValidAddress: () => isValidAddress,
   isValidHex: () => isValidHex,
   megaethChains: () => megaethChains,
   megaethMainnet: () => megaethMainnet,
   megaethTestnet: () => megaethTestnet,
-  mnemonicToAccount: () => import_accounts2.mnemonicToAccount,
+  mnemonicToAccount: () => import_accounts3.mnemonicToAccount,
   numberToHex: () => import_viem5.numberToHex,
+  parseAbi: () => import_viem6.parseAbi,
+  parseAbiItem: () => import_viem6.parseAbiItem,
+  parseAbiParameters: () => import_viem6.parseAbiParameters,
   parseBatchExecutedEvent: () => parseBatchExecutedEvent,
   parseCallExecutedEvents: () => parseCallExecutedEvents,
   parseCallResults: () => parseCallResults,
   parseEther: () => import_viem5.parseEther,
   parseUnits: () => import_viem5.parseUnits,
-  privateKeyToAccount: () => import_accounts2.privateKeyToAccount,
-  zeroAddress: () => import_viem6.zeroAddress
+  privateKeyToAccount: () => import_accounts3.privateKeyToAccount,
+  webSocket: () => import_viem8.webSocket,
+  zeroAddress: () => import_viem7.zeroAddress
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -510,6 +517,7 @@ var MegaFlowError = class extends Error {
 
 // src/builder.ts
 var import_viem3 = require("viem");
+var import_accounts = require("viem/accounts");
 var MegaFlowBuilder = class {
   constructor(config = {}) {
     this.calls = [];
@@ -549,8 +557,16 @@ var MegaFlowBuilder = class {
     return this;
   }
   /**
-   * Disconnect the wallet (for cleanup).
+   * Connect using a raw private key hex string.
+   * The most convenient way to connect in scripts — no viem import needed.
+   *
+   * @example
+   * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
    */
+  connectWithPrivateKey(privateKey, rpcUrl) {
+    const account = (0, import_accounts.privateKeyToAccount)(privateKey);
+    return this.connectWithAccount(account, rpcUrl);
+  }
   disconnect() {
     this.walletClient = void 0;
     return this;
@@ -1094,7 +1110,7 @@ var MegaFlowBuilder = class {
 // src/client.ts
 var import_viem4 = require("viem");
 var import_actions = require("viem/actions");
-var import_accounts = require("viem/accounts");
+var import_accounts2 = require("viem/accounts");
 var MegaFlowClient = class _MegaFlowClient {
   constructor(config = {}) {
     // Local nonce cache: address → last used nonce
@@ -1130,7 +1146,7 @@ var MegaFlowClient = class _MegaFlowClient {
    * ```
    */
   static fromPrivateKey(privateKey, config = {}) {
-    const account = (0, import_accounts.privateKeyToAccount)(privateKey);
+    const account = (0, import_accounts2.privateKeyToAccount)(privateKey);
     return new _MegaFlowClient(config).connectWithAccount(account);
   }
   /**
@@ -1142,7 +1158,7 @@ var MegaFlowClient = class _MegaFlowClient {
    * ```
    */
   static fromMnemonic(mnemonic, config = {}) {
-    const account = (0, import_accounts.mnemonicToAccount)(mnemonic);
+    const account = (0, import_accounts2.mnemonicToAccount)(mnemonic);
     return new _MegaFlowClient(config).connectWithAccount(account);
   }
   // ==========================================================================
@@ -1368,10 +1384,12 @@ var MegaFlowClient = class _MegaFlowClient {
 };
 
 // src/index.ts
-var import_accounts2 = require("viem/accounts");
+var import_accounts3 = require("viem/accounts");
 var import_viem5 = require("viem");
 var import_viem6 = require("viem");
 var import_viem7 = require("viem");
+var import_viem8 = require("viem");
+var import_viem9 = require("viem");
 function createMegaFlow(config) {
   return new MegaFlowBuilder(config);
 }
@@ -1417,6 +1435,8 @@ function createMegaFlowClientTestnet(routerAddress, rpcUrl) {
   createMegaFlowClientTestnet,
   createMegaFlowMainnet,
   createMegaFlowTestnet,
+  createPublicClient,
+  createWalletClient,
   deadlineInMinutes,
   decodeAbiParameters,
   decodeFunctionData,
@@ -1428,6 +1448,7 @@ function createMegaFlowClientTestnet(routerAddress, rpcUrl) {
   getKyberQuote,
   hdKeyToAccount,
   hexToBigInt,
+  http,
   isAddress,
   isUserRejection,
   isValidAddress,
@@ -1437,11 +1458,15 @@ function createMegaFlowClientTestnet(routerAddress, rpcUrl) {
   megaethTestnet,
   mnemonicToAccount,
   numberToHex,
+  parseAbi,
+  parseAbiItem,
+  parseAbiParameters,
   parseBatchExecutedEvent,
   parseCallExecutedEvents,
   parseCallResults,
   parseEther,
   parseUnits,
   privateKeyToAccount,
+  webSocket,
   zeroAddress
 });

package/dist/index.mjs

@@ -441,6 +441,7 @@ import {
   encodeFunctionData,
   http
 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
 var MegaFlowBuilder = class {
   constructor(config = {}) {
     this.calls = [];
@@ -480,8 +481,16 @@ var MegaFlowBuilder = class {
     return this;
   }
   /**
-   * Disconnect the wallet (for cleanup).
+   * Connect using a raw private key hex string.
+   * The most convenient way to connect in scripts — no viem import needed.
+   *
+   * @example
+   * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
    */
+  connectWithPrivateKey(privateKey, rpcUrl) {
+    const account = privateKeyToAccount(privateKey);
+    return this.connectWithAccount(account, rpcUrl);
+  }
   disconnect() {
     this.walletClient = void 0;
     return this;
@@ -1030,7 +1039,7 @@ import {
   webSocket as webSocket2
 } from "viem";
 import { multicall } from "viem/actions";
-import { privateKeyToAccount, mnemonicToAccount } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount2, mnemonicToAccount } from "viem/accounts";
 var MegaFlowClient = class _MegaFlowClient {
   constructor(config = {}) {
     // Local nonce cache: address → last used nonce
@@ -1066,7 +1075,7 @@ var MegaFlowClient = class _MegaFlowClient {
    * ```
    */
   static fromPrivateKey(privateKey, config = {}) {
-    const account = privateKeyToAccount(privateKey);
+    const account = privateKeyToAccount2(privateKey);
     return new _MegaFlowClient(config).connectWithAccount(account);
   }
   /**
@@ -1304,9 +1313,11 @@ var MegaFlowClient = class _MegaFlowClient {
 };
 
 // src/index.ts
-import { privateKeyToAccount as privateKeyToAccount2, mnemonicToAccount as mnemonicToAccount2, hdKeyToAccount } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount3, mnemonicToAccount as mnemonicToAccount2, hdKeyToAccount } from "viem/accounts";
 import { parseUnits, parseEther as parseEther2, formatUnits, formatEther, hexToBigInt, numberToHex } from "viem";
+import { parseAbi as parseAbi2, parseAbiItem, parseAbiParameters } from "viem";
 import { isAddress, getAddress, zeroAddress } from "viem";
+import { createPublicClient as createPublicClient3, createWalletClient as createWalletClient3, http as http3, webSocket as webSocket3 } from "viem";
 import { encodeFunctionData as encodeFunctionData2, decodeFunctionData, encodeAbiParameters, decodeAbiParameters as decodeAbiParameters2 } from "viem";
 function createMegaFlow(config) {
   return new MegaFlowBuilder(config);
@@ -1352,6 +1363,8 @@ export {
   createMegaFlowClientTestnet,
   createMegaFlowMainnet,
   createMegaFlowTestnet,
+  createPublicClient3 as createPublicClient,
+  createWalletClient3 as createWalletClient,
   deadlineInMinutes,
   decodeAbiParameters2 as decodeAbiParameters,
   decodeFunctionData,
@@ -1363,6 +1376,7 @@ export {
   getKyberQuote,
   hdKeyToAccount,
   hexToBigInt,
+  http3 as http,
   isAddress,
   isUserRejection,
   isValidAddress,
@@ -1372,11 +1386,15 @@ export {
   megaethTestnet,
   mnemonicToAccount2 as mnemonicToAccount,
   numberToHex,
+  parseAbi2 as parseAbi,
+  parseAbiItem,
+  parseAbiParameters,
   parseBatchExecutedEvent,
   parseCallExecutedEvents,
   parseCallResults,
   parseEther2 as parseEther,
   parseUnits,
-  privateKeyToAccount2 as privateKeyToAccount,
+  privateKeyToAccount3 as privateKeyToAccount,
+  webSocket3 as webSocket,
   zeroAddress
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@megaflow-labs/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Batch transaction SDK for MegaETH — compose, simulate and execute multiple on-chain operations in a single atomic transaction.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",