Skip to content

LOC lifecycle

Create, read, extend, redeem, convert, and cancel Letters of Credit.

A Letter of Credit is created by one account, the Creator, for another, the Beneficiary. There is no stored status: what a LOC can do next follows from its remaining amounts and its expiration, and deriveLetterOfCreditStatus turns those into one value you can show. Each change is a workflow, built from a params object and validated before a wallet is involved, then executed as however many transactions the change takes. An approve, a deposit, and a create arrive as one object.

Every operation is a method on sdk.loc, documented on LOCModule:

ChangeWhoWorkflow
Create a Static LOCAny accountbuildCreateStaticWorkflow
Create a Dynamic LOCAny accountbuildCreateDynamicWorkflow
ExtendThe CreatorbuildExtendWorkflow
Adjust collateralThe Creator, for a Dynamic LOCbuildModifyCollateralWorkflow
RedeemThe Beneficiary, or an account it authorizedbuildRedeemWorkflow
Convert collateralAny account, once a Dynamic LOC is unhealthybuildConvertWorkflow
CancelBefore expiration, the same as redeem; after it, any accountbuildCancelWorkflow

Extending and adjusting apply while the LOC is live. Redemption can be partial and repeated, and redeeming in full or canceling removes the LOC. Converting leaves it open, now backed by the credited token.

To readStart from
The full record: origin, lifecycle, and resolutionsdk.loc.getLetterOfCredit, sdk.loc.getLetterOfCredits
The live position, straight from the contractsdk.loc.getOutstandingLetterOfCredit, sdk.loc.getOutstandingLetterOfCredits
Transaction historysdk.loc.getLetterOfCreditHistory

The full record comes back as a LetterOfCredit and the live position as an OutstandingLetterOfCredit.

What conversion, redemption, and expiration do is in Redeem, convert, and act for the Beneficiary; collateral factors are in Collateral and risk.

Creating a Static LOC, end to end:

const params: CreateStaticLOCParams = {
beneficiary: '0x1111111111111111111111111111111111111111',
// 1,000 USDC (6 decimals): face value and, for a static LOC,
// collateral.
tokenAmount: {
tokenAddress: testnetProfile.contracts.USDC.address,
amount: 1_000_000_000n,
},
expirationTimestampSeconds: dateToEthereumTimestamp(
await sdk.loc.getMaxDate()
),
};
// Validate before touching the wallet; an empty array means valid
// params.
const issues = await sdk.loc.validateCreateStatic(params);
if (issues.length > 0) throw new Error(JSON.stringify(issues));
// Deposit, approve, and allowance steps appear only if the vault is
// short.
const workflow = await sdk.loc.buildCreateStaticWorkflow(params);
await workflow.execute(operations => {
console.log(operations.map(operation => operation.status));
});

Primary APIs

Operations

  • LOCModule — Letter of Credit operations: create, manage, and read LOCs, look up the collateral and credited tokens they can use, and check each…

Inputs

  • CreateStaticLOCParams — Parameters for creating a Static LOC: one collateralized 1:1 in the same token it credits, so it needs no oracle price and can never be…
  • CreateDynamicLOCParams — Parameters for creating a Dynamic LOC: collateral in one token backing a face value in another, priced by the Pyth oracle and subject…
  • RedeemLOCsParams — Parameters for redeeming one or more LOCs as the Beneficiary, or with the Beneficiary’s signed authorization.
  • RedeemLOCParams — One redemption within RedeemLOCsParams.redemptions: which LOC, how much of its face value, where the tokens go, and — when the caller is…

Reading a LOC

  • LetterOfCredit — The full record of one LOC, read from the subgraph: how it was created, everything that has happened to it since, and its position at the…
  • OutstandingLetterOfCredit — A LOC’s live position, read from the LetterOfCredit contract: who it is between, what it still promises, when it expires, and what backs it.
  • deriveLetterOfCreditStatus — Summarizes a LetterOfCredit as a single status label at a time you choose.