# Changelog

## 0.2.2 (19 October 2026)

One more check in `verifyLine`, from the confirm round of the 0.2.0 review. Nothing else in the API changed, and nothing on chain.

**Fixed:**

- **admin:** `verifyLine` checks each rule's exact policy set on the account: the interpreter, plus the threshold policy where the rule has a threshold, and nothing else. It used to check only whether the threshold policy was there, so it passed a rule with an extra policy (a foreign threshold policy at 1, say) and a rule without the interpreter policy as long as the predicate was stored. On 19 October beta, beta-2 and sim pass it: 126 checks each, every rule with exactly its policies.

## 0.2.1 (19 October 2026)

The fixes of the review of 0.2.0, all in the checks a client makes before it signs or accepts a line. Nothing on chain changed.

**Breaking, for a take-over queue:** the terms `{ kind: 'takeover-queue', asset, repay, asset_amount }` now require `asset_amount`, the asset the recovery account takes for `repay` (the step's summary states it; `termsFromSummary` carries it). Without it, a service could have the admin sign a take of up to 5% above par.

**Fixed:**

- **api:** `checkStepTerms` for a take-over queue rebuilds the stored call with `takeoverT1Batch` from the terms and the line's addresses and wait, and refuses the step unless the wait, the six grants and the call match byte for byte. It needs the line's take-over wait in the summary (`limits.takeover_wait_ledgers`, which `lineSummaryOfConfig` now sets). The optional `wait_ledgers` term is the wait the caller expects.
- **core:** the registry parser refuses a `liquidation.refused` list that leaves out the recovery account or any retired gate, besides the settlement account, custody, the gate, both adapters and the mint account.
- **admin:** `verifyLine` also checks, for each rule, the context rule's scope and signers, the threshold policy and its value, and the interpreter's bound executor. It refuses any context rule the line does not know (rule 0 aside), a gate list that is not exactly the registry's or that names a gate, and a gate-free adapter with a gate, a wait or a run window. `planLine` refuses one key in two roles (the Untangled admin, the PO's keys, the service, custody, recovery and the feeder) and an `extraAllowed` entry that is not an address.

## 0.2.0 (19 October 2026)

Use this release from 19 October 2026: both lines moved that day to the liquidation and take-over through the gate-free adapter, with new gates and rule ids. A 0.1.6 client refuses beta's liquidation step (`TERMS_MISMATCH`) and, on beta-2, builds a liquidation that names a removed rule, so it fails closed. This release breaks the 0.1.x API in the places below; there are no aliases.

**Migrating from 0.1.6:**

Each 0.1.6 name in the 0.1.6 entry below has a new name, one for one, with the same arguments and results:

