@paralock/sdk

@paralock/sdk runs both sides of a swap between ZEC and stablecoins on EVM chains. The taker sells ZEC: it locks ZEC on Zcash and receives stablecoins, for itself or for a third party (a payment). The maker quotes, locks stablecoins on the EVM chain and claims the ZEC. Either both legs settle or both refund.

The SDK wires a Zcash backend, the EVM escrow clients and a durable store. It persists every secret before it matters, and it resumes or refunds swaps after a crash. Start with createTaker or createMaker. Everything else is exported for custom wiring.

Install

npm install @paralock/sdk

Version 0.2.0. Node.js 20 or newer (the SDK uses node:crypto and node:fs, so it does not run in a browser). It depends on @paralock/zcash, @paralock/adaptor, @paralock/evm and viem.

Units used on this page:

createTaker

function createTaker(options: CreateTakerOptions): Taker

Builds a Taker from plain configuration. It throws ParalockError("invalid_request") for a bad key, address, URL or chain entry, when no EVM chain is configured, and when zcash.network is "mainnet" and the store is not durable.

import { type Hex, createTaker } from "@paralock/sdk";

const taker = createTaker({
  zcash: { network: "testnet", rpcUrl: "http://127.0.0.1:18232", key: process.env.ZEC_KEY! },
  evm: {
    base: {
      rpcUrl: "https://sepolia.base.org",
      chainId: 84532, // Base Sepolia
      htlc: HTLC, // ParalockHTLC
      adaptorEscrow: ESCROW, // ParalockAdaptorEscrow (private mode)
      account: process.env.EVM_KEY as Hex,
      fromBlock: DEPLOY_BLOCK,
      // tokens: defaults to the registry's USDC for chain id 84532
    },
  },
  maker: "https://maker.example",
  store: "./paralock-taker", // a FileSwapStore: secrets and refund data
});

const quote = await taker.quoteExactOut(25_000_000n, "base", "adaptor"); // exactly 25 USDC
const swap = await taker.swap(quote, { recipient: "0x1111111111111111111111111111111111111111" });

Contract addresses and deployment blocks are listed on Contracts and deployments.

CreateTakerOptions

Zcash options

ZcashOptions is shared by createTaker and createMaker.

The taker funds swaps from the key's P2PKH address (taker.zcashAddress). Keep the key: htlc-mode refunds are signed with it.

Chain options (taker)

The key is an EvmChain name (tempo, base, ethereum, arbitrum, robinhood, hyperevm). The chainId selects the network, so base with chainId: 84532 is Base Sepolia. These fields come from EvmChainOptions and are shared with the maker:

The taker adds TakerEvmChainOptions:

TakerLimits

DEFAULT_TAKER_LIMITS holds the defaults. TakerLimits extends QuoteLimits.

TakerTimeouts

DEFAULT_TAKER_TIMEOUTS holds the defaults. All values are milliseconds.

createMaker

function createMaker(options: CreateMakerOptions): Maker

Builds a Maker. Call await maker.start() to resume unfinished swaps, then serve it with makerHandler. It throws ParalockError("invalid_request") for bad configuration (including a spreadBps outside [0, 10000) or limits.minZecAmountZat not above limits.zcashFeeZat), and ParalockError("unsafe_timeouts") for an incoherent policy.

import { createServer } from "node:http";
import { type Hex, createMaker, makerHandler, zecUsdPrice } from "@paralock/sdk";

const maker = createMaker({
  zcash: { network: "testnet", rpcUrl: "http://127.0.0.1:18232", key: process.env.ZEC_KEY!, payoutAddress: PAYOUT },
  evm: {
    base: {
      rpcUrl: "https://sepolia.base.org",
      chainId: 84532,
      htlc: HTLC,
      adaptorEscrow: ESCROW,
      account: process.env.EVM_KEY as Hex,
      fromBlock: DEPLOY_BLOCK,
      token: { address: USDC, symbol: "USDC", decimals: 6 },
    },
  },
  price: zecUsdPrice(), // no fixed fallback: an outage stops quoting
  spreadBps: 50,
  limits: { maxZecAmountZat: 500_000_000n, maxConcurrentSwaps: 20 },
  store: "./paralock-maker",
});
await maker.start(); // resumes every unfinished swap

