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[] array during execution.

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:

Type	Creates UTXO?	Description
FlashLoan	Yes	Borrows from flash loan provider, creates output for repayment amount
PullToken	No	Pulls tokens from user to router (requires user approval)
PushToken	No	Sends tokens from UTXO to user
ToOutput	Yes	Creates a UTXO from hardcoded amount/token (no actual transfer)
Approve	Yes (empty)	Approves gateway to spend UTXO. Creates empty output for index sync!
Split	Yes (2)	Splits UTXO into fee portion + remainder (for Aave flash loan fees)
Add	Yes	Combines two UTXOs of same token
Subtract	Yes	Subtracts one UTXO from another

Critical: Approve Creates Empty Output

The Approve instruction creates an empty output to maintain index synchronization. This is why output indices jump after approvals:

// 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:

Op	Creates UTXO?	Description
Deposit	No	Supply tokens to lending protocol
DepositCollateral	No	Supply as collateral (Morpho, Compound)
WithdrawCollateral	Yes	Withdraw collateral, creates output
Borrow	Yes	Borrow tokens, creates output
Repay	Yes	Repay debt, creates refund output (usually 0)
GetBorrowBalance	Yes	Query debt balance, creates output with amount
GetSupplyBalance	Yes	Query supply balance, creates output with amount
Swap	Yes (2)	Swap via DEX, creates (tokenOut, refund) outputs
SwapExactOut	Yes (2)	Exact output swap, creates (tokenOut, refund) outputs

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 to account for fees:

[
  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 })