@chainforge/sdk 1.0.0

package/README.md

@@ -0,0 +1,494 @@
+# ChainForge SDK
+
+> **The Firebase of Web3** — Ship multi-chain dApps in minutes, not months.
+
+ChainForge SDK eliminates the complexity of Web3 development. No blockchain knowledge required. Works just like Firebase, Auth0, or Stripe.
+
+## 🚀 Why ChainForge?
+
+| Problem | Traditional Web3 | ChainForge SDK |
+|---------|-----------------|----------------|
+| Wallet Integration | 100+ lines, multiple libraries | `cf.auth.connectWallet('metamask')` |
+| User Management | Complex SIWE, nonces, signatures | Automatic, built-in |
+| Reading Blockchain | Raw hex data, ABI decoding | Human-readable JSON |
+| Transactions | Gas estimation, nonce management | `cf.transactions.send({to, amount})` |
+| Multi-chain | Different APIs for each chain | One API, 7 chains |
+| Auth State | Manual localStorage handling | Automatic persistence |
+
+## 📦 Installation
+
+```bash
+npm install @chainforge/sdk
+# or
+yarn add @chainforge/sdk
+# or
+<script src="https://unpkg.com/@chainforge/sdk"></script>
+```
+
+## 🔑 Quick Start
+
+### 1. Initialize SDK
+
+```javascript
+import { ChainForge } from '@chainforge/sdk';
+
+const cf = new ChainForge({
+  apiKey: 'your-api-key',  // Get from chainforge.io/dashboard
+  baseURL: 'https://api.chainforge.io'  // Optional: for self-hosted
+});
+```
+
+### 2. Connect Wallet (One Line)
+
+```javascript
+// As simple as Firebase Auth
+const { user, token } = await cf.auth.connectWallet('metamask');
+
+console.log(user.address);  // 0x742d35...
+console.log(user.chain);    // ethereum
+```
+
+### 3. Read Blockchain Data (No Web3 Knowledge)
+
+```javascript
+// Get balance - returns human-readable format
+const balance = await cf.data.getBalance();
+console.log(balance.formatted);  // "1.5"
+console.log(balance.symbol);     // "ETH"
+
+// Get transaction history - auto-humanized
+const history = await cf.data.getHistory({ limit: 10 });
+history.forEach(tx => {
+  console.log(tx.summary);  // "Sent 0.1 ETH to 0x1234..."
+  console.log(tx.display.timeAgo);  // "2h ago"
+});
+```
+
+### 4. Send Transactions (Abstracted Complexity)
+
+```javascript
+// No gas estimation, no nonce management, no hex encoding
+const tx = await cf.transactions.send({
+  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe',
+  amount: '0.1 ETH'
+});
+
+console.log(tx.hash);      // 0xabc123...
+console.log(tx.explorer);  // https://etherscan.io/tx/0xabc123...
+
+// Wait for confirmation
+await tx.wait();
+console.log('Confirmed!');
+```
+
+## 📖 Full API Reference
+
+### Authentication
+
+#### `cf.auth.connectWallet(walletType, options)`
+
+Connect a wallet and authenticate the user.
+
+```javascript
+// Connect MetaMask
+const { user, token } = await cf.auth.connectWallet('metamask');
+
+// Connect Phantom on Solana
+const { user, token } = await cf.auth.connectWallet('phantom', { chain: 'solana' });
+
+// Supported wallets: 'metamask', 'phantom', 'brave', 'coinbase', 'trust'
+```
+
+#### `cf.auth.loginWithEmail(email, password)`
+
+Traditional email/password auth.
+
+```javascript
+const { user, token } = await cf.auth.loginWithEmail('user@example.com', 'password');
+```
+
+#### `cf.auth.signupWithEmail(email, password, name)`
+
+Create account with email/password.
+
+```javascript
+const { user, token } = await cf.auth.signupWithEmail(
+  'user@example.com', 
+  'password',
+  'John Doe'
+);
+```
+
+#### `cf.auth.signOut()`
+
+Sign out and clear session.
+
+```javascript
+await cf.auth.signOut();
+```
+
+#### `cf.auth.getCurrentUser()`
+
+Get currently logged-in user.
+
+```javascript
+const user = cf.auth.getCurrentUser();
+console.log(user.wallets);  // Array of linked wallets
+```
+
+### Data (Reading Blockchain)
+
+#### `cf.data.getBalance(address?, chain?)`
+
+Get wallet balance in human-readable format.
+
+```javascript
+// Get current user's balance
+const balance = await cf.data.getBalance();
+// { formatted: "1.5", symbol: "ETH", raw: "1500000000000000000" }
+
+// Get any address balance
+const balance = await cf.data.getBalance('0x1234...', 'polygon');
+// { formatted: "100.5", symbol: "MATIC", raw: "100500000000000000000" }
+```
+
+#### `cf.data.getHistory(options)`
+
+Get human-readable transaction history.
+
+```javascript
+const history = await cf.data.getHistory({
+  address: '0x1234...',  // Optional: defaults to current user
+  chain: 'ethereum',      // Optional: defaults to user's chain
+  limit: 20              // Optional: default 20
+});
+
+history.forEach(tx => {
+  console.log(tx.summary);           // "Sent 0.5 ETH to 0x5678..."
+  console.log(tx.display.timeAgo);   // "2h ago"
+  console.log(tx.display.statusConfig.label);  // "Confirmed"
+  console.log(tx.display.explorerUrl);  // Link to explorer
+  
+  // Raw data also available
+  console.log(tx.raw.hash);
+  console.log(tx.raw.from);
+  console.log(tx.raw.to);
+});
+```
+
+#### `cf.data.getTransaction(hash, chain?)`
+
+Get details for a specific transaction.
+
+```javascript
+const tx = await cf.data.getTransaction('0xabc123...');
+console.log(tx.summary);  // Human-readable description
+```
+
+#### `cf.data.sync()`
+
+Sync blockchain data to ChainForge (for caching/indexing).
+
+```javascript
+const result = await cf.data.sync();
+console.log(`Synced ${result.synced} transactions`);
+```
+
+### Transactions
+
+#### `cf.transactions.send({ to, amount, data?, options? })`
+
+Send a transaction with automatic gas estimation.
+
+```javascript
+const tx = await cf.transactions.send({
+  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe',
+  amount: '0.1 ETH',  // Human-readable: "amount unit"
+  data: '0x...',       // Optional: contract interaction data
+  options: {
+    gasLimit: '30000',  // Optional: auto-estimated if not provided
+  }
+});
+
+console.log(tx.hash);      // Transaction hash
+console.log(tx.explorer);  // Explorer URL
+await tx.wait();           // Wait for confirmation
+```
+
+#### `cf.transactions.estimateGas(to, amount)`
+
+Estimate gas for a transaction.
+
+```javascript
+const gas = await cf.transactions.estimateGas(
+  '0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe',
+  { value: '0.1', symbol: 'ETH' }
+);
+console.log(gas);  // "21000"
+```
+
+### Wallet Management
+
+#### `cf.wallets.getAll()`
+
+Get all linked wallets.
+
+```javascript
+const wallets = await cf.wallets.getAll();
+wallets.forEach(wallet => {
+  console.log(wallet.address);
+  console.log(wallet.chain);
+  console.log(wallet.isPrimary);
+});
+```
+
+#### `cf.wallets.link(wallet)`
+
+Link a new wallet to the account.
+
+```javascript
+await cf.wallets.link({
+  address: '0x1234...',
+  chain: 'solana',
+  type: 'solana',
+  label: 'My Solana Wallet'
+});
+```
+
+#### `cf.wallets.unlink(walletId)`
+
+Unlink a wallet.
+
+```javascript
+await cf.wallets.unlink('wallet-id');
+```
+
+#### `cf.wallets.setPrimary(walletId)`
+
+Set a wallet as primary.
+
+```javascript
+await cf.wallets.setPrimary('wallet-id');
+```
+
+### Webhooks (Event Subscriptions)
+
+#### `cf.webhooks.on(event, callback)`
+
+Subscribe to on-chain events.
+
+```javascript
+// Subscribe to new transactions
+const unsubscribe = cf.webhooks.on('transaction', (tx) => {
+  console.log('New transaction:', tx.hash);
+  console.log(tx.summary);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+## 🎯 Real-World Examples
+
+### DeFi Dashboard
+
+```javascript
+import { ChainForge } from '@chainforge/sdk';
+
+const cf = new ChainForge({ apiKey: '...' });
+
+// Auto-restore session
+await cf.restoreSession();
+
+// Get all user data in parallel
+const [balance, history, wallets] = await Promise.all([
+  cf.data.getBalance(),
+  cf.data.getHistory({ limit: 10 }),
+  cf.wallets.getAll()
+]);
+
+// Render dashboard
+renderDashboard({
+  balance: `${balance.formatted} ${balance.symbol}`,
+  transactions: history.map(tx => ({
+    description: tx.summary,
+    time: tx.display.timeAgo,
+    status: tx.display.statusConfig.label,
+    link: tx.display.explorerUrl
+  })),
+  wallets: wallets.map(w => ({
+    address: w.shortAddress,
+    chain: w.chain,
+    isPrimary: w.isPrimary
+  }))
+});
+```
+
+### NFT Marketplace Integration
+
+```javascript
+// Connect wallet
+const { user } = await cf.auth.connectWallet('metamask', { chain: 'polygon' });
+
+// Buy NFT - one line transaction
+const tx = await cf.transactions.send({
+  to: nftContractAddress,
+  amount: '0.05 MATIC',
+  data: encodeBuyNFT(tokenId)  // Your encoding function
+});
+
+await tx.wait();
+alert('NFT purchased successfully!');
+```
+
+### Multi-Chain Wallet Viewer
+
+```javascript
+const cf = new ChainForge({ apiKey: '...' });
+await cf.auth.connectWallet('metamask');
+
+// Get balances across all chains
+const chains = ['ethereum', 'polygon', 'bnb', 'avalanche', 'arbitrum', 'optimism'];
+const balances = await Promise.all(
+  chains.map(chain => cf.data.getBalance(null, chain).catch(() => null))
+);
+
+// Show portfolio
+const portfolio = chains.reduce((acc, chain, i) => {
+  if (balances[i]) acc[chain] = balances[i];
+  return acc;
+}, {});
+
+console.log(portfolio);
+// {
+//   ethereum: { formatted: "1.5", symbol: "ETH" },
+//   polygon: { formatted: "100", symbol: "MATIC" },
+//   ...
+// }
+```
+
+## 🔧 Configuration
+
+### Constructor Options
+
+```javascript
+const cf = new ChainForge({
+  apiKey: 'required-api-key',
+  baseURL: 'https://api.chainforge.io',  // Optional
+  timeout: 30000  // Request timeout in ms
+});
+```
+
+### Error Handling
+
+```javascript
+import { ChainForge, ChainForgeError } from '@chainforge/sdk';
+
+try {
+  await cf.auth.connectWallet('metamask');
+} catch (error) {
+  if (error instanceof ChainForgeError) {
+    console.log(error.code);     // 'WALLET_NOT_INSTALLED'
+    console.log(error.message);  // 'MetaMask is not installed'
+    console.log(error.status);   // HTTP status code
+    
+    // Show user-friendly message
+    if (error.code === 'WALLET_NOT_INSTALLED') {
+      showInstallPrompt(error.installUrl);
+    }
+  }
+}
+```
+
+### Error Codes
+
+- `WALLET_NOT_INSTALLED` - User needs to install wallet extension
+- `USER_REJECTED` - User rejected the connection/transaction
+- `NOT_AUTHENTICATED` - User needs to login first
+- `MISSING_ADDRESS` - No wallet address provided
+- `INVALID_AMOUNT` - Wrong format for amount
+- `NETWORK_ERROR` - Connection issue
+- `CHAIN_NOT_SUPPORTED` - Selected chain not available
+
+## 🌐 Supported Chains
+
+| Chain | ID | Type | Wallets |
+|-------|-----|------|---------|
+| Ethereum | `ethereum` | EVM | MetaMask, Phantom (EVM), Brave, Coinbase, Trust |
+| Polygon | `polygon` | EVM | MetaMask, Phantom (EVM), Brave, Coinbase, Trust |
+| BNB Chain | `bnb` | EVM | MetaMask, Brave, Coinbase, Trust |
+| Avalanche | `avalanche` | EVM | MetaMask, Brave, Coinbase, Trust |
+| Arbitrum | `arbitrum` | EVM | MetaMask, Brave, Coinbase, Trust |
+| Optimism | `optimism` | EVM | MetaMask, Brave, Coinbase, Trust |
+| Solana | `solana` | Solana | Phantom, Brave, Coinbase, Trust |
+
+## 📱 React Integration
+
+```jsx
+import { useEffect, useState } from 'react';
+import { ChainForge } from '@chainforge/sdk';
+
+const cf = new ChainForge({ apiKey: '...' });
+
+function App() {
+  const [user, setUser] = useState(null);
+  const [balance, setBalance] = useState(null);
+
+  useEffect(() => {
+    // Restore session on load
+    cf.restoreSession().then(() => {
+      setUser(cf.currentUser);
+    });
+  }, []);
+
+  const connect = async () => {
+    const { user } = await cf.auth.connectWallet('metamask');
+    setUser(user);
+    
+    // Load balance
+    const bal = await cf.data.getBalance();
+    setBalance(bal);
+  };
+
+  return (
+    <div>
+      {user ? (
+        <div>
+          <p>Connected: {user.address}</p>
+          <p>Balance: {balance?.formatted} {balance?.symbol}</p>
+          <button onClick={() => cf.auth.signOut()}>Disconnect</button>
+        </div>
+      ) : (
+        <button onClick={connect}>Connect Wallet</button>
+      )}
+    </div>
+  );
+}
+```
+
+## 🔒 Security
+
+- API keys are scoped per project
+- All requests use HTTPS
+- Wallet private keys never leave the user's device
+- Authentication via JWT with automatic refresh
+- Rate limiting on all endpoints
+
+## 📚 Resources
+
+- [Documentation](https://docs.chainforge.io)
+- [Dashboard](https://chainforge.io/dashboard)
+- [GitHub](https://github.com/chainforge/sdk)
+- [Discord](https://discord.gg/chainforge)
+
+## 💡 Need Help?
+
+- **Dashboard**: Manage API keys, view analytics, configure webhooks
+- **Support**: support@chainforge.io
+- **Discord**: Join our community for real-time help
+
+---
+
+**Built with ❤️ by the ChainForge team**
+
+*Making Web3 as easy as Web2*

package/chainforge-sdk.js

@@ -0,0 +1,731 @@
+/**
+ * ChainForge SDK
+ * The Firebase of Web3 - Simple, powerful Web3 integration
+ *
+ * @example
+ * import { ChainForge } from '@chainforge/sdk';
+ *
+ * const cf = new ChainForge({ apiKey: 'your-api-key' });
+ *
+ * // Auth with wallet - as simple as Firebase Auth
+ * const user = await cf.auth.connectWallet('metamask');
+ *
+ * // Read blockchain data - no Web3 knowledge needed
+ * const balance = await cf.data.getBalance(user.address);
+ *
+ * // Send transactions - abstracted complexity
+ * await cf.transactions.send({
+ *   to: '0x...',
+ *   amount: '0.1 ETH'
+ * });
+ */
+
+class ChainForgeSDK {
+  constructor(config = {}) {
+    this.apiKey = config.apiKey;
+    this.baseURL = config.baseURL || "https://api.chainforge.io";
+    this.timeout = config.timeout || 30000;
+
+    // Initialize sub-modules
+    this.auth = new AuthModule(this);
+    this.data = new DataModule(this);
+    this.transactions = new TransactionModule(this);
+    this.wallets = new WalletModule(this);
+    this.webhooks = new WebhookModule(this);
+
+    // State
+    this._user = null;
+    this._token = null;
+  }
+
+  /**
+   * Make authenticated API request
+   */
+  async _request(method, endpoint, data = null, options = {}) {
+    const url = `${this.baseURL}${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      ...options.headers,
+    };
+
+    if (this._token) {
+      headers["Authorization"] = `Bearer ${this._token}`;
+    }
+
+    const config = {
+      method,
+      headers,
+      ...options,
+    };
+
+    if (data && method !== "GET") {
+      config.body = JSON.stringify(data);
+    }
+
+    try {
+      const response = await fetch(url, config);
+      const result = await response.json();
+
+      if (!response.ok) {
+        throw new ChainForgeError(
+          result.error?.message || `HTTP ${response.status}`,
+          result.error?.code || "UNKNOWN_ERROR",
+          response.status,
+        );
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof ChainForgeError) throw error;
+      throw new ChainForgeError(error.message, "NETWORK_ERROR");
+    }
+  }
+
+  /**
+   * Set auth token (called after successful auth)
+   */
+  _setAuth(token, user) {
+    this._token = token;
+    this._user = user;
+
+    // Store in localStorage for persistence
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("chainforge_token", token);
+      localStorage.setItem("chainforge_user", JSON.stringify(user));
+    }
+  }
+
+  /**
+   * Get current user
+   */
+  get currentUser() {
+    return this._user;
+  }
+
+  /**
+   * Check if user is authenticated
+   */
+  get isAuthenticated() {
+    return !!this._token;
+  }
+
+  /**
+   * Restore session from storage
+   */
+  async restoreSession() {
+    if (typeof localStorage === "undefined") return false;
+
+    const token = localStorage.getItem("chainforge_token");
+    const userStr = localStorage.getItem("chainforge_user");
+
+    if (token && userStr) {
+      this._token = token;
+      this._user = JSON.parse(userStr);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Sign out
+   */
+  async signOut() {
+    this._token = null;
+    this._user = null;
+
+    if (typeof localStorage !== "undefined") {
+      localStorage.removeItem("chainforge_token");
+      localStorage.removeItem("chainforge_user");
+    }
+  }
+}
+
+/**
+ * Custom error class
+ */
+class ChainForgeError extends Error {
+  constructor(message, code, status = null) {
+    super(message);
+    this.name = "ChainForgeError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * Auth Module - Wallet Authentication (like Firebase Auth)
+ */
+class AuthModule {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this._walletSDK = null;
+  }
+
+  /**
+   * Connect wallet and authenticate
+   * @param {string} walletType - 'metamask', 'phantom', 'brave', 'coinbase', 'trust'
+   * @param {Object} options - { chain: 'ethereum', silent: false }
+   * @returns {Promise<{user: Object, token: string}>}
+   *
+   * @example
+   * const { user, token } = await cf.auth.connectWallet('metamask');
+   * console.log(user.address); // 0x...
+   * console.log(user.chain);   // ethereum
+   */
+  async connectWallet(walletType, options = {}) {
+    const chain = options.chain || "ethereum";
+
+    // Check if wallet is installed
+    const wallet = this._detectWallet(walletType);
+    if (!wallet.installed) {
+      throw new ChainForgeError(
+        `${wallet.name} is not installed`,
+        "WALLET_NOT_INSTALLED",
+      );
+    }
+
+    // Connect to wallet
+    const connection = await this._connectToWallet(walletType, chain);
+
+    // Request nonce + canonical message from backend
+    const nonceResult = await this.sdk._request(
+      "GET",
+      `/api/auth/wallet/nonce?address=${encodeURIComponent(connection.address)}&chain=${encodeURIComponent(chain)}`,
+    );
+
+    // Ask wallet to sign the exact server-provided message
+    const signature = await this._signWalletMessage(
+      walletType,
+      nonceResult.message,
+      connection.address,
+    );
+
+    // Complete auth using compatibility endpoint
+    const authResult = await this.sdk._request(
+      "POST",
+      "/api/client/wallet-auth",
+      {
+        walletAddress: connection.address,
+        chain,
+        signature,
+        message: nonceResult.message,
+      },
+    );
+
+    // Store auth
+    this.sdk._setAuth(authResult.token, authResult.user);
+
+    return {
+      user: authResult.user,
+      token: authResult.token,
+      wallet: connection,
+    };
+  }
+
+  /**
+   * Login with email/password
+   */
+  async loginWithEmail(email, password) {
+    const result = await this.sdk._request("POST", "/api/client/login", {
+      email,
+      password,
+    });
+
+    this.sdk._setAuth(result.token, result.user);
+
+    return {
+      user: result.user,
+      token: result.token,
+    };
+  }
+
+  /**
+   * Sign up with email/password
+   */
+  async signupWithEmail(email, password, name = "") {
+    const result = await this.sdk._request("POST", "/api/client/signup", {
+      email,
+      password,
+      name,
+    });
+
+    this.sdk._setAuth(result.token, result.user);
+
+    return {
+      user: result.user,
+      token: result.token,
+    };
+  }
+
+  /**
+   * Sign out
+   */
+  async signOut() {
+    await this.sdk.signOut();
+  }
+
+  /**
+   * Get current user
+   */
+  getCurrentUser() {
+    return this.sdk.currentUser;
+  }
+
+  /**
+   * Check if user is logged in
+   */
+  isLoggedIn() {
+    return this.sdk.isAuthenticated;
+  }
+
+  /**
+   * Auto-connect to previously used wallet
+   */
+  async autoConnect() {
+    if (typeof localStorage === "undefined") return null;
+
+    const saved = localStorage.getItem("chainforge_wallet");
+    if (saved) {
+      const { walletId, chainId } = JSON.parse(saved);
+      return this.connectWallet(walletId, { chain: chainId });
+    }
+    return null;
+  }
+
+  _detectWallet(type) {
+    const wallets = {
+      metamask: {
+        name: "MetaMask",
+        installed: typeof window !== "undefined" && window.ethereum?.isMetaMask,
+        installUrl: "https://metamask.io/download/",
+      },
+      phantom: {
+        name: "Phantom",
+        installed: typeof window !== "undefined" && !!window.solana?.isPhantom,
+        installUrl: "https://phantom.app/download",
+      },
+      brave: {
+        name: "Brave Wallet",
+        installed:
+          typeof window !== "undefined" && window.ethereum?.isBraveWallet,
+        installUrl: "https://brave.com/wallet/",
+      },
+      coinbase: {
+        name: "Coinbase Wallet",
+        installed:
+          typeof window !== "undefined" && window.ethereum?.isCoinbaseWallet,
+        installUrl: "https://www.coinbase.com/wallet",
+      },
+    };
+
+    return wallets[type] || { name: type, installed: false };
+  }
+
+  async _connectToWallet(type, chain) {
+    // Simplified - would use ethers.js or @solana/web3.js
+    // This is a placeholder for the actual implementation
+    if (
+      type === "metamask" &&
+      typeof window !== "undefined" &&
+      window.ethereum
+    ) {
+      const accounts = await window.ethereum.request({
+        method: "eth_requestAccounts",
+      });
+      return {
+        address: accounts[0],
+        chain: chain,
+        type: "evm",
+      };
+    }
+
+    if (type === "phantom" && typeof window !== "undefined" && window.solana) {
+      await window.solana.connect();
+      return {
+        address: window.solana.publicKey.toString(),
+        chain: "solana",
+        type: "solana",
+      };
+    }
+
+    throw new ChainForgeError("Wallet connection failed", "CONNECTION_FAILED");
+  }
+
+  _bytesToBase58(bytes) {
+    const alphabet =
+      "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    if (!bytes || bytes.length === 0) return "";
+
+    let digits = [0];
+    for (let i = 0; i < bytes.length; i += 1) {
+      let carry = bytes[i];
+      for (let j = 0; j < digits.length; j += 1) {
+        const value = digits[j] * 256 + carry;
+        digits[j] = value % 58;
+        carry = Math.floor(value / 58);
+      }
+      while (carry > 0) {
+        digits.push(carry % 58);
+        carry = Math.floor(carry / 58);
+      }
+    }
+
+    let result = "";
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i += 1) {
+      result += "1";
+    }
+    for (let i = digits.length - 1; i >= 0; i -= 1) {
+      result += alphabet[digits[i]];
+    }
+    return result;
+  }
+
+  async _signWalletMessage(walletType, message, address) {
+    if (!message || !address) {
+      throw new ChainForgeError(
+        "Missing message or address for wallet signing",
+        "SIGNATURE_INPUT_MISSING",
+      );
+    }
+
+    if (
+      (walletType === "metamask" ||
+        walletType === "brave" ||
+        walletType === "coinbase") &&
+      typeof window !== "undefined" &&
+      window.ethereum
+    ) {
+      return window.ethereum.request({
+        method: "personal_sign",
+        params: [message, address],
+      });
+    }
+
+    if (
+      walletType === "phantom" &&
+      typeof window !== "undefined" &&
+      window.solana?.signMessage
+    ) {
+      const encodedMessage = new TextEncoder().encode(message);
+      const signed = await window.solana.signMessage(encodedMessage, "utf8");
+      const signatureBytes = signed?.signature || signed;
+      return this._bytesToBase58(signatureBytes);
+    }
+
+    throw new ChainForgeError(
+      "Wallet does not support message signing",
+      "SIGNATURE_NOT_SUPPORTED",
+    );
+  }
+}
+
+/**
+ * Data Module - Read blockchain data (no Web3 knowledge needed)
+ */
+class DataModule {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get wallet balance
+   * @param {string} address - Wallet address (defaults to current user)
+   * @param {string} chain - Chain ID (defaults to user's chain)
+   * @returns {Promise<{formatted: string, symbol: string, raw: string}>}
+   *
+   * @example
+   * const balance = await cf.data.getBalance();
+   * console.log(balance.formatted); // "1.5"
+   * console.log(balance.symbol);    // "ETH"
+   */
+  async getBalance(address = null, chain = null) {
+    const user = this.sdk.currentUser;
+    const targetAddress = address || user?.walletAddress;
+    const targetChain = chain || user?.chain || "ethereum";
+
+    if (!targetAddress) {
+      throw new ChainForgeError("No address provided", "MISSING_ADDRESS");
+    }
+
+    const result = await this.sdk._request(
+      "GET",
+      `/api/onchain/balance/${targetAddress}?chain=${targetChain}`,
+    );
+
+    return result.data.nativeBalance;
+  }
+
+  /**
+   * Get transaction history
+   * @param {Object} options
+   * @returns {Promise<Array>} Human-readable transactions
+   *
+   * @example
+   * const history = await cf.data.getHistory({ limit: 10 });
+   * history.forEach(tx => {
+   *   console.log(tx.summary); // "Sent 0.1 ETH to 0x1234..."
+   * });
+   */
+  async getHistory(options = {}) {
+    const user = this.sdk.currentUser;
+    const address = options.address || user?.walletAddress;
+    const chain = options.chain || user?.chain || "ethereum";
+    const limit = options.limit || 20;
+
+    if (!address) {
+      throw new ChainForgeError("No address provided", "MISSING_ADDRESS");
+    }
+
+    const result = await this.sdk._request(
+      "GET",
+      `/api/onchain/history/${address}?chain=${chain}&limit=${limit}`,
+    );
+
+    return result.data.transactions;
+  }
+
+  /**
+   * Get human-readable transaction details
+   * @param {string} hash - Transaction hash
+   * @param {string} chain - Chain ID
+   */
+  async getTransaction(hash, chain = null) {
+    const targetChain = chain || this.sdk.currentUser?.chain || "ethereum";
+
+    const result = await this.sdk._request(
+      "GET",
+      `/api/onchain/humanize/${hash}?chain=${targetChain}`,
+    );
+
+    return result.data;
+  }
+
+  /**
+   * Sync blockchain data to ChainForge
+   * @returns {Promise<{synced: number}>}
+   */
+  async sync() {
+    const result = await this.sdk._request("POST", "/api/onchain/multisync");
+    return result.data;
+  }
+}
+
+/**
+ * Transaction Module - Send transactions (abstracted complexity)
+ */
+class TransactionModule {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Send a transaction
+   * @param {Object} params
+   * @param {string} params.to - Recipient address
+   * @param {string} params.amount - Amount with unit (e.g., "0.1 ETH")
+   * @param {Object} params.options - Additional options
+   * @returns {Promise<{hash: string, explorer: string, wait: Function}>}
+   *
+   * @example
+   * const tx = await cf.transactions.send({
+   *   to: '0x1234...',
+   *   amount: '0.1 ETH'
+   * });
+   * console.log(tx.hash);
+   * await tx.wait(); // Wait for confirmation
+   */
+  async send({ to, amount, data = null, options = {} }) {
+    const user = this.sdk.currentUser;
+
+    if (!user) {
+      throw new ChainForgeError("User not authenticated", "NOT_AUTHENTICATED");
+    }
+
+    // Parse amount (e.g., "0.1 ETH" -> { value: "0.1", symbol: "ETH" })
+    const parsedAmount = this._parseAmount(amount);
+
+    // Auto-estimate gas
+    const gasEstimate =
+      options.gasLimit || (await this._estimateGas(to, parsedAmount));
+
+    // Send via wallet
+    const tx = await this._sendViaWallet({
+      to,
+      value: parsedAmount,
+      data,
+      gasLimit: gasEstimate,
+      ...options,
+    });
+
+    return {
+      hash: tx.hash,
+      explorer: `${this._getExplorerUrl()}/tx/${tx.hash}`,
+      wait: () => this._waitForConfirmation(tx.hash),
+    };
+  }
+
+  /**
+   * Estimate gas for a transaction
+   */
+  async estimateGas(to, amount) {
+    // Would use actual gas estimation
+    return "21000"; // Default for simple transfer
+  }
+
+  _parseAmount(amount) {
+    const match = amount.match(/^([\d.]+)\s*(\w+)$/);
+    if (!match) {
+      throw new ChainForgeError(
+        'Invalid amount format. Use "0.1 ETH"',
+        "INVALID_AMOUNT",
+      );
+    }
+    return {
+      value: match[1],
+      symbol: match[2],
+    };
+  }
+
+  async _sendViaWallet(params) {
+    // Would use ethers.js or @solana/web3.js
+    // Placeholder implementation
+    if (typeof window !== "undefined" && window.ethereum) {
+      const provider = window.ethereum.providers
+        ? new window.ethereum.providers.Web3Provider(window.ethereum)
+        : null;
+      const signer = provider ? provider.getSigner() : null;
+
+      if (signer) {
+        const tx = await signer.sendTransaction({
+          to: params.to,
+          value: window.ethers?.utils.parseEther(params.value.value),
+        });
+        return tx;
+      }
+    }
+
+    throw new ChainForgeError("Wallet not connected", "WALLET_NOT_CONNECTED");
+  }
+
+  _getExplorerUrl() {
+    const chain = this.sdk.currentUser?.chain || "ethereum";
+    const explorers = {
+      ethereum: "https://etherscan.io",
+      polygon: "https://polygonscan.com",
+      bnb: "https://bscscan.com",
+      solana: "https://solscan.io",
+    };
+    return explorers[chain] || explorers.ethereum;
+  }
+
+  async _waitForConfirmation(hash) {
+    // Would poll for confirmation
+    return new Promise((resolve) => {
+      setTimeout(
+        () => resolve({ confirmed: true, blockNumber: 12345678 }),
+        3000,
+      );
+    });
+  }
+}
+
+/**
+ * Wallet Module - Manage multiple wallets
+ */
+class WalletModule {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Get all linked wallets
+   * @returns {Promise<Array>}
+   */
+  async getAll() {
+    const result = await this.sdk._request("GET", "/api/wallets");
+    return result.data.wallets;
+  }
+
+  /**
+   * Link a new wallet
+   * @param {Object} wallet
+   */
+  async link(wallet) {
+    const result = await this.sdk._request("POST", "/api/wallets/link", wallet);
+    return result.data;
+  }
+
+  /**
+   * Unlink a wallet
+   * @param {string} walletId
+   */
+  async unlink(walletId) {
+    await this.sdk._request("DELETE", `/api/wallets/${walletId}`);
+  }
+
+  /**
+   * Set primary wallet
+   * @param {string} walletId
+   */
+  async setPrimary(walletId) {
+    await this.sdk._request("PATCH", `/api/wallets/${walletId}/primary`);
+  }
+}
+
+/**
+ * Webhook Module - Subscribe to on-chain events
+ */
+class WebhookModule {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this._subscriptions = new Map();
+  }
+
+  /**
+   * Subscribe to wallet events
+   * @param {string} event - 'transaction', 'balance_change'
+   * @param {Function} callback
+   * @returns {Function} Unsubscribe function
+   *
+   * @example
+   * const unsubscribe = cf.webhooks.on('transaction', (tx) => {
+   *   console.log('New transaction:', tx.hash);
+   * });
+   */
+  on(event, callback) {
+    if (!this._subscriptions.has(event)) {
+      this._subscriptions.set(event, new Set());
+    }
+
+    this._subscriptions.get(event).add(callback);
+
+    // Return unsubscribe function
+    return () => {
+      this._subscriptions.get(event)?.delete(callback);
+    };
+  }
+
+  /**
+   * Trigger event (internal use)
+   */
+  _trigger(event, data) {
+    this._subscriptions.get(event)?.forEach((callback) => {
+      try {
+        callback(data);
+      } catch (e) {
+        console.error("Webhook callback error:", e);
+      }
+    });
+  }
+}
+
+// Export
+export { ChainForgeSDK, ChainForgeError };
+export default ChainForgeSDK;
+
+// UMD build compatibility
+if (typeof window !== "undefined") {
+  window.ChainForge = ChainForgeSDK;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@chainforge/sdk",
+  "version": "1.0.0",
+  "description": "The Firebase of Web3 - Simple, powerful Web3 integration without blockchain knowledge",
+  "main": "chainforge-sdk.js",
+  "module": "chainforge-sdk.js",
+  "type": "module",
+  "types": "chainforge-sdk.d.ts",
+  "files": [
+    "chainforge-sdk.js",
+    "chainforge-sdk.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "test": "node test/test.js",
+    "test:watch": "node test/test.js --watch",
+    "lint": "eslint chainforge-sdk.js",
+    "format": "prettier --write chainforge-sdk.js",
+    "prepublishOnly": "echo skipping",
+    "prepack": "npm run build",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "version:pre": "npm version prerelease --preid=beta"
+  },
+  "keywords": [
+    "web3",
+    "blockchain",
+    "ethereum",
+    "solana",
+    "wallet",
+    "authentication",
+    "firebase",
+    "sdk",
+    "dapp",
+    "crypto"
+  ],
+  "author": "ChainForge",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chainforge/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/chainforge/sdk/issues"
+  },
+  "homepage": "https://chainforge.io",
+  "peerDependencies": {
+    "ethers": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0",
+    "jest": "^29.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}