@agoric/inter-protocol 0.18.0-u23.0 → 0.18.0-u23.1

package/src/vaultFactory/vault.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Constants for vault phase.
+ *
+ * - ACTIVE - vault is in use and can be changed
+ * - LIQUIDATING - vault is being liquidated by the vault manager, and cannot be
+ *   changed by the user. If liquidation fails, vaults may remain in this state.
+ *   An upgrade to the contract might be able to recover them.
+ * - TRANSFER - vault is able to be transferred (payments and debits frozen until
+ *   it has a new owner)
+ * - CLOSED - vault was closed by the user and all assets have been paid out
+ * - LIQUIDATED - vault was closed by the manager, with remaining assets paid to
+ *   owner
+ */
+export type Phase = (typeof Phase)[keyof typeof Phase];
+export namespace Phase {
+    let ACTIVE: "active";
+    let LIQUIDATING: "liquidating";
+    let CLOSED: "closed";
+    let LIQUIDATED: "liquidated";
+    let TRANSFER: "transfer";
+}
+/**
+ * @typedef {object} VaultNotification
+ * @property {Amount<'nat'>} locked Amount of Collateral locked
+ * @property {{
+ *   debt: Amount<'nat'>;
+ *   interest: Ratio;
+ * }} debtSnapshot
+ *   'debt' at the point the compounded interest was 'interest'
+ * @property {Phase} vaultState
+ */
+/**
+ * @typedef {object} VaultManager
+ * @property {() => Subscriber<AssetState>} getAssetSubscriber
+ * @property {(collateralAmount: Amount) => Amount<'nat'>} maxDebtFor
+ * @property {() => Brand<'nat'>} getCollateralBrand
+ * @property {(base: string) => string} scopeDescription
+ * @property {() => Brand<'nat'>} getDebtBrand
+ * @property {MintAndTransfer} mintAndTransfer
+ * @property {(amount: Amount, seat: ZCFSeat) => void} burn
+ * @property {() => Ratio} getCompoundedInterest
+ * @property {(
+ *   oldDebt: NormalizedDebt,
+ *   oldCollateral: Amount<'nat'>,
+ *   vaultId: VaultId,
+ *   vaultPhase: VaultPhase,
+ *   vault: Vault,
+ * ) => void} handleBalanceChange
+ * @property {() => GovernedParamGetters} getGovernedParams
+ */
+/**
+ * @typedef {Readonly<{
+ *   idInManager: VaultId;
+ *   manager: VaultManager;
+ *   storageNode: Remote<StorageNode>;
+ *   vaultSeat: ZCFSeat;
+ * }>} ImmutableState
+ */
+/**
+ * Snapshot is of the debt and compounded interest when the principal was last
+ * changed.
+ *
+ * @typedef {{
+ *   interestSnapshot: Ratio;
+ *   phase: VaultPhase;
+ *   debtSnapshot: Amount<'nat'>;
+ *   outerUpdater: Recorder<VaultNotification> | null;
+ * }} MutableState
+ */
+export const VaultI: import("@endo/patterns").InterfaceGuard<{
+    getCollateralAmount: import("@endo/patterns").MethodGuard;
+    getCurrentDebt: import("@endo/patterns").MethodGuard;
+    getNormalizedDebt: import("@endo/patterns").MethodGuard;
+    getVaultSeat: import("@endo/patterns").MethodGuard;
+    initVaultKit: import("@endo/patterns").MethodGuard;
+    liquidated: import("@endo/patterns").MethodGuard;
+    liquidating: import("@endo/patterns").MethodGuard;
+    makeAdjustBalancesInvitation: import("@endo/patterns").MethodGuard;
+    makeCloseInvitation: import("@endo/patterns").MethodGuard;
+    makeTransferInvitation: import("@endo/patterns").MethodGuard;
+    abortLiquidation: import("@endo/patterns").MethodGuard;
+}>;
+export function prepareVault(baggage: Baggage, makeRecorderKit: MakeRecorderKit, zcf: ZCF): (manager: VaultManager, idInManager: string, storageNode: Remote<StorageNode>) => import("@endo/exo").GuardedKit<{
+    helper: {
+        collateralBrand(): Brand<"nat">;
+        debtBrand(): Brand<"nat">;
+        emptyCollateral(): import("@agoric/ertp").NatAmount;
+        emptyDebt(): import("@agoric/ertp").NatAmount;
+        /**
+         * @typedef {{
+         *   give: { Collateral: Amount<'nat'>; Minted: Amount<'nat'> };
+         *   want: { Collateral: Amount<'nat'>; Minted: Amount<'nat'> };
+         * }} FullProposal
+         */
+        /**
+         * @param {ProposalRecord} partial
+         * @returns {FullProposal}
+         */
+        fullProposal(partial: ProposalRecord): {
+            give: {
+                Collateral: Amount<"nat">;
+                Minted: Amount<"nat">;
+            };
+            want: {
+                Collateral: Amount<"nat">;
+                Minted: Amount<"nat">;
+            };
+        };
+        /** @param {VaultPhase} newPhase */
+        assignPhase(newPhase: VaultPhase): void;
+        assertActive(): void;
+        assertCloseable(): void;
+        /**
+         * Called whenever the debt is paid or created through a transaction,
+         * but not for interest accrual.
+         *
+         * @param {Amount<'nat'>} newDebt - principal and all accrued interest
+         */
+        updateDebtSnapshot(newDebt: Amount<"nat">): void;
+        /**
+         * Update the debt balance and propagate upwards to maintain aggregate
+         * debt and liquidation order.
+         *
+         * @param {NormalizedDebt} oldDebtNormalized - prior principal and all
+         *   accrued interest, normalized to the launch of the vaultManager
+         * @param {Amount<'nat'>} oldCollateral - actual collateral
+         * @param {Amount<'nat'>} newDebtActual - actual principal and all
+         *   accrued interest
+         */
+        updateDebtAccounting(oldDebtNormalized: NormalizedDebt, oldCollateral: Amount<"nat">, newDebtActual: Amount<"nat">): void;
+        /**
+         * @param {ZCFSeat} seat
+         * @returns {Amount<'nat'>}
+         */
+        getCollateralAllocated(seat: ZCFSeat): Amount<"nat">;
+        /**
+         * @param {ZCFSeat} seat
+         * @returns {Amount<'nat'>}
+         */
+        getMintedAllocated(seat: ZCFSeat): Amount<"nat">;
+        assertVaultHoldsNoMinted(): void;
+        /**
+         * @param {Amount<'nat'>} collateralAmount
+         * @param {Amount<'nat'>} proposedDebt
+         */
+        assertSufficientCollateral(collateralAmount: Amount<"nat">, proposedDebt: Amount<"nat">): void;
+        /** @param {Phase} newPhase */
+        getStateSnapshot(newPhase: Phase): {
+            debtSnapshot: {
+                debt: import("@agoric/ertp").NatAmount;
+                interest: Ratio;
+            };
+            locked: import("@agoric/ertp").NatAmount;
+            vaultState: Phase;
+        };
+        /** call this whenever anything changes! */
+        updateUiState(): void;
+        /** @param {ZCFSeat} seat */
+        closeHook(seat: ZCFSeat): Promise<string>;
+        /**
+         * Calculate the fee, the amount to mint and the resulting debt. The
+         * give and the want together reflect a delta, where typically one is
+         * zero because they come from the gave/want of an offer proposal. If
+         * the `want` is zero, the `fee` will also be zero, so the simple math
+         * works.
+         *
+         * @param {Amount<'nat'>} currentDebt
+         * @param {Amount<'nat'>} giveAmount
+         * @param {Amount<'nat'>} wantAmount
+         */
+        debtFee(currentDebt: Amount<"nat">, giveAmount: Amount<"nat">, wantAmount: Amount<"nat">): {
+            newDebt: import("@agoric/ertp").NatAmount;
+            toMint: import("@agoric/ertp").NatAmount;
+            fee: import("@agoric/ertp").NatAmount;
+            surplus: import("@agoric/ertp").NatAmount;
+        };
+        /**
+         * Adjust principal and collateral (atomically for offer safety)
+         *
+         * @param {ZCFSeat} clientSeat
+         * @returns {string} success message
+         */
+        adjustBalancesHook(clientSeat: ZCFSeat): string;
+        /**
+         * @param {ZCFSeat} clientSeat
+         * @param {FullProposal} fp
+         * @param {ReturnType<typeof calculateDebtCosts>} costs
+         * @param {object} accounting
+         * @param {NormalizedDebt} accounting.normalizedDebtPre
+         * @param {Amount<'nat'>} accounting.collateralPre
+         * @returns {string} success message
+         */
+        commitBalanceAdjustment(clientSeat: ZCFSeat, fp: {
+            give: {
+                Collateral: Amount<"nat">;
+                Minted: Amount<"nat">;
+            };
+            want: {
+                Collateral: Amount<"nat">;
+                Minted: Amount<"nat">;
+            };
+        }, { newDebt, fee, surplus, toMint }: ReturnType<typeof calculateDebtCosts>, { normalizedDebtPre, collateralPre }: {
+            normalizedDebtPre: NormalizedDebt;
+            collateralPre: Amount<"nat">;
+        }): string;
+        /**
+         * @param {ZCFSeat} seat
+         * @returns {VaultKit}
+         */
+        makeTransferInvitationHook(seat: ZCFSeat): VaultKit;
+    };
+    self: {
+        getVaultSeat(): ZCFSeat;
+        /**
+         * @param {ZCFSeat} seat
+         * @param {Remote<StorageNode>} storageNode
+         */
+        initVaultKit(seat: ZCFSeat, storageNode: Remote<StorageNode>): Promise<{
+            publicSubscribers: {
+                vault: {
+                    description: string;
+                    subscriber: Subscriber<VaultNotification>;
+                    storagePath: Promise<string>;
+                };
+            };
+            invitationMakers: import("@endo/exo").Guarded<{
+                AdjustBalances(): Promise<Invitation<string, undefined>>;
+                CloseVault(): Promise<Invitation<string, undefined>>;
+                TransferVault(): Promise<Invitation</*elided*/ any>>;
+            }>;
+            vault: import("@endo/exo").Guarded<{
+                getPublicTopics(): {
+                    vault: {
+                        description: string;
+                        subscriber: Subscriber<VaultNotification>;
+                        storagePath: Promise<string>;
+                    };
+                };
+                makeAdjustBalancesInvitation(): Promise<Invitation<string, undefined>>;
+                makeCloseInvitation(): Promise<Invitation<string, undefined>>;
+                makeTransferInvitation(): Promise<Invitation</*elided*/ any>>;
+                getCollateralAmount(): import("@agoric/ertp").NatAmount;
+                getCurrentDebt(): import("@agoric/ertp").NatAmount;
+                getNormalizedDebt(): NormalizedDebt;
+            }>;
+            vaultUpdater: Recorder<VaultNotification>;
+        }>;
+        /** Called by manager at start of liquidation. */
+        liquidating(): void;
+        /**
+         * Called by manager at end of liquidation, at which point all debts
+         * have been covered.
+         */
+        liquidated(): void;
+        /**
+         * Called by vaultManager when the auction wasn't able to sell the
+         * collateral. The liquidation fee was charged against the collateral,
+         * but the debt will be restored and the vault will be active again.
+         * Liquidation.md has details on the liquidation approach.
+         */
+        abortLiquidation(): string;
+        makeAdjustBalancesInvitation(): Promise<Invitation<string, undefined>>;
+        makeCloseInvitation(): Promise<Invitation<string, undefined>>;
+        /** @returns {Promise<Invitation<VaultKit>>} */
+        makeTransferInvitation(): Promise<Invitation<VaultKit>>;
+        /** @returns {Amount<'nat'>} */
+        getCollateralAmount(): Amount<"nat">;
+        /**
+         * The actual current debt, including accrued interest.
+         *
+         * This looks like a simple getter but it does a lot of the heavy
+         * lifting for interest accrual. Rather than updating all records when
+         * interest accrues, the vault manager updates just its rolling
+         * compounded interest. Here we calculate what the current debt is given
+         * what's recorded in this vault and what interest has compounded since
+         * this vault record was written.
+         *
+         * @returns {Amount<'nat'>}
+         * @see getNormalizedDebt
+         */
+        getCurrentDebt(): Amount<"nat">;
+        /**
+         * The normalization puts all debts on a common time-independent scale
+         * since the launch of this vault manager. This allows the manager to
+         * order vaults by their debt-to-collateral ratios without having to
+         * mutate the debts as the interest accrues.
+         *
+         * @returns {NormalizedDebt} as if the vault was open at the launch of
+         *   this manager, before any interest accrued
+         * @see getActualDebAmount
+         */
+        getNormalizedDebt(): NormalizedDebt;
+    };
+}>;
+export type VaultPhase = Exclude<Phase, "transfer">;
+export type VaultNotification = {
+    /**
+     * Amount of Collateral locked
+     */
+    locked: Amount<"nat">;
+    /**
+     *   'debt' at the point the compounded interest was 'interest'
+     */
+    debtSnapshot: {
+        debt: Amount<"nat">;
+        interest: Ratio;
+    };
+    vaultState: Phase;
+};
+export type VaultManager = {
+    getAssetSubscriber: () => Subscriber<AssetState>;
+    maxDebtFor: (collateralAmount: Amount) => Amount<"nat">;
+    getCollateralBrand: () => Brand<"nat">;
+    scopeDescription: (base: string) => string;
+    getDebtBrand: () => Brand<"nat">;
+    mintAndTransfer: MintAndTransfer;
+    burn: (amount: Amount, seat: ZCFSeat) => void;
+    getCompoundedInterest: () => Ratio;
+    handleBalanceChange: (oldDebt: NormalizedDebt, oldCollateral: Amount<"nat">, vaultId: VaultId, vaultPhase: VaultPhase, vault: Vault) => void;
+    getGovernedParams: () => GovernedParamGetters;
+};
+export type ImmutableState = Readonly<{
+    idInManager: VaultId;
+    manager: VaultManager;
+    storageNode: Remote<StorageNode>;
+    vaultSeat: ZCFSeat;
+}>;
+/**
+ * Snapshot is of the debt and compounded interest when the principal was last
+ * changed.
+ */
+export type MutableState = {
+    interestSnapshot: Ratio;
+    phase: VaultPhase;
+    debtSnapshot: Amount<"nat">;
+    outerUpdater: Recorder<VaultNotification> | null;
+};
+export type Vault = EReturn<EReturn<typeof prepareVault>>["self"];
+import type { Baggage } from '@agoric/swingset-liveslots';
+import type { MakeRecorderKit } from '@agoric/zoe/src/contractSupport/recorder.js';
+import type { ZCF } from '@agoric/zoe';
+import type { StorageNode } from '@agoric/internal/src/lib-chainStorage.js';
+import type { Remote } from '@agoric/internal';
+import type { Brand } from '@agoric/ertp/src/types.js';
+import type { ProposalRecord } from '@agoric/zoe';
+import type { Amount } from '@agoric/ertp/src/types.js';
+import type { NormalizedDebt } from './storeUtils.js';
+import type { ZCFSeat } from '@agoric/zoe';
+import type { Ratio } from '@agoric/ertp/src/ratio.js';
+import { calculateDebtCosts } from './math.js';
+import type { VaultKit } from './vaultKit.js';
+import type { Subscriber } from '@agoric/notifier';
+import type { Invitation } from '@agoric/zoe';
+import type { Recorder } from '@agoric/zoe/src/contractSupport/recorder.js';
+import type { AssetState } from './vaultManager.js';
+import type { MintAndTransfer } from './types.js';
+import type { VaultId } from './types.js';
+import type { GovernedParamGetters } from './vaultManager.js';
+import type { EReturn } from '@endo/far';
+//# sourceMappingURL=vault.d.ts.map

package/src/vaultFactory/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["vault.js"],"names":[],"mappings":"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"}