- chain: `chain.liquidations.buildLiquidation` (the liquidator's transaction), with `BuildLiquidationOptions`, `BuiltLiquidation`, `LIQUIDATION_LEDGERS` and `MAX_LIQUIDATION_LEDGERS`; `chain.liquidations.quote` keeps its name.
- core: `quoteLiquidation` and `LiquidationQuote` (the quote), `liquidationBatch` and `liquidationOperation` (the batch and its operation), `explainLiquidation`, `LiquidationRefusal` and `LiquidationRefusalCode`, `LIQUIDATION_SLIPPAGE_BPS`; `gatefreeOf`, `GatefreeRules` and `Liquidation` for the registry's liquidation. The cover kit's own quote is `quoteSale`, returning `SaleQuote`.
- api: `checkLiquidationTerms`. A liquidation step is always a transaction step; a preimage liquidation step is refused.
- Registry: a line's `liquidation` is `{ adapter, rules, refused }` (no `mode`), and `takeover: { rules: { queue, take } }` and `gate.retired` are new; both `liquidation` and `takeover` are required. `contracts` no longer names a separate liquidation contract, and the line record has no block for one. `ruleAddressesOf` and the old `ruleSet` are gone: use `lineRuleAddressesOf(line)` and `ruleKit(limits).lineRuleSet(...)`, and `ruleIdOf(line, account, name)` for a rule's id.
- Quote and `LineSummary`: the `mode` field is gone; `LiquidationRecord` carries no `mode`.

**New:**

- **core:** `Liquidation`, `GatefreeRules`, `Takeover`, `takeoverOf`; `gatefreeSalt`, `gatefreeArgs`, `gatefreeAddress(passphrase, settlement)`, `refusedFor(...)`, `lineRuleAddressesOf(line)`, `ruleIdOf`. ruleKit's `lineRuleSet` is a line's whole rule set: the asset rules pay custody or recovery only, liquidate-nr refuses the `refused` list, and takeover-t1 and take-t1. The T1′ take-over: `takeoverT1Batch` (one stored call to the gate-free adapter, six grants), `recoveryPayIn`, `takeoverT1TermsOf` and `takeoverRunOperation` (the run, recovery as the transaction's source).
- **chain:** `chain.takeovers.buildRun(line, { id, asset, repay, assetAmount })` builds and simulates the run of a stored take-over for the recovery account to sign; `codeCheck` checks the gate-free adapter's code.
- **api:** `checkStepTerms` checks a T1′ take-over queue (one call to the gate-free adapter, recovery paying exactly R and receiving the asset).
- **networks:** the testnet profile pins the gate-free adapter's code (`wasm.gatefree`, 4985cd12).
- **Registry:** `TESTNET_REGISTRY` names beta's gate v7 (rules 58 to 69) and beta-2's gate v3 (rules 29 to 33, and 22 to 28), and the sim line.

## 0.1.6 (19 October 2026)

Use this release for beta-2: from today it liquidates without the router. A 0.1.5 client refuses beta-2's liquidation step (`TERMS_MISMATCH`), so it fails closed.


- **Liquidation without the router:** a line's registry entry says how it liquidates: `liquidation: { mode: 'router' }`, or `{ mode: 'norouter', adapter, rules }` with the gate-free execution adapter and the rule ids of its batch. `TESTNET_REGISTRY` sets beta to `router` and beta-2 to `norouter` (adapter `CCTN2RNT…ZRVAO2`, rules 21 to 26). An entry with no mode is a router line.
- **core:** `LiquidationConfig`, `NoRouterRules` and `noRouterOf(line)`. `noRouterBatch` builds the five calls (pay in, the asset out, repay, withdraw, burn) and the settlement account's tree, with its rule ids. `noRouterOperation` adds two entries: the liquidator's TUSD transfer with source-account credentials, and the settlement account's approval, vouched for by the gate-free adapter. `liquidatorEntry` builds the first; no Address-credential entry is ever made for the liquidator, since such an entry can be lifted into another batch. `quoteNoRouter` and `interestMargin` quote on the live debt: R stays a minute of interest below half of it, and y comes from rule 21's prices and bands. `refusedLiquidators` and `explainNoRouter` give rule 21's checks and the contracts' errors in words. Each refusal has a code in `NoRouterRefusal`.
- **chain:** `chain.liquidations.quote(line, { asset, repay?, assetAmount?, liquidator? })` and `chain.liquidations.buildNoRouter(line, { liquidator, asset, repay?, assetAmount?, ledgers? })`. They build the liquidator's transaction from chain reads alone and simulate it; nothing is signed or sent. A quote the chain would refuse throws `REFUSED` with `detail.refusals`; a simulation the contracts refuse throws `REFUSED_BY_CONTRACTS` in words.
- **api:** `checkNoRouterTerms`. On a no-router line, `checkStepTerms` checks a liquidation as the liquidator's own transaction: its source, the five calls, R, the least asset, and exactly two entries, the liquidator's with source-account credentials. `LineSummary.liquidation` and the no-router fields of `Quote` (`mode`, `adapter`, `debt`, `margin`) are typed.
- **Slippage on y:** a no-router quote asks for y `slippageBps` under rule 21's 105% edge, 50 by default (`NO_ROUTER_SLIPPAGE_BPS`), so a price rise of up to about 0.5% before the transaction runs still passes. A caller may set 0 to `maxSlippageBps(line)`, half the bonus (250), so a quote gives away at most half of it; an explicit `assetAmount` is taken as given. The quote gives `fairAsset` (the edge) and `slippageBps`; the service's quote gives `fair_asset_amount` and `slippage_bps`.
- **api:** `liquidations.scan({ from_ledger, to_ledger?, allocate_before_first_scan? })`, the admin's backfill. It reads a ledger range again for liquidations the book missed, at most 20,000 ledgers a call, records each once and returns a `LiquidationScan`. Each is allocated as of its own ledger; one the book cannot place is recorded with `allocated: false`. New event types: `liquidation_scan_skipped` names a range the scan gave up on after five tries, one older than the node keeps, or a transaction that repaid the debt and that the book does not recognise (including one with more than one entry of the settlement account), once per transaction; `liquidation_unallocated` names a liquidation recorded without allocation.
- **Registry:** `TESTNET_REGISTRY` names beta-2's first gate, `CCUVBX…Y77J`. Its payout and repay rules still pull through that gate, so it is right today; beta-2's gated adapter is bound to gate v2 `CDZSHK…V2IQ` since 19 October (the take-over without the router). A registry change of the gate needs an SDK release.
- **openapi:** `LineSummary.liquidation`, `Quote.mode`, `adapter`, `debt` and `margin`, and `LineView.liquidations`, the newest liquidations the book recorded, whether from its own step or read from the chain. On a no-router line `POST …/liquidations` answers a transaction step, which the liquidator signs as its source and submits as `signed_transaction`. `POST /v1/lines/{line}/liquidations/scan` (admin) and `LiquidationScan`; `liquidation_scan_skipped` and `liquidation_unallocated` in `EventType`; `LiquidationRecord.allocated`. A step's quote is `StepQuote`, which carries no `request_id` of its own.

## 0.1.5 (18 October 2026)

- **api:** `payins.resolve(ref, { outcome: 'paid', tx_hash })` and `payins.resolve(ref, { outcome: 'not_paid' })`, the line admin's answer for a release whose release step went on chain but which the chain shows as something else. The service signs nothing for such a pay-in until it is resolved. `paid` is checked on chain where a node shows the transaction; `not_paid` stops the step counting as the payment, so the advance can be renewed or returned.
- **openapi:** `resolvePayin` takes the outcomes `paid` and `not_paid`. `not_paid` is accepted only when the chain answers FAILED for the step's transaction on chain and shows no transfer of the release in it.
- **Events:** `release_disputed` (in `EventType` and the spec), posted at most once an hour per pay-in while a release step on chain is contradicted by the chain; `release_blocked`, posted at most once an hour per advance while an advance of unknown outcome holds a release.

## 0.1.4 (18 October 2026)

- **Release of an advance still settling:** the service builds a release step outside the line's queue. While the payout's own advance is being submitted, or was sent and is not yet seen on chain, `POST …/release/step` answers 409 `STATE_CONFLICT` with `detail.settling: true`, `detail.retry_after_s` and a `Retry-After` header; a release that changed while its step was built answers 409 with `detail.changed: true`. Both mean "ask again then"; neither means renew.
- **core:** `isSettling(err)`, `isAskAgain(err)` and `retryAfterMs(err, fallbackMs?)`.
- **api:** `payins.releaseWhenReady(ref, terms, { maxWaitMs })`: `payins.release`, asked again while the service says so, honouring `Retry-After` (120 s at most by default). `payins.release` itself is unchanged.
- **openapi:** the release step's 409 is `ReleaseRefused`, which documents `detail.settling`, `detail.changed` and `Retry-After`.

## 0.1.3 (18 October 2026)

- **Default service:** `createClient()` calls the testnet beta at https://payfi-beta.untangled.finance when no `baseUrl` is given (`DEFAULT_BASE_URL`). A `baseUrl` still points it anywhere else. The beta's earlier address, https://payfi-beta.untangledfinance.workers.dev, keeps serving `/api`, `/v1` and the spec, so 0.1.2 and clients configured with it keep working.
- **Name:** the product is PayFi. The README's title, its first line, the package description and the spec's `info.title` use that name; the README's example and the spec's `servers` name the beta's address.
- **Types:** `LineView` lists every field the line view returns: the POT price, the first-loss deposit, custody's balance and its allowance to the gate with the ledger it lapses after, the settlement account's holdings and their reasons, unexpected mints, pending and unreleased advances, the daily total, each corridor's open exposure and the overdue references. `Health` gains `ttl` (`TtlHealth`): the lowest time to live left among the lines' ledger entries, from the Worker's keep-alive.
- **openapi:** `ttl` in `Health`.

## 0.1.2 (18 October 2026)

Use this release or later: 0.1.1 is deprecated, because its registry predates the change of the testnet XLM feed.

- **Registry:** `TESTNET_REGISTRY` follows the move of 18 October. Reflector's testnet XLM feed stopped, so both testnet lines price XLM with their own oracle, `CBSNY3FDDREANTLBAU5JGIEFBZQOEABUIDHB2KN2RUSEY6XUTOEJRWLS`. Its basket entry is the key `Stellar(XLM SAC)`, the band 0.05 to 1 USD and a maximum age of 300 s. The rules that read the price have new ids: on beta, payout 53, withdraw 54, liquidate 55, takeover 56 and take 57; on beta-2, payout 16, withdraw 17, liquidate 18, takeover 19 and take 20. Under 0.1.1 the old ids are gone from the chain and steps that name the new ones are refused.
- **core:** `xlmOwnOracle({ passphrase, feed, maxAgeS })` and `XLM_OWN_ORACLE_BAND`. They give XLM priced by the admin-gated oracle. `xlm()` and `XLM_BAND`, the Reflector form, are unchanged.
- **api:** the admin's `line(id).limits.setOverdueWindow(seconds)` and `line(id).limits.setLineCap(amount)` call `POST /v1/lines/{line}/limits`, which the request message describes as "Set the line's limits". New types: `Limits` and `OpenAdvance`. `LineView` gains `open_advances` and `limits`.
- **openapi:** `POST /v1/lines/{line}/limits` (`setLimits`), the `limits` decision kind, and `face` in the line view's `open_advances`.
- **Types:** `globalThis.crypto` is read through a typed lookup, so a host without Web Crypto types still compiles.

## 0.1.1 (17 October 2026)

The reviewed build: the v1 API client, step checks, signers, the admin plan and the testnet registry of beta and beta-2.
