Encumbra
Menu

Run a keeper

Testnet

A keeperKeeper. Anyone who liquidates a lien that is past due or under water. The keeper is paid first from the proceeds, so enforcement does not depend on a single operator. is any address that calls liquidate on a lien that has defaulted. The contract pays the keeper's reward first, ahead of the creditor, the protocol and the owner, and the call is permissionlessPermissionless. No account, approval or allowlist is needed. Any address can call it..

Proof of concept, unaudited, Base Sepolia, no real funds.

What you need

  • An address with gas on the network.
  • A way to read the book: the SDK on a JSON-RPC endpoint, or the dashboard and the explorer by hand.
  • For a lien backed by a title token: the debt token, approved to the contract, for the declared appraised value of the asset.

What you can do today

  • Call isLiquidatable, liquidate and liquidateAsset through the SDK against a test chain.
  • Run the reference keeper, which scans every lien id and liquidates each one that is liquidatable.
  • Watch liens and their cover on the dashboard and in the explorer.

What the contract does

A lien can be liquidated when it is past duePast due. The settlement deadline has passed with debt still open. Anyone can liquidate a past-due lien. or when its debt reaches the liquidation lineLiquidation line. The point where a lien can be liquidated: when debt reaches the lien's threshold share of collateral value (90% by default), or when a payment is overdue.. isLiquidatable(id) returns true in either case, and then any address can call liquidate(id). The call seizes collateral and pays the waterfallWaterfall. The fixed order that liquidation proceeds are paid in: keeper reward, then the creditor, then the protocol penalty, then whatever is left to the owner. in order: keeper, creditor, protocol, owner.

The keeper's share is debt * keeperRewardBps / 10_000. The deploy script defaults to 100 bps, 1%, and the examples below use it. The contract caps every fee at MAX_FEE_BPS, 10%, but the admin can change the rate inside that cap with no delay. The reward is paid in the collateral token and can never exceed the value seized.

Worked example

  • Keeper
  • Creditor
  • Protocol
  • Back to owner
Collateral worth $1,500Plenty of cover. Everyone is paid in full.
  • Keeper $10
  • Creditor $1,000
  • Protocol $20
  • Back to owner $470
Collateral worth $1,015Tight. The protocol takes $5 of its $20 claim.
  • Keeper $10
  • Creditor $1,000
  • Protocol $5
  • Back to owner $0
Collateral worth $900Under water. The keeper is still paid first.
  • Keeper $10
  • Creditor $890
  • Protocol $0
  • Back to owner $0
The creditor is short $110, booked as bad debt
The keeper's slice is the same in all three. What changes is who is paid after it. Arithmetic of the contract, not a forecast.

What the keeper carries:

  • Gas on every call, including a call that reverts because another keeper liquidated the lien first.
  • Price risk. With liquidate the reward arrives in the collateral token and stays in it until the keeper sells it.
  • A reward rate that can change. The admin can move it inside the 10% cap, and a lower rate applies to liens already open.
  • Timing. A healthy book has nothing to liquidate, so there can be long periods with no reward at all.

Title-backed leases: the keeper buys the title

A lease backed by a title tokenTitle token. A token that stands for one physical asset, such as a machine or a vehicle. The contract holds it as collateral. Legal title and physical recovery still follow local law. cannot use liquidate. The keeper calls liquidateAsset(id) instead and pays the asset's declared appraised valueAppraised value. The value the owner declared for a title token when opening the lien. The contract checks only that it is above zero and does not verify it, so an independent appraisal matters. in the debt token. The waterfall is paid out of that payment and the title token transfers to the keeper. Example: a $5,000 appraisal, $4,000 of debt, past due.

Keeper pays in
$5,000
The declared appraised value, in the debt token.
Paid back to the keeper
$40
1% of the $4,000 debt, paid first.
Creditor
$4,000
Protocol
$80
2% of the debt.
Back to the lessee
$880
What is left of the payment: the lessee's equity.
Keeper's net outlay
$4,960
$5,000 paid in, $40 paid back. The keeper now holds the title token.

