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:
EncumbraClientis built around aChainLiketransport.- 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.
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.
| Role | Calls | Notes |
|---|---|---|
| Owner | open, openAsset, addCollateral, setLeaseSchedule, close, freeze, unfreeze | Only the owner can call close and setLeaseSchedule. addCollateral is listed because the owner is the usual caller, but any address can call it. |
| Creditor | charge, chargeWithAuth, freeze, unfreeze | Only the creditor can call charge and chargeWithAuth, and it chooses which one to use. |
| Agent | freeze | The agent's signer is passed to chargeWithAuth, and the creditor submits the transaction. The agent cannot unfreeze. |
| Keeper | liquidate, liquidateAsset | Any address can act as keeper. liquidateAsset needs the debt token approved for the appraised value first. |
| Anyone, to change state | repay, payInstallment, addCollateral | The caller approves the token it pays with first: the debt token for repay and payInstallment, the collateral token for addCollateral. |
| Anyone, to read | getLien, available, isServiceable, isAssetEnabled, healthFactor, isLiquidatable, collateralValue, nextId, chargeNonce, agentStats | Read-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). |
| Admin | setParams, setOracle | The 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
ChainLiketransport and the contractaddress; exposesaddressas a read-only field. - static deploy(chain, cfg, from): Promise<EncumbraClient>
- Deploy the Encumbra lien registry and return a client bound to it. The
cfgcarriestreasury,protocolFeeBps,keeperRewardBps, and an optionalusageFeeBps(defaults to 0);fromis 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);