# Quip Swap SDK

Types exported by @quip.network/quip-swap-sdk, the client for the QuipSwap Omnibus contract.

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.

> **Read first**
>
> The package README asks integrators to read its section on ways to lose funds first. Cross-chain takers can lose funds by skipping commitment verification, and overriding the default buffers too tight can forfeit windows.

```sh
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](/docs/quipswap/integrating).

## `@quip.network/quip-swap-sdk`

### Classes

#### `QuipSwapError`

The error class thrown by every SDK function.

```ts
constructor(args: QuipSwapErrorDetails)
```

| Name | Type | Description |
| --- | --- | --- |
| `name` | `"QuipSwapError"` |  |
| `code` | `QuipSwapErrorCode` |  |
| `contractErrorName?` | `string \| undefined` |  |
| `cause?` | `unknown` |  |
| `details?` | `unknown` |  |
| `message` | `string` |  |
| `stack?` | `string \| undefined` |  |

### Functions

| Name | Type | Description |
| --- | --- | --- |
| `applyGasMultiplier` | `(estimate: bigint, opts?: TxOptions) => bigint` | Applies the resolved safety multiplier to a gas estimate. Parameter estimate - The node's gas estimate (from `estimateContractGas`). Parameter opts - Transaction options; see `resolveGasMultiplier`. Returns: The buffered gas limit, `floor(estimate * multiplier)`. |
| `assertHex32` | `(value: string, label: string) => asserts value is Hex32` | Asserts a value is exactly 32 bytes of valid hex (`0x` + 64 hex chars). Parameter value - The value to check. Parameter label - Name used in the error message (e.g. `"secret"`, `"lock"`). |
| `assertSignerBlob` | `(signer: Hex) => void` | Validates a signer blob's shape: more than 20 bytes of strict hex — the contract reverts `MalformedSigner` at 20 bytes or fewer. Mirrors, never replaces, the on-chain check. Parameter signer - The identity blob. |
| `buildFeeOverrides` | `(opts?: TxOptions) => FeeOverrides` | Builds the FeeOverrides object from caller options. Parameter opts - Transaction options. Returns: An object with only the explicitly-set fee fields present. |
| `buildKeyedSigner` | `(verifier: Address, key: Hex) => Hex` | Builds a keyed ERC-7913 signer blob: `verifier(20 bytes) ‖ key`. Parameter verifier - The ERC-7913 verifier contract address. Parameter key - The verifier-defined key material (non-empty; the blob must exceed 20 bytes). Returns: The concatenated signer blob. |
| `checkScheduleBuffers` | `(proposerTerms: Terms, takerTerms: Terms, minimumBufferSeconds: bigint) => { minimumGapSeconds: bigint; }` | Validates that every adjacent gap in a pairing's interleaved six-timestamp schedule is at least `minimumBufferSeconds`. This is the gap-SIZE check (distinct from interleaving ORDER, validated by `validateTermPairing`); the contract never checks size, so this is the only enforcement point. Parameter proposerTerms - The proposer's leg (smaller `commitmentDeadline`). Parameter takerTerms - The taker's leg. Parameter minimumBufferSeconds - The minimum acceptable gap (seconds) between every adjacent pair of schedule timestamps. Returns: `{minimumGapSeconds}` — the smallest adjacent gap in the schedule. |
| `computeCommitDigest` | `(args: ComputeCommitDigestArgs) => Hex32` | Computes the 32-byte digest a committer's identity must sign — an exact mirror of `Omnibus._commitDigest` (raw tagged keccak, `abi.encode`, NOT packed; no EIP-712): Parameter args - See `ComputeCommitDigestArgs`. Returns: The digest to hand to the keyholder's signing tooling. |
| `computeDomainSeparator` | `(chainId: bigint, omnibusAddress: Address) => Hex32` | Mirrors `Omnibus.DOMAIN_SEPARATOR` (baked at construction on-chain): `keccak256(abi.encode(COMMIT_DIGEST_TAG, chainId, omnibusAddress))`. |
| `createOmnibusClient` | `(args: CreateOmnibusClientArgs) => OmnibusClient` |  |
| `createTerms` | `(args: CreateTermsArgs) => Terms` | Builds and validates a Terms object. Parameter args - The seven Terms fields; see `CreateTermsArgs` for units and constraints. Returns: A frozen, structurally valid `Terms`. |
| `decodeClaimEvents` | `(logs: readonly Log[]) => ClaimEvent[]` | Decodes every `Claim` event in a list of logs. Parameter logs - Raw logs to scan; non-`Claim` logs are skipped. Returns: All decoded `Claim` events, in log order. |
| `decodeCommitmentEvents` | `(logs: readonly Log[]) => CommitmentEvent[]` | Decodes every `Commitment` event in a list of logs (e.g. from a receipt or `getLogs`), recovering the committing side's full typed Terms from event data — this is how a coordinator reconstructs a side's terms from chain history without an off-chain channel. Parameter logs - Pre-scoped logs (a receipt's `logs` array or a `getLogs` result). Returns: All decoded `Commitment` events, in log order. |
| `decodeReclaimedEvents` | `(logs: readonly Log[]) => ReclaimedEvent[]` | Decodes every `Reclaimed` event in a list of logs. Parameter logs - Pre-scoped logs to scan; non-`Reclaimed` logs are skipped. Returns: All decoded `Reclaimed` events, in log order. |
| `deriveSharedLock` | `(secret: Hex32) => Hex32` | Derives the lock from a secret for cross-chain coordination — re-export of generateLock under a workflow-centric name so coordinators depend only on this module. Parameter secret - The proposer's 32-byte secret. Returns: The shared lock used on BOTH chains. |
| `digestTerms` | `(terms: Terms) => Hex32` | Computes the digest of a single side's terms. Parameter terms - The side's terms. Returns: The 32-byte digest used for `posted` tracking and canonical ordering. |
| `digestTermsCanonically` | `(party: Terms, counterparty: Terms) => Hex32` | Computes the canonical digest of a terms pair, identical regardless of which side is passed first. Parameter party - One side's terms (order does not matter). Parameter counterparty - The other side's terms. Returns: The canonical 32-byte digest of the pair. |
| `enforceWithin` | `(lower: bigint, upper: bigint, timestamp: bigint) => void` | Asserts `timestamp` lies within the half-open window `[lower, upper)`. Parameter lower - Inclusive lower bound (Unix seconds). Parameter upper - Exclusive upper bound (Unix seconds). Parameter timestamp - The instant to test (pass the chain's `block.timestamp`). |
| `erc1155Asset` | `(target: Address, tokenId: bigint, amount: bigint) => Asset` | Builds an ERC-1155 asset (a quantity of one token id). Parameter target - The ERC-1155 token contract address; must be non-zero. Parameter tokenId - The token id; `0n` is valid. Parameter amount - Quantity of the token id; must be `> 0n`. Returns: A canonical, frozen `Asset` with `assetType: ERC1155`. |
| `erc20Asset` | `(target: Address, amount: bigint) => Asset` | Builds an ERC-20 asset. Parameter target - The ERC-20 token contract address; must be non-zero. Parameter amount - Token amount in the token's base units; must be `> 0n`. Returns: A canonical, frozen `Asset` with `assetType: ERC20` and `id: 0n`. |
| `erc721Asset` | `(target: Address, tokenId: bigint) => Asset` | Builds an ERC-721 asset for one specific NFT. Parameter target - The ERC-721 token contract address; must be non-zero. Parameter tokenId - The NFT's token id; `0n` is valid. Returns: A canonical, frozen `Asset` with `assetType: ERC721` and `amount: 1n`. |
| `extractContractErrorName` | `(error: unknown) => string \| undefined` | Extracts the decoded Solidity custom-error name from a Viem error, if any. Parameter error - Any error thrown by a Viem contract action. Returns: The custom error name, or `undefined` when the revert could not be decoded (e.g. an out-of-ABI token error with no registered ABI). |
| `extractRevealedSecret` | `(logs: readonly Log[], lock: Hex32) => Hex32 \| undefined` | Extracts the revealed secret for a specific lock from a list of logs. Parameter logs - Raw logs to scan (receipt logs or a `getLogs` result). Parameter lock - The lock whose secret to extract. Returns: The 32-byte secret, or `undefined` when no `Claim` for the lock carries a secret that hashes to it. |
| `extractSecretFromClaims` | `(claims: readonly ClaimEvent[], lock: Hex32) => Hex32 \| undefined` | Extracts the revealed secret for a lock from already-decoded `Claim` events — the safe, address-scoped path (the events typically come from OmnibusReceipt.claims, which `client.waitForReceipt` / `waitForOmnibusReceipt(..., {address})` already filter by `log.address`). Parameter claims - Decoded `Claim` events (e.g. `receipt.claims`). Parameter lock - The lock whose secret to extract. Returns: The 32-byte secret, or `undefined` when none matches. |
| `generateLock` | `(secret: Hex32) => Hex32` | Derives the hashlock from a secret. Parameter secret - A 32-byte hex preimage (`0x` + 64 hex chars). Validated before hashing — externally supplied secrets of the wrong length would otherwise silently produce a lock that can never be claimed. Returns: The 32-byte lock, `keccak256(secret)`. |
| `generateSecret` | `() => SecretLockPair` | Generates a fresh 32-byte secret and its lock. Returns: A `SecretLockPair` where `lock === generateLock(secret)`. Keep `secret` private until claim; `lock` is safe to share. |
| `getClaimEvents` | `(args: EventQueryArgs) => Promise<ClaimEvent[]>` | Queries historical `Claim` events via `publicClient.getLogs`. Parameter args - See `EventQueryArgs`. Returns: Decoded events in chain order. Apply your confirmation policy before treating a revealed secret's claim as settled. |
| `getCommitmentEvents` | `(args: EventQueryArgs) => Promise<CommitmentEvent[]>` | Queries historical `Commitment` events via `publicClient.getLogs`. Parameter args - See `EventQueryArgs`. Returns: Decoded events in chain order. |
| `getReclaimedEvents` | `(args: EventQueryArgs) => Promise<ReclaimedEvent[]>` | Queries historical `Reclaimed` events via `publicClient.getLogs`. Parameter args - See `EventQueryArgs`. Returns: Decoded events in chain order (possibly two per transaction). |
| `getSameChainSwapStatus` | `(client: OmnibusClient, lock: Hex32, plan: SameChainSwapPlan) => Promise<SameChainSwapStatusReport>` | Inspects a same-chain swap's status from ACTUAL on-chain state (`lockState`, `posted`) combined with the current block timestamp. Parameter client - An `OmnibusClient` on the swap's chain. Parameter lock - The swap's hashlock. Parameter plan - The plan from `planSameChainSwap`. Returns: A `SameChainSwapStatusReport`; never throws on unexpected state combinations — the raw fields are included so the application can inspect them. |
| `isWithinWindow` | `(window: TimeWindow, timestamp: bigint) => boolean` | Non-throwing variant of enforceWithin. Parameter window - The half-open window to test. Parameter timestamp - The instant to test (Unix seconds). Returns: `true` iff `window.lower <= timestamp < window.upper` and the window is non-degenerate. |
| `nativeAsset` | `(amount: bigint) => Asset` | Builds a native-currency asset (ETH or the chain's equivalent). Parameter amount - Amount of native currency in wei; must be `> 0n`. Returns: A canonical, frozen `Asset` with `assetType: Native`. |
| `planApprovals` | `(args: PlanApprovalsArgs) => Promise<ApprovalPlan>` | Inspects on-chain approvals for every non-native asset in a side's terms and returns a typed plan describing what is missing. Parameter args - See `PlanApprovalsArgs`. Returns: The typed `ApprovalPlan`. |
| `planSameChainSwap` | `(a: Terms, b: Terms, opts?: { readonly minimumBufferSeconds?: bigint; }) => SameChainSwapPlan` | Validates a same-chain pairing and assembles a SameChainSwapPlan. Parameter a - One side's terms. Parameter b - The other side's terms. Parameter opts - Optional. `minimumBufferSeconds` sets the minimum acceptable gap (seconds) between every adjacent pair of schedule timestamps; defaults to `DEFAULT_SAME_CHAIN_BUFFER_SECONDS` when omitted. Overriding BELOW the default may let dangerously tight windows through — only do so if you understand your chain's finality. Returns: The normalized plan with windows and digests precomputed. |
| `preflightBalanceCheck` | `(publicClient: PublicClient, account: Address, required: bigint) => Promise<void>` | Throws `BALANCE_TOO_LOW` if the account's balance is below `required`. Parameter publicClient - The Viem public client to read the balance through. Parameter account - The sender whose balance is checked. Parameter required - The native value (wei) the call itself must carry. |
| `prepareApproval` | `(args: PrepareApprovalArgs) => Call` | Builds the Call that satisfies one unsatisfied ApprovalItem WITHOUT sending it — for a smart account (e.g. a quip wallet) that must execute the approval itself, since the allowance has to be granted BY the account whose tokens the Omnibus will pull (`allowance(msg.sender, omnibus)`). |
| `prepareTx` | `(args: PrepareTxArgs) => Promise<PreparedTx>` | Prepares a write: balance preflight, then gas estimation (or an explicit limit) with the safety multiplier. Parameter args - See `PrepareTxArgs`. Returns: The `PreparedTx` to spread into `writeContract`. |
| `proposedBy` | `(party: Terms, counterparty: Terms) => 'party' \| 'counterparty'` | Identifies which side of a pairing proposed. Parameter party - The first side's terms. Parameter counterparty - The second side's terms. Returns: `'party'` if `party` proposed, `'counterparty'` otherwise. |
| `proposerClaimWindow` | `(proposer: Terms, taker: Terms) => TimeWindow` | The proposer's claim window: `[taker.commitmentDeadline, proposer.claimDeadline)`. Parameter proposer - The proposer's terms. Parameter taker - The taker's terms. Returns: The half-open claim window for the proposer (secret holder). |
| `proposerCommitWindow` | `(proposer: Terms) => TimeWindow` | The proposer's commit window: `[0, proposer.commitmentDeadline)`. Parameter proposer - The proposer's terms (the side with the earlier `commitmentDeadline`). Returns: The half-open commit window for the proposer. |
| `reclaimWindow` | `(leg: Terms) => TimeWindow` | The reclaim window for one leg: `[leg.reclaimRelease, +infinity)`. Parameter leg - The terms of the leg being reclaimed. Returns: The half-open reclaim window (upper bound `MAX_UINT256`). |
| `resolveDeployment` | `(chainId: bigint, override?: OmnibusDeployment) => OmnibusDeployment` | Resolves the Omnibus deployment for a chain. Parameter chainId - The target chain id. Parameter override - Optional application-supplied deployment for this chain. Returns: The resolved deployment. |
| `resolveGasMultiplier` | `(opts?: TxOptions) => number` | Resolves the effective gas multiplier from TxOptions. Parameter opts - The caller's transaction options (only `gasMultiplier` is read). Returns: The clamped multiplier that `applyGasMultiplier` will use. |
| `secretToPair` | `(secret: string) => SecretLockPair` | Validates an externally supplied secret and derives its lock. Parameter secret - A 0x-prefixed 32-byte hex string. Returns: The validated `SecretLockPair`. |
| `submitApproval` | `` (args: SubmitApprovalArgs) => Promise<`0x${string}`> `` | Simulates and submits the approval transaction that satisfies one unsatisfied ApprovalItem. Parameter args - See `SubmitApprovalArgs`. Returns: The transaction hash. Wait for its receipt before re-planning — a hash alone does not mean the approval landed. |
| `swapId` | `(lock: Hex32, party: Terms, counterparty: Terms) => Hex32` | Computes the swap id for a term pairing — the key ALL Omnibus swap state is stored under (see swapIdFromDigest). Canonical digesting makes the result independent of which side is passed as `party` vs `counterparty`. Mirrors the on-chain `Omnibus.swapId` view. Parameter lock - The hashlock (`generateLock(secret)`). Parameter party - One side's terms. Parameter counterparty - The other side's terms. Returns: The 32-byte swap id. |
| `swapIdFromDigest` | `(lock: Hex32, canonicalDigest: Hex32) => Hex32` | Computes the swap id from a lock and an already-computed canonical terms digest. The swap id is the key ALL Omnibus swap state (`lockState`, `termsHash`, `posted`) is stored under — state is scoped to the (lock, pairing) combination, so an unrelated pairing reusing an observed lock occupies its own slot and cannot block or alter another swap's state. Parameter lock - The hashlock (`generateLock(secret)`). Parameter canonicalDigest - `digestTermsCanonically` over the pairing. Returns: The 32-byte swap id. |
| `takerClaimWindow` | `(proposer: Terms) => TimeWindow` | The taker's claim window: `[proposer.claimDeadline, proposer.reclaimRelease)`. Parameter proposer - The proposer's terms (the claim is gated on the PROPOSER's schedule). Returns: The half-open claim window for the taker. |
| `takerCommitWindow` | `(taker: Terms, proposer: Terms) => TimeWindow` | The taker's commit window: `[proposer.commitmentDeadline, taker.commitmentDeadline)`. Parameter taker - The taker's terms. Parameter proposer - The proposer's terms. Returns: The half-open commit window for the taker. |
| `totalNative` | `(terms: Pick<Terms, 'assets'>) => bigint` | Sums the native amounts in a side's terms — the amount of wei the committer must escrow (before the commitment fee). Parameter terms - The side's terms (only `assets` is read). Returns: The sum of all native-asset amounts in wei (`0n` when none). |
| `validateAsset` | `(asset: Asset) => void` | Validates an asset object received from an untrusted source (JSON, an API, a database, another application). Parameter asset - The asset to validate. |
| `validateClaimWindow` | `(party: Terms, counterparty: Terms, currentTimestamp: bigint) => void` | Validates that `currentTimestamp` lies inside the window `Omnibus.claim` enforces for this pairing. Mirrors the contract exactly: roles (proposer = earlier `commitmentDeadline`) and the window come from the TERMS, never from argument order, so swapping `party`/`counterparty` cannot change the result. The claim executes on the chain holding the counterparty's assets (the client enforces `counterparty.chainId` === connected chain before this preflight); the window depends only on whose assets that chain holds: Parameter party - The claimant role's terms (the side the claimant acts for). Parameter counterparty - The other side's terms (the leg being claimed). Parameter currentTimestamp - The chain's current `block.timestamp` (Unix seconds). |
| `validateCommitWindow` | `(party: Terms, counterparty: Terms, currentTimestamp: bigint) => void` | Validates that `currentTimestamp` lies inside the commit window for the role `party` plays in the pairing — exactly the check `Omnibus.commit` performs: Parameter party - The committing side's terms. Parameter counterparty - The other side's terms. Parameter currentTimestamp - The chain's current `block.timestamp` (Unix seconds) — pass an explicit value; this helper never reads a clock. |
| `validateCrossChainSchedule` | `(args: ValidateCrossChainScheduleArgs) => CrossChainSchedule` | Validates a cross-chain swap schedule before any transaction is sent. Parameter args - See `ValidateCrossChainScheduleArgs`; parameter names are protocol roles (`proposerTerms`/`takerTerms`), not call-site roles. Returns: The `CrossChainSchedule` summary (buffers included). |
| `validateReclaimWindow` | `(party: Terms, currentTimestamp: bigint) => void` | Validates that `currentTimestamp` has reached the reclaim window of the leg being reclaimed — exactly the check `Omnibus.reclaim` performs: `[party.reclaimRelease, type(uint256).max)`. Parameter party - The terms of the leg being reclaimed. Parameter currentTimestamp - The chain's current `block.timestamp` (Unix seconds). |
| `validateTermPairing` | `(a: Terms, b: Terms) => void` | Validates that two sides' lifecycle timestamps strictly interleave. Parameter a - One side's terms. Parameter b - The other side's terms. |
| `validateTerms` | `(terms: Terms) => void` | Structurally validates one side's terms. Parameter terms - The terms to validate (e.g. parsed from JSON or an API). |
| `verifyRemoteCommitment` | `(remoteClient: OmnibusClient, lock: Hex32, proposerTerms: Terms, takerTerms: Terms) => Promise<RemoteCommitmentStatus>` | The taker's MANDATORY pre-commit check: verifies on the PROPOSER's chain that the proposer's commitment has actually taken effect. Parameter remoteClient - An `OmnibusClient` bound to the PROPOSER's chain. Parameter lock - The shared hashlock. Parameter proposerTerms - The proposer's (remote) leg. Parameter takerTerms - The taker's (local) leg. Returns: A `RemoteCommitmentStatus`; commit only when `committed` is true and your confirmation policy is satisfied. |
| `waitForOmnibusReceipt` | `(publicClient: PublicClient, hash: Hash, options?: WaitOptions) => Promise<OmnibusReceipt>` | Waits for a transaction receipt, verifies it succeeded, and decodes all Omnibus events it emitted. Parameter publicClient - The Viem public client to poll through. Parameter hash - The transaction hash returned by a write method. Parameter options - `address` (strongly recommended — scopes decoding to the Omnibus deployment; see `WaitOptions`), plus confirmation count and timeout. Pick confirmations per your finality policy — one confirmation on a reorg-prone chain is weak evidence. Returns: The typed `OmnibusReceipt`; `commitments`/`claims`/ `reclaims` contain only events from `options.address` when supplied. |
| `watchClaimEvents` | `(args: Omit<EventQueryArgs, 'fromBlock' \| 'toBlock'> & { readonly onClaim: (event: ClaimEvent) => void; }) => () => void` | Watches for live `Claim` events on a lock — the cross-chain coordinator's tool for learning the revealed secret promptly. Parameter args - Query args plus the callback. Parameter args.onClaim - Invoked with each decoded `Claim` event observed. Returns: The unwatch function from Viem; call it to stop watching. |
| `wrapContractError` | `(error: unknown, context: string) => QuipSwapError` | Wraps an error thrown by a Viem contract action into a QuipSwapError with code `CONTRACT_REVERT`, preserving the original error in `cause` and the decoded custom-error name (when available) in `contractErrorName`. Parameter error - The original error thrown by Viem. Parameter context - Short description of the operation that failed. Returns: A `QuipSwapError` wrapping the original error. |

### Constants

| Name | Type | Description |
| --- | --- | --- |
| `COMMIT_DIGEST_TAG` | `` `0x${string}` `` | The protocol tag bound into the commit-digest domain separator — `keccak256('QUIP:Omnibus:commit')`, mirroring `Omnibus.COMMIT_DIGEST_TAG` exactly (asserted against the contract's `COMMIT_DIGEST_TAG()` in the integration suite). |
| `DEFAULT_BUFFERS` | `{ readonly fastL2: 300n; readonly standard: 1800n; readonly conservativeL1: 3600n; }` | Suggested minimum-buffer presets (seconds) by chain-finality profile. Starting points to tune to your chains, NOT authoritative values. |
| `DEFAULT_CROSS_CHAIN_BUFFER_SECONDS` | `1800n` | Default minimum buffer applied to CROSS-CHAIN schedules when the caller supplies none. A conservative starting point (DEFAULT_BUFFERS.standard, ~30 min) — tune to your chains; overriding BELOW it can expose users to missed windows and lost funds under congestion/reorgs. |
| `DEFAULT_GAS_MULTIPLIER` | `1.2` | Default gas-limit safety multiplier: a 20% margin over the node's estimate. |
| `DEFAULT_SAME_CHAIN_BUFFER_SECONDS` | `1800n` | Default minimum buffer applied to SAME-CHAIN schedules when the caller supplies none. Same conservative starting point as the cross-chain default (DEFAULT_BUFFERS.standard, ~30 min) but a SEPARATE constant so the two modes can be tuned independently later without touching call sites. |
| `MAX_ASSETS_PER_SIDE` | `20` | Maximum assets permitted in a single side's terms — mirrors `TermsLib.MAX_ASSETS_PER_SIDE`. Bounds the per-side `assets` array so that settling both legs together (same-chain `claim`) always fits the block gas limit; without it a padded leg could commit yet make every claim/reclaim exceed the limit forever (a freeze, and cross-chain a theft). |
| `MAX_GAS_MULTIPLIER` | `2` | Multiplier ceiling; caps the damage of a misconfigured value. |
| `MAX_RECLAIM_HORIZON_SECONDS` | `bigint` | Default maximum horizon (seconds) between a commit and either leg's `reclaimRelease` — two weeks. An SDK-only *reasonableness* guard: the contract only rejects the malformed `type(uint256).max` (see validateTerms), but a `reclaimRelease` far in the future is a well-formed schedule that leaves an unrecoverable-until-then leg if the swap fails. `commit` rejects a schedule beyond this horizon with `RECLAIM_RELEASE_TOO_DISTANT` unless the caller passes CommitArgs.allowDistantReclaimRelease. There is no on-chain equivalent — a determined caller can bypass it, exactly as with the buffer checks. |
| `MAX_UINT256` | `bigint` | `type(uint256).max` — the open upper bound of the reclaim window. |
| `MIN_GAS_MULTIPLIER` | `1` | Multiplier floor; anything below 1.0 risks out-of-gas by construction. |
| `assetArrayAbiParameter` | `{ readonly name: "assets"; readonly type: "tuple[]"; readonly components: readonly [{ readonly name: "assetType"; readonly type: "uint8"; }, { readonly name: "target"; readonly type: "address"; }, { readonly name: "id"; readonly type: "uint256"; }, { readonly name: "amount"; readonly type: "uint256"; }]; }` | The ABI parameter description of the `Asset[]` array — the SINGLE source of truth for the Asset tuple shape in the SDK. `assetType` is a Solidity enum, encoded as `uint8` in the ABI. |
| `knownDeployments` | `ReadonlyMap<bigint, OmnibusDeployment>` | Live deployments, keyed by chain id — the rows with `deployed: true`. |
| `registryRows` | `readonly OmnibusDeployment[]` | EVERY row in the registry, including chains where nothing usable is live. |
| `termsAbiParameter` | `{ readonly name: "terms"; readonly type: "tuple"; readonly components: readonly [{ readonly name: "chainId"; readonly type: "uint256"; }, { readonly name: "reclaimRecipient"; readonly type: "address"; }, { readonly name: "recipient"; readonly type: "address"; }, { readonly name: "commitmentDeadline"; readonly type: "uint256"; }, { readonly name: "claimDeadline"; readonly type: "uint256"; }, { readonly name: "reclaimRelease"; readonly type: "uint256"; }, { readonly name: "assets"; readonly type: "tuple[]"; readonly components: readonly [{ readonly name: "assetType"; readonly type: "uint8"; }, { readonly name: "target"; readonly type: "address"; }, { readonly name: "id"; readonly type: "uint256"; }, { readonly name: "amount"; readonly type: "uint256"; }]; }]; }` | The ABI parameter description of the full `Terms` tuple — the SINGLE source of truth for the Terms shape. Used to decode the `Commitment` event's `party` field back into a typed Terms. |

### ABIs and long literals

Their literal types run too long to print here.

| Export | Description |
| --- | --- |
| `omnibusAbi` | Omnibus contract ABI. |

### Enums

#### `AssetType`

The type of asset in a swap leg.

| Name | Type | Description |
| --- | --- | --- |
| `Native` | `AssetType.Native` | Native chain currency (ETH on mainnet, etc.). |
| `ERC20` | `AssetType.ERC20` | An ERC-20 fungible token. |
| `ERC721` | `AssetType.ERC721` | An ERC-721 non-fungible token (one specific token id). |
| `ERC1155` | `AssetType.ERC1155` | An ERC-1155 semi-fungible token (a quantity of one token id). |

#### `LockState`

Lifecycle state of a hashlock in the Omnibus contract.

| Name | Type | Description |
| --- | --- | --- |
| `Unused` | `LockState.Unused` | Default — the lock has never been used. |
| `Free` | `LockState.Free` | Same-chain only: one party has committed, waiting for the counterparty. |
| `Committed` | `LockState.Committed` | Ready for claim (same-chain: both committed; cross-chain: the single local commit). |
| `Spent` | `LockState.Spent` | Terminal — claimed or reclaimed. |

### Interfaces

#### `ApprovalPlan`

The result of `planApprovals`.

| Name | Type | Description |
| --- | --- | --- |
| `committer` | `` `0x${string}` `` | The wallet whose assets will be pulled (the commit sender). |
| `omnibusAddress` | `` `0x${string}` `` | The Omnibus contract that must be able to pull them. |
| `items` | `readonly ApprovalItem[]` | One item per (token / token+id) requiring approval; empty if all-native. |
| `satisfied` | `boolean` | True iff every item is satisfied. |

#### `Asset`

An asset to be transferred as part of a swap.

| Name | Type | Description |
| --- | --- | --- |
| `assetType` | `AssetType` | The kind of asset; encoded as `uint8` in the ABI. |
| `target` | `` `0x${string}` `` | Token contract address; MUST be the zero address for AssetType.Native. |
| `id` | `bigint` | Token id; used by ERC-721 and ERC-1155 and MUST be `0n` for Native and ERC-20 (the contract rejects a non-zero id for ERC-20 with `InvalidERC20Asset`). Token id `0n` is explicitly VALID for ERC-721 and ERC-1155. |
| `amount` | `bigint` | Quantity in the token's base units (wei for native). MUST be greater than zero for every asset type — including ERC-721, where the SDK canonicalizes the value to `1n` (see erc721Asset). |

#### `Call`

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.

| Name | Type | Description |
| --- | --- | --- |
| `to` | `` `0x${string}` `` | The contract to call. |
| `value` | `bigint` | Native value to attach (wei). |
| `data` | `` `0x${string}` `` | ABI-encoded calldata. |

#### `ClaimArgs`

Arguments for `OmnibusClient.claim`.

| Name | Type | Description |
| --- | --- | --- |
| `secret` | `` `0x${string}` `` | The 32-byte preimage of the lock. Sending it on-chain reveals it publicly. |
| `party` | `Terms` | The claimant role's terms (the side the claimant acts for). |
| `counterparty` | `Terms` | The other side's terms — the leg being claimed; must be local. |
| `verifyOnChainState?` | `boolean \| undefined` | When `true` (default), preflight additionally verifies on-chain state in one parallel read batch: `lockState(swapId)` must be `Committed` (`INVALID_LOCK_STATE` otherwise, with the actual state and likely cause), `termsHash(swapId)` must equal the canonical digest, and the counterparty's side must be `posted` (`TERMS_NOT_ON_CHAIN` otherwise). Costs three extra parallel reads; disable only if you have just verified the state yourself — estimation still catches everything. |

#### `ClaimEvent`

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

| Name | Type | Description |
| --- | --- | --- |
| `recipient` | `` `0x${string}` `` | The terms-pinned address that received this leg's assets (indexed topic). |
| `lock` | `` `0x${string}` `` | The hashlock that was claimed (indexed topic). |
| `secret` | `` `0x${string}` `` | The revealed 32-byte preimage. Public from this moment on. |
| `blockNumber` | `bigint \| null` |  |
| `transactionHash` | `` `0x${string}` \| null `` |  |
| `logIndex` | `number \| null` |  |

#### `CommitArgs`

Arguments for `OmnibusClient.commit`.

| Name | Type | Description |
| --- | --- | --- |
| `lock` | `` `0x${string}` `` | The hashlock (`generateLock(secret)`); the proposer generates the secret. |
| `party` | `Terms` | The committing side's terms — the auth identity endorses this side. |
| `counterparty` | `Terms` | The other side's terms. |
| `auth` | `CommitAuth` | The committing side's identity blob + signature over the commit digest (see computeCommitDigest / buildKeyedSigner). The SDK never signs: `signature` is opaque bytes from the keyholder's own tooling. |
| `verifyOnChainState?` | `boolean \| undefined` | When `true` (default), preflight additionally reads the lock's on-chain state: a `Spent` or `Committed` lock rejects with `INVALID_LOCK_STATE` (no commit can advance from those states), and a `Free` lock requires the canonical `termsHash` to match (`TERMS_NOT_ON_CHAIN` otherwise) and the committing side to not already be posted (`TERMS_ALREADY_POSTED` otherwise — the second same-chain commit must post the OTHER side). Costs three extra parallel reads; with the flag off, gas estimation still catches every case as a decoded `CONTRACT_REVERT`. |
| `allowDistantReclaimRelease?` | `boolean \| undefined` | When `true`, skips the reasonableness guard that rejects a `reclaimRelease` more than MAX_RECLAIM_HORIZON_SECONDS (two weeks) beyond the chain's current time. The guard exists because a far-future `reclaimRelease` leaves a leg unrecoverable until then if the swap fails — but a long window may be intentional, so this flag is the explicit opt-out. Default `false` (guard on). |

#### `CommitAuth`

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

| Name | Type | Description |
| --- | --- | --- |
| `signer` | `` `0x${string}` `` | The committing side's identity blob: `verifier(20) ‖ key` (see module docs). |
| `signature` | `` `0x${string}` `` | Signature over computeCommitDigest, checked by the declared verifier; EMPTY selects the wallet route. |

#### `CommitmentEvent`

A decoded `Commitment` event.

| Name | Type | Description |
| --- | --- | --- |
| `lock` | `` `0x${string}` `` | The hashlock the commitment is bound to (indexed topic). |
| `party` | `Terms` | The committing side's FULL terms, recovered from event data. |
| `signer` | `` `0x${string}` `` | The identity blob that endorsed this commit (event data) — the event's attribution field. A client that cares WHICH identity posted a side (e.g. requiring the counterparty's agreed PQ identity before revealing the secret) checks THIS field off-chain; the contract never does. |
| `sender` | `` `0x${string}` `` | The address that submitted and FUNDED the commit (indexed topic). |
| `blockNumber` | `bigint \| null` | Block number the log was found in (`null` for pending logs). |
| `transactionHash` | `` `0x${string}` \| null `` | Transaction hash the log was found in (`null` for pending logs). |
| `logIndex` | `number \| null` | Log index within the block (`null` for pending logs). |

#### `ComputeCommitDigestArgs`

Argument object for `computeCommitDigest`.

| Name | Type | Description |
| --- | --- | --- |
| `lock` | `` `0x${string}` `` | The hashlock identifying the swap instance. |
| `party` | `Terms` | The COMMITTING side's terms (its `chainId` is the digest's replay scope). |
| `counterparty` | `Terms` | The other side's terms. |
| `signer` | `` `0x${string}` `` | The committing side's full identity blob (hashed into the digest). |
| `omnibusAddress` | `` `0x${string}` `` | The Omnibus deployed on the COMMITTING side's chain. |

#### `CreateOmnibusClientArgs`

Arguments for `createOmnibusClient`.

| Name | Type | Description |
| --- | --- | --- |
| `address` | `` `0x${string}` `` | The deployed Omnibus contract address (see resolveDeployment). |
| `publicClient` | `PublicClient` | A Viem public client connected to the chain the contract lives on. |
| `walletClient?` | `WalletClient` | A Viem wallet client for writes. Optional: a read-only client works without one, and writes then fail with `MISSING_WALLET_CLIENT`. All writes are permissionless — but note the FUNDING MODEL: the commit SENDER funds the party's leg + fee; the identity in `auth` only authorizes. |

#### `CreateTermsArgs`

Input shape for `createTerms`; identical to `Terms`.

| Name | Type | Description |
| --- | --- | --- |
| `chainId` | `bigint` | Chain id where this side's assets live; must be `> 0n`. |
| `reclaimRecipient` | `` `0x${string}` `` | Receives this side's own assets on reclaim; non-zero. |
| `recipient` | `` `0x${string}` `` | Receives the COUNTERPARTY's assets on claim; non-zero. |
| `commitmentDeadline` | `bigint` | Unix seconds; commitment forbidden at/after this instant; non-zero. |
| `claimDeadline` | `bigint` | Unix seconds; strictly after `commitmentDeadline`. |
| `reclaimRelease` | `bigint` | Unix seconds; strictly after `claimDeadline`. |
| `assets` | `readonly Asset[]` | Non-empty list of structurally valid assets. |

#### `CrossChainSchedule`

The validated cross-chain schedule summary.

| Name | Type | Description |
| --- | --- | --- |
| `proposerTerms` | `Terms` | The proposer's (secret holder's) leg. |
| `takerTerms` | `Terms` | The taker's leg. |
| `reactionBufferSeconds` | `bigint` | The taker's post-reveal reaction buffer in seconds: `proposer.reclaimRelease - proposer.claimDeadline` — the gap between the latest possible secret reveal (the proposer-claim window closes at `proposer.claimDeadline`) and the close of the taker's claim window (`proposer.reclaimRelease`). This is the taker's time to observe the revealed secret and land their own claim. |
| `minimumGapSeconds` | `bigint` | The smallest gap between any two adjacent schedule timestamps, in seconds. |

#### `Erc1155ApprovalItem`

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

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `"erc1155"` |  |
| `token` | `` `0x${string}` `` |  |
| `operatorApproved` | `boolean` | `isApprovedForAll(committer, omnibus)`. |
| `satisfied` | `boolean` |  |

#### `Erc20ApprovalItem`

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

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `"erc20"` |  |
| `token` | `` `0x${string}` `` | The token contract. |
| `requiredAllowance` | `bigint` | Sum of every asset entry for this token in the terms. |
| `currentAllowance` | `bigint` | `allowance(committer, omnibus)` at plan time. |
| `satisfied` | `boolean` | `currentAllowance >= requiredAllowance`. |

#### `Erc721ApprovalItem`

ERC-721 approval status for one specific token id.

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `"erc721"` |  |
| `token` | `` `0x${string}` `` |  |
| `tokenId` | `bigint` |  |
| `tokenApproved` | `boolean` | `getApproved(tokenId) == omnibus`. |
| `operatorApproved` | `boolean` | `isApprovedForAll(committer, omnibus)`. |
| `satisfied` | `boolean` | Either single-token or operator approval suffices. |

#### `EventQueryArgs`

Common arguments for historical event queries.

| Name | Type | Description |
| --- | --- | --- |
| `publicClient` | `PublicClient` | The Viem public client to query through. |
| `address` | `` `0x${string}` `` | The Omnibus contract address — always filter by contract address. |
| `lock?` | `` `0x${string}` \| undefined `` | Restrict results to one lock (indexed topic) when provided. |
| `fromBlock?` | `bigint \| BlockTag \| undefined` | Inclusive starting block; supply a deployment block to bound the scan. |
| `toBlock?` | `bigint \| BlockTag \| undefined` | Inclusive ending block. |

#### `FeeOverrides`

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.

| Name | Type | Description |
| --- | --- | --- |
| `maxFeePerGas?` | `bigint \| undefined` |  |
| `maxPriorityFeePerGas?` | `bigint \| undefined` |  |
| `gasPrice?` | `bigint \| undefined` |  |

#### `OmnibusAdmin`

Owner-only administrative operations (Ownable2Step).

| Name | Type | Description |
| --- | --- | --- |
| `setCommitmentFee` | `(newFee: bigint, opts?: TxOptions) => Promise<Hash>` | Sets the commitment fee. Owner only; reverts `FeeExceedsMax` above `MAX_FEE`, `OwnableUnauthorizedAccount` for non-owners. Parameter newFee - The new fee in wei; must be `<= MAX_FEE`. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash. |
| `withdrawFees` | `(to: Address, opts?: TxOptions) => Promise<Hash>` | Withdraws all accrued fees to `to`. Owner only. Escrowed swap native is NOT withdrawable — only accrued fees. Reverts `ZeroFeeRecipient` for the zero address, so a mistaken `to` cannot burn the accrued balance. Parameter to - The recipient of the accrued fees (non-zero). Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash. |
| `transferOwnership` | `(newOwner: Address, opts?: TxOptions) => Promise<Hash>` | Starts the two-step ownership transfer (Ownable2Step): the new owner must later call acceptOwnership. Parameter newOwner - The proposed new owner. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash. |
| `acceptOwnership` | `(opts?: TxOptions) => Promise<Hash>` | Completes a pending two-step ownership transfer; must be sent by the pending owner. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash. |
| `setVerifierActivity` | `(verifier: Address, active: boolean, opts?: TxOptions) => Promise<Hash>` | Sets the activity status of an ERC-7913 verifier for the keyed commit route. Owner only; reverts `ZeroVerifier` for the zero address. Parameter verifier - The verifier contract address (non-zero). Parameter active - The new activity status. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash. |

#### `OmnibusClient`

A typed client bound to one deployed Omnibus contract.

| Name | Type | Description |
| --- | --- | --- |
| `address` | `` `0x${string}` `` | The Omnibus contract address this client is bound to. |
| `publicClient` | `PublicClient` | The underlying public client (exposed for receipt/event helpers). |
| `getVersion` | `() => Promise<bigint>` | Reads the contract version. |
| `getMaxFee` | `() => Promise<bigint>` | Reads the maximum settable commitment fee in wei. |
| `getCommitmentFee` | `() => Promise<bigint>` | Reads the current commitment fee in wei. |
| `getAccruedFees` | `() => Promise<bigint>` | Reads the withdrawable accrued fees in wei. |
| `getLockState` | `(swapIdKey: Hex32) => Promise<LockState>` | Reads a swap's lifecycle state; key with swapId. |
| `getTermsHash` | `(swapIdKey: Hex32) => Promise<Hex32>` | Reads the canonical terms digest recorded for a swap (zero if none); key with swapId. |
| `getPosted` | `(swapIdKey: Hex32, termsDigest: Hex32) => Promise<boolean>` | Reads whether a side's terms digest was posted for a swap; key with swapId. |
| `getReclaimed` | `(swapIdKey: Hex32, sideDigest: Hex32) => Promise<boolean>` | Reads whether a side has already reclaimed its own leg; key with swapId and that side's terms digest. |
| `getOwner` | `() => Promise<Address>` | Reads the current owner. |
| `getPendingOwner` | `() => Promise<Address>` | Reads the pending owner of an in-flight two-step transfer. |
| `isVerifierActive` | `(verifier: Address) => Promise<boolean>` | Reads whether an ERC-7913 verifier is active on the contract — the keyed route (`signer` blob longer than 20 bytes) reverts `VerifierNotActive` unless its leading 20 bytes name an active verifier. Parameter verifier - The ERC-7913 verifier contract address. Returns: `true` iff the verifier is active. |
| `getWalletFactory` | `() => Promise<Address>` | Reads the quip WalletFactory the wallet commit route trusts (baked immutably at construction). Returns: The wallet factory address. |
| `isQuipWallet` | `(account: Address) => Promise<boolean>` | Reads whether `account` is a wallet deployed by the contract's WalletFactory — the wallet commit route's membership check. An empty-signature commit succeeds only when the SENDER passes this check (`commitmentOf(account) != 0`; the contract reverts `NotQuipWallet` otherwise). Parameter account - The address to test for factory membership. Returns: `true` iff `account` was deployed by the wallet factory. |
| `getCommitDigest` | `(lock: Hex32, party: Terms, counterparty: Terms, signerHash: Hex32) => Promise<Hex32>` | Reads the contract's commit digest for the given inputs — the on-chain counterpart of computeCommitDigest (which computes the same value locally without an RPC round-trip). Useful for digest-parity assertions and debugging signature rejections. Parameter lock - The hashlock. Parameter party - The committing side's terms. Parameter counterparty - The other side's terms. Parameter signerHash - `keccak256` of the committing side's identity blob. Returns: The 32-byte commit digest. |
| `commit` | `(args: CommitArgs, opts?: TxOptions) => Promise<Hash>` | Commits a side of a swap. PERMISSIONLESS and payable — the contract authenticates the PAYLOAD (`args.auth`), not the caller. Parameter args - See `CommitArgs`. Parameter opts - Optional per-transaction gas/fee/nonce options (`TxOptions`); `skipPreflightChecks` skips ONLY the balance check, never the protocol preflights. Returns: The transaction hash (not finality — wait for the receipt). |
| `prepareCommit` | `(args: CommitArgs, options: PrepareCallOptions) => Promise<Call>` | Plans a commit for `options.account` and returns the exact Call that account must execute — WITHOUT sending anything. Parameter args - See `CommitArgs`. Parameter options - See `PrepareCallOptions`; `account` is required. Returns: The `{to: omnibus, value, data}` to execute from `account`. |
| `claim` | `(args: ClaimArgs, opts?: TxOptions) => Promise<Hash>` | Claims a swap by revealing the secret. PERMISSIONLESS — the contract allows anyone holding the secret to claim; the SDK adds no caller restriction. The transaction makes the secret PUBLIC. Parameter args - See `ClaimArgs`. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash (not finality). |
| `reclaim` | `(args: ReclaimArgs, opts?: TxOptions) => Promise<Hash>` | Reclaims THIS party's own escrowed leg after its `reclaimRelease`. PERMISSIONLESS — the assets always go to the terms' `reclaimRecipient` regardless of caller, so the SDK adds no caller restriction. Parameter args - See `ReclaimArgs`. Parameter opts - Optional per-transaction gas/fee/nonce options. Returns: The transaction hash (not finality). |
| `waitForReceipt` | `(hash: Hash, options?: WaitOptions) => Promise<OmnibusReceipt>` | Waits for a write's receipt, verifies success, and decodes the Omnibus events — scoped to THIS client's Omnibus address, so a same-signature event from another contract in the same transaction is never decoded as genuine. This is the preferred way to confirm a `commit`/`claim`/ `reclaim`; you do not pass the address again. Parameter hash - The transaction hash returned by a write method. Parameter options - Confirmation count and timeout (`WaitOptions`); `address` is always set to this client's Omnibus address, so you do not pass it. Returns: The typed `OmnibusReceipt` with address-scoped events. |
| `admin` | `OmnibusAdmin` | Owner-only operations, namespaced to avoid mixing with user flows. |

#### `OmnibusDeployment`

A recorded Omnibus deployment on one chain.

| Name | Type | Description |
| --- | --- | --- |
| `chainId` | `bigint` | The chain id the deployment lives on. |
| `omnibusAddress` | `` `0x${string}` `` | The Omnibus singleton address on that chain. |
| `version?` | `string \| undefined` | The salt version label the deployment was made under. Present on every registry row; optional only so a caller-supplied override need not invent one. |
| `deployed?` | `boolean \| undefined` | Whether the Omnibus this build describes is live on that chain — code present AND its `WALLET_FACTORY` immutable matching the one the deploy scripts compile in. Absent on caller-supplied overrides, which are trusted by definition. |
| `walletFactory?` | `` `0x${string}` \| undefined `` | The quip WalletFactory proxy baked into this Omnibus's immutables. Present on every registry row. The wallet commit route calls `commitmentOf` on it, so a deployment wired to the wrong factory rejects otherwise-valid wallets with `NotQuipWallet` — and cannot be repaired without a redeploy. |

#### `OmnibusReceipt`

A successful, decoded Omnibus transaction result.

| Name | Type | Description |
| --- | --- | --- |
| `transactionHash` | `` `0x${string}` `` | The transaction hash that was waited on. |
| `receipt` | `TransactionReceipt` | The full Viem receipt (status is guaranteed `'success'`). |
| `commitments` | `readonly CommitmentEvent[]` | Decoded `Commitment` events emitted by the transaction (0 or 1). |
| `claims` | `readonly ClaimEvent[]` | Decoded `Claim` events (0, 1, or 2 — a same-chain claim emits one per recipient leg). |
| `reclaims` | `readonly ReclaimedEvent[]` | Decoded `Reclaimed` events (0 or 1 — each reclaim settles one side's own leg). |

#### `PlanApprovalsArgs`

Arguments for `planApprovals`.

| Name | Type | Description |
| --- | --- | --- |
| `publicClient` | `PublicClient` | Public client on the chain where `terms.chainId` points. |
| `omnibusAddress` | `` `0x${string}` `` | The deployed Omnibus address (the spender/operator to check for). |
| `committer` | `` `0x${string}` `` | The committing account — the address that will SEND (and fund) the commit transaction. |
| `terms` | `Terms` | The side's terms whose assets will be escrowed. |

#### `PrepareApprovalArgs`

Arguments for `prepareApproval`.

| Name | Type | Description |
| --- | --- | --- |
| `omnibusAddress` | `` `0x${string}` `` | The Omnibus address to approve as spender/operator. |
| `item` | `ApprovalItem` | The unsatisfied plan item to fix. |
| `erc20Mode?` | `Erc20ApprovalMode \| undefined` | REQUIRED for ERC-20 items: exact or unlimited (see Erc20ApprovalMode). |
| `erc721Mode?` | `"operator" \| "token" \| undefined` | For ERC-721 items: `'token'` approves only the specific token id (default — least privilege); `'operator'` grants `setApprovalForAll`. |

#### `PrepareCallOptions`

Options for `OmnibusClient.prepareCommit`.

| Name | Type | Description |
| --- | --- | --- |
| `account` | `` `0x${string}` `` | The account that will be `msg.sender` when the call executes — for a smart account (e.g. a quip wallet), the ACCOUNT CONTRACT's address, not the key that signs or the EOA that pays gas. Every account-dependent preflight (balance, factory membership, revert simulation) runs against this address, because on-chain the assets are pulled from `msg.sender` and `msg.value` is the account's own balance. |
| `skipPreflightChecks?` | `boolean \| undefined` | Skips ONLY the balance preflight (`getBalance(account) >= value`), never the protocol preflights. Default `false`. |

#### `PreparedTx`

The prepared transaction fields, ready to spread into `writeContract`.

| Name | Type | Description |
| --- | --- | --- |
| `gas` | `bigint` | The gas limit to submit with (buffered unless `opts.gas` was set). |
| `fees` | `FeeOverrides` | Only the caller's explicitly-set fee fields (see FeeOverrides). |
| `nonce?` | `number \| undefined` | Present only when the caller pinned a nonce. |

#### `PrepareTxArgs`

Arguments for `prepareTx`.

| Name | Type | Description |
| --- | --- | --- |
| `publicClient` | `PublicClient` |  |
| `contractParams` | `PrepareTxContractParams` |  |
| `totalValue` | `bigint` | The total native value the sender must pay for the call itself, in wei — for commit exactly `totalNative(party) + commitmentFee`; `0n` for claim/reclaim/admin. The balance preflight checks this bare value only (gas funding is deliberately not preflighted — see preflightBalanceCheck); value-less calls skip the check. |
| `opts?` | `TxOptions \| undefined` |  |

#### `PrepareTxContractParams`

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

| Name | Type | Description |
| --- | --- | --- |
| `address` | `` `0x${string}` `` |  |
| `abi` | `Abi` |  |
| `functionName` | `string` |  |
| `args?` | `readonly unknown[] \| undefined` |  |
| `value?` | `bigint \| undefined` | Native value attached to the call (payable functions only). |
| `account` | `` `0x${string}` `` | The sender address — estimation and the balance preflight both use it. |

#### `QuipSwapErrorDetails`

Structured details carried by every `QuipSwapError`.

| Name | Type | Description |
| --- | --- | --- |
| `code` | `QuipSwapErrorCode` | Stable machine-readable code; safe to branch on. |
| `message` | `string` | Human-readable explanation with remediation guidance. |
| `contractErrorName?` | `string \| undefined` | The decoded Solidity custom-error name (e.g. `VerifierNotActive`, `WindowViolated`) when the error wraps an on-chain revert and the error was decodable from the Omnibus ABI. |
| `cause?` | `unknown` | The original underlying error (e.g. the Viem error), never discarded. |
| `details?` | `unknown` | Additional structured context (offending values, window bounds, ...). |

#### `ReclaimArgs`

Arguments for `OmnibusClient.reclaim`.

| Name | Type | Description |
| --- | --- | --- |
| `lock` | `` `0x${string}` `` | The hashlock identifying the swap. |
| `party` | `Terms` | The terms of the leg being reclaimed (must be local to this chain). |
| `counterparty` | `Terms` | The other side's terms. |
| `verifyOnChainState?` | `boolean \| undefined` | When `true` (default), preflight additionally verifies on-chain state in one parallel read batch, mirroring the per-side `Omnibus.reclaim`: `termsHash(swapId)` must equal the canonical digest and the party's side must be `posted` (`TERMS_NOT_ON_CHAIN` otherwise); the party side must not have already reclaimed; and the lock must permit this side's reclaim — `Free`/`Committed` are the first reclaim, a `Spent` lock is allowed ONLY mid-reclaim (the counterparty already reclaimed, this side has not), while a claim-settled `Spent` and an `Unused` lock reject with `INVALID_LOCK_STATE`. Reads `lockState`, `termsHash`, `posted`, and both sides' `reclaimed` flags. |

#### `ReclaimedEvent`

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

| Name | Type | Description |
| --- | --- | --- |
| `caller` | `` `0x${string}` `` | The address that called `reclaim` (permissionless — any account). |
| `lock` | `` `0x${string}` `` | The hashlock that was reclaimed (indexed topic). |
| `recipient` | `` `0x${string}` `` | The `reclaimRecipient` that received this leg's assets (indexed topic). |
| `blockNumber` | `bigint \| null` |  |
| `transactionHash` | `` `0x${string}` \| null `` |  |
| `logIndex` | `number \| null` |  |

#### `RemoteCommitmentStatus`

The result of `verifyRemoteCommitment`.

| Name | Type | Description |
| --- | --- | --- |
| `committed` | `boolean` | True iff the remote lock is `Committed` AND the remote side's terms are posted. |
| `lockState` | `LockState` | The remote lock's state. |
| `proposerPosted` | `boolean` | Whether the remote (proposer) side's terms digest is posted for the lock. |
| `termsHashMatches` | `boolean` | Whether the on-chain canonical termsHash matches the supplied pairing. |

#### `SameChainSwapPlan`

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

| Name | Type | Description |
| --- | --- | --- |
| `proposerTerms` | `Terms` | The proposer's terms (earlier schedule; commits first; holds the secret). |
| `takerTerms` | `Terms` | The taker's terms (later schedule; commits second). |
| `canonicalDigest` | `` `0x${string}` `` | The canonical trade digest stored in `termsHash[lock]` on commit. |
| `proposerDigest` | `` `0x${string}` `` | The proposer side's single-terms digest (its `posted` key). |
| `takerDigest` | `` `0x${string}` `` | The taker side's single-terms digest (its `posted` key). |
| `proposerCommitWindow` | `TimeWindow` | `[0, proposer.commitmentDeadline)`. |
| `takerCommitWindow` | `TimeWindow` | `[proposer.commitmentDeadline, taker.commitmentDeadline)`. |
| `claimWindow` | `TimeWindow` | `[taker.commitmentDeadline, proposer.claimDeadline)` — one claim settles both legs. |
| `proposerReclaimWindow` | `TimeWindow` | `[proposer.reclaimRelease, +inf)` for the proposer's leg. |
| `takerReclaimWindow` | `TimeWindow` | `[taker.reclaimRelease, +inf)` for the taker's leg. |

#### `SameChainSwapStatusReport`

The full status report returned by `getSameChainSwapStatus`.

| Name | Type | Description |
| --- | --- | --- |
| `status` | `SameChainSwapStatus` | The application-level status (see SameChainSwapStatus). |
| `lockState` | `LockState` | The raw on-chain LockState the status was derived from. |
| `proposerPosted` | `boolean` | Whether the proposer's side is posted on-chain. |
| `takerPosted` | `boolean` | Whether the taker's side is posted on-chain. |
| `proposerReclaimed` | `boolean` | Whether the proposer's side has reclaimed its own leg (per-side reclaim). |
| `takerReclaimed` | `boolean` | Whether the taker's side has reclaimed its own leg (per-side reclaim). |
| `timestamp` | `bigint` | The chain timestamp the report was computed at. |

#### `SecretLockPair`

A freshly generated hashlock pair.

| Name | Type | Description |
| --- | --- | --- |
| `secret` | `` `0x${string}` `` | The 32-byte preimage. Keep private until claim. |
| `lock` | `` `0x${string}` `` | `keccak256(secret)` — safe to share. |

#### `SubmitApprovalArgs`

Arguments for `submitApproval`.

| Name | Type | Description |
| --- | --- | --- |
| `publicClient` | `PublicClient` | Public client used for simulation. |
| `walletClient` | `WalletClient` | Wallet client of the COMMITTER (the wallet that owns the assets). |
| `omnibusAddress` | `` `0x${string}` `` | The Omnibus address to approve as spender/operator. |
| `item` | `ApprovalItem` | The unsatisfied plan item to fix. |
| `erc20Mode?` | `Erc20ApprovalMode \| undefined` | REQUIRED for ERC-20 items: exact or unlimited (see Erc20ApprovalMode). |
| `erc721Mode?` | `"operator" \| "token" \| undefined` | For ERC-721 items: `'token'` approves only the specific token id (default — least privilege); `'operator'` grants `setApprovalForAll`. |

#### `Terms`

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

| Name | Type | Description |
| --- | --- | --- |
| `chainId` | `bigint` | The chain id where THIS side's assets are held and escrowed. The two sides may name different chains (cross-chain swap) or the same chain (same-chain swap). Must be non-zero. |
| `reclaimRecipient` | `` `0x${string}` `` | The address that receives this side's own assets back if the swap is reclaimed instead of claimed. Must be non-zero. |
| `recipient` | `` `0x${string}` `` | The address that receives the COUNTERPARTY's assets when the swap is claimed — not this side's own assets. Must be non-zero. |
| `commitmentDeadline` | `bigint` | Unix timestamp (seconds) at and after which this side may no longer commit. Also the instant the counterparty-taker's commit window opens when this side proposes. Must be non-zero. |
| `claimDeadline` | `bigint` | Unix timestamp (seconds) at and after which claiming gated by this side's claim schedule is forbidden. Must be strictly greater than `commitmentDeadline`. |
| `reclaimRelease` | `bigint` | Unix timestamp (seconds) at and after which this side's escrowed assets may be reclaimed to `reclaimRecipient`. Must be strictly greater than `claimDeadline`. |
| `assets` | `readonly Asset[]` | The assets this side escrows. Must be non-empty and each asset valid. |

#### `TimeWindow`

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

| Name | Type | Description |
| --- | --- | --- |
| `lower` | `bigint` | Inclusive lower bound (Unix seconds). |
| `upper` | `bigint` | EXCLUSIVE upper bound (Unix seconds); `MAX_UINT256` means unbounded. |

#### `TxOptions`

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.

| Name | Type | Description |
| --- | --- | --- |
| `gas?` | `bigint \| undefined` | Explicit gas limit. When set, THREE things are skipped: (a) gas estimation, (b) the safety multiplier, and (c) the pre-submission revert check — because `estimateContractGas` is also what catches a would-be revert before broadcast, and it does not run. The protocol preflights still run, but a call that would revert is signed and broadcast anyway and burns its gas. Use an explicit `gas` only when the call is known to succeed (e.g. replaying a previously simulated call) and you accept on-chain revert risk; leave `gas` unset to keep the revert check, and use TxOptions.gasMultiplier if you only want to tune the buffer. |
| `gasMultiplier?` | `number \| undefined` | Gas-limit safety multiplier: `gas = floor(estimate * multiplier)`, computed with bigint-safe 3-decimal math (never a bigint×float multiplication). Defaults to DEFAULT_GAS_MULTIPLIER; clamped to [MIN_GAS_MULTIPLIER, MAX_GAS_MULTIPLIER]; non-finite values fall back to the MIN (no buffer). |
| `maxFeePerGas?` | `bigint \| undefined` | EIP-1559 total fee ceiling per gas, in wei (exclusive with `gasPrice`). |
| `maxPriorityFeePerGas?` | `bigint \| undefined` | EIP-1559 priority tip per gas, in wei (exclusive with `gasPrice`). |
| `gasPrice?` | `bigint \| undefined` | Legacy gas price, in wei, for non-EIP-1559 chains (exclusive with the two fields above). |
| `nonce?` | `number \| undefined` | Pin the transaction nonce; by default viem fetches the next nonce. |
| `skipPreflightChecks?` | `boolean \| undefined` | Skips the stage-1 BALANCE preflight ONLY (the bare-call-value check that runs before gas estimation; see preflightBalanceCheck). The protocol preflights (windows, pairing, chain id, lock state) ALWAYS run — they are correctness checks, not robustness checks. |

#### `ValidateCrossChainScheduleArgs`

Arguments for `validateCrossChainSchedule`.

| Name | Type | Description |
| --- | --- | --- |
| `proposerTerms` | `Terms` | The SECRET HOLDER's leg. The secret holder must be the proposer (the side with the smaller `commitmentDeadline`); anything else is the free-option misconfiguration and is rejected. |
| `takerTerms` | `Terms` | The counterparty's (taker's) leg, on the other chain. |
| `minimumBufferSeconds?` | `bigint \| undefined` | Minimum acceptable gap, in SECONDS, between EVERY pair of adjacent timestamps in the interleaved schedule — including the taker's post-reveal reaction buffer (`proposer.reclaimRelease - proposer.claimDeadline`). |
| `maxClockSkewSeconds?` | `bigint \| undefined` | The maximum plausible CLOCK SKEW, in SECONDS, between the two chains' block timestamps — the amount by which the taker's chain may lag (or the proposer's chain may run ahead of) wall-clock relative to each other. |

#### `WaitOptions`

Options forwarded to `publicClient.waitForTransactionReceipt`, plus address scoping.

| Name | Type | Description |
| --- | --- | --- |
| `address?` | `` `0x${string}` \| undefined `` | The expected Omnibus contract address. When set, only logs emitted by this address are decoded into `commitments`/`claims`/`reclaims` — the defense against same-signature events from other contracts in the same transaction. Omitting it decodes every matching log (legacy behavior; not recommended). OmnibusClient.waitForReceipt fills this in. |
| `confirmations?` | `number \| undefined` | Number of confirmations to wait for (default: the client's default, 1). |
| `timeout?` | `number \| undefined` | Milliseconds to wait before giving up. |

### Type aliases

#### `ApprovalItem`

One entry of an `ApprovalPlan`.

```ts
type ApprovalItem = Erc20ApprovalItem | Erc721ApprovalItem | Erc1155ApprovalItem;
```

#### `Erc20ApprovalMode`

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).

```ts
type Erc20ApprovalMode = 'exact' | 'unlimited';
```

#### `Hex32`

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

```ts
type Hex32 = Hex;
```

#### `QuipSwapErrorCode`

Stable machine-readable SDK error codes.

```ts
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';
```

#### `SameChainSwapStatus`

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.

```ts
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';
```