relayer

Classes

RelayerClient

Thin HTTP client for one relayer’s API. No retry, no caching; callers compose those concerns. Errors throw with the relayer’s error body field when present, falling back to the HTTP status line. Every method accepts an optional signal so callers can cancel from a UI’s AbortController.

Constructors

Constructor

new RelayerClient(baseUrl, opts?): RelayerClient;

Parameters

Returns

RelayerClient

Methods

getInfo()

getInfo(signal?): Promise<RelayerApiInfo>;

Parameters

Returns

Promise<RelayerApiInfo>

getStats()

getStats(signal?): Promise<RelayerStatsResponse>;

Public stats from /api/relayer/stats — operational counters (totalOrders, settledOrders, avgSettleTimeMs, …). No auth, no PII; surfaces for cross-relayer comparison on the leaderboard.

Parameters

Returns

Promise<RelayerStatsResponse>

submitOrder()

submitOrder(
   order, 
   signature, 
   feeMode?, 
   signal?): Promise<{
  status: string;
  txHash?: string;
  nonce?: string;
}>;

Parameters

Returns

Promise<{ status: string; txHash?: string; nonce?: string; }>

getOrders()

getOrders(address, signal?): Promise<RelayerOrder[]>;

Parameters

Returns

Promise<RelayerOrder[]>

getOrderHistory()

getOrderHistory(address, opts?): Promise<OrderHistoryResponse>;

Parameters

Returns

Promise<OrderHistoryResponse>

getOrderDetail()

getOrderDetail(
   address, 
   nonce, 
signal?): Promise<RelayerOrder>;

Parameters

Returns

Promise<RelayerOrder>

cancelOrder()

cancelOrder(
   address, 
   nonce, 
   signature, 
signal?): Promise<void>;

Parameters

Returns

Promise<void>

submitClaim()

submitClaim(body, signal?): Promise<{
  status: string;
  txHash: string;
}>;

Submit a recipient’s claim for the relayer to dispatch. Pairs with POST /api/private-claim on zk-relayer (route validates the proof + the claimsRoot the relayer settled). The relayer pays gas in exchange for having earned the settle fee.

Parameters

Returns

Promise<{ status: string; txHash: string; }>

submitAuthorizeOrder()

submitAuthorizeOrder(body, signal?): Promise<AuthorizeOrderStatus>;

Submit a same-token scatter authorize proof for the relayer to dispatch via scatterDirectAuth. Pairs with POST /api/authorize-orders on zk-relayer; the order is queued and the relayer’s settlement worker calls the contract once the pre-flight checks pass. The endpoint returns a 202 with the nullifier, which the caller polls via pollAuthorizeOrder until settleTxHash lands.

Parameters

Returns

Promise<AuthorizeOrderStatus>

pollAuthorizeOrder()

pollAuthorizeOrder(nullifier, signal?): Promise<AuthorizeOrderStatus>;

Poll the order status. Used after submitAuthorizeOrder to wait for the relayer to actually broadcast the scatterDirectAuth tx.

Parameters

Returns

Promise<AuthorizeOrderStatus>

Interfaces

AuthorizeOrderBody

Wire-format body for POST /api/authorize-orders — same shape the legacy frontend sends. publicSignals is the named-field view; publicSignalsArray mirrors the raw circom output that the relayer re-verifies.

Properties

AuthorizeOrderStatus

Properties

GaslessClaimBody

Wire-format request body for POST /api/private-claim. The relayer revalidates every field on-chain so the recipient page doesn’t have to sign anything; submitting through a relayer is purely a gas-payment relationship.

Properties

FeeVaultBalance

Properties

PendingFeeChange

A scheduled platform-fee change waiting on the timelock. Returns null when no change is pending (the contract zeros both fields once a change is applied or cancelled). effectiveAt is the unix second when applyFeeChange() becomes callable.

Properties

IdentityVerification

Properties

IdentityGateAdminSnapshot

Properties

UpdateRelayerInfoParams

Properties

OperatorRow

Properties

ForceRemoval

Details of an admin-initiated removal (adminRemoveRelayer).

Properties

RegistrationStatus

Properties

RegisterRelayerParams

Properties

BondMeta

