@paralock/zcash

@paralock/zcash builds the Zcash side of a Paralock swap in pure TypeScript: sha256 HTLCs, 2-of-2 multisig locks with pre-signed time-locked refunds, v5 transactions with ZIP 244 signature hashes (checked against the official test vectors), ZIP 317 fees, and a Zebra or Zakura JSON-RPC client.

It is browser-safe: no Node built-ins. Its only dependencies are @noble/hashes, @noble/curves and @scure/base.

Install

npm install @paralock/zcash

Version 0.2.0. Conventions:

• Amounts are bigint zatoshi (1 ZEC = 100,000,000 zat).
• Txids are display-order hex without 0x.
• Functions that take Uint8Array | string accept bytes or hex, with or without 0x. Returned hex (pubkeys, hashlocks in Htlc.params) is lowercase without 0x.
• Network is "mainnet" | "testnet" | "regtest". Regtest shares testnet's address prefixes.
• Heights and lock times are block heights, never timestamps.

Keys and addresses

HTLC

The script

The HTLC is a P2SH output. Its redeem script puts the claim branch first, with a sha256 hashlock and a 32-byte size check:

OP_IF
  OP_SIZE 32 OP_EQUALVERIFY OP_SHA256 <hashlock> OP_EQUALVERIFY <claimPubkey>
OP_ELSE
  <refundHeight> OP_CHECKLOCKTIMEVERIFY OP_DROP <refundPubkey>
OP_ENDIF
OP_CHECKSIG

• Claim: <sig> <secret> OP_1 <redeemScript>. Works before and after the timeout.
• Refund: <sig> OP_0 <redeemScript>, with lock_time = refundHeight and a non-final input sequence. It can be mined once the tip reaches refundHeight (in block refundHeight + 1 or later).

The same hashlock (sha256 of the secret) locks the EVM side, see ParalockHTLC.

Creating and parsing

Building transactions

Every builder returns a SignedTx:

They take a Utxo ({ txid: string; vout: number; value: bigint; scriptPubKey: Uint8Array | string }) and the shared TxOptions:

Builders throw on a missing or malformed branchId or network, insufficient funds, a UTXO the key doesn't own, a duplicate UTXO, a UTXO value outside (0, MAX_MONEY], an output below DUST_LIMIT, a negative fee override or one not below the value spent, or an amount that doesn't cover the fee.

End-to-end HTLC example

The taker locks 0.1 ZEC for the maker. The maker claims with the secret, or the taker refunds after 144 blocks. Anyone can read the secret from the claim.

import {
  FUNDING_EXPIRY_DELTA,
  ZcashRpc,
  buildHtlcClaim,
  buildHtlcFunding,
  buildHtlcRefund,
  createHtlc,
  extractPreimage,
  keyAddress,
  keyPairFromPrivate,
} from "@paralock/zcash";

const network = "testnet";
const rpc = new ZcashRpc("http://127.0.0.1:18232", { timeoutMs: 15_000, retries: 3 });
const taker = keyPairFromPrivate(process.env.TAKER_KEY!); // funds the lock; can refund it
const maker = keyPairFromPrivate(process.env.MAKER_KEY!); // claims it with the secret

// 1. A 32-byte secret. Its sha256 is the hashlock.
const secret = crypto.getRandomValues(new Uint8Array(32));
const hashlock = new Uint8Array(await crypto.subtle.digest("SHA-256", secret));

// 2. The HTLC: the maker claims with the secret, the taker refunds from block tip + 144.
const tip = await rpc.getBlockCount();
const branchId = await rpc.getNextBranchId(); // always sign with the node's next branch id
const htlc = createHtlc(
  { hashlock, claimPubkey: maker.publicKey, refundPubkey: taker.publicKey, refundHeight: tip + 144 },
  network,
);

// 3. Fund it from the taker's UTXOs. The funding expires if it isn't mined within 40 blocks.
const amount = 10_000_000n; // 0.1 ZEC
const funding = buildHtlcFunding({
  htlc,
  amount,
  utxos: await rpc.getAddressUtxos([keyAddress(taker, network)]), // all of them are spent
  key: taker,
  branchId,
  network,
  expiryHeight: tip + FUNDING_EXPIRY_DELTA,
});
await rpc.sendRawTransaction(funding.hex);
const utxo = { txid: funding.txid, vout: 0, value: amount, scriptPubKey: htlc.scriptPubKey };

// 4a. The maker claims with the secret. The fee (10,000 zat) comes out of the HTLC.
const claim = buildHtlcClaim({ htlc, utxo, key: maker, preimage: secret, to: keyAddress(maker, network), branchId, network });
await rpc.sendRawTransaction(claim.hex);

// 4b. Or, once the tip reaches refundHeight, the taker refunds.
const refund = buildHtlcRefund({ htlc, utxo, key: taker, to: keyAddress(taker, network), branchId, network });

