Building Transactions

Every state-changing flow on the client.iris.core(chainId) entity returns the same shape: getRequirements() resolves the on-chain prerequisites, and buildTx(signatures?) synchronously encodes the final Transaction object (to, value, data, plus a typed action discriminator). Building is deterministic — no simulation, no gas estimation, no sending; the SDK produces calldata and your application decides when and how to submit it. Each flow validates locally what the contract would reject — deadlines, bounds, roles, bitmap membership — as typed errors, so bad input fails at build time rather than as a revert.

How flows are routed

Flow	Route	Who
`take`	Bundler3	Borrower
`repay`	Bundler3	Anyone
`supplyCollateral` / `supplyBond`	Bundler3	Anyone
`escape`	Bundler3	Borrower
`refinance`	Bundler3	Solver
`withdrawCollateral`	Direct Iris call	Borrower
`withdrawBond`	Direct Iris call	Solver
`claim`	Direct Iris call	Balance owner

Flows that move tokens in run through Bundler3’s general adapter: Iris pulls funding atomically with the call, so the transfer and the Iris call must share one transaction — and the bundle is what lets a permit, a Permit2 approval or an Iris authorization signature ride along instead of costing a standalone transaction. Flows that only move tokens out call Iris directly: nothing is pulled from the caller, so there is nothing to make atomic and no approval to fold in. Accruing pulls are funded with an upper bound. Iris prices repay, escape and refinance at execution, and the amount owed accrues per second — funding the fetched amount would under-fund the pull and revert. These bundles fund the position projected two hours forward and sweep the residual back to the receiver. The projection doubles as the transaction’s validity window: rebuild after two hours rather than sending a stale one.

Requirements

getRequirements() returns what must be satisfied before the transaction can land:

ERC-20 approval — approve the general adapter (or, on the Permit2 path, the Permit2 contract) to pull tokens. Returned as a standard approve transaction to send first.
Permit / Permit2 signature — off-chain approvals passed into buildTx instead of costing a transaction. Enabled by irisViemExtension({ supportSignature: true }); pass useSimplePermit: true to getRequirements to prefer an ERC-2612 permit when the token supports one.
Iris authorization — bundled flows that operate on a user’s loan need that user to authorize the general adapter on Iris: take and escape the borrower’s, refinance the solver’s. Returned as a setAuthorization transaction — or, with supportSignature, as a signable requirement folded into the bundle — and omitted when already in place.

import { isRequirementSignature } from "@iris-credit/iris-sdk";

const { buildTx, getRequirements } = iris.take({ userAddress, quote, quoteSignature });

const requirements = await getRequirements();

const signatures = [];
for (const requirement of requirements) {
  if (isRequirementSignature(requirement)) {
    // A signable requirement — a permit / Permit2 allowance or an Iris authorization.
    signatures.push(await requirement.sign(client, userAddress));
  } else {
    // A prerequisite transaction — an ERC-20 approval or the Iris authorization.
    await client.sendTransaction(requirement);
  }
}

const tx = buildTx(signatures);
const hash = await client.sendTransaction(tx);

The isRequirementApproval and isRequirementIrisAuthorization guards narrow the transaction requirements further when the two must be handled differently. buildTx consumes at most one permit and one authorization signature — passing several of a kind, or a kind the flow does not consume, throws instead of silently dropping a signed requirement.

Builder = signer. userAddress must be the account that signs and sends the transaction. The entity enforces the contract’s pinned roles at build time — take, escape and withdrawCollateral require the borrower, withdrawBond and refinance the solver — and every requirement’s sign(client, userAddress) rejects a client whose account is not userAddress.

Take

Opens a loan from a solver-signed quote delivered through the RFQ — the response carries the quote, its signature and, for solvers funding bonds per-quote, the solverPermit2 payload. Validation is local-only: the RFQ already validated the quote, and the contract re-verifies everything at execution.

const { buildTx, getRequirements } = iris.take({
  userAddress: borrower, // must be quote.borrower.
  quote,
  quoteSignature,
  solverPermit2, // optional — delivered with the quote.
});

const requirements = await getRequirements({ useSimplePermit: true });
const tx = buildTx(signatures);

// For quotes collateralized in the chain's wNative, part (or all) of the
// collateral can be paid natively and wrapped in-bundle; the ERC-20 pull
// covers the remainder and the transaction's `value` carries the native amount.
const { buildTx, getRequirements } = iris.take({
  userAddress: borrower,
  quote,
  quoteSignature,
  nativeAmount: 1000000000000000000n, // 1 ETH of the collateral, wrapped in-bundle.
});

The same nativeAmount parameter funds the debt token on repay / escape / refinance and the deposit on supplyCollateral / supplyBond, always requiring the funded asset to be the chain’s wNative.

Repay

Closes the loan in full — there are no partial repays on Iris. Permissionless: anyone can fund it, and the sweep returns the residual to userAddress.

