Quip Swap SDK

Documented version: 0.1.1.

TypeScript SDK for the Quip Swap Omnibus protocol: hashlocked same-chain and cross-chain swaps of Native, ERC-20, ERC-721 and ERC-1155 assets. Built on viem, a peer dependency.

npm install @quip.network/quip-swap-sdk@0.1.1

Generated at build from the type declarations in the published package. A description is the first paragraph of the package’s own doc comment, and an export with none shows its type alone. For walkthroughs, see the Integrating guide.

@quip.network/quip-swap-sdkCopy Anchor Link

ClassesCopy Anchor Link

QuipSwapErrorCopy Anchor Link

The error class thrown by every SDK function.

constructor(args: QuipSwapErrorDetails)

FunctionsCopy Anchor Link

ConstantsCopy Anchor Link

ABIs and long literalsCopy Anchor Link

Their literal types run too long to print here.

EnumsCopy Anchor Link

AssetTypeCopy Anchor Link

The type of asset in a swap leg.

LockStateCopy Anchor Link

Lifecycle state of a hashlock in the Omnibus contract.

InterfacesCopy Anchor Link

ApprovalPlanCopy Anchor Link

The result of planApprovals.

AssetCopy Anchor Link

An asset to be transferred as part of a swap.

CallCopy Anchor Link

A single contract call in the ERC-5792 / ERC-4337 shape: the exact {to, value, data} a transaction (or a smart account’s execute) must carry. Produced by OmnibusClient.prepareCommit and prepareApproval; the SDK never executes a Call on behalf of a smart account — that is the account’s own tooling’s job.

ClaimArgsCopy Anchor Link

Arguments for OmnibusClient.claim.

ClaimEventCopy Anchor Link

A decoded Claim event — one per payout leg (a same-chain claim emits two, one per recipient). The secret field is public once emitted.

CommitArgsCopy Anchor Link

Arguments for OmnibusClient.commit.

CommitAuthCopy Anchor Link

Auth data for one commit, mirroring the Solidity struct CommitAuth field-for-field. Identities attribute, they don’t gate.

CommitmentEventCopy Anchor Link

A decoded Commitment event.

ComputeCommitDigestArgsCopy Anchor Link

Argument object for computeCommitDigest.

CreateOmnibusClientArgsCopy Anchor Link

Arguments for createOmnibusClient.

CreateTermsArgsCopy Anchor Link

Input shape for createTerms; identical to Terms.

CrossChainScheduleCopy Anchor Link

The validated cross-chain schedule summary.

Erc1155ApprovalItemCopy Anchor Link

ERC-1155 approval status for one token contract (operator approval covers all ids).

Erc20ApprovalItemCopy Anchor Link

ERC-20 approval status for one token (amounts aggregated across asset entries).

Erc721ApprovalItemCopy Anchor Link

ERC-721 approval status for one specific token id.

EventQueryArgsCopy Anchor Link

Common arguments for historical event queries.

FeeOverridesCopy Anchor Link

The fee fields forwarded to writeContract — containing ONLY the fields the caller explicitly set, so viem’s automatic fee pricing keeps working for everything unset. undefined fee fields are never passed through.

OmnibusAdminCopy Anchor Link

Owner-only administrative operations (Ownable2Step).

OmnibusClientCopy Anchor Link

A typed client bound to one deployed Omnibus contract.

OmnibusDeploymentCopy Anchor Link

A recorded Omnibus deployment on one chain.

OmnibusReceiptCopy Anchor Link

A successful, decoded Omnibus transaction result.

PlanApprovalsArgsCopy Anchor Link

Arguments for planApprovals.

PrepareApprovalArgsCopy Anchor Link

Arguments for prepareApproval.

PrepareCallOptionsCopy Anchor Link

Options for OmnibusClient.prepareCommit.

PreparedTxCopy Anchor Link

The prepared transaction fields, ready to spread into writeContract.

PrepareTxArgsCopy Anchor Link

Arguments for prepareTx.

PrepareTxContractParamsCopy Anchor Link

The contract call being prepared (the exact params estimateContractGas receives).

QuipSwapErrorDetailsCopy Anchor Link

Structured details carried by every QuipSwapError.

ReclaimArgsCopy Anchor Link

Arguments for OmnibusClient.reclaim.

ReclaimedEventCopy Anchor Link

A decoded Reclaimed event. Each reclaim call emits exactly one (its own side).

RemoteCommitmentStatusCopy Anchor Link

The result of verifyRemoteCommitment.

SameChainSwapPlanCopy Anchor Link

A validated same-chain swap plan with both sides normalized into proposer/taker roles and all five action windows precomputed.

SameChainSwapStatusReportCopy Anchor Link

The full status report returned by getSameChainSwapStatus.

SecretLockPairCopy Anchor Link

A freshly generated hashlock pair.

SubmitApprovalArgsCopy Anchor Link

Arguments for submitApproval.

TermsCopy Anchor Link

The terms for a single party (one “leg”) of an Omnibus swap.

TimeWindowCopy Anchor Link

A half-open time window [lower, upper) in Unix seconds.

TxOptionsCopy Anchor Link

Per-transaction options accepted by every write method (commit, claim, reclaim, and all admin.* writes). All fields optional; everything unset falls back to viem’s automatic behavior.

