@anywalletkit/wallet-zcash 0.0.0-stage → 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,419 @@
+import { S as SpentOutput, Z as ZcashNetwork, a as ZcashTxDescription, b as ZcashClient, U as Utxo, c as ZcashTxInfo, d as ZcashConfig, e as ZcashSpend, f as ZcashTransferOptions, g as ZcashMaxSpendableResult, h as ZcashReceipt, i as ZcashTransaction } from './history-DQNeEwXE.cjs';
+export { B as BLOCKCHAIR_URL, j as BlockchairClient, k as BlockchairTxDashboard, C as CAIP2, H as HistoryUnavailableError, l as ZcashChainTx, m as ZcashClientConfig, n as ZcashHistoryCursor, o as ZcashHistoryOptions, p as ZcashHistoryPage, q as ZcashHistoryRaw, r as ZcashHistorySource, s as ZcashTxInputDescription, t as ZcashTxOutputDescription, u as ZcashWarning, v as blockchairTime, w as createZcashHistory, x as decodeHistoryCursor, y as encodeHistoryCursor, z as mapDashboardTx, A as zcashExplorerTxUrl } from './history-DQNeEwXE.cjs';
+import { Signer, IWalletAccountReadOnly, IWalletAccount, TransferResult, WalletManager, FeeRates } from '@anywalletkit/core';
+
+declare const TX_VERSION_V5 = 2147483653;
+declare const VERSION_GROUP_ID_V5 = 648488714;
+declare const SIGHASH_ALL = 1;
+/** Mainnet network upgrades and their consensus branch ids (ZIP-200 table), oldest first. */
+declare const MAINNET_UPGRADES: ReadonlyArray<{
+    name: string;
+    height: number;
+    branchId: number;
+}>;
+/** The branch id the current mainnet tip signs under (NU6.3 "Ironwood", active since block 3 428 143, 2026-07-28). */
+declare const CURRENT_BRANCH_ID: number;
+/** Branch id in force at `height` on mainnet (the newest upgrade when the height is unknown or ahead of the table). */
+declare function branchIdForHeight(height: number | undefined): number;
+interface TxInput {
+    /** Display-order hex (as explorers show it). */
+    txid: string;
+    vout: number;
+    scriptSig: Uint8Array;
+    sequence: number;
+}
+interface TxOutput {
+    value: bigint;
+    script: Uint8Array;
+}
+/**
+ * A v5 (NU5) transaction with transparent inputs and outputs only, as signed and serialized here.
+ */
+interface TransparentTxV5 {
+    consensusBranchId: number;
+    lockTime: number;
+    expiryHeight: number;
+    inputs: TxInput[];
+    outputs: TxOutput[];
+}
+declare const FINAL_SEQUENCE = 4294967294;
+declare const MAX_SEQUENCE = 4294967295;
+/** ZIP-225 wire format with empty Sapling and Orchard bundles. */
+declare function serializeTx(tx: TransparentTxV5): Uint8Array;
+/** Parse raw hex / bytes. Accepts v5 transactions whose shielded bundles are empty; anything else is refused by name. */
+declare function parseTx(raw: string | Uint8Array): TransparentTxV5;
+/** `ZcashTxHash_` ‖ consensus branch id (LE) — the personalization of both the txid and the signature digest. */
+declare function txHashPersonalization(consensusBranchId: number): Uint8Array;
+declare function headerDigest(tx: TransparentTxV5): Uint8Array;
+declare function prevoutsDigest(tx: TransparentTxV5): Uint8Array;
+declare function sequenceDigest(tx: TransparentTxV5): Uint8Array;
+declare function outputsDigest(tx: TransparentTxV5): Uint8Array;
+/** T.2: hash of the three transparent digests; the hash of the empty string when there are no inputs AND no outputs. */
+declare function transparentDigest(tx: TransparentTxV5): Uint8Array;
+/** Non-malleable transaction id (ZIP-244 T.1 … T.4), internal byte order. */
+declare function txidDigest(tx: TransparentTxV5): Uint8Array;
+/** Transaction id as explorers display it (byte-reversed hex). */
+declare function txid(tx: TransparentTxV5): string;
+/**
+ * ZIP-244 S.2 transparent signature digest + S.1 … S.4 wrapper for SIGHASH_ALL
+ * over input `index`. `spent[i]` is the output input `i` spends (value and
+ * scriptPubKey are both committed to, so a lying transport cannot make us sign
+ * for a different amount).
+ */
+declare function sighashAll(tx: TransparentTxV5, index: number, spent: SpentOutput[]): Uint8Array;
+/** `<sig ‖ 0x01> <pubkey>` — the scriptSig of a P2PKH spend. */
+declare function p2pkhScriptSig(derSignature: Uint8Array, publicKey: Uint8Array): Uint8Array;
+/** Split a P2PKH scriptSig back into DER signature (hash type stripped) and public key; undefined when it is not one. */
+declare function parseP2pkhScriptSig(scriptSig: Uint8Array): {
+    signature: Uint8Array;
+    hashType: number;
+    publicKey: Uint8Array;
+} | undefined;
+
+/** Default hard fee ceiling: 0.01 ZEC. */
+declare const DEFAULT_MAX_FEE = 1000000n;
+/** Why a spend was refused before signing. */
+type UnsafeTransactionCode = 
+/** Fee above `maxFee`. */
+'fee-too-high'
+/** Outputs exceed inputs. */
+ | 'outputs-exceed-inputs'
+/** An output that is neither the requested recipient/amount nor our change. */
+ | 'unexpected-output'
+/** The recipient output is missing or carries a different amount. */
+ | 'recipient-mismatch'
+/** A change output pays an address that is not ours. */
+ | 'change-not-ours';
+/** A transaction failed a hard safety check and was not signed / broadcast. */
+declare class UnsafeTransactionError extends Error {
+    readonly code: UnsafeTransactionCode;
+    constructor(code: UnsafeTransactionCode, message: string);
+}
+/** What a description needs to tell recipient, change and unknown outputs apart. */
+interface DescribeContext {
+    network: ZcashNetwork;
+    /** Our own address: outputs paying it are tagged `change`. */
+    ownAddress: string;
+    /** The spend the caller asked for. Outputs matching it are `recipient`; anything else is `unknown`. */
+    intended?: {
+        to: string;
+        value: bigint;
+    } | undefined;
+    maxFee?: bigint | undefined;
+}
+/** Describe a (signed or unsigned) transaction given the output every input spends. Pure: no network, no signing. */
+declare function describeTransaction(tx: TransparentTxV5, spent: SpentOutput[], ctx: DescribeContext): ZcashTxDescription;
+/**
+ * Hard checks run before signing and before broadcasting. Throws UnsafeTransactionError;
+ * never mutates. With `intended`, exactly one output must be the requested
+ * recipient/amount and every other output must be our change.
+ */
+declare function assertSafe(desc: ZcashTxDescription, ctx: DescribeContext): void;
+
+interface BlockbookVin {
+    txid?: string;
+    vout?: number;
+    n?: number;
+    isAddress?: boolean;
+    addresses?: string[];
+    value?: string;
+}
+interface BlockbookVout {
+    n: number;
+    isAddress?: boolean;
+    addresses?: string[];
+    value?: string;
+    hex?: string;
+}
+interface BlockbookTxDetails {
+    txid: string;
+    blockHeight: number;
+    confirmations: number;
+    blockTime?: number;
+    fees?: string;
+    hex?: string;
+    vin?: BlockbookVin[];
+    vout?: BlockbookVout[];
+}
+declare class ZcashBlockbookClient implements ZcashClient {
+    private readonly base;
+    private readonly headers;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    constructor(config: {
+        url: string;
+        headers?: Record<string, string>;
+    }, fetchFn?: typeof fetch, timeoutMs?: number);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private get;
+    getBalance(address: string): Promise<{
+        confirmed: bigint;
+        unconfirmed: bigint;
+    }>;
+    listUnspent(address: string): Promise<Utxo[]>;
+    private static isTx;
+    getTransactionDetails(txid: string): Promise<BlockbookTxDetails | undefined>;
+    getTransaction(txid: string): Promise<string>;
+    getOutput(txid: string, vout: number): Promise<SpentOutput | undefined>;
+    getTransactionInfo(txid: string): Promise<ZcashTxInfo | undefined>;
+    broadcast(rawTx: string): Promise<string>;
+    getBlockHeight(): Promise<number>;
+}
+
+/**
+ * One client, or a failover client over the list: each call walks the list in
+ * order, `retries` extra rounds. A node's rejection of a broadcast (plain
+ * Error) is final — only transport failures (NetworkError) move on.
+ */
+declare function createClient(config: ZcashConfig): ZcashClient | undefined;
+
+/** Hash of a signed message (`Zcash Signed Message:` prefix, double SHA-256). */
+declare function magicHash(message: string | Uint8Array): Uint8Array;
+/** Encode `r‖s` + recovery id as a base64 signature (compressed-key header 31 + recovery). */
+declare function encodeMessageSignature(rs: Uint8Array, recovery: number): string;
+/** Sign through a {@link Signer} (`ecdsa-recoverable`, context `zcash-message`). */
+declare function signMessageWith(message: string | Uint8Array, signer: Signer): Promise<string>;
+/** Recover the compressed public key from a message signature, or undefined when malformed. */
+declare function recoverMessagePublicKey(message: string | Uint8Array, signature: string): Uint8Array | undefined;
+
+declare const MARGINAL_FEE = 5000n;
+declare const GRACE_ACTIONS = 2;
+/** Serialized size of one signed P2PKH input: prevout 36 + CompactSize 1 + scriptSig (1+73+1+33) + sequence 4. */
+declare const P2PKH_INPUT_SIZE = 149;
+/** Most inputs one spend may use. */
+declare const MAX_UTXO_INPUTS = 200;
+declare function logicalActions(inputSizes: readonly number[], outputSizes: readonly number[]): number;
+/** The fee a transaction of this shape should pay (zatoshis). */
+declare function conventionalFee(inputSizes: readonly number[], outputSizes: readonly number[]): bigint;
+/** Transaction size estimate: v5 header 20 + counts 2 + inputs + outputs + 3 empty bundle counts. */
+declare function estimateSize(inputs: number, outputSizes: readonly number[]): number;
+/** A spend would need more inputs than allowed; consolidate the UTXOs first. */
+declare class TooManyInputsError extends Error {
+    readonly maxInputs: number;
+    constructor(maxInputs: number);
+}
+/** Input to {@link selectCoins}. */
+interface CoinSelectOptions {
+    utxos: Utxo[];
+    /** Zatoshis the recipient gets. */
+    target: bigint;
+    /** Serialized size of the recipient output. */
+    recipientOutputSize: number;
+    /** Serialized size of a change output to our own address. */
+    changeOutputSize: number;
+    changeDust?: bigint;
+    maxInputs?: number;
+    /** Caller-chosen fee (replaces the conventional fee; still has to be covered by the inputs). */
+    fee?: bigint;
+}
+/** UTXOs chosen for a spend, the ZIP-317 fee and the change. */
+interface CoinSelection {
+    utxos: Utxo[];
+    fee: bigint;
+    /** The ZIP-317 fee for the chosen shape (equals `fee` unless the caller overrode it or change was folded in). */
+    conventionalFee: bigint;
+    /** Change back to us; 0n when folded into the fee. */
+    change: bigint;
+    /** True when change existed but fell below dust and became fee. */
+    changeFolded: boolean;
+    size: number;
+}
+/** UTXOs worth spending (each adds at most one logical action = 5000 zatoshis), largest first. */
+declare function spendableUtxos(utxos: Utxo[]): Utxo[];
+/**
+ * Pick UTXOs to fund `target` at the ZIP-317 fee; change below dust joins the fee.
+ *
+ * @throws `InsufficientFundsError` (core) when the UTXOs cannot cover target plus fee,
+ * `TooManyInputsError` above `maxInputs`.
+ */
+declare function selectCoins(o: CoinSelectOptions): CoinSelection;
+/** Sweep: every spendable input (largest first, capped), one output, no change. */
+declare function selectAll(o: {
+    utxos: Utxo[];
+    outputSize: number;
+    maxInputs?: number;
+    fee?: bigint;
+}): {
+    utxos: Utxo[];
+    fee: bigint;
+    amount: bigint;
+    size: number;
+};
+
+/** Transparent address type: pay-to-pubkey-hash (`t1…`) or pay-to-script-hash (`t3…`). */
+type ScriptKind = 'p2pkh' | 'p2sh';
+/** A transparent address decoded to its type and 20-byte hash. */
+interface DecodedAddress {
+    kind: ScriptKind;
+    /** 20-byte hash (pubkey hash or script hash). */
+    hash: Uint8Array;
+    /** The scriptPubKey. */
+    script: Uint8Array;
+}
+/** Base58Check version prefix for a transparent address kind on a network (exported for tests / tooling). */
+declare function addressPrefix(network: ZcashNetwork, kind: ScriptKind): readonly [number, number];
+/** RIPEMD-160 of SHA-256, the hash inside a transparent address. */
+declare function hash160(data: Uint8Array): Uint8Array;
+/** OP_DUP OP_HASH160 <20> OP_EQUALVERIFY OP_CHECKSIG, or OP_HASH160 <20> OP_EQUAL. */
+declare function scriptFor(kind: ScriptKind, hash: Uint8Array): Uint8Array;
+/** Type of an output script; `unknown` for anything but p2pkh and p2sh. */
+declare function scriptKind(script: Uint8Array): ScriptKind | 'unknown';
+/** Transparent address of a 20-byte hash. */
+declare function encodeAddress(kind: ScriptKind, hash: Uint8Array, network: ZcashNetwork): string;
+/** Decode and validate a transparent address for `network`; throws a message that names the problem. */
+declare function decodeAddress(address: string, network: ZcashNetwork): DecodedAddress;
+/** Address for an output script, or undefined when the script has no address form. */
+declare function addressFromScript(script: Uint8Array, network: ZcashNetwork): string | undefined;
+/** P2PKH address of a compressed secp256k1 public key (what `m/44'/133'/0'/0/i` yields). */
+declare function addressFromPublicKey(publicKey: Uint8Array, network?: ZcashNetwork): string;
+/** Output size in bytes: 8 (value) + CompactSize + script. */
+declare function outputSize(script: Uint8Array): number;
+/** Below this an output is uneconomic to spend (Bitcoin Core's P2PKH dust floor; zatoshis). */
+declare const DUST_LIMIT = 546n;
+
+/** A coin selection for one spend, with the decoded recipient. */
+interface SpendPlan extends CoinSelection {
+    /** Zatoshis the recipient gets (the requested value — never reduced). */
+    amount: bigint;
+    recipient: DecodedAddress;
+}
+/** Watch-only Zcash account: balances, quotes, receipts, message verification. No key. */
+declare class WalletAccountReadOnlyZcash implements IWalletAccountReadOnly {
+    /** The transparent address. */
+    readonly address: string;
+    readonly chain: string;
+    /** The address's scriptPubKey. */
+    readonly scriptPubKey: Uint8Array;
+    /** Script type of the address. */
+    readonly scriptKind: DecodedAddress['kind'];
+    protected readonly _config: ZcashConfig;
+    protected readonly _client: ZcashClient | undefined;
+    protected readonly _network: ZcashNetwork;
+    constructor(address: string, config?: ZcashConfig);
+    protected requireClient(what: string): ZcashClient;
+    /** Fee ceiling in zatoshis: `ZcashConfig.maxFee` or the default. */
+    get maxFee(): bigint;
+    /** The transparent address. */
+    getAddress(): Promise<string>;
+    /** Confirmed plus incoming mempool value (the transports do not expose pending spends of our own outputs). */
+    getBalance(): Promise<bigint>;
+    /** Always throws: Zcash has no tokens. */
+    getTokenBalance(_token: string): Promise<bigint>;
+    /** Coin selection for a spend (ZIP-317 fee). Validates the recipient and the dust floor first. */
+    protected planSpend(spend: ZcashSpend): Promise<SpendPlan>;
+    /** ZIP-317 fee of a spend in zatoshis. */
+    quoteSendTransaction(tx: ZcashSpend): Promise<{
+        fee: bigint;
+    }>;
+    /** ZIP-317 fee of a transfer in zatoshis. */
+    quoteTransfer(o: ZcashTransferOptions): Promise<{
+        fee: bigint;
+    }>;
+    /** Everything spendable in ONE transaction to a single output, no change. */
+    getMaxSpendable(opts?: {
+        to?: string;
+        fee?: bigint | number;
+    }): Promise<ZcashMaxSpendableResult>;
+    /** Undefined until the transaction is mined. */
+    getTransactionReceipt(hash: string): Promise<ZcashReceipt | undefined>;
+    /** Recover the key from a Zcash message signature and compare its P2PKH address with ours. */
+    verify(message: string | Uint8Array, signature: string): Promise<boolean>;
+    /** Chain tip for lock time / expiry; undefined when the transport cannot tell. */
+    protected tipHeight(): Promise<number | undefined>;
+}
+
+/** t-address for a compressed public key. */
+declare function addressFor(publicKey: Uint8Array, network?: ZcashNetwork): string;
+/** ZIP-203 default: a transaction expires 40 blocks (~50 min) after it was built. */
+declare const DEFAULT_EXPIRY_DELTA = 40;
+interface Built {
+    tx: TransparentTxV5;
+    hex: string;
+    txid: string;
+    fee: bigint;
+    plan: SpendPlan;
+    desc: ZcashTxDescription;
+}
+/**
+ * Signing Zcash account — BIP-44 P2PKH at m/44'/133'/0'/0/i (t1…). The key never
+ * enters this package: every input is one `signer.sign(...)` call over the
+ * ZIP-244 signature digest computed here (`ecdsa`, DER-encoded + SIGHASH_ALL
+ * into the scriptSig); messages are `ecdsa-recoverable` over the Zcash magic hash.
+ *
+ * Every spend is resolved to a full description ("what you sign") and run through
+ * the hard safety checks (fee ceiling, recipient/amount exactness, change
+ * ownership) before signing AND before broadcast — also for caller-supplied raw hex.
+ */
+declare class WalletAccountZcash extends WalletAccountReadOnlyZcash implements IWalletAccount {
+    /** UTXOs and the tip height come from the network before signing. */
+    readonly needsNetwork = true;
+    /** Derivation path, or `external` for an external signer. */
+    readonly path: string;
+    /** Compressed secp256k1 public key. */
+    readonly publicKey: Uint8Array;
+    /** The signer that holds the key. */
+    readonly signer: Signer;
+    private _disposed;
+    private _readOnly;
+    /** `publicKey` is the signer's compressed secp256k1 key (33 bytes); it is needed synchronously for the address. */
+    constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: ZcashConfig);
+    /** Back-compat: wrap a raw derived key in a {@link LocalSigner} (the account takes ownership; it cannot derive). */
+    static fromPrivateKey(privateKey: Uint8Array, publicKey: Uint8Array, path: string, config?: ZcashConfig): WalletAccountZcash;
+    /** Account index for the standard m/44'/133'/0'/0/i path. */
+    get index(): number | undefined;
+    private live;
+    /** Zcash message signature (zcashd `signmessage` encoding), base64. */
+    sign(message: string | Uint8Array): Promise<string>;
+    private ctx;
+    /** Lock time + expiry + branch id from the tip (or the config override). */
+    private chainParams;
+    /** Sign every input through the signer; the scriptSig is `<DER ‖ 0x01> <pubkey>`. */
+    private signInputs;
+    protected buildSignedTransaction(spend: ZcashSpend): Promise<Built>;
+    private checkMax;
+    /** The outputs a raw transaction spends, fetched through the client (the wire format carries no values). */
+    private spentOutputs;
+    /** Describe a raw signed tx (needs the network for prevouts) and run the safety checks. */
+    private describeRaw;
+    /** "What you sign": the fully resolved spend (signed, NOT broadcast) or a caller's raw hex. */
+    describeTransaction(tx: ZcashTransaction): Promise<ZcashTxDescription>;
+    /** Sign without broadcasting. Returns the raw transaction hex. Raw hex input is returned unchanged. */
+    signTransaction(tx: ZcashTransaction): Promise<string>;
+    quoteSendTransaction(tx: ZcashTransaction): Promise<{
+        fee: bigint;
+    }>;
+    sendTransaction(tx: ZcashTransaction): Promise<TransferResult>;
+    /** Native ZEC only (`token` is rejected). Subject to `transferMaxFee`. */
+    transfer(o: ZcashTransferOptions): Promise<TransferResult>;
+    /** The same address as a {@link WalletAccountReadOnlyZcash}. */
+    toReadOnlyAccount(): IWalletAccountReadOnly;
+    dispose(): void;
+}
+
+/** SLIP-44 coin type: 133 for mainnet, 1 for testnet. */
+declare const coinType: (network: ZcashNetwork) => 133 | 1;
+/**
+ * One seed → Zcash transparent accounts at m/44'/133'/0'/0/i (BIP-44, the path
+ * Zashi, YWallet, Ledger and Trezor use for the transparent receiver) — t1… on
+ * mainnet, tm… on testnet. Paths may be relative to the purpose/coin prefix
+ * ("0'/0/i") or given in full.
+ *
+ * Built with a secp256k1 `Signer` instead of a seed, the manager wraps it:
+ * a derivable `SeedSigner` yields `getAccount(i)` children below its path; a
+ * leaf or external signer is `getAccount(0)`.
+ */
+declare class WalletManagerZcash extends WalletManager<WalletAccountZcash, ZcashConfig> {
+    constructor(seedOrSigner: string | Uint8Array | Signer, config?: ZcashConfig);
+    /** `m/44'/133'` on mainnet (coin type 1 on testnet); account `i` is at `basePath/0'/0/i`. */
+    get basePath(): string;
+    getAccount(index?: number): Promise<WalletAccountZcash>;
+    getAccountByPath(path: string): Promise<WalletAccountZcash>;
+    private fromSigner;
+    /** A read-only account for any transparent address, with this manager's config. */
+    getReadOnlyAccount(address: string): WalletAccountReadOnlyZcash;
+    /** ZIP-317 has no fee market: every tier is the 5000-zatoshi marginal fee per logical action. */
+    getFeeRates(): Promise<FeeRates>;
+}
+
+export { type BlockbookTxDetails, type BlockbookVin, type BlockbookVout, CURRENT_BRANCH_ID, type CoinSelectOptions, type CoinSelection, DEFAULT_EXPIRY_DELTA, DEFAULT_MAX_FEE, DUST_LIMIT, type DecodedAddress, type DescribeContext, FINAL_SEQUENCE, GRACE_ACTIONS, MAINNET_UPGRADES, MARGINAL_FEE, MAX_SEQUENCE, MAX_UTXO_INPUTS, P2PKH_INPUT_SIZE, SIGHASH_ALL, type ScriptKind, type SpendPlan, SpentOutput, TX_VERSION_V5, TooManyInputsError, type TransparentTxV5, type TxInput, type TxOutput, type UnsafeTransactionCode, UnsafeTransactionError, Utxo, VERSION_GROUP_ID_V5, WalletAccountReadOnlyZcash, WalletAccountZcash, WalletManagerZcash, ZcashBlockbookClient, ZcashClient, ZcashConfig, ZcashMaxSpendableResult, ZcashNetwork, ZcashReceipt, ZcashSpend, ZcashTransaction, ZcashTransferOptions, ZcashTxDescription, ZcashTxInfo, addressFor, addressFromPublicKey, addressFromScript, addressPrefix, assertSafe, branchIdForHeight, coinType, conventionalFee, createClient, decodeAddress, WalletManagerZcash as default, describeTransaction, encodeAddress, encodeMessageSignature, estimateSize, hash160, headerDigest, logicalActions, magicHash, outputSize, outputsDigest, p2pkhScriptSig, parseP2pkhScriptSig, parseTx, prevoutsDigest, recoverMessagePublicKey, scriptFor, scriptKind, selectAll, selectCoins, sequenceDigest, serializeTx, sighashAll, signMessageWith, spendableUtxos, transparentDigest, txHashPersonalization, txid, txidDigest };