@zucchinifi/dapp-sdk 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# Zucchini SDK
+
+The Zucchini SDK provides a simple way for DApps to interact with the Zucchini Wallet extension.
+
+## Installation
+
+```bash
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+// 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.
+
+```typescript
+// 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](https://zips.z.cash/zip-0321) payment URIs (`zcash:`).
+
+### Create Payment URI
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+// Get supported tokens
+const tokens = await zucchini.getTokens();
+
+// Get a swap quote
+const quote = await zucchini.getSwapQuote({
+    from: 'ZEC',
+    to: 'USDC',
+    amount: '100000000', // Amount in base units
+    recipient: '0x...', // Destination address
+    refundAddress: '0x...' // Refund address (if needed)
+});
+```
+
+## Events
+
+Listen for account and chain changes.
+
+```typescript
+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:
+    ```bash
+    cd example
+    ```
+
+2.  Install dependencies:
+    ```bash
+    pnpm install
+    ```
+
+3.  Start the development server:
+    ```bash
+    pnpm dev
+    ```
+
+4.  Open `http://localhost:3000` in your browser.

package/dist/f4jumble.d.ts

@@ -0,0 +1,2 @@
+export declare function f4jumble(message: Uint8Array): Uint8Array;
+export declare function f4jumble_inv(message: Uint8Array): Uint8Array | null;

package/dist/f4jumble.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.f4jumble = f4jumble;
+exports.f4jumble_inv = f4jumble_inv;
+// @ts-ignore
+const blakejs_1 = require("blakejs");
+// ZIP 316: F4Jumble
+// Based on librustzcash implementation
+function get_h_pers(i) {
+    // "UA_F4Jumble_H" || i || 0 || 0
+    const p = new Uint8Array(16);
+    p.set([85, 65, 95, 70, 52, 74, 117, 109, 98, 108, 101, 95, 72, i, 0, 0]);
+    return p;
+}
+function get_g_pers(i, j) {
+    // "UA_F4Jumble_G" || i || j_low || j_high
+    const p = new Uint8Array(16);
+    p.set([85, 65, 95, 70, 52, 74, 117, 109, 98, 108, 101, 95, 71, i, j & 0xFF, (j >> 8) & 0xFF]);
+    return p;
+}
+function xor(target, source) {
+    const len = Math.min(target.length, source.length);
+    for (let i = 0; i < len; i++) {
+        target[i] ^= source[i];
+    }
+}
+class State {
+    constructor(message) {
+        const leftLen = Math.min(64, Math.floor(message.length / 2));
+        this.left = message.subarray(0, leftLen);
+        this.right = message.subarray(leftLen);
+    }
+    h_round(i) {
+        // Hash right, xor into left
+        // hash_length = left.len() (max 64)
+        // @ts-ignore
+        const ctx = (0, blakejs_1.blake2bInit)(this.left.length, null, null, get_h_pers(i));
+        (0, blakejs_1.blake2bUpdate)(ctx, this.right);
+        const hash = (0, blakejs_1.blake2bFinal)(ctx);
+        xor(this.left, hash);
+    }
+    g_round(i) {
+        // Hash left, xor into right
+        // Iterate j
+        const outBytes = 64;
+        const numChunks = Math.ceil(this.right.length / outBytes);
+        for (let j = 0; j < numChunks; j++) {
+            // @ts-ignore
+            const ctx = (0, blakejs_1.blake2bInit)(outBytes, null, null, get_g_pers(i, j));
+            (0, blakejs_1.blake2bUpdate)(ctx, this.left);
+            const hash = (0, blakejs_1.blake2bFinal)(ctx);
+            const offset = j * outBytes;
+            const targetChunk = this.right.subarray(offset, offset + outBytes);
+            xor(targetChunk, hash);
+        }
+    }
+    apply_f4jumble() {
+        this.g_round(0);
+        this.h_round(0);
+        this.g_round(1);
+        this.h_round(1);
+    }
+    apply_f4jumble_inv() {
+        this.h_round(1);
+        this.g_round(1);
+        this.h_round(0);
+        this.g_round(0);
+    }
+}
+function f4jumble(message) {
+    // We need to copy message because State modifies it in place
+    const msgCopy = new Uint8Array(message);
+    const state = new State(msgCopy);
+    state.apply_f4jumble();
+    return msgCopy;
+}
+function f4jumble_inv(message) {
+    const msgCopy = new Uint8Array(message);
+    const state = new State(msgCopy);
+    state.apply_f4jumble_inv();
+    return msgCopy;
+}

