Home/Docs

Cicero Developer Documentation

The universal wallet connection toolkit for shielded Zcash. Drop-in React components, real-time balance polling, and AI agent skills for high-speed dApp development.

Overview

Cicero is the developer payment and wallet connection kit for shielded Zcash apps. Designed with the familiar ergonomics of RainbowKit, it abstracts the complexities of Zcash browser extension APIs, mobile QR handoffs, zero-knowledge unified addresses, and real-time balance queries into simple React hooks and components.

One Button Integration

Drop <CiceroConnectButton /> into your navigation bar for instant wallet connectivity.

Zero-Knowledge Shielded

Supports Orchard and Sapling shielded pools, unified addresses (ZIP-316), and encrypted memos.

RainbowKit Experience

Modal drawer with live balance display, network switching indicator, and address copy.

Installation

v0.2.10 (Latest)

Install the package using your favorite package manager:

$ pnpm add @cicero-zcash/react

Quick Start: Provider Setup

Wrap your client component tree in CiceroProvider. This establishes the React context for wallet discovery, balance polling, and modal state.

app/providers.tsx
'use client';

import { CiceroProvider } from '@cicero-zcash/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CiceroProvider
      initialNetwork="mainnet" // 'mainnet' | 'testnet'
      appName="My Zcash dApp"
    >
      {children}
    </CiceroProvider>
  );
}

AI Agent Skill & Developer Prompts

Build 10x faster by giving your AI coding assistant (Cursor, Claude Code, Windsurf, Antigravity, Copilot, ChatGPT) the exact Cicero mental model. Never deal with hallucinations or outdated API calls.

AI-Assisted Development Ecosystem

Install Cicero Agent Skill or Copy Prompts

Equip your AI assistant (Cursor, Claude Code, Windsurf, Antigravity, ChatGPT, Copilot) with deep knowledge of shielded Zcash, `@cicero-zcash/react`, and ZIP-321 payment request specs.

Download SKILL.md
Full dApp Specialist System Prompt
You are an expert full-stack developer specialized in building decentralized applications (dApps) on Zcash using @cicero-zcash/react (the universal wallet connection kit for shielded Zcash).

Context & Rules:
1. Always use '@cicero-zcash/react' for all wallet connection, address management, shielded balances, and payment dispatch.
2. Setup requires wrapping client components with <CiceroProvider initialNetwork="mainnet" appName="YourAppName">.
3. For drop-in connection buttons, use <CiceroConnectButton variant="primary" size="md" radius="md" showBalance={true} showNetwork={true} />.
4. Supported wallets include:
   - Zucchini Browser Extension (via @zucchinifi/dapp-sdk with 1-click in-browser authorization)
   - Noir Wallet (self-custodial privacy extension for Orchard & ZECFi with native in-browser RPC 'zcash_requestAccounts')
   - Zelcore Wallet (multi-asset extension & desktop with 1-click transparent ZEC binding and 'zel:' URI protocol)
   - Zashi & Ywallet (mobile/desktop shielded wallets connecting via ZIP-321 QR handoff)
   - Viewing Keys (read-only auditor view for accounting and taxes with 'uview...' or 'zxviews...')
   - Ephemeral Dev Sessions (in-memory testnet wallet for testing without external tools)
5. Address formats:
   - Unified Addresses start with 'u1' (mainnet) or 'utest1' (testnet).
   - Sapling addresses start with 'zs1'.
   - Transparent addresses start with 't1' (mainnet) or 'tm' (testnet).
6. Hooks available:
   - useAccount(): { isConnected, isConnecting, address, wallet, disconnect }
   - useBalance(): { zec, usd, isLoading, refetch }
   - useCicero(): { network, switchNetwork, openConnectModal, openAccountModal, sendPayment, disconnect, wallets }
7. For payments or micro-tips, use 'generateZip321Uri({ address, amount, memo })' and 'getWalletDeepLinks(uri)'.
Paste into Cursor Composer, Claude Code, Windsurf, or CopilotTokens: ~350

Component: CiceroConnectButton

The primary UI component. When disconnected, it displays a connect trigger. When connected, it transforms into an interactive pill showing active network, shielded balance, and a truncated address.

Header.tsx
import { CiceroConnectButton } from '@cicero-zcash/react';

export function Header() {
  return (
    <header className="flex justify-between items-center p-4 border-b border-zinc-800">
      <h1 className="font-semibold text-white">My Zcash Store</h1>
      <CiceroConnectButton
        variant="primary"       // 'primary' | 'outline' | 'dark' | 'ghost' | 'gradient' | 'gold'
        size="md"              // 'sm' | 'md' | 'lg'
        radius="md"            // 'none' | 'sm' | 'md' | 'lg' | 'full'
        label="Connect Zcash"  // Custom disconnected button text
        showBalance={true}     // Displays balance pill when connected
        showNetwork={true}     // Displays active network pill (mainnet/testnet)
        showIcon={true}        // Displays shielded icon
      />
    </header>
  );
}
PropTypeDefaultDescription
variant'primary' | 'outline' | 'dark' | 'ghost' | 'gradient' | 'gold''primary'Button visual appearance token.
size'sm' | 'md' | 'lg''md'Padding and typography tier.
radius'none' | 'sm' | 'md' | 'lg' | 'full''md'Corner border-radius token.
labelstring'Connect Zcash Wallet'Disconnected state text.
showBalancebooleantrueRenders shielded ZEC balance in connected pill.
showNetworkbooleantrueRenders mainnet/testnet status indicator.

