Skip to content
SDK Documentation

Redeem, convert, and act for the Beneficiary

Outcome: you know how each settling call behaves before you build it: what redemption, cancellation, and conversion deliver, who can submit each one, and what a signed authorization lets another account do.

You need: a configured SDK, and the live position of the LOC you’re acting on. Create and redeem a LOC walks through a direct redemption by the Beneficiary; this page covers the rest. Beneficiary actions and settlement explains the protocol side.

Redeem

The Beneficiary can redeem some or all of the credited value before expiration, and another account can redeem with the Beneficiary’s signed authorization.

A partial redemption reduces the remaining credited value and the matching collateral, and the LOC stays open. A full redemption settles the remaining credited value, and the contract removes the LOC. If an insolvent Dynamic LOC’s collateral converts for less than its face value, the amount delivered is lower.

Redeeming a Dynamic LOC converts its collateral into the credited token as part of the redemption, through a liquidation. An external liquidator contract can exchange the collateral for the credited token, or the redeemer can act as the liquidator: a deliberate trade in which they supply the credited amount and take the collateral, plus the liquidator incentive. When a redeemer who liquidates for themselves is also the redemption’s destination, the protocol nets the two credited-token transfers, so the redeemer receives the collateral without fronting credited tokens that would come straight back.

A Beneficiary-authorized redeemLOC can liquidate collateral the same way. A healthy redemption pays the redemption buffer, and an unhealthy or insolvent one pays the liquidator incentive.

Cancel

Before expiration, cancellation needs the Beneficiary or the Beneficiary’s signed authorization. After expiration, anyone can cancel. Cancellation removes the LOC and releases the unused reserved collateral, or any already converted assets, back to the Creator.

Collateral stays reserved after expiration until someone submits the cancellation transaction. Redemption, conversion, extension, and collateral changes all stop at expiration.

Convert

Conversion exchanges a Dynamic LOC’s collateral for the credited token, using the current oracle price and the pair’s current liquidator incentive (Collateral and risk explains why the current settings apply).

convertLOC converts the whole LOC, and only once it’s unhealthy. Anyone can call it for an unexpired, unhealthy Dynamic LOC, and it always converts in full; a partial liquidation happens only through a partial redemption. Standalone conversion of a healthy LOC reverts for every caller, including the Creator. The Creator-authorization argument stays in the contract ABI so existing liquidation infrastructure keeps working, and V3 ignores it.

The caller picks one of two ways to settle:

  • Name an ILiquidator contract and pass its opaque parameters. The LetterOfCredit contract sends it the collateral and requires the exact credited-token amount back.
  • Pass the zero address and liquidate directly. The caller supplies the credited tokens and receives the collateral plus the liquidator incentive, so they must hold and approve the credited amount first.

The SDK accepts either choice, and your app picks and deploys the liquidator.

const params: ConvertLOCParams = {
  id: 42n,
  // Any ILiquidator is valid; the SDK does not choose one for you.
  liquidator,
  liquidatorParams,
  // Omitted: fetch a fresh Pyth update when the transaction is built.
};


const issues = await sdk.loc.validateConvert(params);
if (issues.length > 0) throw new Error(JSON.stringify(issues));


// Healthy LOCs still revert for every caller. Conversion is
// permissionless
// only after the current pair's liquidation threshold is reached.
const workflow = await sdk.loc.buildConvertWorkflow(params);
await workflow.execute();

A full conversion swaps the LOC’s reserved collateral for credited tokens held for a later redemption. The Beneficiary still redeems afterward, and the LOC stays open until they do. If the LOC is insolvent when it converts, the proceeds fall short of the face value and the contract lowers the stored credited amount to the actual proceeds: from then on, the Beneficiary’s claim is the converted amount.

Calls anyone can make

Two calls are open to any account by design:

  • Canceling an expired LOC. Collateral stays reserved after expiration until someone submits the cancellation, and any account can.
  • Calling convertLOC on an unhealthy LOC. Once a Dynamic LOC reaches its pair’s current liquidation collateral factor, any account can submit the conversion. The Creator-authorization ABI argument is ignored.

Act with the Beneficiary’s signed authorization

An authorization is an EIP-712 typed signature from the Beneficiary. Using one consumes a per-signer nonce, so each authorization works once. The two types bind different terms:

  • A redeem authorization binds the LOC id, the amount to redeem, the LOC’s current credited amount, and the destination address. Binding the current credited amount voids the authorization if the LOC changes between signing and submission, and binding the destination keeps the redeemed funds going where the Beneficiary said.
  • A cancel authorization binds the LOC id.

Signature checks accept ERC-1271 contract signatures as well as EOA signatures, so a contract account such as a Safe multisig can be a Creator or a Beneficiary and can sign authorizations.

Act with a Collateral Vault authorization

The Collateral Vault has its own signed authorizations, separate from the LOC ones above. The account holder whose collateral is involved signs them, and they can name any contract that Anvil Governance has approved as a collateralizable, LetterOfCredit being one.

  • A deposit approval (CollateralizableDepositApproval) binds the collateralizable contract, the token, the exact amount, and the signer’s next deposit-approval nonce. The account holder signs it, and the named collateralizable contract submits it by calling the vault’s depositFromAccount. The vault includes its caller in the digest, so the same bytes work for that contract alone. The vault checks the signature, pulls exactly that amount of the token from the signer’s wallet into the signer’s vault balance, and raises the collateralizable’s allowance to cover it. The signer still needs an ERC-20 approval to the vault for the transfer.
  • An allowance adjustment binds the collateralizable contract, the token, and a signed amount. It changes how much of the signer’s vault balance that contract can reserve, and moves no tokens.

Both are signed against the vault’s own EIP-712 domain, so a signature is valid only for the vault address and chain it was made for. Neither has a deadline: a vault authorization stays usable until the vault consumes its nonce or the signer invalidates it with sdk.vault.buildInvalidateNoncesWorkflow. Build and sign a deposit approval with sdk.vault.buildDepositAuthorizationWorkflow; before the wallet prompt, the definition it returns shows the chain, vault, signer, nonce, and typed data being signed.

What the SDK handles, and what your app handles

  • The SDK builds and checks each call. It validates redemption, cancellation, and conversion parameters against live protocol state, fetches a fresh Pyth price update when a conversion needs one and you haven’t supplied it, and shows a deposit approval’s typed data before the wallet signs it.
  • Your app owns the counterparties. It decides who submits each call, collects and stores the Beneficiary’s or account holder’s signatures, and picks the liquidator for a conversion.

2026 © Anvil

Designed by Acronym