package/dist/index.d.mts

@@ -0,0 +1,239 @@
+type Permission = 'view_balance' | 'view_addresses' | 'send_transaction' | 'view_keys';
+interface RequestArguments {
+    method: string;
+    params?: any;
+}
+interface SendTransactionArgs {
+    to: string;
+    amount: string;
+    memo?: string;
+}
+interface ConnectRequest {
+    permissions?: Permission[];
+}
+interface ConnectResponse {
+    connected: boolean;
+    accounts: Account[];
+    approvedPermissions: Permission[];
+}
+interface Account {
+    name: string;
+    address: string;
+}
+interface ZucchiniProvider {
+    request(args: RequestArguments): Promise<any>;
+    getBalance(): Promise<{
+        total: string;
+        sapling: string;
+        orchard: string;
+    }>;
+    getAddresses(): Promise<{
+        transparent: string;
+        unified: string;
+    }>;
+    getNetwork(): Promise<{
+        network: 'main' | 'test';
+    }>;
+    getUniversalViewingKey(): Promise<string>;
+    getAllViewingKeys(): Promise<Record<string, DetailedKey>>;
+    getWalletStatus(): Promise<{
+        isLocked: boolean;
+        hasWallet: boolean;
+    }>;
+    on(event: string, callback: (data: any) => void): void;
+    off(event: string, callback: (data: any) => void): void;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+}
+interface DetailedKey {
+    unified: string;
+    unified_full: string;
+    unified_incoming: string;
+    unified_outgoing?: string;
+    transparent?: string;
+    sapling?: string;
+    orchard?: string;
+}
+interface Token {
+    symbol: string;
+    name: string;
+    icon: string;
+    decimals: number;
+    assetId?: string;
+}
+interface SwapQuote {
+    quote: {
+        amountOutFormatted: string;
+        amountIn: string;
+        amountOut: string;
+        depositAddress?: string;
+        depositMemo?: string;
+        timeEstimate: number;
+    };
+    quoteRequest: {
+        deadline: string;
+    };
+    depositAddress?: string;
+}
+interface QuoteRequestArgs {
+    from: string;
+    to: string;
+    amount: string;
+    recipient?: string;
+    refundAddress?: string;
+}
+declare global {
+    interface Window {
+        zucchini?: ZucchiniProvider;
+    }
+}
+
+/**
+ * Convert ZEC (decimal string or number) to Zatoshis (bigint).
+ * 1 ZEC = 100,000,000 Zatoshis.
+ * Handles up to 8 decimal places.
+ */
+declare function toZats(amount: string | number): bigint;
+/**
+ * Convert Zatoshis (bigint or string) to ZEC (decimal string).
+ * 1 ZEC = 100,000,000 Zatoshis.
+ */
+declare function fromZats(amount: bigint | string): string;
+/**
+ * Shorten an address for display.
+ * Example: zs1...abcd
+ */
+declare function shortenAddress(address: string, chars?: number): string;
+
+interface Payment {
+    address: string;
+    amount?: bigint;
+    assetId?: string;
+    memo?: string;
+    label?: string;
+    message?: string;
+    otherParams?: Record<string, string>;
+}
+interface Zip321Options {
+    useOrchard?: boolean;
+}
+declare class Zip321ParsingError extends Error {
+    constructor(message: string);
+}
+declare class Zip321Parser {
+    /**
+     * Parses a zcash: URI into a list of Payment objects.
+     * @param uri The zcash URI string.
+     * @param options Parsing options.
+     * @returns An array of Payment objects.
+     * @throws Zip321ParsingError if the URI is invalid.
+     */
+    static parse(uri: string, options?: Zip321Options): Payment[];
+    private static isValidAddress;
+    private static isTransparent;
+    private static isSapling;
+    private static isUnified;
+    private static parseAmount;
+    private static parseAsset;
+    private static isValidBase64Url;
+}
+declare class Zip321Generator {
+    /**
+     * Creates a ZIP 321 compliant URI from a list of payments.
+     * @param payments List of Payment objects.
+     * @param options Generation options.
+     * @returns The formatted zcash: URI.
+     * @throws Error if payments list is empty or invalid.
+     */
+    static create(payments: Payment[], options?: Zip321Options): string;
+    private static formatAmount;
+    private static formatAsset;
+}
+declare function parsePaymentUri(uri: string, options?: Zip321Options): Payment[];
+declare function createPaymentUri(payments: Payment[], options?: Zip321Options): string;
+
+interface QRCodeOptions {
+    width?: number;
+    margin?: number;
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+    logoUrl?: string;
+    logoWidth?: number;
+    logoHeight?: number;
+}
+/**
+ * Generates a QR code Data URL from a string (e.g., a ZIP 321 URI).
+ * @param text The text to encode.
+ * @param options QR code options.
+ * @returns A Promise resolving to a Data URL string (image/png).
+ */
+declare function generateQRCode(text: string, options?: QRCodeOptions): Promise<string>;
+
+interface UnifiedAddressResult {
+    orchard?: string;
+    sapling?: string;
+    transparent?: string;
+    unknown?: Receiver[];
+}
+interface Receiver {
+    typeCode: number;
+    data: Uint8Array;
+}
+declare function parseUnifiedAddress(unifiedAddress: string): UnifiedAddressResult;
+
+declare class ZucchiniSDK {
+    /**
+     * Check if the Zucchini extension is installed and the provider is injected.
+     */
+    get isInstalled(): boolean;
+    /**
+     * Get the provider instance.
+     * @throws Error if Zucchini is not installed.
+     */
+    get provider(): ZucchiniProvider;
+    /**
+     * Connect to the wallet.
+     * Requests permission from the user to access their accounts.
+     * @param permissions List of permissions to request.
+     */
+    connect(permissions?: Permission[]): Promise<ConnectResponse>;
+    /**
+     * Send a transaction.
+     * Requires 'send_transaction' permission.
+     */
+    sendTransaction(args: SendTransactionArgs): Promise<string>;
+    getBalance(): Promise<{
+        total: string;
+        sapling: string;
+        orchard: string;
+    }>;
+    getAddresses(): Promise<{
+        sapling: string;
+        transparent: string;
+        unified: string;
+    }>;
+    getNetwork(): Promise<{
+        network: 'main' | 'test';
+    }>;
+    /**
+     * Send a generic request to the wallet.
+     */
+    request(args: RequestArguments): Promise<any>;
+    on(event: string, handler: (data: any) => void): void;
+    off(event: string, handler: (data: any) => void): void;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    getUniversalViewingKey(): Promise<string>;
+    getAllViewingKeys(): Promise<Record<string, string>>;
+    getWalletStatus(): Promise<{
+        isLocked: boolean;
+        hasWallet: boolean;
+    }>;
+    getTokens(): Promise<Token[]>;
+    getSwapQuote(args: QuoteRequestArgs): Promise<SwapQuote>;
+}
+declare const zucchini: ZucchiniSDK;
+
+export { type Account, type ConnectRequest, type ConnectResponse, type DetailedKey, type Payment, type Permission, type QRCodeOptions, type QuoteRequestArgs, type Receiver, type RequestArguments, type SendTransactionArgs, type SwapQuote, type Token, type UnifiedAddressResult, Zip321Generator, type Zip321Options, Zip321Parser, Zip321ParsingError, type ZucchiniProvider, ZucchiniSDK, createPaymentUri, fromZats, generateQRCode, parsePaymentUri, parseUnifiedAddress, shortenAddress, toZats, zucchini };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { ZucchiniProvider, ConnectResponse, RequestArguments, Permission, SendTransactionArgs, Token, SwapQuote, QuoteRequestArgs } from './types';
+export * from './types';
+export * from './utils';
+export * from './zip321';
+export * from './qrcode';
+export * from './unified_address';
+export declare class ZucchiniSDK {
+    /**
+     * Check if the Zucchini extension is installed and the provider is injected.
+     */
+    get isInstalled(): boolean;
+    /**
+     * Get the provider instance.
+     * @throws Error if Zucchini is not installed.
+     */
+    get provider(): ZucchiniProvider;
+    /**
+     * Connect to the wallet.
+     * Requests permission from the user to access their accounts.
+     * @param permissions List of permissions to request.
+     */
+    connect(permissions?: Permission[]): Promise<ConnectResponse>;
+    /**
+     * Send a transaction.
+     * Requires 'send_transaction' permission.
+     */
+    sendTransaction(args: SendTransactionArgs): Promise<string>;
+    getBalance(): Promise<{
+        total: string;
+        sapling: string;
+        orchard: string;
+    }>;
+    getAddresses(): Promise<{
+        sapling: string;
+        transparent: string;
+        unified: string;
+    }>;
+    getNetwork(): Promise<{
+        network: 'main' | 'test';
+    }>;
+    /**
+     * Send a generic request to the wallet.
+     */
+    request(args: RequestArguments): Promise<any>;
+    on(event: string, handler: (data: any) => void): void;
+    off(event: string, handler: (data: any) => void): void;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    getUniversalViewingKey(): Promise<string>;
+    getAllViewingKeys(): Promise<Record<string, string>>;
+    getWalletStatus(): Promise<{
+        isLocked: boolean;
+        hasWallet: boolean;
+    }>;
+    getTokens(): Promise<Token[]>;
+    getSwapQuote(args: QuoteRequestArgs): Promise<SwapQuote>;
+}
+export declare const zucchini: ZucchiniSDK;