Bond token metadata used to render the InsufficientBond minimum in the operator’s actual bond token rather than assuming ETH.

Properties

LoadOpts

Properties

RelayerSettlement

Properties

LoadSettlementsOpts

Properties

RelayerOnChain

Relayer info as recorded in the on-chain RelayerRegistry.

Extended by

• RelayerInfo

Properties

RelayerProfile

Optional metadata a relayer publishes via its /api/info. We trust nothing inside profile: see sanitizeProfile.

Properties

RelayerApiInfo

Live response from a relayer’s /api/info.

Properties

RelayerSettledVolume

Per-token settled volume (one row per sell_token). totalVolume is a wei-string (BigInt-safe) so callers can BigInt() it back.

Properties

RelayerRuntimeMetrics

In-memory metrics shape returned alongside DB-derived counters. Optional because older relayer builds don’t compute it.

Properties

RelayerStatsResponse

Public stats from a relayer’s /api/relayer/stats. Surfaced for cross-relayer comparison (leaderboard performance columns).

• avgSettleTimeMs is null when there are no confirmed settlements in the window (the SQL AVG returns null).
• uptimeSince is null when the started_at meta key is missing or unparseable — independent of settlement count.

Properties

RelayerStatsByApp

Per-app subset of RelayerStatsResponse. Mirrors the aggregate fields the leaderboard ranks on (orders / volume / fees) so the segmented control can re-rank using the same comparator logic.

Properties

RelayerInfo

Combined view: on-chain registry data + live /api/info probe. api is undefined when the relayer is offline / unreachable. stats is undefined when the stats probe failed (older relayer build, network error, or feature not enabled).

Extends

• RelayerOnChain

Properties

RelayerOrder

A single submitted order as the relayer reports it.

Properties

OrderHistoryResponse

Properties

OrderData

Order payload as the relayer expects it on submit.

Properties

Type Aliases

OperatorStatus

type OperatorStatus = "active" | "cooldown" | "offline" | "unregistered";

UI-friendly status derived from the on-chain relayers() row.

• unregistered: never registered on this registry
• active: registered, not in the exit cool-down
• cooldown: requested exit, waiting out the exit cool-down
• offline: registered + exit executed (the row’s active flag is false but registeredAt is non-zero)

SettlementRole

type SettlementRole = "maker" | "taker";

AppSegment

type AppSegment = "pay" | "pro";

One of the two app flows the relayer surfaces in byApp: Pay maps to scatterDirectAuth (single-party direct payouts) and Pro maps to settleAuth (half-proof order matches). Callers model the “All” / aggregate view at the UI layer, not via this type — the aggregate stats already live on RelayerStatsResponse itself, so no null member is needed here.

FeeMode

type FeeMode = "cover_taker";

Fee modes the relayer accepts on submitOrder.

Variables

EXIT_COOLDOWN_SECONDS

const EXIT_COOLDOWN_SECONDS: number;

The registry’s default exit cool-down (7 days). The live value is governance-settable via setExitCooldown and read back from exitCooldown(), so this is only a fallback for the brief window before the live read resolves — UIs that render the countdown or compute the withdrawable time MUST prefer loadExitCooldownSeconds and not bake this constant into either calculation.

NATIVE_BOND_TOKEN

const NATIVE_BOND_TOKEN: string = ethers.ZeroAddress;

Sentinel for native (msg.value) bond mode — bondToken() returns the zero address on registries deployed in native mode (e.g. on Tokamak L2 where TON is the native gas token).

MAX_RELAYER_FEE_BPS

const MAX_RELAYER_FEE_BPS: 500 = 500;

Maximum per-trade fee a relayer may register, in basis points. Mirrors RelayerRegistry.MAX_FEE (50 bps) — kept in sync here so the SDK can reject invalid input before a wallet prompt and so consumer apps don’t redeclare the magic number.

Functions

callExceptionErrorName()

function callExceptionErrorName(err): string | null;

Read the named error off ethers v6 contract-call exceptions when the ABI carries the matching error fragment. Falls back to null so callers can substring-match the message instead. Shared by every per-contract explainXxxError in the relayer module.

Parameters

Returns

string | null

unwrapEthersError()

function unwrapEthersError(err): string;

