Instructions#

All 20 instructions in the Coalesce Finance program (discriminators 0–16, 18–20).

Admin/Setup Instructions#

0. InitializeProtocol#

Creates the global ProtocolConfig. Can only be called by the program's upgrade authority.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig PDA
1	`admin`	Yes	Yes	Program upgrade authority (pays rent)
2	`fee_authority`	No	No	Address to receive fees
3	`whitelist_manager`	No	No	Whitelist manager address
4	`blacklist_program`	No	No	External blacklist program
5	`system_program`	No	No	System Program
6	`program_data`	No	No	BPF Loader upgrade data

Data:

fee_rate_bps: u16 — Protocol fee rate in basis points

1. SetFeeConfig#

Updates protocol fee configuration.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig PDA
1	`admin`	No	Yes	Admin signer
2	`new_fee_authority`	No	No	New fee authority address

Data:

new_fee_rate_bps: u16 — New protocol fee rate in basis points

2. CreateMarket#

Creates a new lending market.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Market PDA
1	`borrower`	Yes	Yes	Borrower / market creator
2	`mint`	No	No	Token mint (USDC)
3	`vault`	Yes	No	Vault PDA (token account)
4	`market_authority`	No	No	Market authority PDA
5	`protocol_config`	No	No	ProtocolConfig
6	`borrower_whitelist`	No	No	BorrowerWhitelist
7	`blacklist_check`	No	No	Blacklist validation account
8	`system_program`	No	No	System Program
9	`token_program`	No	No	SPL Token Program
10	`haircut_state`	Yes	No	HaircutState PDA

Data:

market_nonce: u64 — Unique nonce for PDA derivation
annual_interest_bps: u16 — Fixed annual interest rate
maturity_timestamp: i64 — Unix timestamp of loan maturity
max_total_supply: u64 — Maximum deposit capacity

Core Lending Instructions#

3. Deposit#

Lender deposits USDC into a market.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`lender`	Yes	Yes	Lender signer
2	`lender_token`	Yes	No	Lender's USDC token account
3	`vault`	Yes	No	Market vault
4	`lender_position`	Yes	No	LenderPosition PDA
5	`blacklist_check`	No	No	Blacklist validation account
6	`protocol_config`	No	No	ProtocolConfig
7	`mint`	No	No	Token mint
8	`token_program`	No	No	SPL Token Program
9	`system_program`	No	No	System Program

Data:

amount: u64 — USDC amount to deposit

4. Borrow#

Borrower takes funds from their market.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`borrower`	No	Yes	Borrower signer
2	`borrower_token`	Yes	No	Borrower's USDC token account
3	`vault`	Yes	No	Market vault
4	`market_authority`	No	No	Market authority PDA
5	`borrower_whitelist`	Yes	No	BorrowerWhitelist (debt tracking)
6	`blacklist_check`	No	No	Blacklist validation account
7	`protocol_config`	No	No	ProtocolConfig
8	`token_program`	No	No	SPL Token Program

Data:

amount: u64 — USDC amount to borrow

5. Repay#

Repays borrowed principal. Anyone can call (not just the borrower).

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`payer`	No	Yes	Token holder repaying
2	`payer_token`	Yes	No	Payer's USDC token account
3	`vault`	Yes	No	Market vault
4	`protocol_config`	No	No	ProtocolConfig
5	`mint`	No	No	Token mint
6	`borrower_whitelist`	Yes	No	BorrowerWhitelist (debt tracking)
7	`token_program`	No	No	SPL Token Program

Data:

amount: u64 — USDC amount to repay

6. RepayInterest#

