@paralock/evm

@paralock/evm provides viem clients for Paralock's two EVM escrows, on Tempo and any other EVM chain (Base, Ethereum, Arbitrum, Robinhood Chain, HyperEVM, local anvils):

• ParalockHTLC (htlc mode): a sha256 hash-time-locked escrow. createEvmHtlc.
• ParalockAdaptorEscrow (adaptor mode): releases to a fixed recipient on a one-time signer's signature over claimDigest(id). No hash on-chain. createAdaptorEscrow.

Both contracts store one slot per swap, pay only the recipient fixed at lock time (anyone may submit the claim, for example a relayer), and mark ids and hashlocks settled forever. See Contracts and deployments for the contracts themselves and their addresses.

Install

npm install @paralock/evm viem

Version 0.2.0. Its only dependency is viem. Amounts are bigint token base units (the supported stablecoins have 6 decimals: 25 USDC = 25_000_000n). Expiries are Unix seconds.

createEvmHtlc

function createEvmHtlc(options: CreateEvmHtlcOptions): EvmHtlc

import { createEvmHtlc, knownNetwork } from "@paralock/evm";
import type { Hex } from "viem";

const base = knownNetwork(84532)!; // Base Sepolia
const usdc = base.tokens.USDC!;
const htlc = createEvmHtlc({
  rpcUrl: base.rpcUrl!,
  chainId: base.chainId,
  contract: HTLC,
  account: process.env.EVM_KEY as Hex,
  fromBlock: DEPLOY_BLOCK, // the contract's deployment block
});

const swap = {
  hashlock, // sha256 of the 32-byte secret: the same value as the Zcash HTLC's
  token: usdc,
  sender: htlc.walletClient!.account.address,
  recipient,
  amount: 25_000_000n, // 25 USDC
  expiry: BigInt(Math.floor(Date.now() / 1000) + 3600), // Unix seconds, 1 h from now
};
await htlc.approveIfNeeded(usdc, swap.amount); // exact allowance, only if needed
await htlc.lock(swap);
const preimage = await htlc.waitForClaimPreimage(hashlock, { timeoutMs: 3_600_000 }); // the secret, once claimed

Options

CreateEvmHtlcOptions and CreateAdaptorEscrowOptions share these fields (EvmConnectionOptions plus the scan settings):

EvmHtlc

WaitOptions is { timeoutMs?: number; signal?: AbortSignal }. Without timeoutMs a waiter waits forever. TxResult is { hash: Hex; blockNumber: bigint; gasUsed: bigint }, returned once the transaction is mined and successful.

createAdaptorEscrow

function createAdaptorEscrow(options: CreateAdaptorEscrowOptions): AdaptorEscrow

Same options as createEvmHtlc, with contract set to the ParalockAdaptorEscrow address.

import { createAdaptorEscrow, randomSalt } from "@paralock/evm";

const escrow = createAdaptorEscrow({ rpcUrl, chainId: 84532, contract: ESCROW, account, fromBlock: DEPLOY_BLOCK });
const swap = { token: usdc, sender, recipient, signer, amount: 25_000_000n, expiry, salt: randomSalt() };
await escrow.approveIfNeeded(usdc, swap.amount);
const { id } = await escrow.lock(swap);
const digest = escrow.claimDigest(id); // what `signer` signs: raw, no EIP-191 prefix

// Later, anyone submits signer's signature; the funds go to swap.recipient.
await escrow.claim(swap, signature);
const { v, r, s } = await escrow.waitForClaimSignature(id, { timeoutMs: 60_000 });

AdaptorEscrow

Swap data

Known networks

KNOWN_NETWORKS is a registry of public networks, each value checked on 2026-10-11 against the chain's official docs (and Circle's USDC list), with a live eth_chainId call per RPC and symbol() / decimals() per token. A field is left out where no official source gives it.

KnownNetwork is { chain, chainId, name, testnet, rpcUrl?, explorerUrl?, nativeCurrency?, usdc?, tokens: Record<string, Address> }.

Stablecoins (tokens; all have 6 decimals):

The SDK's createTaker uses these tokens as the default accepted stablecoins for a chain id. plainEvmChain uses the name, gas token and explorer.

Tempo

Tempo has no native gas token: fees are paid in TIP-20 USD stablecoins. Every TIP-20 token lives at an address starting with 0x20c0….

• Fee token. With feeToken set, every transaction is sent as a Tempo (0x76) transaction paying fees in that token. Set it on Moderato and mainnet to a stablecoin the account holds, for example TEMPO_TOKENS.PathUSD or OUSD. Without it, plain EIP-1559 transactions are sent and the node picks the account's fee token (its FeeManager preference, preset for anvil dev accounts).
• Chain detection. TEMPO_CHAIN_IDS is [4217, 42431, 31318, 1337, 31337]: mainnet, Moderato, Tempo devnet, tempo node --dev, and the Paralock devnet's anvil --network tempo (ANVIL_TEMPO_CHAIN_ID, 31337). 31337 is also plain anvil's default id: pass tempo: false to use it as an ordinary EVM chain.
• Memos. On TIP-20 tokens the contracts move funds with transferFromWithMemo / transferWithMemo, with the hashlock or escrow id as memo, so explorers can link every movement to its swap.
• Storage cost. Each new storage slot costs about 250k gas (TIP-1000), so a ParalockHTLC lock costs about 305k gas on a local Tempo chain.

import { TEMPO_TOKENS, createEvmHtlc } from "@paralock/evm";

const htlc = createEvmHtlc({
  rpcUrl: "https://rpc.moderato.tempo.xyz",
  chainId: 42431,
  contract: HTLC,
  account,
  fromBlock: DEPLOY_BLOCK,
  feeToken: TEMPO_TOKENS.PathUSD, // pay gas in pathUSD
});

TEMPO_TOKENS lists PathUSD, AlphaUSD, BetaUSD, ThetaUSD (dev tokens, pre-funded on local chains and from the Moderato faucet) and OUSD (Open USD on Tempo mainnet and Moderato).

Errors

Every write is simulated first (simulateContract), so a call that would revert throws viem's contract error, carrying the contract's custom error (for example SwapExpired), before any transaction is sent. Plain Errors are thrown for a read-only client asked to send, a preimage that doesn't match the hashlock, a claim signature that doesn't recover to swap.signer, and a Locked event that doesn't match the on-chain state.

ABIs and deployment

The ABIs are generated from the Foundry build (pnpm --filter @paralock/evm generate:abi) and typed as const, so viem infers argument and event types.

The aliases from the package's earlier name, @paralock/tempo, remain: createTempoHtlc, createTempoClients, TempoHtlc, TempoClients, TempoConnectionOptions, CreateTempoHtlcOptions.

Security notes

• Set fromBlock to the deployment block on public chains: lock lookups scan logs from there.
• getLock and getLockedSwap rebuild a swap from its Locked event and check it against the on-chain commitment (HTLC) or id (adaptor escrow). Use getLock().blockNumber to require confirmations before acting on a lock.
• Allowances are exact, never unlimited.
• Fee-on-transfer and other non-standard ERC-20s are rejected by the contracts.