const handle = makerHandler(maker, { cors: { origin: ["https://app.example"] } });
createServer(async (req, res) => {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer); // also cap the size at your proxy
  const headers = new Headers();
  for (const [k, v] of Object.entries(req.headers)) if (typeof v === "string") headers.set(k, v);
  const body = chunks.length ? Buffer.concat(chunks) : undefined;
  const response = await handle(new Request(`http://maker${req.url}`, { method: req.method, headers, body }));
  res.writeHead(response.status, Object.fromEntries(response.headers)).end(await response.text());
}).listen(7420);

See Run a maker for operations.

CreateMakerOptions

Chain options (maker)

MakerEvmChainOptions takes every EvmChainOptions field from the taker table (rpcUrl, chainId, htlc, adaptorEscrow, account, fromBlock, feeToken, tempo, rpcTimeoutMs, rpcRetryCount) plus:

MakerLimits

DEFAULT_MAKER_LIMITS holds the defaults.

Taker

class Taker {
  constructor(cfg: TakerConfig);
}

The taker side of a ZEC to stablecoin swap. It holds the secret (htlc mode) or the adaptor secret (adaptor mode) and reveals it only by claiming on the EVM chain, after verifying the maker's lock on-chain. Every secret and key is written to the store before any transaction is broadcast, so resume and refund work after a crash.

Running a swap

