browser-rpc 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,152 @@
+# browser-rpc
+
+A local RPC proxy that routes Ethereum transactions through your browser wallet instead of requiring private keys in `.env` files.
+
+## The Problem
+
+Deploying smart contracts requires signing transactions with a private key. Most developers use a separate "deployer" wallet with the key stored in a `.env` file, which:
+
+- Is less secure than a browser wallet or hardware wallet
+- Requires maintaining ETH balances across multiple chains
+- Is tedious to set up and manage
+
+## The Solution
+
+`browser-rpc` is a local proxy server that intercepts transaction requests from your development tools (Foundry, Hardhat, viem scripts) and routes them through your browser wallet for signing.
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Foundry/HH     │────▶│   browser-rpc   │────▶│  Upstream RPC   │
+│  Script         │◀────│ (localhost:8545)│◀────│  (Alchemy, etc) │
+└─────────────────┘     └────────┬────────┘     └─────────────────┘
+                                 │
+                                 │ Opens browser for signing
+                                 ▼
+                        ┌─────────────────┐     ┌─────────────────┐
+                        │    Web UI       │────▶│  Browser Wallet │
+                        │ (localhost:8545)│◀────│  (MetaMask)     │
+                        └─────────────────┘     └─────────────────┘
+```
+
+## Installation
+
+```bash
+npm install -g browser-rpc
+```
+
+Or run directly with npx:
+
+```bash
+npx browser-rpc --rpc https://mainnet.base.org
+```
+
+## Usage
+
+1. Start the proxy server pointing to your target network:
+
+```bash
+browser-rpc --rpc https://mainnet.base.org
+```
+
+2. Configure your tool to use `http://localhost:8545` as the RPC URL
+
+3. Run your script - when it sends a transaction, your browser will open for approval
+
+### With Foundry
+
+```bash
+# Start the proxy
+browser-rpc --rpc https://mainnet.base.org
+
+# In another terminal, run your script
+forge script script/Deploy.s.sol --rpc-url http://localhost:8545 --broadcast
+```
+
+### With Hardhat
+
+```javascript
+// hardhat.config.js
+module.exports = {
+  networks: {
+    browserRpc: {
+      url: 'http://localhost:8545',
+    },
+  },
+}
+```
+
+```bash
+npx hardhat run scripts/deploy.js --network browserRpc
+```
+
+### With viem
+
+```typescript
+import { createWalletClient, http } from 'viem'
+import { base } from 'viem/chains'
+
+const client = createWalletClient({
+  chain: base,
+  transport: http('http://localhost:8545'),
+})
+
+// This will open your browser for approval
+const hash = await client.sendTransaction({
+  to: '0x...',
+  value: parseEther('0.01'),
+})
+```
+
+## CLI Options
+
+| Flag           | Default    | Description                      |
+| -------------- | ---------- | -------------------------------- |
+| `--rpc`, `-r`  | (required) | Upstream RPC URL for read calls  |
+| `--port`, `-p` | `8545`     | Port for the proxy server        |
+| `--no-open`    | `false`    | Disable auto-opening the browser |
+
+## How It Works
+
+1. Your script sends `eth_sendTransaction` to the proxy
+2. The proxy holds the connection open and opens a browser UI
+3. You connect your wallet and review the transaction
+4. Click "Execute" to sign and send via your wallet
+5. The transaction hash is returned to your script
+
+Read-only calls (`eth_call`, `eth_getBalance`, etc.) pass through directly to the upstream RPC.
+
+## Supported Methods
+
+| Method                 | Behavior                       |
+| ---------------------- | ------------------------------ |
+| `eth_sendTransaction`  | Opens browser for signing      |
+| `eth_signTypedData_v4` | Opens browser for signing      |
+| `eth_sign`             | Opens browser for signing      |
+| Everything else        | Passes through to upstream RPC |
+
+## Chain Support
+
+The proxy automatically detects the chain from your upstream RPC and configures the UI accordingly. Any EVM-compatible chain is supported.
+
+If your wallet is connected to the wrong chain, the UI will prompt you to switch.
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/gskril/browser-rpc.git
+cd browser-rpc
+
+# Install dependencies
+bun install
+
+# Build everything
+bun run build
+
+# Start the dev server
+bun run dev:server -- --rpc https://mainnet.base.org
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -3801,7 +3801,6 @@ function createPendingEntry(id, request) {
     request,
     resolve: resolvePromise
   });
-  console.log(`\uD83D\uDD10 Pending saved: id=${id} type=${request.type} jsonrpc=${request.jsonRpcId}`);
   setTimeout(() => {
     const entry = pending.get(id);
     if (entry) {
@@ -3854,10 +3853,10 @@ api.post("/tx/:id/hash", async (c) => {
   }
   const request = getPendingRequest(id);
   if (!request) {
-    console.warn(`\uD83D\uDD10 Pending missing: id=${id} hash=${body.hash}`);
+    console.warn(`\x1B[31m✗ Unknown request:\x1B[0m ${id}`);
     return c.json({ error: "Request not found or expired" }, 404);
   }
-  console.log(`\uD83D\uDD10 Tx submitted: ${body.hash}`);
+  console.log(`\x1B[32m✓ Submitted:\x1B[0m ${body.hash}`);
   return c.json({ ok: true });
 });
 api.post("/complete/:id", async (c) => {
@@ -4093,7 +4092,7 @@ function createServer(config) {
       const body = await c.req.json();
       if (Array.isArray(body)) {
         const methods = body.map((req) => req.method).join(", ");
-        console.log(`  RPC batch: [${methods}]`);
+        console.log(`\x1B[2m← [${methods}]\x1B[0m`);
         const responses = await Promise.all(body.map((req) => handleRpcRequest(req, {
           upstreamRpcUrl: config.upstreamRpcUrl,
           uiBaseUrl: `http://localhost:${config.port}`,
@@ -4101,7 +4100,7 @@ function createServer(config) {
         })));
         return c.json(responses);
       }
-      console.log(`  RPC: ${body.method}`);
+      console.log(`\x1B[2m← ${body.method}\x1B[0m`);
       const response = await handleRpcRequest(body, {
         upstreamRpcUrl: config.upstreamRpcUrl,
         uiBaseUrl: `http://localhost:${config.port}`,
@@ -4160,7 +4159,7 @@ var server = createServer({
   port,
   onPendingRequest: (id, url) => {
     console.log(`
-\uD83D\uDD10 Transaction pending: ${url}`);
+\x1B[33m\u23F3 Awaiting approval:\x1B[0m ${url}`);
     if (options.open) {
       openBrowser(url);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-rpc",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Local RPC proxy that routes Ethereum transactions through your browser wallet",
   "type": "module",
   "repository": {
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "web-dist"
+    "web-dist",
+    "README.md"
   ],
   "scripts": {
     "dev": "bun run --watch src/index.ts",