// 5. Anyone can read the secret from the confirmed claim.
const spend = await rpc.findSpend(htlc.address, funding.txid, 0);
const revealed = spend && extractPreimage(spend.vin[0]!.scriptSig!.hex, htlc.params.hashlock);

2-of-2 multisig

Private (adaptor) mode locks ZEC in a plain 2-of-2 multisig: OP_2 <pkA> <pkB> OP_2 OP_CHECKMULTISIG with BIP 67 sorted keys. On-chain it looks like any multisig: no hashlock, no timelock. The refund path is a pre-signed transaction with a lock_time.

A signature can come from anywhere, for example one completed from an adaptor pre-signature with der(sig) plus the sighash byte.

import {
  bytesToHex,
  buildMultisigSpend,
  createMultisig2of2,
  finalizeMultisigSpend,
  signMultisigSpend,
  verifyMultisigSignature,
} from "@paralock/zcash";

const multisig = createMultisig2of2(alice.publicKey, bob.publicKey, "testnet");
const utxo = { txid: fundingTxid, vout: 0, value: 10_000_000n, scriptPubKey: multisig.scriptPubKey };

// Alice's time-locked refund, signed by Bob BEFORE Alice funds the multisig.
const refund = buildMultisigSpend({ multisig, utxo, to: aliceAddress, lockTime: refundHeight, branchId, network: "testnet" });
const bobSig = signMultisigSpend(refund, bob);
if (!verifyMultisigSignature(refund, bob.publicKey, bobSig)) throw new Error("bad refund signature: don't fund");

// After refundHeight, Alice completes and broadcasts it.
const signed = finalizeMultisigSpend(refund, {
  [bytesToHex(alice.publicKey)]: signMultisigSpend(refund, alice),
  [bytesToHex(bob.publicKey)]: bobSig,
});

This is safe because the funding txid is final before anyone signs it: v5 txids don't commit to signatures.

Transactions

Paralock builds transparent-only v5 transactions (ZIP 225).

Signature hashes (ZIP 244)

function transparentSighash(
  tx: TransparentTx,
  index: number,
  prevouts: PrevOut[],
  hashType: number = SIGHASH_ALL,
  shielded?: ShieldedDigests,
): Uint8Array

The ZIP 244 signature digest for transparent input index. prevouts lists the value and scriptPubKey of every spent output, in input order. For a P2SH input the scriptPubKey is the P2SH script, not the redeem script. All six sighash types are supported and checked against the official vectors; Paralock uses SIGHASH_ALL everywhere.

The digest building blocks are exported too: blake2b256(personalization, data), headerDigest, prevoutsDigest, sequenceDigest, outputsDigest, transparentTxidDigest, emptySaplingDigest, emptyOrchardDigest, txidPersonalization(branchId) and the ShieldedDigests type.

Fees (ZIP 317)

function zip317Fee(tx: Pick<TransparentTx, "inputs" | "outputs">): bigint

The ZIP 317 conventional fee of a transparent-only transaction, in zatoshi:

5000 × max(2, max(ceil(inputBytes / 150), ceil(outputBytes / 34)))

Inputs are sized with their final scriptSig, so pass a transaction with placeholder signatures of realistic length. The builders use 73-byte placeholders (the DER maximum plus the sighash byte), so the fee never comes out short. A one-input, one-output HTLC or 2-of-2 spend costs 10,000 zat.

Constants and limits

assertOutputValue(value, what?), assertExpiryHeight(expiryHeight) and assertP2shSizes(redeemScript, scriptSig) throw when a value breaks these limits.

The ZcashNode interface

ZcashNode is the backend the SDK engines depend on. ZcashRpc implements all of it. Light backends such as LightwalletdClient implement the required methods and may omit the optional ones.

ZcashRpc

class ZcashRpc implements ZcashNode {
  constructor(url: string, options?: ZcashRpcOptions);
}

JSON-RPC client for Zebra and Zakura nodes (and zcashd-compatible endpoints). Browser-safe: it uses fetch. Every call has a timeout. Idempotent calls are retried with exponential backoff on transport failures (network errors, timeouts, HTTP 5xx, non-JSON bodies). JSON-RPC errors are thrown at once.

A bare { username, password } second argument is still accepted (0.1 compatibility).

Errors

import { ZcashRpcError } from "@paralock/zcash";

try {
  await rpc.sendRawTransaction(hex);
} catch (err) {
  if (!(err instanceof ZcashRpcError && err.alreadyKnown)) throw err; // already broadcast: fine
}

Low-level helpers

Security notes

• Public keys are checked to be valid compressed points. HTLC claim and refund keys must differ.
• Signatures are low-S, strict DER, with RFC 6979 nonces. finalizeMultisigSpend verifies both signatures.
• The builders require network, so an address from the wrong network is rejected, and branchId, so nothing is signed for the wrong upgrade.
• Read the branch id from your node and check upgradeBefore for pre-signed spends.
• Redeem scripts and scriptSigs are checked against consensus and relay size limits.
• Check counterparty scripts with htlcFromRedeemScript or multisigFromRedeemScript: both rebuild the template and compare bytes.