Best-effort unwrap of an ethers v6 error to a human-readable string. v6 surfaces the user-facing summary on shortMessage, the decoded revert reason on reason, and the underlying provider error on info.error.message. Fall through these in priority order before landing on the raw Error.message so callers (read-side error banners, write-side explainXxxError) always have the most descriptive string available.

Parameters

Returns

string

loadFeeVaultBalances()

function loadFeeVaultBalances(
   feeVaultAddress, 
   operator, 
   tokens, 
provider): Promise<FeeVaultBalance[]>;

Read every passed token’s claimable balance for operator in one shot. Caller decides which tokens to query — typically the network’s tokens whitelist — so this stays a pure batched read with no contract-side enumeration assumed. Tokens whose address is the zero sentinel (unconfigured slot in a partially deployed network config) are skipped.

Parameters

Returns

Promise<FeeVaultBalance[]>

loadPlatformFeeBps()

function loadPlatformFeeBps(feeVaultAddress, provider): Promise<number>;

Read the platform-fee cut (in basis points) that FeeVault skims off the top of every relayer claim(). 0 means no platform cut. Returned as a plain number because the contract caps it at MAX_PLATFORM_FEE (≤ 10_000), well inside safe integer range.

Parameters

Returns

Promise<number>

loadPendingFeeChange()

function loadPendingFeeChange(feeVaultAddress, provider): Promise<PendingFeeChange | null>;

Parameters

Returns

Promise<PendingFeeChange | null>

claimRelayerFees()

function claimRelayerFees(
   feeVaultAddress, 
   tokenAddress, 
signer): Promise<TransactionResponse>;

Submit claim(token) to pull the operator’s accrued balance for a single token. Reverts with NothingToClaim when the balance is zero — gate the button on a non-zero balance read so the wallet prompt never lands on a guaranteed-fail tx.

Parameters

Returns

Promise<TransactionResponse>

explainFeeVaultError()

function explainFeeVaultError(err): string;

Map FeeVault custom-error reverts to user-facing copy. Falls back to the unwrapped ethers v6 message so unexpected errors still surface a useful string instead of [object Object].

Parameters

Returns

string

loadIdentityGateAdmin()

function loadIdentityGateAdmin(gateAddress, provider): Promise<IdentityGateAdminSnapshot>;

One-shot admin read for the IdentityGate management UI. Pure read — no mutation.

Parameters

Returns

Promise<IdentityGateAdminSnapshot>

loadIdentityVerification()

function loadIdentityVerification(
   gateAddress, 
   account, 
provider): Promise<IdentityVerification>;

Read an account’s verification status from an arbitrary IdentityGate contract. zkScatter’s Dual-CA architecture deploys one gate per CA (User CA = privacy-preserving, Relayer CA = full-disclosure), so callers pass the gate address explicitly rather than letting the SDK guess one. Pure read.

Parameters

Returns

Promise<IdentityVerification>

loadExitCooldownSeconds()

function loadExitCooldownSeconds(registryAddress, provider): Promise<number>;

Read the live exit cool-down (in seconds) from the registry’s exitCooldown() getter. Governance can rewrite it via setExitCooldown, so the displayed cool-down and the bond withdrawable time must both derive from this value rather than the EXIT_COOLDOWN_SECONDS fallback. Pure read.

Parameters

Returns

Promise<number>

updateRelayerInfo()

function updateRelayerInfo(
   registryAddress, 
   params, 
signer): Promise<TransactionResponse>;

Submit updateInfo(url, name, fee) — operator-self-service edit of endpoint URL, display name, and per-trade fee. Validates the fee range up front for the same UX reason registerRelayer does.

Parameters

Returns

Promise<TransactionResponse>

addRelayerBond()

function addRelayerBond(
   registryAddress, 
   bondEth, 
   signer, 
bondToken?): Promise<TransactionResponse>;

Submit addBond(bondAmount).

• Native mode: top-up paid via msg.value.
• ERC20 mode: caller MUST approve the registry for at least bondEth first (see approveBondToken); this helper just submits the addBond call.

When bondToken is omitted, the helper reads bondToken() from the registry itself — convenient for simple top-up UIs that already hold the registry address but not its mode.

Rejects zero / negative amounts before a wallet prompt.

Parameters

Returns

