Kapan Lending Instructions System

The KapanRouter uses a UTXO-based instruction system where each operation can consume inputs from previous outputs and produce new outputs. Understanding this is critical for building correct flows.

Core Concepts

UTXO (Unspent Transaction Output)

Each instruction can create outputs that subsequent instructions reference by index. The router maintains an

outputs[]

Two Instruction Types

1. Router Instructions (

   protocolName: "router"

   ) - Handled by KapanRouter directly
2. Protocol Instructions (

   protocolName: "aave"

   ,

   "compound"

   , etc.) - Delegated to gateways

Router Instructions

Defined in

utils/v2/instructionHelpers.ts:4-13

FlashLoan

PullToken

PushToken

ToOutput

Approve

Split

Add

Subtract

Critical: Approve Creates Empty Output

The

Approve

// After Approve(2), the next output is index 3, not 2!
addRouter(encodeApprove(2, "aave"), true); // createsUtxo=true

Lending Operations

Defined in

utils/v2/instructionHelpers.ts:26-36

Deposit

DepositCollateral

WithdrawCollateral

Borrow

Repay

GetBorrowBalance

GetSupplyBalance

Swap

SwapExactOut

Input Index Conventions

• inputIndex: 999

  - Ignore input, use

  amount

  parameter directly

• inputIndex: 0-998

  - Read amount/token from

  outputs[inputIndex]

Flash Loan Providers

enum FlashLoanProvider {
  BalancerV2 = 0,  // 0% fee
  BalancerV3 = 1,  // 0% fee  
  Aave = 2,        // ~5-9 bps fee
  ZeroLend = 3,    // ~5 bps fee
  UniswapV3 = 4,   // Requires pool address
  Morpho = 5,      // 0% fee
}

Important: Aave/ZeroLend flash loans create an output with the repayment amount (principal + fee), not the borrowed amount. The router receives the principal but must track repayment separately.

Common Flows

Basic Deposit

[
  PullToken(amount, token, user),      // No output
  Approve(0, protocol),                // Output[0] = empty (for sync)
  DepositCollateral(token, user, 0, inputIndex=0),  // No output
]

Withdraw Max

[
  GetSupplyBalance(token, user),       // Output[0] = balance
  WithdrawCollateral(token, user, inputIndex=0),  // Output[1] = withdrawn
  PushToken(1, user),                  // No output
]

Flash Loan Pattern

[
  ToOutput(amount, token),             // Output[0] = virtual UTXO
  FlashLoan(provider, inputIndex=0),   // Output[1] = repayment amount
  // ... use borrowed funds (router has Output[0] worth of tokens)
  // ... must leave Output[1] worth in router for repayment
]

Aave Flash Loan with Fee (Max Withdrawal)

When using Aave flash loans for max operations, use

Split

[
  GetSupplyBalance(token),             // Output[0] = 100
  Split(0, 9),                         // Output[1] = 0.09 (fee buffer), Output[2] = 99.91
  FlashLoan(Aave, 2),                  // Output[3] = 100 (repayment), router has 99.91
  // ... operations using Output[2] (what we actually have)
  // ... withdraw Output[3] worth to repay
]

File Locations

• Instruction Helpers:

  packages/nextjs/utils/v2/instructionHelpers.ts

• Flow Builders:

  packages/nextjs/hooks/useKapanRouterV2.tsx:219-936

• Move Builder:

  packages/nextjs/hooks/useKapanRouterV2.tsx:1519-1631

• Starknet Instructions:

  packages/nextjs/hooks/useStarknetMovePosition.ts

Debugging Tips

1. Track UTXO indices manually - Draw out the output array as you build instructions
2. Approve creates empty output - Always increment your expected index after Approve
3. Flash loan outputs - Remember: Aave Output = repayment (more than borrowed)
4. Use simulation -

   simulateInstructions()

   catches most errors before execution
5. Check authorization -

   getAuthorizations()

   returns needed approvals

Protocol Context Encoding

Different protocols need different context bytes:

// Aave: empty context
context = "0x"

// Compound: market address
context = encodeAbiParameters([{ type: "address" }], [marketAddress])

// Morpho: full MarketParams tuple
context = encodeMorphoContext({ loanToken, collateralToken, oracle, irm, lltv })