Zucchini SDK

The Zucchini SDK provides a simple way for DApps to interact with the Zucchini Wallet extension and Mini-App.

Zucchini Wallet is now live!

• Desktop: Chrome Web Store
• Mobile: Coming soon to the Base App as a Farcaster Mini-App.

Installation

npm install @zucchinifi/dapp-sdk
# or
pnpm add @zucchinifi/dapp-sdk

Getting Started

First, check if the Zucchini wallet is installed and connect to it.

import { zucchini } from '@zucchinifi/dapp-sdk';

// Check if installed
if (zucchini.isInstalled) {
    // Connect and request permissions
    // Available permissions: 'view_balance', 'send_transaction', 'view_addresses', 'view_keys'
    const response = await zucchini.connect(['view_balance', 'send_transaction']);
    console.log('Connected:', response);
} else {
    console.log('Zucchini Wallet is not installed');
}

Core Features

Get Balance

Requires view_balance permission.

const balance = await zucchini.getBalance();
console.log('Total:', balance.total);
console.log('Sapling:', balance.sapling);
console.log('Orchard:', balance.orchard);

Get Addresses

Requires view_addresses permission.

const addresses = await zucchini.getAddresses();
console.log('Unified:', addresses.unified);
console.log('Sapling:', addresses.sapling);
console.log('Transparent:', addresses.transparent);

Send Transaction

Requires send_transaction permission.

const txid = await zucchini.sendTransaction({
    to: 'u1...', // Recipient address
    amount: '0.001', // Amount in ZEC
    memo: 'Hello Zcash!' // Optional memo
});
console.log('Transaction sent:', txid);

Network & Status

// Get current network ('main' or 'test')
const network = await zucchini.getNetwork();

// Check wallet status
const status = await zucchini.getWalletStatus();
console.log('Is Locked:', status.isLocked);
console.log('Has Wallet:', status.hasWallet);

Viewing Keys

Requires view_keys permission.

// Get Universal Viewing Key (UVK)
const uvk = await zucchini.getUniversalViewingKey();

// Get all viewing keys
const keys = await zucchini.getAllViewingKeys();

ZIP 321 Payment Requests

The SDK provides utilities for creating and parsing ZIP 321 payment URIs (zcash:).

Create Payment URI

import { createPaymentUri } from '@zucchinifi/dapp-sdk';

const payments = [{
    address: 'u1...',
    amount: 100000n, // Amount in zatoshis (BigInt)
    memo: 'Thanks!', // Base64URL encoded memo
    label: 'Coffee'
}];

// Create URI
const uri = createPaymentUri(payments);

// Create URI with auto-conversion of Unified Addresses to Orchard receivers
// This is useful for compatibility with wallets that prefer Orchard-only addresses
const orchardUri = createPaymentUri(payments, { useOrchard: true });

Parse Payment URI

import { parsePaymentUri } from '@zucchinifi/dapp-sdk';

const uri = 'zcash:u1...?amount=0.001';

const requests = parsePaymentUri(uri);

// Parse and automatically extract Orchard receivers from Unified Addresses
const orchardRequests = parsePaymentUri(uri, { useOrchard: true });

Generate QR Code

Generate a QR code for a payment URI. The Zucchini logo is embedded by default.

import { generateQRCode } from '@zucchinifi/dapp-sdk';

const dataUrl = await generateQRCode(uri);

// Display in an image tag
document.getElementById('qr-code').src = dataUrl;

// Custom options
const customQr = await generateQRCode(uri, {
    logoUrl: 'https://example.com/logo.png', // Custom logo
    width: 256,
    logoWidth: 60,
    logoHeight: 60
});

Swap

Fetch supported tokens and get swap quotes.

// Get supported tokens
const tokens = await zucchini.getTokens();

// Get a swap quote
const quote = await zucchini.swap.getQuote({
    from: 'ZEC',
    to: 'nep141:usd-coin.omft.near', // Using asset ID or symbol
    amount: '100000000', // Amount in base units
    recipient: '0x...', // Destination address
    refundAddress: '0x...' // Refund address (if needed)
});

Explorer

Query transaction history from the Zucchini Explorer.

// Get transactions
const transactions = await zucchini.explorer.getTransactions({
    limit: 10,
    offset: 0
});

Events

Listen for account and chain changes.

zucchini.on('accountsChanged', (accounts) => {
    console.log('Accounts changed:', accounts);
});

zucchini.on('chainChanged', (chain) => {
    console.log('Chain changed:', chain);
});

Running the Example

An example project is included in the example directory. To run it:

1. Navigate to the example directory:

   cd example

2. Install dependencies:

   pnpm install

3. Start the development server:

   pnpm dev

4. Open http://localhost:3000 in your browser.

Changelog

0.1.3

• Branded QR Codes: Added QRCode class and generateQRCode utility with automatic Zucchini logo embedding.
• Premium OG Previews: Integrated the branded QR system into social previews with improved layout stability and centering.
• Logo Customization: Support for custom logo URLs in QR code generation.
• Edge Runtime Support: Optimized image rendering for Next.js Edge runtime compatibility.