Skip to content

Repayments

How repayments flow through the protocol - debt detection, share burning, and overpayment handling

On this page

Repayment Flow Overview

LendingPoolckAsset LedgerckAsset MinterNative ChainLendingPoolckAsset LedgerckAsset MinterNative ChainWait for confirmationsTimer: check_for_new_subaccount_inflows (60s)WAL executionTimer: process_treasury_movements (60s)Timer: process_event_queue (60s)UserSend native asset to repayment addressTransaction confirmedMint ckAsset to repayment subaccountQuery subaccount balanceSchedule transfer to treasuryTransfer from subaccount to treasuryDetect treasury inflow from repayment subaccountCreate RepaymentConfirmed eventnotify_pool_event(RepaymentConfirmed)Burn debt sharesAckUser

Repayment Subaccount

Repayments use a different prefix than deposits to distinguish them:

  • Deposit prefix: 0x1
  • Repayment prefix: 0x2

This allows the protocol to correctly attribute incoming funds as debt repayment rather than new collateral.

Detection Process

The detection process is identical to deposits:

  1. Inflow Detection - Pool scans for new balances every 60 seconds
  2. Treasury Transfer - Funds moved from repayment subaccount to treasury
  3. Event Creation - Pool creates a RepaymentConfirmed event

Debt Share Burning

When the lending canister receives a repayment event:

  1. Checks idempotency (skip if already processed)
  2. Syncs pool indices
  3. Calculates current debt
  4. Burns debt shares: shares_to_burn = repay_amount / borrow_index
  5. Handles any overpayment

Example: User has 1000 debt shares at borrow_index = 1.05 → Current debt = 1050 tokens. User repays 525 tokens → Shares burned = 525 / 1.05 = 500 shares → Remaining: 500 shares = 525 tokens debt

Overpayment Handling

Repayment overpayments are handled according to each pool's configuration. After a one-smallest-unit rounding adjustment, excess is scheduled for refund only when the pool has enabled overpayment refunds and the excess is strictly greater than its configured minimum. If refunds are disabled, or the adjusted excess is at or below that minimum, it is retained as protocol service fees.

A repayment received when no corresponding debt position exists is handled separately: the inflow is scheduled for refund without applying the overpayment threshold. Refund delivery fees still apply.

Scheduled refunds are first moved to a pool-held recovery subaccount associated with the user, not sent directly back to the sending wallet. A ledger transfer fee is deducted during this step, and additional transfer or network fees may apply when the funds are released. Scheduling a refund does not mean it has already been delivered.

Refund availability depends on the deployed pool version and configuration; do not assume every live pool has refunds enabled. If you repaid when there was no open debt position, recover the refund from Failed actions → Recover funds in the app. The account-recovery page is not a refund tracker. For other overpayment refunds, contact support.

[!WARNING]Do not deliberately overpay or rely on a refund. In the connected-wallet advanced flow, copy the current outstanding debt from the app and repay the exact amount shown.

Partial Repayments

Users can repay any amount up to their full debt. The protocol calculates how many debt shares to burn based on the current borrow index.

Example:

  • User has 1000 debt shares at borrow_index = 1.05 → Current debt = 1050 tokens
  • User repays 525 tokens → Shares burned = 525 / 1.05 = 500 shares
  • Remaining: 500 shares = 525 tokens debt

Interest Consideration

When repaying, remember that debt accrues interest continuously (even while repayment transactions are processing):

Original Borrow

+ Accrued Interest

Total Debt

Repayment Amount

Example (simplified, compounding not shown for clarity): Borrowed 1000 USDT, 6 months elapsed, 10% APR → Accrued interest: ~50 USDT → Total debt: ~1050 USDT

Repayment Address

Each user has a unique repayment address per pool:

Chain Method
Bitcoin Same address as deposit, distinguished by subaccount prefix

Timing

Step Trigger Latency
Native tx confirmation Blockchain Varies by chain
ckAsset minting Minter Immediate
Inflow detection Timer ~60 sec
Treasury transfer WAL ~30 sec
Treasury detection Timer ~60 sec
Event notification Timer ~60 sec
Debt share burning Event Immediate

Health Factor Impact

Repaying debt improves your health factor by reducing borrowed debt. It does not withdraw supplied collateral; in the connected-wallet advanced flow, use Withdraw after reducing or clearing debt to remove supplied assets.

Before repayment: Collateral: $50,000, Debt: $40,000, HF = 1.0 (at risk)

After repaying $10,000: Collateral: $50,000, Debt: $30,000, HF = 1.33 (safer)

Idempotency

Repayments have the same deduplication as deposits:

  1. Ledger index tracking: Each transaction processed once
  2. PROCESSED_INFLOWS set: Event deduplication
  3. Subaccount debouncing: One job per subaccount per scan

Repayments are automatically detected when the supported borrowed asset is sent through the repayment method shown in the app. Wrong-asset, wrong-network, or wrong-address transfers require support investigation and are not guaranteed to be recoverable.

Esc