package/dist/index.global.js

@@ -0,0 +1,108 @@
+"use strict";
+var ZucchiniSDK = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    ZucchiniSDK: () => ZucchiniSDK,
+    zucchini: () => zucchini
+  });
+  var ZucchiniSDK = class {
+    /**
+     * Check if the Zucchini extension is installed and the provider is injected.
+     */
+    get isInstalled() {
+      return typeof window !== "undefined" && !!window.zucchini;
+    }
+    /**
+     * Get the provider instance.
+     * @throws Error if Zucchini is not installed.
+     */
+    get provider() {
+      if (!this.isInstalled) {
+        throw new Error("Zucchini Wallet is not installed");
+      }
+      return window.zucchini;
+    }
+    /**
+     * Connect to the wallet.
+     * Requests permission from the user to access their accounts.
+     * @param permissions List of permissions to request.
+     */
+    async connect(permissions = []) {
+      return this.request({ method: "connect", params: { permissions } });
+    }
+    /**
+     * Send a transaction.
+     * Requires 'send_transaction' permission.
+     */
+    async sendTransaction(args) {
+      return this.request({
+        method: "sendTransaction",
+        params: args
+      });
+    }
+    async getBalance() {
+      return this.request({
+        method: "getBalance"
+      });
+    }
+    async getAddresses() {
+      return this.request({
+        method: "getAddresses"
+      });
+    }
+    async getNetwork() {
+      return this.request({
+        method: "getNetwork"
+      });
+    }
+    /**
+     * Send a generic request to the wallet.
+     */
+    async request(args) {
+      return this.provider.request(args);
+    }
+    on(event, handler) {
+      this.provider.on(event, handler);
+    }
+    off(event, handler) {
+      this.provider.off(event, handler);
+    }
+    async disconnect() {
+      return this.request({ method: "disconnect" });
+    }
+    async isConnected() {
+      try {
+        return await this.request({ method: "isConnected" });
+      } catch (e) {
+        return false;
+      }
+    }
+    async getUniversalViewingKey() {
+      return this.request({ method: "getUniversalViewingKey" });
+    }
+    async getAllViewingKeys() {
+      return this.request({ method: "getAllViewingKeys" });
+    }
+  };
+  var zucchini = new ZucchiniSDK();
+  return __toCommonJS(index_exports);
+})();