The keeper gains only if it can realise more than $4,960 for the asset. The appraised value is declared when the lease opens, not found by a market, so the keeper carries the whole price risk. The title token moves on-chain; physical recovery and legal title still follow local law.

Honest limits

  • The reference bot and the dashboard keeper call liquidate, which reverts for a title-backed lien. The dashboard keeper skips a lien it cannot liquidate and carries on. The reference bot stops at the first revert, so one overdue title lease halts its whole run.
  • The reference bot scans every id from 1 to nextId() on each run. That is enough for a demonstration. It has no gas strategy, no retry and no price check.
  • Rewards are proportional only. A small lien can pay less than the gas to liquidate it. A flat keeper tip is proposed, not built.
  • Nothing is bonded. Keeper bonds are planned for a later contract version; see staking and bonds.
  • The official Base Sepolia address is published on the networks page once the deployment is live. Until then there is nothing public to point a keeper at, and the steps below run against a local test chain.

Run the reference keeper on a test chain

  1. Watch it run once

    With the repository checked out and its dependencies installed, as the quickstart describes, pnpm demo:ops runs the reference keeper against an in-process chain: a lien goes past due and the keeper clears it. Read src/keeper.ts next to it. The bot is short.

  2. Choose a chain and fund an address

    RpcChain.ganache() starts a local JSON-RPC node with funded accounts and needs no network. For any other chain, RpcChain.rpc(url, [privateKey]) takes a JSON-RPC URL and the keeper's key, and that address needs gas. Keep the key out of source control and use a throwaway key on a test chain.

  3. Connect the client

    new EncumbraClient(chain, address) wraps a deployed registry, as the SDK reference describes. The reference bot, runKeeper(encumbra, keeperAddress, log), takes that client and the keeper address.

  4. Scan and liquidate

    The reference bot walks every id from 1 to nextId() and calls liquidate on each lien that isLiquidatable reports. The loop below is the same walk with a branch for title-backed liens and a skip for a call that reverts.

    import { EncumbraClient, Token } from "../src/sdk.ts";
    import { RpcChain } from "../src/rpc.ts";
    
    const chain = await RpcChain.ganache(); // or RpcChain.rpc(url, [privateKey])
    const keeper = chain.accounts[0]; // the address that pays gas and receives the reward
    const encumbra = new EncumbraClient(chain, "0x...your registry address...");
    
    const n = Number(await encumbra.nextId());
    for (let i = 1; i < n; i++) {
      const id = BigInt(i);
      if (!(await encumbra.isLiquidatable(id))) continue;
      const lien = await encumbra.getLien(id);
      try {
        if (lien.collateralIsNft) {
          // Title-backed: the keeper pays the declared appraised value and takes the title.
          const debtToken = new Token(chain, lien.debtToken);
          await debtToken.approve(encumbra.address, lien.assetValue, keeper);
          await encumbra.liquidateAsset(id, keeper);
        } else {
          const r = await encumbra.liquidate(id, keeper);
          console.log("lien", id, "keeper reward", r.keeperReward);
        }
      } catch {
        // Another keeper got there first, or the call reverted. Carry on with the next lien.
      }
    }
    await chain.disconnect();
    Method names are from the SDK reference. Run it only against a test chain.
  5. Read the result

    liquidate and liquidateAsset return a LiquidationResult: seized, toCreditor, keeperReward, protocolFee, surplusToOwner and residualBadDebt.

What is still open

Keeping works on a test deployment today. These gates stand between it and real value, and none of them is met.

  • Not met: Official Base Sepolia address published on the networks page
  • Not met: Independent audit of the contract
  • Not met: A flat keeper tip so small liens can cover their own gas (proposed, not built)
  • Not met: An auction for title-backed liens in place of the fixed appraised-value purchase (proposed, not built)

Read next