fibx 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# fibx
+
+A command-line tool for specialized DeFi operations on **Base**, powered by [Fibrous Finance](https://fibrous.finance) aggregation and [Privy](https://privy.io) Server Wallets.
+
+## Features
+
+- **Privy Server Wallets**: Uses "Agentic" server-side wallets (ownerless) for seamless, automated signing without user interaction.
+- **ETH & Token Transfers**: Send ETH or any ERC-20 token with a simple command.
+- **Fibrous Aggregation**: Execute token swaps with optimal routing and auto-slippage protection.
+- **Automated Auth Flow**: One-time email OTP login provisions a persistent server wallet linked to your user profile.
+- **JSON Output**: All commands support `--json` for easy integration into scripts and pipelines.
+
+## Requirements
+
+- Node.js ≥ 20
+- pnpm
+- Privy App ID and Secret (from [dashboard.privy.io](https://dashboard.privy.io))
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Configure Environment
+
+Copy the example environment file and add your Privy credentials:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+PRIVY_APP_ID=your_app_id
+PRIVY_APP_SECRET=your_app_secret
+```
+
+### 3. Authenticate & Provision Wallet
+
+This two-step process links your email to a server-side wallet.
+
+**Step 1: Request OTP**
+
+```bash
+pnpm dev auth login <email>
+# Example:
+pnpm dev auth login user@example.com
+```
+
+**Step 2: Verify & Create Session**
+
+```bash
+pnpm dev auth verify <email> <code>
+# Example:
+pnpm dev auth verify user@example.com 123456
+```
+
+_Successfully verifying will create a local session file and provision a Server Wallet if one doesn't exist._
+
+### 4. Check Status
+
+Verify that you are authenticated and the API is healthy:
+
+```bash
+pnpm dev status
+```
+
+## Usage
+
+### Check Balance
+
+View your ETH and USDC balances on Base:
+
+```bash
+pnpm dev balance
+```
+
+### Send Tokens
+
+Transfer ETH or ERC-20 tokens to another address.
+
+**Send ETH (Default):**
+
+```bash
+pnpm dev send 0.001 0xRecipientAddress
+```
+
+**Send ERC-20 (e.g., USDC):**
+
+```bash
+pnpm dev send 10 0xRecipientAddress USDC
+```
+
+### Swap Tokens
+
+Swap tokens using Fibrous Finance's aggregator.
+
+```bash
+pnpm dev trade <amount> <from_token> <to_token>
+```
+
+**Examples:**
+
+```bash
+# Swap 0.0001 ETH to USDC
+pnpm dev trade 0.0001 ETH USDC
+
+# Swap 20 USDC to DAI
+pnpm dev trade 20 USDC DAI
+```
+
+**Options:**
+
+- `--slippage <number>`: Set slippage tolerance (default: 0.5%)
+- `--json`: Output result as JSON
+
+### View Wallet Address
+
+Print your connected server wallet address:
+
+```bash
+pnpm dev address
+```
+
+# Architecture
+
+This CLI uses a **Server Wallet** architecture:
+
+1.  **Privy**: Manages the embedded wallets. We use "Ownerless" wallets (Agents) that are controlled via the Privy App Secret, allowing the CLI to sign transactions programmatically without requiring a user-side browser or JWT.
+2.  **Viem**: Handles all blockchain interactions (RPC calls, transaction signing) using a custom Privy-backed account.
+3.  **Fibrous**: Provides the routing and calldata for optimal token swaps on Base.
+
+## Project Structure
+
+```
+src/
+├── cli.ts               # Entry point & Command definitions
+├── commands/            # Command implementation logic
+│   ├── auth-login.ts    # Step 1: Request OTP
+│   ├── auth-verify.ts   # Step 2: Verify & Provision Wallet
+│   ├── trade.ts         # Swap logic via Fibrous
+│   ├── send.ts          # ETH/ERC20 transfer logic
+│   └── ...
+├── chain/               # Blockchain layer
+│   └── viem.ts          # Viem client & Custom Privy Account
+├── wallet/              # Wallet management
+│   ├── privy.ts         # Privy SDK integration (Server Wallets)
+│   └── session.ts       # Local session management
+├── fibrous/             # Fibrous API integration
+└── utils/               # Config, validation, and helpers
+```
+
+## License
+
+MIT

package/dist/chain/chains.d.ts

@@ -0,0 +1,14 @@
+import type { Abi } from "viem";
+import { base } from "viem/chains";
+export interface ChainConfig {
+    id: number;
+    name: string;
+    viemChain: typeof base;
+    rpcUrl: string;
+    nativeTokenAddress: string;
+    fibrousNetwork: string;
+    routerAbi: Abi;
+}
+export declare const SUPPORTED_CHAINS: Record<string, ChainConfig>;
+export declare function getChainConfig(network: string): ChainConfig;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chain/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../src/chain/chains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGnC,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,GAAG,CAAC;CACf;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAUxD,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAQ3D"}

package/dist/chain/chains.js

@@ -0,0 +1,21 @@
+import { base } from "viem/chains";
+import { baseRouterAbi } from "../fibrous/abi/base.js";
+export const SUPPORTED_CHAINS = {
+    base: {
+        id: 8453,
+        name: "base",
+        viemChain: base,
+        rpcUrl: "https://mainnet.base.org",
+        nativeTokenAddress: "0x0000000000000000000000000000000000000000",
+        fibrousNetwork: "base",
+        routerAbi: baseRouterAbi,
+    },
+};
+export function getChainConfig(network) {
+    const config = SUPPORTED_CHAINS[network];
+    if (!config) {
+        throw new Error(`Unsupported chain: ${network}. Supported: ${Object.keys(SUPPORTED_CHAINS).join(", ")}`);
+    }
+    return config;
+}
+//# sourceMappingURL=chains.js.map

package/dist/chain/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../../src/chain/chains.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAYvD,MAAM,CAAC,MAAM,gBAAgB,GAAgC;IAC5D,IAAI,EAAE;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,0BAA0B;QAClC,kBAAkB,EAAE,4CAA4C;QAChE,cAAc,EAAE,MAAM;QACtB,SAAS,EAAE,aAAoB;KAC/B;CACD,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,OAAe;IAC7C,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACd,sBAAsB,OAAO,gBAAgB,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvF,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/chain/erc20.d.ts

@@ -0,0 +1,6 @@
+import { type Address } from "viem";
+export declare function getERC20Balance(tokenAddress: Address, walletAddress: Address): Promise<bigint>;
+export declare function encodeTransfer(to: Address, amount: bigint): `0x${string}`;
+export declare function encodeApprove(spender: Address, amount: bigint): `0x${string}`;
+export declare function getAllowance(tokenAddress: Address, owner: Address, spender: Address): Promise<bigint>;
+//# sourceMappingURL=erc20.d.ts.map

package/dist/chain/erc20.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc20.d.ts","sourceRoot":"","sources":["../../src/chain/erc20.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AA2CxD,wBAAsB,eAAe,CACpC,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,GACpB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAMzE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAM7E;AAED,wBAAsB,YAAY,CACjC,YAAY,EAAE,OAAO,EACrB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/chain/erc20.js

@@ -0,0 +1,72 @@
+import { encodeFunctionData } from "viem";
+import { publicClient } from "./viem.js";
+const ERC20_ABI = [
+    {
+        name: "balanceOf",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "transfer",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        name: "approve",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "spender", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        name: "allowance",
+        type: "function",
+        stateMutability: "view",
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+];
+export async function getERC20Balance(tokenAddress, walletAddress) {
+    return publicClient.readContract({
+        address: tokenAddress,
+        abi: ERC20_ABI,
+        functionName: "balanceOf",
+        args: [walletAddress],
+    });
+}
+export function encodeTransfer(to, amount) {
+    return encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: "transfer",
+        args: [to, amount],
+    });
+}
+export function encodeApprove(spender, amount) {
+    return encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: "approve",
+        args: [spender, amount],
+    });
+}
+export async function getAllowance(tokenAddress, owner, spender) {
+    return publicClient.readContract({
+        address: tokenAddress,
+        abi: ERC20_ABI,
+        functionName: "allowance",
+        args: [owner, spender],
+    });
+}
+//# sourceMappingURL=erc20.js.map

package/dist/chain/erc20.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc20.js","sourceRoot":"","sources":["../../src/chain/erc20.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAgB,MAAM,MAAM,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,SAAS,GAAG;IACjB;QACC,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACxC;IACD;QACC,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACP,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;YAC/B,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;SACnC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACrC;IACD;QACC,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACP,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;SACnC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACrC;IACD;QACC,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE;YACP,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;YAClC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;SACpC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACxC;CACQ,CAAC;AAEX,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,YAAqB,EACrB,aAAsB;IAEtB,OAAO,YAAY,CAAC,YAAY,CAAC;QAChC,OAAO,EAAE,YAAY;QACrB,GAAG,EAAE,SAAS;QACd,YAAY,EAAE,WAAW;QACzB,IAAI,EAAE,CAAC,aAAa,CAAC;KACrB,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAW,EAAE,MAAc;IACzD,OAAO,kBAAkB,CAAC;QACzB,GAAG,EAAE,SAAS;QACd,YAAY,EAAE,UAAU;QACxB,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,MAAc;IAC7D,OAAO,kBAAkB,CAAC;QACzB,GAAG,EAAE,SAAS;QACd,YAAY,EAAE,SAAS;QACvB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,YAAqB,EACrB,KAAc,EACd,OAAgB;IAEhB,OAAO,YAAY,CAAC,YAAY,CAAC;QAChC,OAAO,EAAE,YAAY;QACrB,GAAG,EAAE,SAAS;QACd,YAAY,EAAE,WAAW;QACzB,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC;KACtB,CAAC,CAAC;AACJ,CAAC"}