1  /**
  2   *
  3   * This object is returned from the smart contract following the execution of successful offerHandler funciton.
  4   *
  5   * It contains invitations which the account holder can use for further interaction with a lending pool.
  6   *
  7   * In addition to offer invitations, the AccountOfferResult also returns a reference to an account's AccountStore key-value pair, which can be used to view information about their balances.
  8   *
  9   * @typedef {object} AccountOfferResult
 10   * @property {() => Promise<AccountStore>} getStore AccountStore key-value pair, which can be used to view information about their balances.
 11   * @property {() => Promise<Invitation>} makeBorrowInvitation Invitation for initiating a borrow offer against an account's deposits.
 12   * @property {() => Promise<Invitation>} makeAddCollateralInvitation Invitation for adding additional collateral to the lending pool.
 13   */
 14  
 15  /**
 16   * @typedef PoolCollateral
 17   * @property {Issuer} issuer the issuer responsible for minting these tokens. this can be used to verify that the tokens an offer contains are genuine.
 18   * @property {bigint} value the total supply of tokens for this issuer type.
 19   */
 20  
 21  /**
 22   *
 23   * This object is returned from the smart contract following the execution of successful offerHandler funciton.
 24   *
 25   *
 26   * @typedef {object} PoolCreatorResult
 27   * @property {() => Promise<Invitation>} deployInitialCollateral
 28   * @property {() => MapStore<Keyword, PoolCollateral>} getStore Invitation for adding additional collateral to the lending pool.
 29   */
 30  
 31  /**
 32   * Key-value pair containing details of a lending pools collaterals. These values can be exposed publically for users to read, and do not need to be protected.
 33   *
 34   * @typedef {MapStore<Keyword, PoolCollateral>} PoolCollateralStore
 35   */
 36  
 37  /**
 38   * Provides information about an account's balance for a specific token issuer.
 39   * When an account makes an offer using this issues, the details will be used to update the balance with their account store.
 40   *
 41   * @typedef {object} Balance
 42   * @property {Brand} brand Brand of the tokens deposit
 43   * @property {MaxAllowed} maxAllowed information about maximum LTV values
 44   * @property {Ratio} maxLtv the maximum LTV value for a specific brand.
 45   * @property {bigint} value The sum of all deposits that an account has made for a particular issuer.
 46   */
 47  
 48  /**
 49   * Provides information about an account's balance for all markets that it has interacted with.
 50   *
 51   * Each time an acccount interacts a lending market, information about the transaction is recorded using the AccountStore, which can then be viewed by the account's holder.
 52   * When the contract execution finishes, the holder can view the updated values reflected within their AccountStore.
 53   *
 54   * @typedef {MapStore<'Keyword', Balance>} AccountStore
 55   */
 56  
 57  /**
 58   * @typedef {object} MaxAllowed This object represents how much an account can borrow against the collateral they have supplied to specific market.
 59   * MaxAllowed uses calculates the total supply in USD and uses the LTV for a market to arrive at the MaxAllowed value.
 60   * When executing a borrow offer, the contract will take the combine the MaxAllowed value from each market and verify it against the requested amount.
 61   * @property {Brand} brand denomination brand which the value is calculated.
 62   * @property {bigint} value integer representation of the maximum value an account can borrow.
 63   */
 64  
 65  /**
 66   *
 67   * @typedef {Function} MakeAccountOfferHandler
 68   * @param {(store: AccountStore)} store
 69   * @returns {ERef<AccountOfferResult>} offerResult
 70   */
 71  
 72  /**
 73   *  this function returns pool creators with the references needed to configuring a lending pool. In addition to handling initial configuration, these references can be used throughout the pool's lifecycle to adjust details of a pool
 74   *
 75   * @typedef {Function} MakeCreatePoolCreatorResult
 76   * @param {object} adminState private state containing details about this pool.
 77   * @returns {PoolCreatorResult}
 78   */
 79  
 80  /**
 81   * @typedef {object} ImmutableLoanState
 82   * @prop {string} debtKey
 83   * @prop {string} collateralKey
 84   * @prop {Brand} debtBrand
 85   * @prop {Brand} collateralBrand
 86   * @prop {bigint} expiry
 87   * @prop {bigint} interestRate
 88   * @prop {string} id
 89   */
 90  
 91  /**
 92   * @typedef {object} EphemeralLoanState
 93   * @prop {string} debtKey
 94   * @prop {string} collateralKey
 95   * @prop {Brand} debtBrand
 96   * @prop {Brand} collateralBrand
 97   * @prop {bigint} expiry
 98   * @prop {bigint} interestRate
 99   * @prop {string} id
100   */
101  
102  /**
103   * @typedef {object} DurableLoanState
104   * @prop {string} debtKey
105   * @prop {string} collateralKey
106   * @prop {Brand} debtBrand
107   * @prop {Brand} collateralBrand
108   * @prop {bigint} expiry
109   * @prop {bigint} interestRate
110   * @prop {string} id
111   * @prop {Promise} expirationP promise representing a loan's expiration (wake handler). when this value transitions from "pending" to "resolved" is the time in which a loan has reached its expiration date.
112   */
113  
114  /**
115   * @typedef {object} ExpiryState
116   * @prop {bigint} loanTermInHours
117   * @prop {bigint} loanTermInDays
118   */
119  
120  // Metrics naming scheme: nouns are present values; past-participles are accumulative.
121  /**
122   * @typedef {object} MetricsNotification
123   *
124   * @property {number}         numActiveLoans     present count of loans
125   * @property {number}         numExpiringLoans  present count of expiring loans
126   * @property {Amount<'nat'>}  totalCollateral    present sum of collateral across all loans
127   * @property {Amount<'nat'>}  totalDebt          present sum of debt across all loans
128   * @property {Amount<'nat'>}  expiringCollateral  present sum of collateral in loans approaching liquidation
129   * @property {Amount<'nat'>}  totalLoansRepaid    running sum of loans that have been repaid.
130   * @property {number}         numLoansExpired  running count of loans that have expired
131   * @property {number}         numLoansRepaid    running count of loans that have been repaid
132   */
133  
134  
135  /**
136   * @typedef {function} LoanExpirationHandler
137   * 
138   * @todo not currently used, could be used with expirationHandler (wakeup)
139   * @param {ZCF} zcf
140   * @param {ZCFSeat} lenderSeat the lender's seat
141   * @param {ZCFSeat} collateralSeat the collateral (contract) seat
142   * @param {string} collateralKey issuerKeywordRecord key for collateral
143   * @returns {void}
144   */