ValidateCrossChainScheduleArgsCopy Anchor Link

Arguments for validateCrossChainSchedule.

WaitOptionsCopy Anchor Link

Options forwarded to publicClient.waitForTransactionReceipt, plus address scoping.

Type aliasesCopy Anchor Link

ApprovalItemCopy Anchor Link

One entry of an ApprovalPlan.

type ApprovalItem = Erc20ApprovalItem | Erc721ApprovalItem | Erc1155ApprovalItem;

Erc20ApprovalModeCopy Anchor Link

ERC-20 approval sizing. The choice is explicit because it is a real trade-off the application must own: - 'exact' approves only the required amount (safer: a compromised or buggy spender can take at most the swap amount; costs one approval per swap). - 'unlimited' approves type(uint256).max (convenient: one approval forever; risk: the spender can pull ANY future balance).

type Erc20ApprovalMode = 'exact' | 'unlimited';

Hex32Copy Anchor Link

A 32-byte hex value (0x + 64 hex chars), e.g. a secret, lock, or digest.

type Hex32 = Hex;

QuipSwapErrorCodeCopy Anchor Link

Stable machine-readable SDK error codes.

type QuipSwapErrorCode = 'ZERO_AMOUNT' | 'INVALID_NATIVE_ASSET' | 'INVALID_ERC20_ASSET' | 'INVALID_ERC721_ASSET' | 'INVALID_ERC1155_ASSET' | 'INVALID_ASSET_TYPE' | 'EMPTY_ASSETS' | 'TOO_MANY_ASSETS' | 'ZERO_ADDRESS_RECIPIENT' | 'ZERO_DEADLINE' | 'DISORDERED_DEADLINES' | 'INVALID_RECLAIM_RELEASE' | 'ZERO_CHAIN_ID' | 'INVALID_RANGE' | 'WINDOW_VIOLATED' | 'INVALID_HEX32' | 'CHAIN_ID_MISMATCH' | 'MALFORMED_SIGNER' | 'ASSET_TYPE_MISMATCH' | 'RECLAIM_RELEASE_TOO_DISTANT' | 'NOT_QUIP_WALLET' | 'MISSING_WALLET_CLIENT' | 'MISSING_ACCOUNT' | 'TERMS_NOT_ON_CHAIN' | 'INVALID_LOCK_STATE' | 'TERMS_ALREADY_POSTED' | 'GAS_ESTIMATION_FAILED' | 'BALANCE_TOO_LOW' | 'SECRET_HOLDER_NOT_PROPOSER' | 'INSUFFICIENT_BUFFER' | 'INSUFFICIENT_REACTION_BUFFER' | 'UNKNOWN_DEPLOYMENT' | 'TRANSACTION_REVERTED' | 'EVENT_NOT_FOUND' | 'CONTRACT_REVERT';

SameChainSwapStatusCopy Anchor Link

Application-level swap status — deliberately SEPARATE from the Solidity LockState: the chain knows four states, but an application also needs to know which window is open and which side has posted.

type SameChainSwapStatus = 
/** Nothing committed; the proposer's commit window is open. */
'awaiting-proposer-commit'
/**
 * Nothing committed and the proposer's window has closed. The swap can
 * no longer COMPLETE (the proposer can never commit, so the lock can
 * never reach Committed) — but the contract will still accept a
 * taker-first commit in `[proposer.commitmentDeadline,
 * taker.commitmentDeadline)`: `Omnibus.commit` checks only the window,
 * not that the proposer actually committed (verifying the counterparty's
 * commitment is the committer's duty, per the contract comments). Such a
 * commit is pointless and self-harming — it moves the lock Unused→Free
 * and strands the taker's assets until `taker.reclaimRelease` (reclaim
 * from Free). Treat this status as terminal and do NOT commit into it.
 */
 | 'proposer-commit-expired'
/** Proposer committed (lock Free); the taker's window has not opened yet. */
 | 'awaiting-taker-window'
/** Proposer committed (lock Free); the taker's window is open. */
 | 'awaiting-taker-commit'
/** Only the proposer committed and the taker's window closed; awaiting the proposer's reclaimRelease. */
 | 'half-committed-expired'
/** Both committed before the taker's commitment deadline; the proposer-claim window has not opened yet. */
 | 'awaiting-claim-window'
/** Both committed; the claim window is open — the secret holder should claim. */
 | 'claimable'
/**
 * Both committed; the claim window closed with no claim. Nothing can
 * happen until `proposer.reclaimRelease` opens reclaim — the contract
 * derives claim roles from the terms themselves, so no argument ordering
 * reopens a claim path in this region.
 */
 | 'claim-expired'
/** Both committed; no claim landed and a leg's reclaim window is open. */
 | 'reclaimable'
/** Lock Free and the proposer's reclaim window is open (reclaim-from-Free). */
 | 'reclaimable-from-free'
/**
 * The lock is Spent because ONE side already reclaimed its own leg, but
 * the other side has not — that side should still call reclaim to recover
 * its escrowed leg (per-side reclaim, Finding 4). Not terminal for the
 * un-reclaimed side.
 */
 | 'partially-reclaimed'
/** Terminal: the lock is Spent and fully settled (claimed, or both sides reclaimed). */
 | 'settled';