@liq/onchain

Onchain helpers for the Liq perpetuals exchange — deposits, collateral, accounts, positions, and settlement via viem.

Overview

@liq/onchain provides the LiqOnchain façade and individual service classes for all onchain interactions: depositing USDC collateral, managing SNX accounts, reading open positions, and submitting settlement transactions to the Synthetix V3 PerpsMarketProxy. It also exports the canonical contract ABIs and EIP-712 signing utilities. The only runtime dependencies are @liq/core and viem.

Key Exports

LiqOnchain (façade)

Instantiated with OnchainConfig ({ chainId, walletClient, publicClient }). Exposes:

| Property | Service | Description | | ------------- | ------------------------- | ---------------------------------------------------- | | .accounts | AccountsService | Create SNX account NFTs, set book mode | | .collateral | CollateralService | Read available + locked margins | | .deposit | DepositService | USDC → sUSDC → modifyCollateral flow | | .positions | OnchainPositionsService | Read open positions from PerpsMarketProxy | | .delegate | Delegate7702Client | Gasless relay reads: delegate address, state(user) | | .settlement | SettlementService | Call settleBookOrders() |

Builders (standalone, no wallet required)

• DepositBuilder / WithdrawBuilder — build(): TxPlan returns the deposit / withdraw steps; each step's forwarderSafe flag says whether it can ride a wallet-sender batch
• executeTypedData(chainId, user, { calls, nonce, deadline }) — the signTypedData arguments of a relayed batch
• claimFaucetCall(faucetAddress, token) — the faucet claim as one PlanStep (forwarderSafe: false); sent by whichever sender the plan uses, wallet included
• RepayBuilder.build() — the repay legs of a withdraw as a TxPlan (WithdrawBuilder.afterRepay)
• tokenTransferPlan(token, amount, recipients) — a TxPlan of one direct ERC-20 transfer per recipient (forwarderSafe: false: transfer reads msg.sender); token is the { token, decimals } pair a getCollateral result already is, so the address and its decimals cannot drift apart

Sending a plan

A builder only returns a TxPlan (readonly PlanStep[]); turning it into transactions is the sender's job, picked at the call site:

• executePlan(plan, { sender, publicClient }) — sends the plan group by group, waits for each receipt, stops at the first that doesn't land
• walletSender(config) — batches a contiguous forwarderSafe run of steps into one TrustedMulticallForwarder.aggregate3 call; a step marked forwarderSafe: false (a bare ERC-20 approve) goes as its own transaction
• relaySender(config) — sends the whole plan as one Delegate7702.execute batch through the gasless relay (ADR-0063)
• landedOrThrow(outcome, what) — the outcome as a throw: returns LandedTx[] when the plan landed, throws PlanRevertedError (or the sender/transport's own error) otherwise

Signing utilities

• signOrder(walletClient, domain, order) — EIP-712 sign an order message
• buildSigningArgs(chainId, verifyingContract, order) — build signTypedData arguments

ABIs

• perpsMarketProxyAbi, perpsAccountProxyAbi, bookOrderModuleAbi
• spotMarketProxyAbi, trustedMulticallForwarderAbi, isolatedMarginManagerAbi, erc20Abi, oracleManagerProxyAbi
• Legacy aliases: PERPS_MARKET_PROXY_ABI, PERPS_ACCOUNT_PROXY_ABI, SPOT_MARKET_PROXY_ABI, ERC20_ABI, TRUSTED_MULTICALL_FORWARDER_ABI

Oracle helpers

• OnchainMarketsService.getChainlinkFeedAddress(nodeId) — resolves a price node's Chainlink-type (RedStone) feed address, or null when that node isn't type 3

Chain helpers

• getViemChain(chainId) — returns viem Chain object for a given chain ID

Install

pnpm add @liq/onchain

Dependencies

• @liq/core — chain config, contract addresses, shared types
• viem — onchain interaction (read/write contracts, wallet client)

Build

moon run liq-onchain:build    # tsup → dist/