> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leokit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Shielded ZCash

> Scan and transfer shielded ZEC (Sapling/Orchard) via the WebZjs-backed adapter

## Overview

The `ShieldedZcashKeystoreAdapter` runs a [WebZjs](https://github.com/Electric-Coin-Company/webzjs) light-client in the browser to:

* Derive shielded (`zs1...`) and unified (`u1...`) addresses from a mnemonic.
* Scan the blockchain for shielded notes belonging to the wallet.
* Build and sign shielded transfer transactions.

Shielded ZEC is the only privacy-preserving asset LeoKit supports natively in-wallet. Transparent (`t1.../t3...`) ZEC is handled by the regular UTXO flow.

## Connect

```typescript theme={null}
await sdk.connectWallet("shielded-zcash-keystore", {
  mnemonic: "abandon abandon abandon ...",  // 24 words
  // Optional: override WebZjs config
  webZjsConfig: { /* WebZjsConfig */ },
});
```

The adapter is lazy-loaded — pulling in the WebZjs WASM only when the user actually opts in.

## Read Balance

```typescript theme={null}
const balance = await sdk.getShieldedZcashBalance();
// ShieldedZcashBalance {
//   transparent: { confirmed: "0.0", unconfirmed: "0.0" },
//   sapling:     { confirmed: "0.5", unconfirmed: "0.0", spendable: "0.5" },
//   orchard:     { confirmed: "1.2", unconfirmed: "0.0", spendable: "1.2" },
//   total:       "1.7",
//   total_usd:   42.50
// }
```

## Sync the Light Client

Shielded ZEC requires scanning the chain for notes belonging to the wallet. The first sync can take minutes; subsequent syncs are incremental.

```typescript theme={null}
await sdk.startShieldedZcashScan({
  // ZcashScanProgress callbacks (optional)
  onProgress: (p) => console.log(p.scannedBlocks, "/", p.targetBlock),
  onComplete: () => console.log("synced"),
  onError:    (err) => console.error(err),
});
```

The scan runs in the background; `getShieldedZcashBalance` reads from the in-memory note set, so refresh whenever a `onProgress` event reports new notes.

## Address Helpers

```typescript theme={null}
import {
  getZcashAddressType,
  isZcashAddress,
  isShieldedZcashAddress,
  parseUnifiedAddress,
  extractTransparentFromUnified,
  resolveSwapDestinationAddress,
} from "leokit-sdk";

getZcashAddressType("zs1...");         // "z"
getZcashAddressType("u1...");          // "u"
getZcashAddressType("t1...");          // "t"

isShieldedZcashAddress("zs1...");      // true
isShieldedZcashAddress("t1...");       // false

// Unified address has both transparent and shielded receivers
const { transparent, shielded } = parseUnifiedAddress("u1...");
const t = extractTransparentFromUnified("u1...");

// When swapping TO a unified address, pick the correct sub-receiver
// based on the protocol's native address type:
const dest = resolveSwapDestinationAddress({
  unifiedAddress: "u1...",
  preferredType: "transparent",  // many cross-chain protocols only support t-addresses
});
```

## Shielded Transfers

Shielded transfers are built via the protocol layer rather than `sdk.transfer()`. The shielded protocol handler exposes:

```typescript theme={null}
import type {
  ShieldedTransferType,
  ShieldedTransferParams,
  ShieldedZcashUnsignedTx,
  ShieldedZcashProvider,
} from "leokit-sdk";
```

Through `sdk.executeSwap`, the SDK automatically selects the shielded protocol when the source asset is shielded ZEC. For non-swap shielded sends, see the SDK README's "Shielded Transfers" section.

## Notes

* The first chain scan downloads \~1 GB of compact-block data. Run it on a fast connection and persist the WebZjs state to IndexedDB across sessions.
* Shielded ZEC swaps are routed through `mayachain` (and increasingly `near` via shielded-pool support); the `ShieldedZcashProtocol` handler abstracts this.
* A user-friendly setup wizard is built into LeoDex; reuse the same `ShieldedZcashKeystoreAdapter` API to clone that flow.