Encumbra
Menu

Quickstart

Open a lien, draw on it and repay it with the Encumbra client, in a few minutes.

Encumbra is launching on Base Sepolia. The contract address is not yet published, so you cannot connect to the official deployment today. This quickstart takes you from the repository to opening a lien and drawing on it with the real EncumbraClient.

The steps target Base Sepolia, Encumbra's launch testnet, once the address is published. The same calls work on a local chain today. Work through the steps in order; by the end you will have made the same calls your production integration would make.

  1. Get the SDKsrc/sdk.ts in the repo
  2. ConnectEncumbraClient(chain, address)
  3. Open and drawapprove, open, charge
  4. Repayrepay, getLien
The steps target Base Sepolia once the address is published. The same calls work on a local chain today.
  1. Get the SDK

    @encumbra/sdk is not published. The SDK lives in the Encumbra repository, in src/sdk.ts, with its chain transports in src/evm.ts and src/rpc.ts. You import it from there. Work inside the repository and install its dependencies, which include ethers. The client surface — every method and its parameters — is documented in the SDK reference.

    pnpm install
    pnpm demo:rpc
    Optional check: this script runs a lien through open, draws, repay and a liquidation on a local chain.
  2. Connect to a chain

    An EncumbraClient is built from a chain and a contract address: new EncumbraClient(chain, address). For a JSON-RPC network the chain is RpcChain.rpc(url, privateKeys). It signs with the keys you pass, so every address that sends a transaction needs its key in that list. Every state-changing method then takes the acting address as an argument.

    import { Wallet } from "ethers";
    import { RpcChain } from "./src/rpc.ts";
    import { EncumbraClient, Token } from "./src/sdk.ts";
    
    const ENCUMBRA_ADDRESS = process.env.ENCUMBRA_ADDRESS!; // from /docs/networks
    const USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"; // Circle testnet USDC
    
    // Owner and creditor send transactions, so their keys go to the chain.
    const chain = await RpcChain.rpc("https://sepolia.base.org", [
      process.env.OWNER_KEY!,
      process.env.CREDITOR_KEY!,
    ]);
    const [owner, creditor] = chain.accounts; // addresses, in key order
    const agentWallet = new Wallet(process.env.AGENT_KEY!); // the agent only signs
    
    const encumbra = new EncumbraClient(chain, ENCUMBRA_ADDRESS);
    const usdc = new Token(chain, USDC_ADDRESS);
    Base Sepolia, once the address is published on the Networks page. The sample files sit at the repository root.

    To run the same code on a local chain, create the chain with RpcChain.ganache() and deploy a registry and a token with EncumbraClient.deploy and Token.deploy. Mint test tokens with usdc.mint. src/rpc-demo.ts shows the full setup.

  3. Open a lien and draw on it

    The owner approves the settlement token to the Encumbra contract, then opens a lien: it escrows the collateral and grants the agent a bounded credit line against a creditor. open returns the new lien's id. Today the owner opens the lien alone and names the agent. The agent does not sign at open.

    const UNIT = 1_000_000n; // USDC, 6 decimals
    
    // The contract pulls the collateral with transferFrom, so approve it first.
    await usdc.approve(encumbra.address, 100n * UNIT, owner);
    
    const id = await encumbra.open(
      {
        agent: agentWallet.address,
        creditor,
        token: USDC_ADDRESS,     // settlement and collateral token
        collateral: 100n * UNIT,
        creditLimit: 60n * UNIT,
        dueDate: 0,              // open-ended
        liqThresholdBps: 9000,
      },
      owner,
    );
    Escrow $100 of USDC, grant a $60 line. USDC has 6 decimals.

    As the agent consumes a metered service, the creditor records usage against the line with charge, which needs only the creditor. With chargeWithAuth the agent also signs each draw as an EIP-712 payload and the creditor relays it. The contract adds its usage fee to the debt on every charge, and the debt must stay within the credit limit. The fee is capped at 10%, so the $50 below is at most $55 of debt against the $60 limit.

    // Creditor records $30 of usage directly against the line.
    await encumbra.charge(id, 30n * UNIT, creditor);
    
    // The agent signs the next draw off-chain and the creditor submits it.
    await encumbra.chargeWithAuth(id, 20n * UNIT, agentWallet, creditor);
    Two draws: one from the creditor alone, one carrying the agent's signature.

    The owner (or anyone funding settlement) pays the debt back down with repay. The payer must first approve the debt token to the contract. Once the debt is zero the owner calls close to take the collateral back. getLien reads the lien's live state at any point.

    const lien = await encumbra.getLien(id);
    if (lien.debt > 0n) {
      // lien.debt includes the usage fee.
      await usdc.approve(encumbra.address, lien.debt, owner);
      await encumbra.repay(id, lien.debt, owner);
    }
    await encumbra.close(id, owner);
    
    const settled = await encumbra.getLien(id);
    // settled.debt · settled.status · settled.creditLimit
    Settle outstanding debt, close the lien and read the final state.

    The calls from this step, and who sends each one:

    CallWho sends itWhat it does
    openOwnerEscrows collateral and grants the credit line. Returns the lien id.
    chargeCreditorRecords usage against the line.
    chargeWithAuthCreditorRecords usage using a signature the agent made off-chain.
    repayOwner, or anyone funding settlementPays the debt down. The payer must have approved the debt token to the contract.
    getLienAnyoneReads the lien's live state.
    closeOwnerReturns the escrowed collateral once the debt is zero.
  4. Where to go next

Testnet only. Encumbra is launching on Base Sepolia with no real funds, and the protocol is unaudited. Use testnet USDC only and treat nothing here as financial, legal, or investment advice.