@agoric/inter-protocol 0.16.2-upgrade-14-dev-0169c7e.0 → 0.16.2-upgrade-16-dev-8879538.0

package/src/vaultFactory/vault.d.ts

@@ -0,0 +1,402 @@
+export namespace Phase {
+    let ACTIVE: "active";
+    let LIQUIDATING: "liquidating";
+    let CLOSED: "closed";
+    let LIQUIDATED: "liquidated";
+    let TRANSFER: "transfer";
+}
+/**
+ * @typedef {Phase[keyof typeof Phase]} HolderPhase
+ *
+ * @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 {HolderPhase} vaultState
+ */
+/**
+ * @typedef {object} VaultManager
+ * @property {() => Subscriber<import('./vaultManager.js').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: import('./storeUtils.js').NormalizedDebt,
+ *   oldCollateral: Amount<'nat'>,
+ *   vaultId: VaultId,
+ *   vaultPhase: VaultPhase,
+ *   vault: Vault,
+ * ) => void} handleBalanceChange
+ * @property {() => import('./vaultManager.js').GovernedParamGetters} getGovernedParams
+ */
+/**
+ * @typedef {Readonly<{
+ *   idInManager: VaultId;
+ *   manager: VaultManager;
+ *   storageNode: 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:
+ *     | import('@agoric/zoe/src/contractSupport/recorder.js').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: import("@agoric/swingset-liveslots").Baggage, makeRecorderKit: import("@agoric/zoe/src/contractSupport/recorder.js").MakeRecorderKit, zcf: ZCF): (manager: VaultManager, idInManager: string, storageNode: globalThis.StorageNode) => import("@endo/exo").GuardedKit<{
+    helper: {
+        collateralBrand(): Brand<"nat">;
+        debtBrand(): Brand<"nat">;
+        emptyCollateral(): import("@agoric/ertp/src/types.js").NatAmount;
+        emptyDebt(): import("@agoric/ertp/src/types.js").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 {HolderPhase} newPhase */
+        getStateSnapshot(newPhase: HolderPhase): {
+            debtSnapshot: {
+                debt: import("@agoric/ertp/src/types.js").NatAmount;
+                interest: Ratio;
+            };
+            locked: import("@agoric/ertp/src/types.js").NatAmount;
+            vaultState: HolderPhase;
+        };
+        /** 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/src/types.js").NatAmount;
+            toMint: import("@agoric/ertp/src/types.js").NatAmount;
+            fee: import("@agoric/ertp/src/types.js").NatAmount;
+            surplus: import("@agoric/ertp/src/types.js").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): {
+            publicSubscribers: {
+                vault: {
+                    description: string;
+                    subscriber: globalThis.Subscriber<VaultNotification>;
+                    storagePath: Promise<string>;
+                };
+            };
+            invitationMakers: import("@endo/exo").Guarded<{
+                AdjustBalances(): Promise<Invitation<string, undefined>>;
+                CloseVault(): Promise<Invitation<string, undefined>>;
+                TransferVault(): Promise<Invitation<any, undefined>>;
+            }>;
+            vault: import("@endo/exo").Guarded<{
+                getPublicTopics(): {
+                    vault: {
+                        description: string;
+                        subscriber: globalThis.Subscriber<VaultNotification>;
+                        storagePath: Promise<string>;
+                    };
+                };
+                makeAdjustBalancesInvitation(): Promise<Invitation<string, undefined>>;
+                makeCloseInvitation(): Promise<Invitation<string, undefined>>;
+                makeTransferInvitation(): Promise<Invitation<any, undefined>>;
+                getCollateralAmount(): import("@agoric/ertp/src/types.js").NatAmount;
+                getCurrentDebt(): import("@agoric/ertp/src/types.js").NatAmount;
+                getNormalizedDebt(): NormalizedDebt;
+            }>;
+            vaultUpdater: import("@agoric/zoe/src/contractSupport/recorder.js").Recorder<VaultNotification>;
+        };
+    };
+    self: {
+        getVaultSeat(): ZCFSeat;
+        /**
+         * @param {ZCFSeat} seat
+         * @param {StorageNode} storageNode
+         */
+        initVaultKit(seat: ZCFSeat, storageNode: StorageNode): Promise<{
+            publicSubscribers: {
+                vault: {
+                    description: string;
+                    subscriber: globalThis.Subscriber<VaultNotification>;
+                    storagePath: Promise<string>;
+                };
+            };
+            invitationMakers: import("@endo/exo").Guarded<{
+                AdjustBalances(): Promise<Invitation<string, undefined>>;
+                CloseVault(): Promise<Invitation<string, undefined>>;
+                TransferVault(): Promise<Invitation<any, undefined>>;
+            }>;
+            vault: import("@endo/exo").Guarded<{
+                getPublicTopics(): {
+                    vault: {
+                        description: string;
+                        subscriber: globalThis.Subscriber<VaultNotification>;
+                        storagePath: Promise<string>;
+                    };
+                };
+                makeAdjustBalancesInvitation(): Promise<Invitation<string, undefined>>;
+                makeCloseInvitation(): Promise<Invitation<string, undefined>>;
+                makeTransferInvitation(): Promise<Invitation<any, undefined>>;
+                getCollateralAmount(): import("@agoric/ertp/src/types.js").NatAmount;
+                getCurrentDebt(): import("@agoric/ertp/src/types.js").NatAmount;
+                getNormalizedDebt(): NormalizedDebt;
+            }>;
+            vaultUpdater: import("@agoric/zoe/src/contractSupport/recorder.js").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<{
+            publicSubscribers: {
+                vault: {
+                    description: string;
+                    subscriber: globalThis.Subscriber<VaultNotification>;
+                    storagePath: Promise<string>;
+                };
+            };
+            invitationMakers: import("@endo/exo").Guarded<{
+                AdjustBalances(): Promise<Invitation<string, undefined>>;
+                CloseVault(): Promise<Invitation<string, undefined>>;
+                TransferVault(): Promise<Invitation<any, undefined>>;
+            }>;
+            vault: import("@endo/exo").Guarded<{
+                getPublicTopics(): {
+                    vault: {
+                        description: string;
+                        subscriber: globalThis.Subscriber<VaultNotification>;
+                        storagePath: Promise<string>;
+                    };
+                };
+                makeAdjustBalancesInvitation(): Promise<Invitation<string, undefined>>;
+                makeCloseInvitation(): Promise<Invitation<string, undefined>>;
+                makeTransferInvitation(): Promise<Invitation<any, undefined>>;
+                getCollateralAmount(): import("@agoric/ertp/src/types.js").NatAmount;
+                getCurrentDebt(): import("@agoric/ertp/src/types.js").NatAmount;
+                getNormalizedDebt(): NormalizedDebt;
+            }>;
+            vaultUpdater: import("@agoric/zoe/src/contractSupport/recorder.js").Recorder<VaultNotification>;
+        }, undefined>>;
+        /** @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 {import('./storeUtils.js').NormalizedDebt} as if the vault
+         *   was open at the launch of this manager, before any interest
+         *   accrued
+         * @see getActualDebAmount
+         */
+        getNormalizedDebt(): import("./storeUtils.js").NormalizedDebt;
+    };
+}>;
+export type VaultPhase = {
+    readonly ACTIVE: "active";
+    readonly LIQUIDATING: "liquidating";
+    readonly CLOSED: "closed";
+    readonly LIQUIDATED: "liquidated";
+    readonly TRANSFER: "transfer";
+}[keyof Omit<typeof Phase, "TRANSFER">];
+export type HolderPhase = {
+    readonly ACTIVE: "active";
+    readonly LIQUIDATING: "liquidating";
+    readonly CLOSED: "closed";
+    readonly LIQUIDATED: "liquidated";
+    readonly TRANSFER: "transfer";
+}[keyof typeof Phase];
+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: HolderPhase;
+};
+export type VaultManager = {
+    getAssetSubscriber: () => Subscriber<import("./vaultManager.js").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: import("./storeUtils.js").NormalizedDebt, oldCollateral: Amount<"nat">, vaultId: VaultId, vaultPhase: VaultPhase, vault: Vault) => void;
+    getGovernedParams: () => import("./vaultManager.js").GovernedParamGetters;
+};
+export type ImmutableState = Readonly<{
+    idInManager: VaultId;
+    manager: VaultManager;
+    storageNode: 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: import("@agoric/zoe/src/contractSupport/recorder.js").Recorder<VaultNotification> | null;
+};
+export type Vault = ReturnType<ReturnType<typeof prepareVault>>["self"];
+import type { Brand } from '@agoric/ertp/src/types.js';
+import type { NormalizedDebt } from './storeUtils.js';
+import { calculateDebtCosts } from './math.js';
+//# 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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"}