Promise<TransactionResponse>

requestRelayerExit()

function requestRelayerExit(registryAddress, signer): Promise<TransactionResponse>;

Submit requestExit() — flips the operator into the cool-down window. New orders stop routing immediately; bond becomes withdrawable via executeRelayerExit after EXIT_COOLDOWN_SECONDS.

Parameters

Returns

Promise<TransactionResponse>

executeRelayerExit()

function executeRelayerExit(registryAddress, signer): Promise<TransactionResponse>;

Submit executeExit() — finalises the exit and returns the bond. Will revert with CooldownNotPassed until the cool-down window has elapsed; gate the button on cooldownReadyAt.

Parameters

Returns

Promise<TransactionResponse>

loadOperatorRow()

function loadOperatorRow(
   registryAddress, 
   account, 
provider): Promise<OperatorRow>;

Read the on-chain registry row for account. Returns the full set of operator-scoped state every dashboard / profile / treasury page needs, plus a derived status for UI gating. Pure read.

Issues one RPC after the first call per registry: the row read. bondToken is fetched once and memoised because it’s immutable.

Parameters

Returns

Promise<OperatorRow>

loadForceRemoval()

function loadForceRemoval(
   registryAddress, 
   relayer, 
   provider, 
fromBlock?): Promise<ForceRemoval | null>;

Whether relayer was removed by an admin (vs a voluntary exit). Returns the most recent RelayerForceRemoved event’s details, or null when the relayer exited on their own (no such event).

An admin removal sets the same exitRequestedAt cool-down as a self requestExit, so a forced relayer’s row is indistinguishable from a voluntary exit by state alone — the event is the only signal. Only meaningful while the operator is in the cooldown status; call it there, not on every row read.

Uses queryFilter (not contract.on) — event subscriptions stop firing on anvil, and this is a one-shot read anyway.

Parameters

Returns

Promise<ForceRemoval | null>

sanitizeProfile()

function sanitizeProfile(input): RelayerProfile | undefined;

Sanitize the profile block returned by an arbitrary relayer’s /api/info. We trust nothing here: keep only known string fields, enforce a length cap, reject URL fields whose scheme isn’t on the allowlist. Guards against:

• UI crashes from non-string fields breaking .replace etc.
• rendered-link XSS via javascript: / data: schemes
• DOS via huge strings

Returns undefined when the input isn’t a plain object.

Parameters

Returns

RelayerProfile | undefined

loadRegistrationStatus()

function loadRegistrationStatus(
   registryAddress, 
   account, 
provider): Promise<RegistrationStatus>;

Read the prerequisite state for relayer registration: identity verification, prior active-relayer status, the registry’s current minimum bond, and (in ERC20 mode) the operator’s existing allowance.

Parameters

Returns

Promise<RegistrationStatus>

registerRelayer()

function registerRelayer(
   registryAddress, 
   params, 
signer): Promise<TransactionResponse>;

Submit register(url, name, fee, bondAmount).

• Native mode (bondToken omitted or zero): bond paid via msg.value.
• ERC20 mode: caller MUST approve the registry for at least bondAmount first (see approveBondToken); this helper just submits the register call.

Validates fee range and bond format up front so the user sees a clean error before a wallet prompt. Returns the transaction response; caller awaits .wait().

Parameters

Returns

Promise<TransactionResponse>

needsBondApproval()

function needsBondApproval(status, bondEth): boolean;

True when the registry is in ERC20 mode AND the operator’s current allowance is below the desired bond amount, i.e. an approve is required before register / addBond can succeed. Returns false in native mode regardless of the input.

Parameters

Returns

boolean

hasEnoughBondBalance()

function hasEnoughBondBalance(status, bondEth): boolean;

True when the operator holds enough of the bond token to cover bondEth — i.e. bondBalance >= parse(bondEth). In native mode bondBalance is the account’s ETH balance, so this only checks the bond amount, not the extra gas the register tx needs. Returns true on an unparseable amount so a transient input state never blocks the form (the on-chain transfer/msg.value still guards the bond).

Parameters

Returns

boolean

loadBondAllowance()

function loadBondAllowance(
   registryAddress, 
   bondToken, 
   account, 
provider): Promise<bigint>;

