@cicero-zcash/react 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 🛡️ Cicero
+
+### The RainbowKit for Shielded Zcash
+
+**Universal wallet connection, bi-directional network synchronization, and multi-wallet state management for React and Next.js applications.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-3ecf8e.svg)](https://opensource.org/licenses/MIT)
+[![NPM Version](https://img.shields.io/npm/v/@cicero-zcash/react?color=3ecf8e)](https://www.npmjs.com/package/@cicero-zcash/react)
+[![Zcash](https://img.shields.io/badge/Zcash-Shielded-171717?logo=zcash&logoColor=3ecf8e)](https://z.cash)
+[![Design](https://img.shields.io/badge/Design-Supabase%20Tokens-3ecf8e)](./DESIGN.md)
+
+[Quickstart](#-quickstart) • [React Hooks](#-react-hooks) • [Wallets Supported](#-supported-wallets) • [Components](#-components)
+
+---
+
+</div>
+
+## 📖 What is Cicero?
+
+**Cicero** is the **"RainbowKit of Zcash"**. It provides a drop-in, zero-knowledge native wallet connection suite:
+
+- 🥒 **Zucchini Chrome Extension:** 1-click in-browser connection and shielded account detection.
+- 📱 **Mobile & Desktop Wallets:** Zashi (Electric Coin Co.) and Ywallet QR handoff.
+- 🔑 **Viewing Key Mode:** Audit and read-only treasury dashboard connection.
+- 🔄 **Bi-Directional Network Sync:** Automatically detects Mainnet vs Testnet from wallet address prefixes and listens to extension network change events.
+- 💰 **Per-Network Balance Segregation:** Independent balance caching for Mainnet and Testnet with live USD conversion.
+
+```tsx
+import { CiceroProvider, CiceroConnectButton, useAccount, useBalance } from '@cicero-zcash/react';
+
+export default function App() {
+  return (
+    <CiceroProvider initialNetwork="mainnet">
+      <nav className="flex justify-between p-4 border-b">
+        <span>My Zcash dApp</span>
+        <CiceroConnectButton variant="primary" size="md" />
+      </nav>
+      <Dashboard />
+    </CiceroProvider>
+  );
+}
+
+function Dashboard() {
+  const { address, isConnected, wallet } = useAccount();
+  const { zec, usd } = useBalance();
+
+  if (!isConnected) return <p>Please connect your Zcash wallet.</p>;
+
+  return (
+    <div>
+      <p>Connected to {wallet?.name}</p>
+      <p>Address: {address}</p>
+      <p>Balance: {zec} ZEC (~${usd} USD)</p>
+    </div>
+  );
+}
+```
+
+---
+
+## ⚡ Features
+
+- **🛡️ Shielded-First Architecture:** Built specifically for Zcash's Unified Address standard (ZIP-316), Sapling (`zs1`), and Transparent (`t1`) pools.
+- **🔄 Live Network & Chain Synchronization:** Listens to wallet extension events (`networkChanged`, `accountsChanged`). Switching between Mainnet and Testnet inside Zucchini immediately updates Cicero and queries the new balance.
+- **💼 RainbowKit-Style Connected Pill:** Displays active network indicator (green/amber dot), current ZEC balance, and truncated address. Clicking opens an account drawer with address copying, QR code receive view, and network switch assistance.
+- **🎨 Supabase Design Language:** Styled with Supabase tokens (`#3ecf8e` emerald accents, `#171717` ink typography, 6px button radii, clean border tokens).
+- **🪙 Live Fiat Conversions:** `useZcashPrice()` hook provides cached, rate-limited ZEC/USD pricing with automatic fallback.
+
+---
+
+## 🚀 Quickstart
+
+### 1. Install
+
+```bash
+pnpm add @cicero-zcash/react
+# or
+npm install @cicero-zcash/react
+# or
+yarn add @cicero-zcash/react
+```
+
+### 2. Wrap your app in `<CiceroProvider>`
+
+```tsx
+import { CiceroProvider } from '@cicero-zcash/react';
+
+export function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <CiceroProvider initialNetwork="mainnet" appName="My Zcash dApp">
+      {children}
+    </CiceroProvider>
+  );
+}
+```
+
+### 3. Add the `<CiceroConnectButton />`
+
+```tsx
+import { CiceroConnectButton } from '@cicero-zcash/react';
+
+export function Header() {
+  return (
+    <header className="flex justify-between items-center p-4">
+      <h1>Zcash Portal</h1>
+      <CiceroConnectButton variant="primary" size="md" />
+    </header>
+  );
+}
+```
+
+---
+
+## 🪝 React Hooks
+
+Cicero exports familiar, ergonomic hooks modeled after RainbowKit and wagmi:
+
+### `useAccount()`
+```tsx
+const {
+  address,        // string | null - Active shielded or transparent address
+  isConnected,    // boolean - Whether a wallet is connected
+  isConnecting,   // boolean - True during connection handshake
+  wallet,         // ZcashWallet | null - Active wallet adapter metadata
+  disconnect,     // () => Promise<void> - Disconnect handler
+} = useAccount();
+```
+
+### `useBalance()`
+```tsx
+const {
+  zec,            // number - Shielded balance in ZEC
+  usd,            // string | null - Estimated USD equivalent
+  isLoading,      // boolean - True when querying balance
+  refetch,        // () => Promise<void> - Re-queries balance from wallet/RPC
+} = useBalance();
+```
+
+### `useCicero()`
+Full context access including network state, modal controls, and raw wallet methods:
+```tsx
+const {
+  account,
+  network,        // 'mainnet' | 'testnet'
+  switchNetwork,  // (net: 'mainnet' | 'testnet') => Promise<SwitchResult>
+  openConnectModal,
+  closeConnectModal,
+  openAccountModal,
+  closeAccountModal,
+} = useCicero();
+```
+
+### `useZucchiniWallet()`
+Direct low-level hook for interacting with the Zucchini browser extension:
+```tsx
+const {
+  isAvailable,    // boolean - True if Zucchini Chrome extension is installed
+  isConnected,    // boolean
+  connect,        // () => Promise<WalletSession>
+  address,        // string | null
+  network,        // 'mainnet' | 'testnet'
+  getBalance,     // () => Promise<number | null>
+} = useZucchiniWallet();
+```
+
+---
+
+## 🔌 Supported Wallets
+
+| Wallet | Type | Support | Features |
+|---|---|---|---|
+| **Zucchini** | Chrome Extension | Direct in-browser | 1-click connect, live network sync, shielded balance |
+| **Zashi** | Mobile (iOS/Android) | QR Handoff | Electric Coin Co. official wallet |
+| **Ywallet** | Desktop & Mobile | QR Handoff | Multi-platform shielded wallet |
+| **Viewing Key** | Read-Only | Manual Input | Auditor compliance, treasury dashboards |
+| **Burner Wallet**| Dev / Sandbox | Ephemeral | Instant testing in development |
+
+---
+
+## 🧩 Components
+
+### `<CiceroConnectButton />`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'primary' \| 'outline' \| 'dark'` | `'primary'` | Visual style token |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button dimensions |
+| `showBalance` | `boolean` | `true` | Show balance in connected pill |
+| `showNetwork` | `boolean` | `true` | Show network indicator dot |
+| `label` | `string` | `'Connect Zcash Wallet'` | Custom disconnect trigger text |
+| `className` | `string` | `''` | Custom CSS class names |
+
+---
+
+## 📄 License
+
+MIT © [Kaycee276](https://github.com/Kaycee276)

package/dist/index.d.mts

@@ -0,0 +1,374 @@
+import React from 'react';
+
+type ZcashAddressType = 'unified' | 'sapling' | 'transparent' | 'unknown';
+type ZcashNetwork = 'mainnet' | 'testnet';
+type CiceroTheme = 'supabase' | 'emerald' | 'dark' | 'light';
+interface Zip321PaymentRequest {
+    address: string;
+    amount?: string;
+    memo?: string;
+    message?: string;
+    rawUri: string;
+}
+
+type WalletCategory = 'extension' | 'mobile' | 'desktop' | 'read-only' | 'developer';
+interface WalletSession$1 {
+    address?: string;
+    viewingKey?: string;
+    network?: ZcashNetwork;
+    connected: boolean;
+    walletId: string;
+    balance?: number;
+}
+interface SendPaymentParams {
+    recipient: string;
+    amount: number | string;
+    memo?: string;
+    message?: string;
+}
+interface SendPaymentResult {
+    txId: string;
+    submitted: boolean;
+    rawUri?: string;
+}
+interface ZcashWallet {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    category: WalletCategory;
+    downloadUrl?: string;
+    isAvailable: () => boolean;
+    connect: (options?: {
+        network?: ZcashNetwork;
+    }) => Promise<WalletSession$1>;
+    disconnect?: () => Promise<void>;
+    getBalance?: (options?: {
+        address?: string;
+        network?: ZcashNetwork;
+    }) => Promise<number | null>;
+    getNetwork?: () => Promise<ZcashNetwork>;
+    switchNetwork?: (network: ZcashNetwork) => Promise<{
+        success: boolean;
+        requiresManualSwitch?: boolean;
+        currentNetwork?: ZcashNetwork;
+    }>;
+    sendPayment?: (params: SendPaymentParams) => Promise<SendPaymentResult>;
+}
+
+declare const zucchiniWallet: ZcashWallet;
+
+declare const zashiWallet: ZcashWallet;
+
+declare const ywallet: ZcashWallet;
+
+declare const viewingKeyWallet: ZcashWallet;
+
+declare const burnerWallet: ZcashWallet;
+
+/**
+ * Returns the default suite of supported Zcash wallets.
+ * Zucchini will be marked as available if the browser extension is detected.
+ */
+declare function getDefaultWallets(): ZcashWallet[];
+
+interface AccountState {
+    address: string | null;
+    viewingKey: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    status: 'disconnected' | 'connecting' | 'connected' | 'error';
+    wallet: ZcashWallet | null;
+    error: string | null;
+}
+interface BalanceState {
+    zec: number;
+    usd: string | null;
+    isLoading: boolean;
+}
+interface CiceroContextType {
+    account: AccountState;
+    address: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    wallet: ZcashWallet | null;
+    network: ZcashNetwork;
+    switchNetwork: (net: ZcashNetwork) => Promise<{
+        success: boolean;
+        requiresManualSwitch?: boolean;
+        currentNetwork?: ZcashNetwork;
+    }>;
+    balance: BalanceState;
+    refetchBalance: () => Promise<void>;
+    connect: (walletId: string, customAddressOrKey?: string) => Promise<void>;
+    disconnect: () => Promise<void>;
+    sendPayment: (params: SendPaymentParams) => Promise<SendPaymentResult>;
+    isConnectModalOpen: boolean;
+    openConnectModal: () => void;
+    closeConnectModal: () => void;
+    isAccountModalOpen: boolean;
+    openAccountModal: () => void;
+    closeAccountModal: () => void;
+    wallets: ZcashWallet[];
+    appName?: string;
+    appLogo?: string;
+}
+interface CiceroProviderProps {
+    children: React.ReactNode;
+    initialNetwork?: ZcashNetwork;
+    wallets?: ZcashWallet[];
+    appName?: string;
+    appLogo?: string;
+    autoConnect?: boolean;
+}
+declare const CiceroProvider: React.FC<CiceroProviderProps>;
+declare function useCicero(): CiceroContextType;
+declare const useAccount: () => {
+    address: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    wallet: ZcashWallet | null;
+    disconnect: () => Promise<void>;
+    viewingKey: string | null;
+    status: "disconnected" | "connecting" | "connected" | "error";
+    error: string | null;
+};
+declare const useBalance: () => {
+    refetch: () => Promise<void>;
+    zec: number;
+    usd: string | null;
+    isLoading: boolean;
+};
+declare const useConnectModal: () => {
+    isOpen: boolean;
+    openConnectModal: () => void;
+    closeConnectModal: () => void;
+};
+declare const useAccountModal: () => {
+    isOpen: boolean;
+    openAccountModal: () => void;
+    closeAccountModal: () => void;
+};
+
+interface CiceroConnectButtonProps {
+    label?: string;
+    variant?: 'primary' | 'outline' | 'dark';
+    size?: 'sm' | 'md' | 'lg';
+    showBalance?: boolean;
+    showNetwork?: boolean;
+    className?: string;
+}
+declare const CiceroConnectButton: React.FC<CiceroConnectButtonProps>;
+
+interface CiceroConnectModalProps {
+    isOpen?: boolean;
+    onClose?: () => void;
+}
+declare const CiceroConnectModal: React.FC<CiceroConnectModalProps>;
+
+interface CiceroAccountModalProps {
+    isOpen?: boolean;
+    onClose?: () => void;
+}
+declare const CiceroAccountModal: React.FC<CiceroAccountModalProps>;
+
+interface CiceroQRCodeProps {
+    value: string;
+    size?: number;
+    className?: string;
+    level?: 'L' | 'M' | 'Q' | 'H';
+    includeMargin?: boolean;
+}
+declare const CiceroQRCode: React.FC<CiceroQRCodeProps>;
+
+declare function useZcashPrice(enabled?: boolean): {
+    convertZecToUsd: (zecAmount: number | string) => string | null;
+    usdPrice: number | null;
+    loading: boolean;
+    error: string | null;
+    lastUpdated: number | null;
+};
+
+type WalletConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+type WalletPaymentStatus = 'idle' | 'requesting' | 'submitted' | 'error';
+interface WalletSession {
+    address?: string;
+    connected: boolean;
+    network?: ZcashNetwork;
+    balance?: number;
+}
+interface WalletPaymentResult {
+    txId: string;
+    submitted: boolean;
+}
+/**
+ * Adapter for the Zucchini Wallet browser extension.
+ *
+ * Zucchini injects a provider onto window.zucchini (or window.zcash) and implements
+ * the typed @zucchinifi/dapp-sdk Zcash contract.
+ */
+declare class ZucchiniWalletAdapter {
+    private client;
+    private provider;
+    private _connected;
+    private _address;
+    private _lastAccounts;
+    /**
+     * Checks whether the Zucchini Wallet extension is installed and its
+     * provider is available in the current browser environment.
+     */
+    static isAvailable(): boolean;
+    /**
+     * Subscribes to wallet readiness. Fires callback immediately if already available,
+     * or listens for injection events / polls briefly for late extension initialization.
+     */
+    static onReady(callback: () => void): () => void;
+    /**
+     * Discovers and initializes the Zucchini Client using @zucchinifi/dapp-sdk/zcash
+     * with graceful fallback to raw window.zucchini / window.zcash globals.
+     */
+    private getClient;
+    /**
+     * Requests connection with view_addresses and send_transaction permissions.
+     * Resolves the user's active Shielded Unified Address.
+     */
+    connect(): Promise<WalletSession>;
+    /**
+     * Queries the active network of the Zucchini Wallet ('mainnet' | 'testnet').
+     */
+    getNetwork(): Promise<ZcashNetwork>;
+    /**
+     * Requests a network change. If the extension does not support programmatic
+     * switching, informs the application that manual user toggle is needed.
+     */
+    switchNetwork(targetNetwork: ZcashNetwork): Promise<{
+        success: boolean;
+        requiresManualSwitch?: boolean;
+        currentNetwork: ZcashNetwork;
+    }>;
+    /**
+     * Subscribes to network change events from the wallet extension.
+     */
+    onNetworkChanged(listener: (network: ZcashNetwork) => void): () => void;
+    /**
+     * Helper to normalize raw balance formats (e.g. number, string, zatoshis, or pool totals).
+     */
+    private parseBalancePayload;
+    /**
+     * Reads real-time balance from Zucchini provider.
+     */
+    getBalance(options?: {
+        address?: string;
+        network?: string;
+    }): Promise<number | null>;
+    /**
+     * Sends payment via standard ZIP-321 URI requestPayment or transaction fallback.
+     */
+    requestPayment(params: {
+        recipient: string;
+        amount: number | string;
+        memo?: string;
+    }): Promise<WalletPaymentResult>;
+    /**
+     * Subscribes to accountsChanged events.
+     */
+    onAccountsChanged(listener: (accounts: any) => void): () => void;
+    /**
+     * Subscribes to disconnect events.
+     */
+    onDisconnect(listener: () => void): () => void;
+    /**
+     * Disconnects the current session.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    get address(): string | null;
+}
+
+interface UseZucchiniWalletOptions {
+    /** Auto-connect on mount when extension is detected */
+    autoConnect?: boolean;
+}
+declare function useZucchiniWallet(options?: UseZucchiniWalletOptions): {
+    /** Whether the Zucchini extension is installed in this browser */
+    isAvailable: boolean;
+    /** Current wallet connection lifecycle state */
+    connectionStatus: WalletConnectionStatus;
+    /** Current payment request lifecycle state */
+    paymentStatus: WalletPaymentStatus;
+    /** Active session info (address, etc.) */
+    session: WalletSession | null;
+    /** Last error message (if any) */
+    error: string | null;
+    /** Prompt the user to connect their Zucchini Wallet */
+    connect: () => Promise<WalletSession>;
+    /** Send a ZIP-321 payment request for user review & approval */
+    requestPayment: (params: {
+        recipient: string;
+        amount: number | string;
+        memo?: string;
+    }) => Promise<WalletPaymentResult>;
+    /** Disconnect the current session */
+    disconnect: () => Promise<void>;
+};
+
+/**
+ * Detects the type of a Zcash address.
+ */
+declare function getAddressType(address: string): ZcashAddressType;
+/**
+ * Checks whether an address supports zero-knowledge shielded encryption (Unified or Sapling).
+ */
+declare function isShieldedAddress(address: string): boolean;
+/**
+ * Truncates a long address for display purposes.
+ * e.g., u1abcdef...987654
+ */
+declare function truncateAddress(address: string, start?: number, end?: number): string;
+/**
+ * Validates whether the address supports encrypted memos.
+ * Memos in Zcash are strictly for shielded receivers (Sapling & Orchard).
+ * Transparent addresses do not support on-chain encrypted memos.
+ */
+declare function validateMemoSupport(address: string, memo?: string): {
+    valid: boolean;
+    warning?: string;
+    byteLength: number;
+};
+
+/**
+ * Encodes a string to Base64URL without padding per RFC 4648 §5 / ZIP-321 specification.
+ */
+declare function encodeBase64Url(str: string): string;
+/**
+ * Decodes a Base64URL string without padding per ZIP-321 specification.
+ */
+declare function decodeBase64Url(base64url: string): string;
+interface BuildZip321Params {
+    address: string;
+    amount?: number | string;
+    memo?: string;
+    message?: string;
+}
+/**
+ * Generates an RFC-compliant ZIP-321 Payment Request URI.
+ * Example output:
+ * zcash:u1xyz...?amount=0.05&memo=T3JkZXIgIzEwNDI&message=Payment%20for%20order
+ */
+declare function generateZip321Uri({ address, amount, memo, message, }: BuildZip321Params): string;
+/**
+ * Parses a ZIP-321 URI back into its component parts.
+ */
+declare function parseZip321Uri(rawUri: string): Zip321PaymentRequest;
+/**
+ * Generates deep link URLs for major mobile Zcash wallets:
+ * - Zashi (Electric Coin Co.)
+ * - Ywallet
+ */
+declare function getWalletDeepLinks(zip321Uri: string): {
+    generic: string;
+    zashi: string;
+    ywallet: string;
+};
+
+export { type AccountState, type BalanceState, type BuildZip321Params, CiceroAccountModal, type CiceroAccountModalProps, CiceroConnectButton, type CiceroConnectButtonProps, CiceroConnectModal, type CiceroConnectModalProps, type CiceroContextType, CiceroProvider, type CiceroProviderProps, CiceroQRCode, type CiceroTheme, type SendPaymentParams, type SendPaymentResult, type UseZucchiniWalletOptions, type WalletCategory, type WalletSession$1 as WalletSession, type ZcashAddressType, type ZcashNetwork, type ZcashWallet, ZucchiniWalletAdapter, burnerWallet, decodeBase64Url, encodeBase64Url, generateZip321Uri, getAddressType, getDefaultWallets, getWalletDeepLinks, isShieldedAddress, parseZip321Uri, truncateAddress, useAccount, useAccountModal, useBalance, useCicero, useConnectModal, useZcashPrice, useZucchiniWallet, validateMemoSupport, viewingKeyWallet, ywallet, zashiWallet, zucchiniWallet };