Design Principles
Lorrow is built on five principles that every implementation must preserve. These are not preferences. They are the standard.
A Standard, Not a Product
Lorrow defines the common nouns, verbs, states, and disclosures of bilateral lending. It does not dictate every risk parameter. Other protocols implement around it and declare themselves Lorrow-compatible, the same way tokens declare themselves compatible with a token standard. This preserves flexibility while forcing transparency.
Bilateral Agreement
Every loan is a direct agreement between a specific lender and a specific borrower. There are no pools, no anonymous counterparties, and no protocol-set rates. One party posts terms. The other accepts. The deal is between them.
Immutable Terms
Once a loan agreement is created on-chain, no variable can be modified by either party or by the protocol. The terms agreed at origination are the terms enforced at maturity. There are no repricing events, no governance votes that affect live loans, and no admin keys that can alter an active agreement.
Standardized Variables
Every loan on every Lorrow implementation uses exactly the same set of variables. No custom fields. No implementation-specific terms that one party can use to obscure risk. A lender or borrower who understands the variable set can read any loan on any chain running Lorrow.
Transparent Commitment
Capital and collateral locking is visible and rated. A party who locks funds at posting signals stronger commitment than one who does not. The protocol surfaces this difference so counterparties can make informed decisions. Over time, a wallet builds a verifiable on-chain credit history.
Protocol Roles
Lender
A lender is any wallet that posts an offer to extend credit or accepts a borrower's posted request. The lender provides the loan asset and receives interest in return. The lender bears the risk of borrower default, mitigated by the collateral escrow.
Borrower
A borrower is any wallet that posts a request for credit or accepts a lender's posted offer. The borrower provides collateral, receives the loan asset, and is obligated to repay principal plus accrued interest according to the agreed repayment structure.
Protocol
The protocol is the smart contract. It holds escrowed collateral, disburses loan assets at origination, enforces repayment schedules, monitors collateral value against the breach threshold, and executes default transfers. The protocol has no discretion. It executes the terms as written.
Lorrow does not define who operates a frontend, who provides price oracle data, or who deploys the contract. Those are implementation decisions. The protocol defines only the mechanics that any compliant implementation must enforce.
Loan Variables CORE
The following variables define every Lorrow loan. All are required. None can be added, removed, or renamed by an implementation. A loan object that does not contain all of these fields exactly is not a valid Lorrow loan. Where a range is shown, it is the Core outer bound. Each implementation sets its own narrower range inside it and publishes it in its Profile.
| Variable | Set By | Core Bound | Description |
|---|---|---|---|
| loan_asset | Poster | Profile-defined | The asset the borrower receives. Each implementation defines its supported asset list in its Profile. |
| loan_amount | Poster | > 0 | The principal amount denominated in the loan asset. |
| collateral_asset | Poster | Profile-defined | The asset the borrower pledges. Must be distinct from the loan asset. |
| collateral_amount | Poster | > 0 | The amount of collateral escrowed. LTV is derived and displayed but not directly set. |
| breach_threshold | Poster | Min 110% | The collateral-to-outstanding-principal ratio below which a breach begins. Core sets a hard floor of 110%. Profile sets the range above it. |
| loan_term | Poster | Fixed set | 14d / 30d / 60d / 90d / 12m / 18m. An implementation may support a subset but may not invent new terms. |
| interest_rate | Poster | 0% to 36% | Fixed annual rate on outstanding principal. Core sets a hard ceiling of 36%. Profile sets the band within it. |
| repayment_structure | Poster | LUMP / INSTALLMENT / BALLOON | LUMP: principal plus interest at maturity. INSTALLMENT: equal payments over term. BALLOON: interest-only during term, principal at maturity. |
| early_repayment_allowed | Poster | true / false | Whether the borrower may repay before maturity. If false, the contract rejects early repayment. |
| early_repayment_penalty | Poster | 0% to 5% | Percentage of outstanding principal charged on early repayment. Core sets a hard ceiling of 5%. Only valid if early_repayment_allowed is true. |
| capital_locked | Poster | true / false | Whether the lender has escrowed the loan asset at posting. Affects Commitment Score. |
| collateral_locked | Poster | true / false | Whether the borrower has escrowed collateral at posting. Affects Commitment Score. |
LTV is a derived display value only. LTV = loan_amount divided by current collateral value. It is shown to both parties before acceptance but is not stored as a loan variable. The stored variables are loan_amount and collateral_amount.
Commitment Model
Every post on Lorrow is either locked or unlocked. This applies to both lenders and borrowers.
Locked Post
A lender who posts locked has escrowed the loan asset into the protocol contract at the time of posting. The funds are held and unavailable to the lender until a borrower accepts or the lender cancels. Cancellation returns funds immediately.
A borrower who posts locked has escrowed the collateral into the protocol contract at the time of posting. The collateral is held until a lender accepts or the borrower cancels.
Unlocked Post
An unlocked post is a statement of intent. The capital or collateral is not escrowed until the moment of acceptance. When a counterparty accepts an unlocked post, the contract attempts to pull the required funds from the poster's wallet. If the funds are not present or approval is not granted, the acceptance fails and the post is invalidated.
Unlocked posts are valid and useful, particularly for large positions where locking capital speculatively carries opportunity cost. The protocol does not discourage them. It simply surfaces the difference.
Effect on Commitment Score
Locked posts contribute positively to a wallet's Commitment Score. Unlocked posts that result in failed acceptance contribute negatively. See Section 8 for full scoring mechanics.
Loan Lifecycle
| State | Trigger | Outcome |
|---|---|---|
| POSTED | Lender or borrower submits terms to order book | Post visible on order book. Capital or collateral escrowed if locked post. |
| ACTIVE | Counterparty accepts posted terms | Contract created on-chain. Capital disbursed to borrower. Collateral held in escrow. Loan clock starts. Repayment schedule running. Collateral monitored against breach threshold. |
| BREACHED | Collateral value falls below breach_threshold | Breach clock starts, sized by loan term. Borrower can cure by paying down, or collateral can recover. Recovery above threshold resets the clock to zero. |
| DEFAULTED | Breach clock runs full window while continuously below threshold, or borrower fails to repay past maturity grace period | Collateral valued. Debt portion transferred to lender. Surplus returned to borrower. Loan closed. Recorded in both wallet histories. |
| COMPLETED | Borrower repays in full, at or before maturity | Principal plus accrued interest plus early penalty if applicable returned to lender. Collateral returned to borrower. Loan closed in good standing. Early closure noted by a flag on the record. |
| EXPIRED | Locked post cancelled, or unlocked post acceptance fails | Escrowed funds returned. Post removed from order book. |
Escrow Contract Spec
The following defines the required behavior of a compliant Lorrow escrow contract. Implementation language, chain, and framework are left to the builder.
Required Functions
postOffer(params)
Called by a lender. Accepts all loan variables. If capital_locked is true, pulls loan_amount of loan_asset from the caller's wallet into escrow. Emits OfferPosted event.
postRequest(params)
Called by a borrower. Accepts all loan variables. If collateral_locked is true, pulls collateral_amount of collateral_asset from the caller's wallet into escrow. Emits RequestPosted event.
acceptOffer(offerId)
Called by a borrower. Pulls collateral from borrower if not already locked. Pulls capital from lender if not already locked. Creates loan record. Disburses loan_amount to borrower. Starts loan clock. Emits LoanCreated event.
acceptRequest(requestId)
Called by a lender. Pulls capital from lender if not already locked. Pulls collateral from borrower if not already locked. Creates loan record. Disburses loan_amount to borrower. Starts loan clock. Emits LoanCreated event.
repay(loanId, amount)
Called by borrower. Accepts full or partial payment for any repayment structure. A partial payment reduces outstanding principal and, where the collateral ratio was in breach, can cure it. For INSTALLMENT loans, payments are validated against the stored schedule. If the payment closes the loan before maturity and early_repayment_allowed is false, the contract reverts. If early repayment is allowed, the contract adds accrued interest plus the early penalty if any. On full repayment the contract releases collateral to the borrower and moves the loan to COMPLETED.
reportBreach(loanId)
Called by a lender or an automated keeper. If the collateral ratio is below breach_threshold and the loan is not already BREACHED, moves the loan to BREACHED and starts the breach clock sized by loan term. Emits BreachTriggered.
checkRecovery(loanId)
Called by anyone, or run by a keeper. If a BREACHED loan's collateral ratio has returned above breach_threshold, resets the breach clock and returns the loan to ACTIVE. Emits BreachCleared.
executeDefault(loanId)
Called by a lender or keeper. Valid only if the breach clock has run its full window while the collateral stayed continuously below threshold, or if the loan is past its maturity grace period unpaid. The contract values the collateral, transfers the portion covering outstanding principal plus accrued interest to the lender, and returns any surplus collateral to the borrower. Moves the loan to DEFAULTED. Emits LoanDefaulted.
cancelPost(postId)
Called by poster. Only valid if post has not been accepted. Returns any escrowed funds to poster. Removes post from order book. Emits PostCancelled event.
Required Events
OfferPosted(offerId, lender, params, locked)
RequestPosted(requestId, borrower, params, locked)
LoanCreated(loanId, lender, borrower, params, timestamp)
RepaymentMade(loanId, amount, remainingPrincipal, timestamp)
BreachTriggered(loanId, collateralValue, threshold, windowSeconds, timestamp)
BreachCleared(loanId, collateralValue, timestamp)
LoanDefaulted(loanId, debtToLender, surplusToBorrower, timestamp)
LoanCompleted(loanId, totalInterestPaid, earlyClosure, timestamp)
PostCancelled(postId, fundsReturned, timestamp)Loan Record Structure
loanId: bytes32
lender: address
borrower: address
loan_asset: address
loan_amount: uint256
collateral_asset: address
collateral_amount: uint256
breach_threshold: uint16 // basis points, e.g. 12000 = 120%
loan_term: uint32 // seconds
interest_rate: uint16 // basis points annually
repayment_structure: uint8 // 0=LUMP 1=INSTALLMENT 2=BALLOON
early_repayment_allowed: bool
early_repayment_penalty: uint16 // basis points
capital_locked_at_post: bool
collateral_locked_at_post: bool
origination_timestamp: uint256
maturity_timestamp: uint256
outstanding_principal: uint256
state: uint8 // 0=POSTED 1=ACTIVE 2=BREACHED
// 3=DEFAULTED 4=COMPLETED 5=EXPIRED
breach_clock_start: uint256 // 0 if not breached
breach_window: uint32 // seconds, derived from loan_term
closed_early: bool // true if COMPLETED before maturityDefault & Breach Handling
The Breach Window
When the market value of escrowed collateral falls below the agreed breach_threshold percentage of outstanding principal, the loan moves to BREACHED and a single breach clock begins. The length of that clock is fixed by the protocol and sized to the loan term. Shorter loans resolve faster because there is little time for recovery anyway. Longer loans get more room because multi-day price dips over a year or more are expected noise.
| Loan Term | Breach Window |
|---|---|
| 14 days | 1 day |
| 30, 60, 90 days | 3 days |
| 12 months, 18 months | 6 days |
Cure and Recovery
During the breach window the loan can return to good standing two ways. The borrower can cure by paying down principal until the collateral ratio rises back above the breach_threshold. Or the collateral price can recover on its own back above the threshold. Either way, the moment the ratio is restored the breach clock resets to zero and the loan returns to ACTIVE.
This means the window measures continuous time below threshold, not cumulative time. A price wick that dips under the line and recovers does not consume the window. Only a sustained decline that stays below threshold for the full window length leads to default. This protects borrowers from flash crashes while still protecting lenders from real, sustained collateral erosion.
A cure payment is not early repayment. It does not trigger the early_repayment_penalty regardless of the loan terms. It is treated purely as a principal reduction.
Default and Surplus Return
If the breach clock runs its full window while the collateral stays continuously below threshold, default executes. The contract values the collateral, transfers the portion covering outstanding principal plus accrued interest to the lender, and returns any remaining collateral to the borrower.
The lender is made whole, not enriched. They recover what they are owed and no more. If the collateral at default is worth less than the debt, the lender absorbs the shortfall and the borrower owes nothing further. This downside is the lender's primary risk and should be priced into the breach_threshold and interest_rate they post.
Maturity Default
If the borrower has not repaid in full by the maturity timestamp, a 3-day maturity grace period begins. If the loan is still unpaid at the end of it, the lender or a keeper may call executeDefault. The same valuation and surplus-return mechanics apply: lender takes the debt portion of the collateral, borrower receives any surplus.
Implementations must define their oracle source. Lorrow does not mandate a specific oracle. Any implementation must use the same oracle source for breach detection, recovery detection, and LTV display so the three are always consistent.
Commitment Score
Every wallet that participates in Lorrow accumulates a Commitment Score. This score is on-chain, public, and derived entirely from verifiable loan history. It is not subjective and cannot be gamed through off-chain activity.
Score Components
Locked Post Ratio
The percentage of a wallet's total posts that were locked. Higher is better. A wallet that always posts locked has a ratio of 1.0.
Completion Rate
The percentage of accepted loans that reached COMPLETED state without default. Calculated separately for lender and borrower activity.
Breach Recovery Rate
Of the times a wallet's loans entered BREACHED, the share that returned to ACTIVE through cure or recovery rather than proceeding to default. Only applicable to borrower history. A high rate signals a borrower who actively manages collateral.
Failed Acceptance Rate
The percentage of unlocked posts that failed at acceptance due to insufficient funds. High failure rate signals unreliable posting behavior and reduces score significantly.
Loan Volume
Total lifetime loan volume in USD terms. Larger volume provides more signal. A wallet with 100 completed loans carries more weight than one with 2.
Score Display
Implementations should display Commitment Score visibly on every order book listing. The score is a signal to the counterparty, not a gate. There is no minimum score required to post or accept. The market decides how much weight to give it.
Lorrow defines the inputs to Commitment Score but does not mandate a specific formula or weighting. Implementations may weight components differently. The inputs themselves are standardized so scores remain meaningful across implementations that use the same formula.
Order Book Design
Lorrow uses a dual order book. Lender offers and borrower requests are posted and displayed separately. There is no algorithmic matching. A counterparty browses the relevant book and selects terms they accept.
Lender Order Book
Displays all open lender offers. Each entry shows all loan variables, the lender's Commitment Score, whether the post is locked, and the current LTV derived from live collateral pricing.
Borrower Order Book
Displays all open borrower requests. Each entry shows all loan variables, the borrower's Commitment Score, whether the post is locked, and the current LTV.
No Counter-Offer Mechanic
Lorrow does not support counter-offers or negotiation. A counterparty either accepts the posted terms exactly or does not. This is intentional. Counter-offer mechanics introduce complexity, delay, and the possibility of terms drift that undermines the immutability principle.
Filtering
Implementations should provide filtering by loan asset, collateral asset, loan term, interest rate range, breach threshold, repayment structure, locked status, and Commitment Score minimum. Filtering is a UI concern and not defined by the protocol.
Core Guardrails
These are the non-negotiable protections that make a protocol Lorrow-compatible. They are fixed in Core. No implementation may relax, override, or remove them. They exist for one reason: no Lorrow-compatible protocol should ever be able to be predatory. An implementation may always be more generous to the borrower than these bounds require. It may never be harsher.
| Guardrail | Core Rule | Why It Protects Users |
|---|---|---|
| Surplus Return | Mandatory | At default the lender takes only the debt owed. All surplus collateral returns to the borrower. Seizing surplus is the single most predatory move in collateralized lending, so it is forbidden at the Core level. |
| Interest Rate Ceiling | 36% hard | No loan on any compatible protocol may charge more. Aligned with recognized usury and hard money limits. |
| Early Penalty Ceiling | 5% hard | Above this a penalty traps borrowers rather than compensating lenders. |
| Breach Threshold Floor | 110% hard | Below this a borrower could be defaulted while still roughly solvent. The floor guarantees a real buffer. |
| Breach Window Floors | 1d / 3d / 6d | A compatible protocol may give borrowers more time to cure or recover, but never less than these per-term minimums. Prevents unfair flash defaults. |
| Maturity Grace Floor | 3 days min | No protocol may default a borrower the instant a loan matures. Profiles may offer more. |
| Recovery Resets Clock | Mandatory | Any return above threshold during a breach window resets the clock. Protects borrowers from wicks and flash crashes. |
| Immutable Terms | Mandatory | No party and no admin may alter an active loan's terms. What was agreed is what is enforced. |
Everything not listed here is a Profile parameter. An implementation sets it, within these bounds, and publishes it. The guardrails are the floor of user protection. The Profile is where each protocol expresses its own risk appetite above that floor.
The Implementation Profile
Every Lorrow-compatible protocol must publish an Implementation Profile. The Profile is how a protocol declares the choices Core leaves open. It must be public, machine-readable, and linked from the protocol's interface so any user can read it before they post or accept a loan. A protocol that does not publish a complete Profile is not Lorrow-compatible, regardless of how its contract behaves.
| Profile Field | What It Declares |
|---|---|
| Protocol Name | The implementation's name and version. |
| Chain / VM | The chain or virtual machine the contract runs on. |
| Supported Loan Assets | The exact list of assets that may be borrowed. |
| Supported Collateral Assets | The exact list of assets that may be pledged. |
| Collateral Ratio Range | The implementation's breach_threshold range, at or above the 110% Core floor. |
| Interest Rate Range | The implementation's allowed rate band, at or below the 36% Core ceiling. |
| Oracle Provider | The price oracle used for collateral valuation, breach detection, and LTV display. |
| Oracle Fallback Policy | The secondary source or procedure if the primary oracle is unavailable. |
| Oracle Failure Behavior | What the protocol does when no reliable price is available. The Core-recommended default is to pause breach detection without freezing active loans. |
| Default Settlement Method | How collateral is valued and transferred at default, and how surplus is returned. |
| Liquidation Method, if any | Whether any mechanism beyond the standard breach-and-default flow exists, and how it works. |
| Maturity Grace Period | The grace period offered, at or above the 3-day Core floor. |
| Breach Window Policy | The breach windows per term, at or above the Core floors. |
| Commitment Score Formula | How the standardized Score inputs are weighted into a final score. |
| Fee Model | Whether a protocol fee is charged, its size in basis points, and its recipient. |
| Upgradeability / Admin | What admin controls or upgrade mechanisms exist, and their limits. Active loans must remain immutable regardless. |
| Compliance / KYC Posture | Any identity, KYC, or AML requirements imposed on participants. |
| Keeper Model | Who runs breach detection and default execution, and whether it is open or permissioned. |
| Frontend / Operator | Who operates the interface and any operator disclosures. |
Lorrow Compatibility
A protocol is Lorrow-compatible when it satisfies two conditions, both required.
It Preserves Core
The contract uses the standardized loan variables without addition, removal, or renaming. It implements the six lifecycle states and the required functions and events. It enforces the escrow model. And it honors every Core Guardrail, including surplus return and the anti-predation bounds. A user who understands Lorrow can read any loan on the protocol in the common format.
It Publishes a Complete Profile
The protocol publishes a public, complete Implementation Profile covering every field in Section 11. Nothing material is left undisclosed. A user can see, before acting, exactly how this implementation handles the choices Core leaves open.
What the Claim Means
"Lorrow-compatible" is a promise to the user: the loan terms, lifecycle, escrow model, breach and default process, and commitment signals are legible in a common format, and the protocol's specific risk rules are fully disclosed. It does not mean two compatible protocols share the same risk parameters. It means a user can read and compare them on equal footing, and that neither can be predatory within the meaning of the Core Guardrails.
Compatibility is self-declared and verifiable. Because Core behavior is on-chain and the Profile is public, anyone can check a protocol's claim against its contract and its disclosures. Lorrow defines no central authority that grants or revokes the label.
Implementation Notes
Chain Agnosticism
Lorrow is designed to be implemented on any chain that supports smart contracts and escrow mechanics. EVM chains, Solana, Cosmos app chains, and others are all valid targets. The protocol does not reference chain-specific primitives in its specification.
Asset Support
Each implementation defines its own supported asset list for both loan assets and collateral assets. The protocol recommends starting with stablecoins as loan assets to eliminate loan asset price risk for the lender. Collateral assets should be liquid, widely held, and have reliable oracle pricing available.
Oracle Requirements
Breach detection requires reliable price data for collateral assets. Implementations must specify their oracle source and use it consistently for both breach monitoring and LTV display. A recommended safe default is to pause breach detection but not freeze active loans if oracle data becomes unavailable.
Interest Calculation
Interest accrues on outstanding principal from the origination timestamp. For INSTALLMENT repayment structure, each installment amount is calculated at origination based on the fixed rate and term and stored in the loan record. Implementations must not recalculate installment amounts after origination.
For early repayment, accrued interest is calculated as: annual_rate divided by 365, multiplied by days elapsed, multiplied by outstanding principal at the time of repayment.
Keeper Bots
The breach detection and default execution functions can be called by any wallet. Implementations may choose to run keeper bots that monitor active loans and call these functions automatically. The contract must not depend on a specific keeper for correct behavior.
Frontend Independence
The protocol does not define a frontend. Any interface that correctly reads from and writes to a compliant Lorrow contract is a valid Lorrow frontend. Multiple competing frontends can serve the same contract.
Optional Fee Hook
Lorrow does not require a protocol fee. Implementations that want one should expose a single fee hook applied at origination as a basis-point cut of the loan amount, with a recipient address set at deployment. The fee must be visible to both parties before acceptance and must not exceed 100 basis points so it never materially distorts the agreed terms. Implementations with no fee set the hook to zero.
What Lorrow Does Not Define
Lorrow draws a deliberate line. Some things it leaves to each implementation but requires to be disclosed in the Profile. Other things it places entirely outside its scope. Both are intentional. Neither is an omission.
Left to the Profile, but Must Be Disclosed
The chain or VM, the supported assets, the oracle provider and its fallback and failure behavior, the specific risk ranges within Core's bounds, the Commitment Score weighting, the fee model, the admin and upgrade controls, the KYC posture, and the keeper model. Each implementation chooses these and publishes them in its Implementation Profile. Core does not dictate the answers. It only requires that they be declared.
Outside Lorrow's Scope Entirely
- Legal enforceability or jurisdictional compliance of any loan
- Insurance or external loss protection mechanisms
- Multi-collateral or cross-margin loan structures
- Undercollateralized or pure reputation-based lending
- Secondary markets for transferring or trading active loans
- Any central authority that grants or revokes the compatibility label
The discipline of the standard is in the line itself. Core protects users and keeps loans legible. The Profile forces transparency on everything else. What falls outside both is left to builders, markets, and jurisdictions to settle on their own.