Component: CiceroQRCode

A hardened SVG QR code component optimized for high-density ZIP-321 payment request URIs and unified addresses. Includes error correction level 'M'.

import { CiceroQRCode } from '@cicero-zcash/react';

// ZIP-321 Payment URI with amount and encrypted memo
const zip321Uri = "zcash:u1testaddress...?amount=1.25&message=Order%20%234912";

export function PaymentBox() {
  return (
    <div className="p-4 bg-white rounded-lg border inline-block">
      <CiceroQRCode value={zip321Uri} size={180} />
    </div>
  );
}

Hook: useAccount()

Provides access to current connection status, connected shielded address, and active wallet metadata.

import { useAccount } from '@cicero-zcash/react';

export function ProfileWidget() {
  const { isConnected, isConnecting, address, wallet } = useAccount();

  if (isConnecting) return <span>Authorizing wallet...</span>;
  if (!isConnected) return <span>Not connected</span>;

  return (
    <div>
      <p>Wallet: {wallet?.name} ({wallet?.category})</p>
      <p>Address: {address}</p>
    </div>
  );
}

Hook: useBalance()

Queries shielded balance in ZEC, computes fiat USD estimates, tracks loading state, and exposes manual refetch.

import { useBalance } from '@cicero-zcash/react';

export function WalletBalance() {
  const { zec, usd, isLoading, refetch } = useBalance();

  return (
    <div className="flex items-center gap-3">
      <span>{isLoading ? 'Syncing...' : `${zec} ZEC`}</span>
      {usd && <span className="text-zinc-500">(β‰ˆ $${usd} USD)</span>}
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}

Hook: useCicero()

Exposes the master Cicero context: network switching between Mainnet and Testnet, modal triggers, and disconnect controls.

import { useCicero } from '@cicero-zcash/react';

export function NetworkSwitch() {
  const { network, switchNetwork, openConnectModal, disconnect } = useCicero();

  return (
    <div>
      <p>Current Network: {network}</p>
      <button onClick={() => switchNetwork(network === 'mainnet' ? 'testnet' : 'mainnet')}>
        Switch to {network === 'mainnet' ? 'Testnet' : 'Mainnet'}
      </button>
      <button onClick={openConnectModal}>Open Wallet List</button>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Hook: useZucchiniWallet()

Direct interface to the Zucchini web browser extension via @zucchinifi/dapp-sdk. Auto-detects extension presence and listens for unlock events.

import { useZucchiniWallet } from '@cicero-zcash/react';

export function ExtensionCard() {
  const { isAvailable, isConnected, connect, address } = useZucchiniWallet();

  if (!isAvailable) {
    return <a href="https://chromewebstore.google.com">Install Zucchini Extension</a>;
  }

  if (!isConnected) {
    return <button onClick={() => connect()}>Connect Zucchini</button>;
  }

  return <div>Connected: {address}</div>;
}

Supported Wallets Architecture

Web browsers enforce strict sandbox security preventing websites from querying arbitrary local OS processes. Cicero supports both in-browser injected extensions and zero-knowledge QR handoffs for mobile wallets:

WalletCategoryConnection TypeShielded Pool
πŸ₯’ Zucchini WalletBrowser Extension1-Click Sidepanel ApprovalMainnet & Testnet (Orchard & Sapling)
πŸ–€ Noir WalletBrowser Extension1-Click In-Browser PopupMainnet & Testnet (Shielded & ZECFi)
πŸ”· ZelcoreMulti-Asset ExtensionAddress Input (No ZEC dApp RPC)Mainnet Only (Transparent t1)
πŸ›‘οΈ ZashiMobile (ECC)ZIP-321 QR ScanMainnet (Orchard & Sapling)
πŸ“± YwalletMobile & DesktopZIP-321 QR ScanMainnet & Testnet (Orchard & Sapling)
πŸ‘οΈ Viewing KeyAuditor / Read-OnlyUnified Viewing Key (uview...)Shielded Decryption
πŸ”₯ Burner Dev SessionLocal DevelopmentEphemeral In-Memory TestnetTestnet Orchard

Zcash Standards: ZIP-321 & ZIP-316

ZIP-321: Payment Request URIs

Standardizes payment URIs for Zcash (zcash:<address>?amount=<val>&message=<memo>). Enables mobile and desktop wallets to auto-fill recipients, exact amounts, and encrypted memos.

ZIP-316: Unified Addresses

Combines multiple receiver types (Orchard, Sapling, and Transparent) into a single address starting with u1 (mainnet) or utest1 (testnet) to prevent cross-pool confusion.