Encumbra
Menu

Contract reference

EncumbraLien.sol is the single, non-upgradeable contract every lien is booked against. It holds collateral in escrow and moves it only by its own rules.

Overview

EncumbraLien is a single Solidity contract that escrows an owner's collateral and moves it only along the rules below. It has no proxy, no upgrade path and no pause function.

What the admin can and cannot do

The admin is a single address, set at deployment, that can hand the role to another address in one step with transferAdmin. Three calls are admin only.

  • setParams sets the protocol fee, the keeper reward and the usage fee, and the treasury address. Each fee is bounded by MAX_FEE_BPS, a hard cap of 1000 bps (10%), enforced in the constructor and again in setParams. The treasury address is not bounded, and a new rate applies to open liens immediately. It emits ParamsUpdated.
  • setOracle replaces the price source for liens whose collateral and debt are different tokens. It cannot be set to the zero address. It emits no event.
  • transferAdmin hands the role to a new non-zero address in one step. It emits no event.

No admin function withdraws escrowed collateral, closes a lien, or changes a lien's debt or credit limit. The oracle is still an indirect path to user funds. For a cross-token lien, a replaced oracle can make the collateral look under water, so anyone can liquidate it, and the payout is computed at the replaced price.

Not built yet. There is no timelock today, so every admin change takes effect at once. Per-lien oracle binding, a timelocked multisig admin, a two-step admin transfer and an intake pause are planned for v1. They are scope, not code. See Security and Risks.

A lien binds three roles around escrowed collateral. The owner is the sponsor who posts collateral and sets the credit limit. The agent is the delegated spender identity. The creditor extends credit, reports usage, and on default is paid from the collateral after the keeper reward.

Sponsor

Owner

Posts the collateral and sets the credit limit, which is the owner's consent.

Alone can call close and setLeaseSchedule. Can also freeze and unfreeze.

Spender

Agent

The delegated spender identity.

Signs the EIP-712 authorization that chargeWithAuth checks. Can freeze the line, but cannot unfreeze it.

Provider

Creditor

Extends credit and reports usage. On default it is paid from the collateral after the keeper reward.

Alone can call charge and chargeWithAuth, and chooses which to use. Can also freeze and unfreeze.

The line functions only while both sides are satisfied. On default, anyone can liquidate the collateral with no court in the loop, up to the value of that collateral. The payout order is designed to be keeper reward, creditor, protocol, then owner surplus. The contract flags that keeper-first order as a policy choice that may be revisited.

Proof of concept. The contract assumes collateral and debt tokens share the same decimals; a production deployment should normalize decimals in the oracle.

How a lien moves between statuses

A lien has one status and it only moves forward. Each node names the call that puts the lien in that status.

A lien that is settled
  1. NoneAn id that was never opened reads as None
  2. Activeopen or openAsset. Anyone can call; the caller becomes the owner
  3. Closedclose. Owner only, and only once debt is zero
A lien that defaults
  1. NoneAn id that was never opened reads as None
  2. Activeopen or openAsset. Anyone can call; the caller becomes the owner
  3. Liquidatedliquidate or liquidateAsset. Anyone can call, while the lien is liquidatable
Liquidated and Closed are final: every other lien verb requires status Active.

The Lien struct

Every credit line is one Lien record in storage, keyed by an incrementing id that starts at 1. Its fields are grouped below.

Parties

owner
The sponsor who posted collateral and may reclaim surplus, freeze, or close.
agent
The delegated spender identity whose EIP-712 signature chargeWithAuth checks.
creditor
The party that charges usage. On default it is paid after the keeper reward and before the protocol.

Collateral

collateralToken
The escrowed asset (an ERC-20, or an ERC-721 title when collateralIsNft).
collateral
The escrowed owner funds, locked while the lien is active.
collateralIsNft
True when the collateral is a whole-asset ERC-721 title rather than an ERC-20.
collateralTokenId
The escrowed title's tokenId, used when collateralIsNft.
assetValue
The non-fungible token's appraised value in debt-token units, used when collateralIsNft.
assetClass
A bytes32 tag for the book, such as agent-credit, equipment, or land.

Money

debtToken
The settlement denomination the receivable is owed in.
debt
Total outstanding: the creditor receivable plus accrued protocol fees.
protocolAccrued
The portion of debt owed to the protocol from usage fees.
creditLimit
The maximum debt the owner pre-authorized; their consent, in token units.

Terms and schedule

dueDate
A uint64 settlement deadline; 0 is open-ended, and past due makes the lien liquidatable while it has debt.
liqThresholdBps
Liquidation trips when debt * 1e4 >= collateralValue * liqThresholdBps, where collateralValue is the oracle-priced collateral, or assetValue for a title.
installmentAmount
The amount due each period; 0 means lump or open-ended.
installmentPeriod
The seconds between installments for a lease schedule.

State

status
The lifecycle enum: None, Active, Liquidated, or Closed.
frozen
The kill-switch; while true it blocks new charges.
everPastDue
Set when repay, payInstallment, or close finds the lien past due, and never cleared. A lien closed with this flag counts as cured late, not as a clean settlement.

In this section

The rest of the contract reference is split across the pages below.