Read the operator’s current ERC20 bond-token allowance to the registry. Returns 0n in native mode (no token to query). Useful for top-up UIs that already know the bond token (e.g. via OperatorRow.bondToken) but only need the live allowance.

Parameters

Returns

Promise<bigint>

approveBondToken()

function approveBondToken(
   bondToken, 
   registryAddress, 
   bondEth, 
   signer, 
bondDecimals?): Promise<TransactionResponse>;

Submit ERC20.approve(registry, amount) so the operator can subsequently register or addBond in ERC20 mode. Native-mode registries never need this. Returns the transaction response; caller awaits .wait() before submitting the register call.

Parameters

Returns

Promise<TransactionResponse>

explainRegistryError()

function explainRegistryError(
   err, 
   minBond, 
   bond?): string;

Map known registry custom errors (decoded by ethers from the ABI fragments on RELAYER_REGISTRY_ABI) and local validation errors thrown from any registry write helper to user-friendly copy. Falls back to the raw message when no rule matches so callers don’t swallow unexpected errors. minBond is only used when the error is InsufficientBond; pass 0n if unknown.

Parameters

Returns

string

loadActiveRelayers()

function loadActiveRelayers(registryAddress, provider): Promise<RelayerOnChain[]>;

Read the registry contract’s active list and return the full on-chain row for each. Pure read; no side effects.

Parameters

Returns

Promise<RelayerOnChain[]>

loadRelayersWithApiInfo()

function loadRelayersWithApiInfo(
   registryAddress, 
   provider, 
opts?): Promise<RelayerInfo[]>;

Combine on-chain registry data with a live /api/info probe per relayer. Probes run in parallel; offline relayers come back with online: false and api: undefined.

When withStats is set, also probes /api/relayer/stats in parallel with /api/info. The two probes are independent — a relayer can be online: true (info ok) but have stats: undefined if it’s an older build that doesn’t expose the endpoint.

Parameters

Returns

Promise<RelayerInfo[]>

loadRelayersWithSharedOrderbookStats()

function loadRelayersWithSharedOrderbookStats(
   registryAddress, 
   provider, 
   sharedOrderbookUrl, 
opts?): Promise<RelayerInfo[]>;

Combine on-chain registry + live /api/info (per-peer health probe)

• per-relayer stats aggregated from the shared orderbook indexer instead of each peer’s local DB.

Why prefer shared-OB over peer /api/relayer/stats?

• Survives relayer DB wipe. Peer local DBs reset whenever the relayer is restarted with RESET_STATE=1 or rm’d manually; the shared-OB indexer is the durable source of truth.
• No double-count. Each on-chain settle is one row in shared-OB with explicit maker_relayer / taker_relayer / fee_maker / fee_taker columns, so per-relayer attribution doesn’t depend on whether the peer’s local writer happened to be sell-only or both-leg. Volume here is built sell-side per role (maker_relayer sells sellToken, taker_relayer sells buyToken).
• Revenue parity for counterparty. Fees are attributed by the relayer that brought each order (maker_relayer earns fee_maker in buyToken, taker_relayer earns fee_taker in sellToken), regardless of which peer actually submitted on-chain.

Parameters

Returns

Promise<RelayerInfo[]>

fetchRelayerStatsFromSharedOrderbook()

function fetchRelayerStatsFromSharedOrderbook(
   sharedOrderbookUrl, 
   address, 
timeoutMs?): Promise<RelayerStatsResponse | null>;

Fetch + build per-relayer stats from the shared orderbook for ONE address. Used by the relayer detail page so its numbers don’t drift from the leaderboard (which already reads from shared-OB). Returns null on fetch failure so the caller can fall back to the peer’s local /api/relayer/stats.

Parameters

Returns

Promise<RelayerStatsResponse | null>

loadRelayerSettlements()

function loadRelayerSettlements(
   settlementAddress, 
   relayer, 
   provider, 
opts?): Promise<RelayerSettlement[]>;

Read recent PrivateSettledAuth events where the given relayer was the maker-side counterparty. The contract only indexes makerRelayer, so taker-side settlements require either an indexer or a full-event scan with post-hoc filtering — out of scope for this helper. Returns events sorted newest-first.

Parameters

Returns

Promise<RelayerSettlement[]>