const positionData = await iris.getPositionData(pod);

const { buildTx, getRequirements } = iris.repay({
  userAddress: payer, // anyone — repay is permissionless; the sweep returns here.
  positionData,
});

const requirements = await getRequirements();
const tx = buildTx([permitSignature]);

Repay resolves the loan but leaves the collateral with the position — exit it afterwards with escape.

Top-ups

supplyCollateral and supplyBond are permissionless — anyone can fund either side of a loan:

const loanData = await iris.getLoanData(pod);

const { buildTx, getRequirements } = iris.supplyCollateral({
  userAddress: payer, // anyone — the supply is permissionless.
  loanData,
  amount: 50000000n, // 0.5 cbBTC.
});

const requirements = await getRequirements();
const tx = buildTx([permitSignature]);

const loanData = await iris.getLoanData(pod);

const { buildTx, getRequirements } = iris.supplyBond({
  userAddress: payer,
  loanData, // the bond is denominated in loanData.debtToken.
  amount: 1_000_000000n, // 1k USDC.
});

const requirements = await getRequirements();
const tx = buildTx([permitSignature]);

Withdrawals

Direct Iris calls — no bundler, no approval. Withdrawals are validated locally against the ceilings Iris re-checks onchain, measured with a 0.5% buffer below the relevant LLTV so a withdrawal sized to the fetched state still clears once it lands. withdrawCollateral additionally validates the venue’s own ceiling, which Iris’s does not imply.

import { Time } from "@iris-credit/iris-ts";

const positionData = await iris.getPositionData(pod);

const { buildTx } = iris.withdrawCollateral({
  userAddress: borrower, // must be the loan's borrower (or authorized by them on Iris).
  positionData: positionData.accrueLegs(Time.timestamp()).rebase(), // ceilings are measured on it as given.
  amount: 50000000n, // 0.5 cbBTC.
});

const tx = buildTx();

const positionData = await iris.getPositionData(pod);

const { buildTx } = iris.withdrawBond({
  userAddress: solver, // must be the loan's solver (or authorized by them on Iris).
  positionData,
  amount: 1_000_000000n, // 1k USDC.
});

const tx = buildTx();

Claim

Settlement credits the solver’s net and surplus — and the fee recipient’s fees — to claimable balances. claim draws one down; amount defaults to the whole balance.

const claimableData = await iris.getClaimableData(solver, debtToken);

const { buildTx } = iris.claim({
  userAddress: solver, // whose balance is drawn down and who receives the tokens.
  token: debtToken,
  claimableData,
});

const tx = buildTx();

Escape

Exits the venue position of a resolved loan (bondRequirement === 0n): the bundle funds any remaining venue debt (projected two hours forward, residual swept back), settles it, and withdraws the venue collateral — yield included — to userAddress. After a repay or liquidation the venue usually carries no debt, in which case the funding requirement comes back empty.

const positionData = await iris.getPositionData(pod);

const { buildTx, getRequirements } = iris.escape({
  userAddress: borrower, // must be the loan's borrower.
  positionData,
});

const requirements = await getRequirements();
const tx = buildTx(signatures);

Refinance

Moves the loan’s position to another venue enabled in the loan’s venueBitmap. The migration is replayed locally to reject what the contract would reject; the bundle then funds the current venue’s debt (projected two hours forward), re-enters the new venue, and returns the borrow proceeds plus the swept residual to userAddress, leaving it whole.

import { ChainId, getChainRegistry } from "@iris-credit/core-sdk";

const { venues, marketDatas } = getChainRegistry(ChainId.EthMainnet);

const positionData = await iris.getPositionData(pod);
const newVenue = await iris.getVenueData({
  loanData: positionData.loan,
  venueId: venues.morphoBlue,
  data: marketDatas["morphoBlue:cbBTC/USDC"].data, // the target venue's market data payload.
});

const { buildTx, getRequirements } = iris.refinance({
  userAddress: solver, // must be the loan's solver.
  positionData,
  newVenue,
});

const requirements = await getRequirements();
const tx = buildTx(signatures);

Whether the new venue’s data payload is enabled on Iris is not read here — the contract rejects a disabled payload at execution. Check upfront with fetchIsDataEnabled from @iris-credit/core-sdk.

Solver Signing

The maker-flow counterpart: sign quotes and manage bond allowances.

Entities & Reads

What the flows’ pre-fetched inputs are made of.

Solver Economics & Lifecycle

Integration & Development

Smart Contracts Reference

How flows are routed

Requirements

Take

Repay

Top-ups

Withdrawals

Claim

Escape

Refinance

Next

Solver Signing

Entities & Reads

​How flows are routed

​Requirements

​Take

​Repay

​Top-ups

​Withdrawals

​Claim

​Escape

​Refinance

​Next

Solver Signing

Entities & Reads

How flows are routed

Requirements

Take

Repay

Top-ups

Withdrawals

Claim

Escape

Refinance

Next