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.
Drop <CiceroConnectButton /> into your navigation bar for instant wallet connectivity.
Supports Orchard and Sapling shielded pools, unified addresses (ZIP-316), and encrypted memos.
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:
Quick Start: Provider Setup
Wrap your client component tree in CiceroProvider. This establishes the React context for wallet discovery, balance polling, and modal state.
'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.
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.
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)'.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:
| Wallet | Category | Connection Type | Shielded Pool |
|---|---|---|---|
| π₯ Zucchini Wallet | Browser Extension | 1-Click Sidepanel Approval | Mainnet & Testnet (Orchard & Sapling) |
| π€ Noir Wallet | Browser Extension | 1-Click In-Browser Popup | Mainnet & Testnet (Shielded & ZECFi) |
| π· Zelcore | Multi-Asset Extension | Address Input (No ZEC dApp RPC) | Mainnet Only (Transparent t1) |
| π‘οΈ Zashi | Mobile (ECC) | ZIP-321 QR Scan | Mainnet (Orchard & Sapling) |
| π± Ywallet | Mobile & Desktop | ZIP-321 QR Scan | Mainnet & Testnet (Orchard & Sapling) |
| ποΈ Viewing Key | Auditor / Read-Only | Unified Viewing Key (uview...) | Shielded Decryption |
| π₯ Burner Dev Session | Local Development | Ephemeral In-Memory Testnet | Testnet Orchard |
Zcash Standards: ZIP-321 & ZIP-316
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.
Combines multiple receiver types (Orchard, Sapling, and Transparent) into a single address starting with u1 (mainnet) or utest1 (testnet) to prevent cross-pool confusion.