Repays interest only (does not reduce borrower's outstanding debt). Anyone can call. Updates market.total_repaid and market.total_interest_repaid.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`payer`	No	Yes	Token holder paying
2	`payer_token`	Yes	No	Payer's USDC token account
3	`vault`	Yes	No	Market vault
4	`protocol_config`	No	No	ProtocolConfig
5	`token_program`	No	No	SPL Token Program

Data:

amount: u64 — USDC amount to repay as interest

7. Withdraw#

Lender withdraws after maturity. If the market is still unsettled, the first withdrawal after the 5-minute grace period triggers the settlement factor lock.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`lender`	No	Yes	Lender signer
2	`lender_token`	Yes	No	Lender's USDC token account
3	`vault`	Yes	No	Market vault
4	`lender_position`	Yes	No	LenderPosition PDA
5	`market_authority`	No	No	Market authority PDA
6	`blacklist_check`	No	No	Blacklist validation account
7	`protocol_config`	No	No	ProtocolConfig
8	`token_program`	No	No	SPL Token Program
9	`haircut_state`	Yes	No	HaircutState PDA

Data:

scaled_amount: u128 — Shares to withdraw (0 = full withdrawal)
min_payout: u64 — Minimum USDC to receive (slippage protection)

Settlement Instructions#

8. CollectFees#

Collects accrued protocol fees from a market.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`protocol_config`	No	No	ProtocolConfig
2	`fee_authority`	No	Yes	Authorized fee collector
3	`fee_destination`	Yes	No	Fee authority's token account
4	`vault`	Yes	No	Market vault
5	`market_authority`	No	No	Market authority PDA
6	`token_program`	No	No	SPL Token Program

Data: None (discriminator only)

9. ReSettle#

Improves settlement factor after late repayment. Permissionless.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`vault`	No	No	Market vault
2	`protocol_config`	No	No	ProtocolConfig
3	`haircut_state`	No	No	HaircutState PDA (read-only)

Data: None (discriminator only)

10. CloseLenderPosition#

Closes an empty lender position account and returns rent.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	No	No	Associated market
1	`lender`	Yes	Yes	Position owner (receives rent lamports)
2	`lender_position`	Yes	No	LenderPosition PDA
3	`system_program`	No	No	System Program
4	`protocol_config`	No	No	ProtocolConfig

Data: None (discriminator only)

11. WithdrawExcess#

Borrower withdraws remaining vault funds after full settlement and fee collection.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	No	No	Target market
1	`borrower`	No	Yes	Market borrower
2	`borrower_token`	Yes	No	Borrower's USDC token account
3	`vault`	Yes	No	Market vault
4	`market_authority`	No	No	Market authority PDA
5	`token_program`	No	No	SPL Token Program
6	`protocol_config`	No	No	ProtocolConfig
7	`blacklist_check`	No	No	Blacklist validation account
8	`borrower_whitelist`	No	No	BorrowerWhitelist (read-only validation)

Data: None (discriminator only)

Preconditions (all required):

borrower must match market.borrower and be a signer
Market must be matured (now >= maturity_timestamp)
scaled_total_supply == 0 (all lenders have withdrawn)
settlement_factor_wad > 0 (market settled)
settlement_factor_wad == WAD (full settlement only)
accrued_protocol_fees == 0 (fees collected first)
Borrower must pass blacklist check
vault must match market vault
Excess amount (vault_balance - haircut_accumulator) must be greater than zero

Access Control Instructions#

12. SetBorrowerWhitelist#

Adds or updates a borrower whitelist entry. Called by Whitelist Manager.

Accounts:

#	Account	Writable	Signer	Description
0	`borrower_whitelist`	Yes	No	BorrowerWhitelist PDA
1	`protocol_config`	No	No	ProtocolConfig
2	`whitelist_manager`	Yes	Yes	Whitelist manager signer
3	`borrower`	No	No	Borrower address
4	`system_program`	No	No	System Program

Data:

is_whitelisted: u8 — 1 = whitelist, 0 = remove
max_borrow_capacity: u64 — Maximum outstanding borrowing capacity

13. SetPause#

Pauses or unpauses the protocol. Admin only.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig
1	`admin`	No	Yes	Admin signer

Data:

paused: u8 — 1 = pause, 0 = unpause

14. SetBlacklistMode#

Sets blacklist enforcement mode. Admin only.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig
1	`admin`	No	Yes	Admin signer

Data:

fail_closed: u8 — 1 = fail-closed, 0 = fail-open

15. SetAdmin#

Transfers admin role to a new address. Current admin only.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig
1	`current_admin`	No	Yes	Current admin
2	`new_admin`	No	No	New admin address

Data: None (discriminator only)

16. SetWhitelistManager#

Sets the whitelist manager address. Admin only.

Accounts:

#	Account	Writable	Signer	Description
0	`protocol_config`	Yes	No	ProtocolConfig
1	`admin`	No	Yes	Admin signer
2	`new_whitelist_manager`	No	No	New whitelist manager addr

Data: None (discriminator only)

Post-Maturity Instructions#

18. ForceClosePosition#

Borrower force-closes a lender position after maturity + grace period. Computes payout using the same formula as Withdraw, transfers to a lender-owned token account, zeros the position, and decrements scaled_total_supply. If the market has not settled yet, the instruction computes and locks settlement_factor_wad inline. This enables withdraw_excess to succeed when dust, lost wallets, or blacklisted lenders prevent voluntary withdrawal.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`borrower`	No	Yes	Market borrower (signer)
2	`lender_position`	Yes	No	LenderPosition PDA to force-close
3	`vault`	Yes	No	Market vault
4	`escrow_token_account`	Yes	No	Lender-owned token account (receives payout)
5	`market_authority`	No	No	Market authority PDA
6	`protocol_config`	No	No	ProtocolConfig
7	`token_program`	No	No	SPL Token Program
8	`haircut_state`	Yes	No	HaircutState PDA

Data: None (discriminator only)

Preconditions (all required):

borrower must match market.borrower and be a signer
Market must be past maturity_timestamp + SETTLEMENT_GRACE_PERIOD
settlement_factor_wad may be 0; on first eligible force-close the instruction computes and locks settlement inline
Lender position must have valid PDA derivation
If payout is zero (dust/deadlock), transfer is skipped and position is still cleared

19. ClaimHaircut#

Allows a lender to claim haircut recovery tokens when the settlement factor improves. The lender receives tokens proportional to their share of the haircut gap that has been recovered since their last claim.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`lender`	No	Yes	Lender signer
2	`lender_position`	Yes	No	LenderPosition PDA
3	`lender_token`	Yes	No	Lender's USDC token account
4	`vault`	Yes	No	Market vault
5	`market_authority`	No	No	Market authority PDA
6	`haircut_state`	Yes	No	HaircutState PDA
7	`protocol_config`	No	No	ProtocolConfig
8	`token_program`	No	No	SPL Token Program

Data: None (discriminator only)

20. ForceClaimHaircut#

Borrower force-claims haircut recovery on behalf of a lender, sending recovered tokens to an escrow token account. Used when a lender is unable or unwilling to claim.

Accounts:

#	Account	Writable	Signer	Description
0	`market`	Yes	No	Target market
1	`borrower`	No	Yes	Market borrower (signer)
2	`lender_position`	Yes	No	LenderPosition PDA
3	`escrow_token_account`	Yes	No	Lender-owned token account (receives payout)
4	`vault`	Yes	No	Market vault
5	`market_authority`	No	No	Market authority PDA
6	`haircut_state`	Yes	No	HaircutState PDA
7	`protocol_config`	No	No	ProtocolConfig
8	`token_program`	No	No	SPL Token Program

Data: None (discriminator only)