Encumbra
Menu

SDK reference

EncumbraClient is the TypeScript surface a developer touches: a handful of verbs over a lien.

The SDK hides the EVM plumbing behind plain verbs: open a lien, charge usage, repay, liquidate, close, and read a lien's live state.

The SDK is transport-agnostic:

  • EncumbraClient is built around a ChainLike transport.
  • Both the in-process EVM chain and a real JSON-RPC chain (ethers) implement that interface.
  • The same client and agent code runs locally or against a testnet or mainnet unchanged. Only the transport underneath changes.

A ChainLike exposes five calls the SDK builds on:

deploy
Deploy a contract and return its address.
send
A state-changing transaction.
call
A read-only view.
now
Chain time in unix seconds.
warp
Advance the clock, used to drive past-due liquidation in tests.

The PoC ships a deterministic set of accounts in ACCOUNTS (deployer, owner, agent, provider, keeper, treasury) for wiring up demos.

Proof of concept. This client talks to unaudited contracts on a local development chain with no real funds. The helper classes (Token, Nft, MockOracle) are stand-ins for a real stablecoin, asset title, and price feed.

Which role calls what

The role is whoever you pass as the acting address. The contract checks the caller, so a role-restricted method called from the wrong address reverts.

RoleCallsNotes
Owneropen, openAsset, addCollateral, setLeaseSchedule, close, freeze, unfreezeOnly the owner can call close and setLeaseSchedule. addCollateral is listed because the owner is the usual caller, but any address can call it.
Creditorcharge, chargeWithAuth, freeze, unfreezeOnly the creditor can call charge and chargeWithAuth, and it chooses which one to use.
AgentfreezeThe agent's signer is passed to chargeWithAuth, and the creditor submits the transaction. The agent cannot unfreeze.
Keeperliquidate, liquidateAssetAny address can act as keeper. liquidateAsset needs the debt token approved for the appraised value first.
Anyone, to change staterepay, payInstallment, addCollateralThe caller approves the token it pays with first: the debt token for repay and payInstallment, the collateral token for addCollateral.
Anyone, to readgetLien, available, isServiceable, isAssetEnabled, healthFactor, isLiquidatable, collateralValue, nextId, chargeNonce, agentStatsRead-only. These change no state and need no role. The SDK has no wrappers for the contract's other getters (see the first point above).
AdminsetParams, setOracleThe address that deploys the registry is the admin. setOracle controls the price the underwater check uses, and it emits no event. transferAdmin has no SDK wrapper.

Construction and deploy

An EncumbraClient wraps a deployed lien registry at a known address. You either deploy a fresh registry with the static EncumbraClient.deploy or construct a client around an existing one.

new EncumbraClient(chain, address)
Wrap an already-deployed registry. Takes a ChainLike transport and the contract address; exposes address as a read-only field.
static deploy(chain, cfg, from): Promise<EncumbraClient>
Deploy the Encumbra lien registry and return a client bound to it. The cfg carries treasury, protocolFeeBps, keeperRewardBps, and an optional usageFeeBps (defaults to 0); from is the deployer address.
import { Chain, ACCOUNTS } from "../src/evm.ts";
import { EncumbraClient, Token } from "../src/sdk.ts";

const chain = await Chain.create();
const { deployer, treasury, owner } = ACCOUNTS;

const encumbra = await EncumbraClient.deploy(
  chain,
  { treasury, protocolFeeBps: 100, keeperRewardBps: 50 },
  deployer,
);

const usd = await Token.deploy(chain, "USD Coin", "USDC", 6, deployer);
await usd.mint(owner, 1_000_000n, deployer);
Deploy a registry and a stand-in stablecoin on the in-process chain

In this section