On this page
Build conviction from the contracts up.
A concise technical reference for Woodlark’s fixed-term lending model, isolated position vaults, risk controls and transaction boundaries.
Overview
Woodlark is a non-custodial, overcollateralized lending protocol designed for Robinhood Chain. Borrowers lock registry-approved ERC-20 collateral and receive a fixed principal in WETH for a fixed duration. Liquidity providers receive non-transferable internal units representing a proportional claim on pool assets.
The borrower can see maturity, fee and gross repayment before signing. There is no utilization-driven rate change during an active loan.
Core guarantees
- Onchain contracts remain the source of truth for collateral, debt and settlement.
- Every position’s collateral and automated-exit proceeds are isolated in its own minimal vault.
- Repayment and collateral top-up remain available when risk-increasing actions are paused.
- The interface pins contract identities at build time and verifies that the API reports the same deployment before enabling a write.
Architecture
The system separates accounting, collateral custody, price validation and execution. This narrows contract responsibilities and makes critical invariants easier to verify.
Offchain services
The indexer, read API and permissionless keeper workers improve usability but cannot change protocol state without satisfying the same contract checks as any wallet. If every service stops, users can still repay and add collateral directly through verified contracts. Lender exits reopen on-chain after all funded principal is resolved.
Borrowing lifecycle
Protocol configuration defines explicit terms per collateral category. The initial specification uses three tiers for RWA and volatile assets.
Supported position operations
Deposit collateral, choose a tier and receive net WETH proceeds.
Return all outstanding gross principal and recover remaining collateral.
Reduce debt without closing; the position health factor improves immediately.
Add collateral at any time, including during a protective pause.
Pay the configured extension fee and move maturity by the selected tier term.
previewOpenLoan(borrower, collateral, collateralAmount, principal, tierId, referralCode)
openLoan(collateral, collateralAmount, principal, tierId, referralCode, expectedTermsHash, minCollateralPrice, minPayout, deadline)
repay(loanId, amount, useVaultProceeds)
repayFull(loanId, useVaultProceeds)
addCollateral(loanId, amount)
extend(loanId, maxExtensionFee, minDuration, deadline)
liquidate(loanId, maxPayment, minCollateralOut, deadline)
takeOverExpiredLoan(loanId, maxPayment, minCollateralOut, deadline)After maturity plus the configured grace period, isolated WETH is applied first and an oracle-independent seven-day Dutch takeover moves from full residual debt to a terminal zero price. Its caller bounds remain enforced atomically.
Automated exits
A borrower may attach price-conditioned instructions to collateral held by the loan vault. Execution is permissionless, but valid only when fresh conservative pricing, route and minimum-output constraints all pass.
Take profit
Sell when the validated price reaches or exceeds a target.
Stop-limit
Attempt a sale at or below the trigger without ever accepting less than the borrower-signed minimum output.
Bracket · OCO
Pair one profit and one loss threshold; the first valid execution cancels the other.
Ladder
Split up to eight slices across distinct targets; total allocation cannot exceed 100%.
Trailing stop
Track a verified high-water mark and execute after the configured drawdown.
Cancel or update
The borrower can cancel an active instruction or update its minimum output onchain.
Every downside order is a stop-limit: a downward gap or insufficient WETH route below the signed minimum output leaves the order active and collateral unsold until it can execute or the borrower cancels it.
Execution proceeds can remain inside the loan vault or be applied to debt according to the borrower-signed instruction. Keepers have no custody and no privileged withdrawal path.
WETH liquidity vault
The lending pool uses proportional conversion and preview accounting without issuing a transferable receipt token. Its state-changing ABI requires a deadline and an explicit minimum or maximum execution bound. Deposits credit internal position units; withdrawals burn only the caller’s units. Deposits remain available during active loans; withdrawals are limited to mature position value and WETH that is not currently lent. ThetotalAssets view includes idle WETH, outstanding lender principal and realized lender fees, net of principal write-offs. Newly credited units participate in NAV immediately but remain in a 60-second cooling period before they can be withdrawn or redeemed.
Position units expose no ERC-20 metadata, transfer or approval surface. The interface renders them with 24-digit display precision while all transaction bounds and accounting retain the original integer amount.
- Deposit and exit calls include deadline plus slippage bounds.
- Native ETH helpers wrap or unwrap only at the transaction boundary.
maturePositionUnitsOfexcludes cooling units without requiring a separate activation transaction; later deposits do not relock units that already matured.maxWithdrawis zero while principal is outstanding and cannot exceed idle pool liquidity once the book is settled.- Virtual units/assets mitigate first-depositor and donation attacks.
- No administrative method may withdraw lender principal.
Risk model
Price-sensitive actions use a validated primary adapter. A market can optionally add a secondary source; when present, the protocol enforces its deviation limit and uses the lower price. Staleness is always enforced, and sequencer health is enforced when a sequencer adapter is configured.
Failure posture
Collateral admission
No discovered token is hardcoded or auto-enabled. Its canonical Robinhood Chain address, decimals, transfer behaviour, onchain price source and executable WETH depth must pass registry review and fork tests before activation by the owner.
Credit model
Scores start at 500 and remain between 300 and 850. Only qualifying principal can affect the score, and positive events are rate-limited.
Benefits remain bounded by the market’s absolute LTV and fee constraints. Reputation cannot bypass collateral or liquidity caps.
Contract system
LARK tokenExternal fixed-supply Noxa launch; no voting or staking capability is required.
WETHLendingVaultNon-transferable position units, idle liquidity and principal accounting.
LoanManagerPosition lifecycle, separated debt, fee realization and price/expiry liquidation.
FeeRouterImmutable 60/20/10/10 routing for every realized WETH fee.
LarkMerkleDistributorReviewable proof-bound holder epochs with no staking requirement.
InsuranceReserveAvailable-WETH coverage before lender principal write-off.
ReferralRegistryPermanent beneficiary-bound codes; 10% of realized referred fees route automatically in WETH.
LoanVaultMinimal isolated custody per position.
CollateralRegistryAssets, categories, tiers, caps and oracle configuration.
OracleRouterFreshness, deviation and conservative-price validation.
ExitOrderManagerConditional exit storage and permissionless execution.
CreditRegistryBounded score events and borrower tier.
Contract addresses, runtime hashes, ownership, economic wiring and external LARK provenance must match the pinned release identity before transaction surfaces can be enabled.
The production build fixes these addresses and manifest hashes into its public transaction allowlist. The browser rejects an API response whose chain, ABI, manifest or contract identities do not match that build.
REST API
The web application uses a read API and transaction-builder endpoints. Builders return unsigned calldata and simulation metadata; they never custody keys or cosign user actions.
GET /v1/health
GET /v1/protocol
GET /v1/markets
GET /v1/tokens
GET /v1/tiers
GET /v1/quotes/borrow
GET /v1/positions/:wallet
GET /v1/credit/:wallet
GET /v1/stats
GET /v1/activity
GET /v1/status
GET /v1/rewards/lark/claims/:wallet
GET /v1/rewards/lark/claims/:epochId/:wallet
POST /v1/transactions/borrow
POST /v1/transactions/register-referral
POST /v1/transactions/repay
POST /v1/transactions/partial-repay
POST /v1/transactions/top-up
POST /v1/transactions/extend
POST /v1/transactions/deposit
POST /v1/transactions/withdraw
POST /v1/transactions/exit-order
POST /v1/transactions/cancel-exit-order
POST /v1/transactions/update-exit-order
POST /v1/transactions/liquidate
POST /v1/transactions/take-over-expiredEvery builder response includes the expected chain ID, destination, calldata, value, quote expiry and simulation metadata. Builders mark simulation as required and not yet performed; the browser reproduces the expected calldata, rejects any mismatch, then runseth_call and gas estimation through the connected wallet before sending.
LARK token
Production LARK is an external fixed-supply Noxa launch with one billion tokens. It does not administer the lending core; bounded configuration belongs directly to the reviewed 2-of-3 owner Safe, and LARK carries no voting or staking requirement.
The immutable FeeRouter funds 60% of every realized WETH fee into the holder distributor. Finalized LARK balances are time-weighted into reviewable Merkle epochs; proofs bind each WETH claim to its exact account and cannot be redirected by a relayer.
View the token design