swap(quote, opts) validates the quote, persists the secret, keys and signed funding, has the maker commit to the funding (htlc: accept, which consumes the quote and reserves the maker's stablecoins; adaptor: the maker signs the refund), and only then broadcasts it. Right before asking the maker, it re-checks the quote's expiry (with 5 s of allowance for clock skew) and fails without broadcasting if it has passed. It then waits for the maker's EVM lock and verifies it: recipient, token, amount, signer and release pre-signature (adaptor mode), minConfirmations and at least minClaimWindowSeconds left. Only then does it claim, which reveals the secret. It resolves once the stablecoins are claimed, after waiting up to timeouts.followMakerMs for the maker's ZEC claim (status completed if seen, evm_claimed otherwise).

Errors:

• Before anything is broadcast, errors are thrown as they are, usually a ParalockError: quote_rejected (validation), invalid_request (a bad option), conflict (the quote was already used), unsafe_timeouts (adaptor mode: a network upgrade activates before the refund height), quote_expired (the quote expired before the maker committed), or the maker's own error when it refuses to commit (busy, insufficient_liquidity, …). The swap is marked abandoned.
• Once the funding may have reached the network, it throws SwapFailedError. The swap stays in the store and taker.refund(err.swap.id) returns the ZEC once the refund height is reached. A funding broadcast that fails without the node reporting the transaction also throws SwapFailedError: a node may have it anyway, so the swap stays pending until resume settles it.

import { SwapFailedError } from "@paralock/sdk";

try {
  await taker.swap(quote, { privacy: { freshRecipient: true, relayClaim: true } });
} catch (err) {
  if (!(err instanceof SwapFailedError)) throw err; // nothing was locked
  console.log(`failed after locking (${err.code}); refunding`);
  await taker.refund(err.swap.id); // waits for the refund height
}

SwapOptions

PrivacyOptions

These options don't hide the link between the two legs of one swap (adaptor mode does that). They keep a swap from linking to the rest of your activity. See Privacy.

Resuming a swap

resume(id, { claim, relayClaim }) continues a persisted swap after a restart. It claims if the maker's lock is there and still safe to claim, and follows the maker's ZEC claim. claim overrides the option the swap was started with, so resume(id, { claim: true }) claims a swap started with claim: false. relayClaim: false submits the claim from your own EVM account, for example after the relayer refused (the SDK doesn't fall back by itself); the recipient stays the one in the lock. A finished swap is returned as it is.

A swap interrupted before its funding reached the network is resumed conservatively:

• prepared (the maker never committed): marked abandoned (status failed, nothing was locked); the funding is not broadcast.
• reserved or proposed (the maker committed): the funding is broadcast late only if the tip is at least FUNDING_BROADCAST_MARGIN_BLOCKS (5) below its expiry height, at least limits.minZcashLockBlocks of the refund window remain, and the maker still holds the swap. The maker re-checks its timeout policy on every poll and drops a reservation it can no longer lock safely, so that check covers the windows. Otherwise the swap is marked abandoned.
• A funding that was already handed to a node is never given up on while it could still be mined: resume throws conflict until the tip is more than FUNDING_EXPIRY_MARGIN_BLOCKS (2) past its expiry height, then marks the swap abandoned.

Refunding a swap

refund(swapOrId, { wait }) refunds the Zcash lock once the chain tip reaches the swap's refund height. By default it waits for that height (polling every max(pollIntervalMs, 15 s), or mining with mineZcash on a devnet). With wait: false it throws ParalockError("conflict") with the message "the refund opens at block N" instead. It works after a restart: everything it needs is in the store. It resolves once the refund transaction confirms.

It throws not_found when the swap isn't in this taker's store, and conflict when the lock was already spent (the maker claimed it) or the funding never confirmed.

for (const swap of await taker.pendingSwaps()) {
  try {
    await taker.resume(swap.id); // claims if the maker's lock is there and still safe to claim
  } catch {
    await taker.refund(swap.id); // waits for the refund height, then returns the ZEC
  }
}

See Persistence and recovery.

Swap ids

TakerStage

The taker persists an internal stage per swap (TakerSwapRecord.stage):

TakerConfig

new Taker(config) takes already-built clients instead of plain options. Use it to plug in your own EVM client library or a custody API.

MakerApi is the interface a taker uses to talk to a maker: quote, quoteExactOut, accept, getSwap, proposeAdaptor, adaptorPreSignature, with the same signatures as on Maker. Maker and HttpMakerApi both implement it.

Maker

class Maker implements MakerApi {
  constructor(cfg: MakerConfig);
}

The market-maker side of ZEC to stablecoin swaps on every configured EVM chain, in both modes. It never locks stablecoins before the taker's ZEC is confirmed in a lock it verified byte for byte, with the exact value, while the remaining Zcash window still outlasts the EVM lock by policy.safetyFactor. Every quote, swap and per-swap key is persisted before it is used.

The quoted rate is price × (1 − spreadBps / 10,000), in USD per ZEC.

Quote errors: invalid_request (unknown chain, bad mode, chain not served, private mode not configured), busy (too many open quotes or swaps in flight), limit_exceeded (outside minZecAmountZat to maxZecAmountZat, or a zero dollar amount), insufficient_liquidity (not enough stablecoin after reservations) and unavailable (price feed down).

MakerStage

Protocol messages

adaptorSpends(args) builds the two spends of the 2-of-2 lock (time-locked refund and claim) exactly as both parties must, so their sighashes match. See How it works for the protocol.

MakerConfig

new Maker(config) takes built clients: network, zcash: ZcashNode, zcashKey: KeyPair, zcashPayoutAddress: string, chains: Partial<Record<EvmChain, ChainClients>>, price, spreadBps: number (required here), policy: TimeoutPolicy (required here), and optional limits, store, pollIntervalMs, afterClaim, log. quoteTtlSeconds is deprecated: use limits.quoteTtlSeconds.

ChainClients is { chain, chainId, token, tokenSymbol, tokenDecimals, htlc: EvmClient, adaptor?: AdaptorEvmClient }.

Core types

Quote

A maker's offer. The taker validates it before acting on it.

Swap

The public view of a swap. It never contains secrets or private keys; those live only in the SwapStore.

SwapStatus

ZcashLeg

EvmLeg

SwapEvent

SwapMode and EvmChain

type SwapMode = "htlc" | "adaptor";
type EvmChain = "tempo" | "base" | "ethereum" | "arbitrum" | "robinhood" | "hyperevm";
type Chain = "zcash" | EvmChain;

EVM_CHAIN_NAMES: Record<EvmChain, string> maps them to display names ("Robinhood Chain", "HyperEVM", …). createTaker and createMaker accept only these six names. Each one works with any chain id and RPC where the Paralock escrows are deployed (for example its testnet); another chain needs a new EvmChain name.

Timeout policy

The maker's EVM lock must expire well before the taker's Zcash refund height, so whoever learns the secret always has time to use it on the other chain. The rule: Zcash blocks left × zcashBlockSeconds must be at least safetyFactor × EVM lock seconds.

MAINNET_POLICY is the default of createMaker on every network (Zcash testnet also has 75 s blocks). DEVNET_POLICY uses short windows so refunds can be demoed on the local devnet.

assertValidPolicy(policy) and assertSafeWindows(policy, blocksUntilZcashRefund, evmLockSeconds) throw ParalockError("unsafe_timeouts"). The maker checks the window when it accepts a lock and again right before it locks stablecoins.

Two constants govern the funding's expiry height (FUNDING_EXPIRY_DELTA, 40 blocks after it is built): FUNDING_BROADCAST_MARGIN_BLOCKS (5), the taker broadcasts a funding only while the tip is at least this far below its expiry; and FUNDING_EXPIRY_MARGIN_BLOCKS (2), once the tip is more than this far past it and the funding is unmined, both sides treat it as dead (the maker drops its reservation, the taker abandons the swap).

Stores

SwapStore

interface SwapStore {
  readonly durable: boolean;
  get<T extends StoredRecord = Record<string, unknown>>(key: string): Promise<T | undefined>;
  put(key: string, record: StoredRecord): Promise<void>;
  delete(key: string): Promise<void>;
  list<T extends StoredRecord = Record<string, unknown>>(prefix: string): Promise<{ key: string; record: T }[]>;
}

Keys are short ASCII paths: [A-Za-z0-9._:/-], at most 200 characters, no .., not starting with / (assertStoreKey checks this). The taker writes taker/<id>; the maker writes maker/quote/<id> and maker/swap/<id>.

MemorySwapStore and FileSwapStore

Custom stores

encodeRecord(record) and decodeRecord(json) serialize records to JSON with bigints tagged as { "$bigint": "123" }, so a database-backed store round-trips them exactly.

import { type StoredRecord, type SwapStore, assertStoreKey, decodeRecord, encodeRecord } from "@paralock/sdk";

/** Your database client. */
interface Kv {
  get(key: string): Promise<string | undefined>;
  set(key: string, value: string): Promise<void>;
  delete(key: string): Promise<void>;
  scan(prefix: string): Promise<[string, string][]>;
}

/** A store over any key-value database with durable writes. */
class KvSwapStore implements SwapStore {
  readonly durable = true;
  constructor(private readonly db: Kv) {}

  async get<T extends StoredRecord = Record<string, unknown>>(key: string): Promise<T | undefined> {
    const json = await this.db.get(key);
    return json === undefined ? undefined : decodeRecord<T>(json);
  }
  async put(key: string, record: StoredRecord): Promise<void> {
    assertStoreKey(key);
    await this.db.set(key, encodeRecord(record)); // must be durable when it resolves
  }
  async delete(key: string): Promise<void> {
    await this.db.delete(key);
  }
  async list<T extends StoredRecord = Record<string, unknown>>(prefix: string): Promise<{ key: string; record: T }[]> {
    const rows = await this.db.scan(prefix); // sorted by key
    return rows.map(([key, json]) => ({ key, record: decodeRecord<T>(json) }));
  }
}

HTTP transport

Bigints travel as decimal strings. toJson(value) encodes them; reviveQuote and reviveSwap restore the bigint fields of JSON received from a maker.

makerHandler

function makerHandler(maker: Maker, options?: MakerHandlerOptions): (req: Request) => Promise<Response>

A web-standard Request to Response handler, so it runs in Node (through a small adapter, as in the createMaker example), Bun, Deno, Next.js route handlers and Cloudflare Workers. Put it behind TLS and a rate limiter.

Routes:

chain defaults to tempo and mode to htlc. Amounts must be 1 to 30 decimal digits. Swap ids in paths are a UUID or a 0x hashlock. Responses carry cache-control: no-store.

Errors are JSON { "error": string, "code": ParalockErrorCode } with the code's HTTP status (see Errors). Unexpected errors become a generic 500 with code internal, or 503 with code unavailable when the maker's Zcash node fails.

HttpMakerApi

class HttpMakerApi implements MakerApi {
  constructor(url: string, options?: HttpMakerApiOptions);
  readonly url: string;
  health(): Promise<{ ok: boolean; chains: EvmChain[]; zcashPubkey?: string }>;
}

Talks to a makerHandler over HTTP and validates every response (parseQuote) before use. getSwap returns undefined on 404. Failed requests throw ParalockError with the maker's code (or unavailable when the code is unknown or the maker is unreachable) and a message prefixed maker: .

Errors

class ParalockError extends Error {
  readonly code: ParalockErrorCode;
  readonly status: number; // HTTP status of the code
}

Expected failures throw ParalockError with a stable code. Messages are safe to show to a counterparty: they never include keys, secrets, RPC URLs or stack traces.

import { isParalockError } from "@paralock/sdk";

try {
  await taker.quote(10_000_000n, "base", "adaptor");
} catch (err) {
  if (isParalockError(err) && err.code === "busy") {
    // the maker is at capacity: retry later
  } else throw err;
}

Helpers

zecUsdPrice

function zecUsdPrice(opts?: PriceFeedOptions): () => Promise<number>

USD per ZEC from CoinGecko (or url), cached, with bounded staleness. Pass the result as price.

zatToUsdUnits(zat, usdPerZec, decimals) converts zatoshi to token base units, rounding down. usdUnitsToZat(usdUnits, usdPerZec, decimals) converts back, rounding up so a payee always gets the full amount. Both use the price truncated to 6 decimal places.

Retry and polling

RetryOptions: retries (default 3, extra attempts after the first), minDelayMs (250), maxDelayMs (10_000), signal, shouldRetry(err, attempt) (return false to fail at once), onRetry(err, attempt, delayMs).

PollOptions: what (used in the timeout message, required), intervalMs (required), timeoutMs (default: never), giveUp() (stop as soon as it returns true), signal, onError(err), onIdle() (runs after every unsuccessful check; devnets mine a block there).

import { pollUntil } from "@paralock/sdk";

const confirmed = await pollUntil(
  async () => ((await node.getRawTransaction(txid)).confirmations ?? 0) > 0 || undefined,
  { what: `transaction ${txid}`, intervalMs: 5_000, timeoutMs: 600_000 },
);

Wiring and keys

Privacy and amounts

Validation

Everything that crosses a trust boundary is validated with these. Failures throw ParalockError (quote_rejected for validateQuote, invalid_request for the parsers).

Zcash backend helpers

Engine interfaces

EvmClient (htlc mode) and AdaptorEvmClient (adaptor mode) are what the engines need from an EVM chain: lock, claim, refund, getLock, getLockedSwap, outcome, now, blockNumber, rpcChainId, tokenBalance, plus idOf and claimDigest for the adaptor escrow. evmClientFrom(chain, htlc) and adaptorClientFrom(chain, escrow) implement them over @paralock/evm. Implement them yourself to use another EVM library or a custody API. The deprecated waitForClaimPreimage and waitForClaimSignature remain; poll outcome instead.

Devnet helpers

Built on the same factories, for the local devnet that paralock devnet up writes to .paralock/devnet.json: