@agoric/zoe 0.27.0-u19.2 → 0.27.0-u20.0

package/src/zoeService/types.d.ts

@@ -0,0 +1,238 @@
+import type { AnyAmount, AssetKind, DisplayInfo, Issuer, NatValue, Payment } from '@agoric/ertp';
+import type { Subscriber } from '@agoric/notifier';
+import type { ERef, EReturn } from '@endo/eventual-send';
+import type { Bundle, BundleID } from '@agoric/swingset-vat';
+import type { ContractStartFunction, StartParams } from './utils.js';
+import type { Keyword, InvitationHandle, BrandKeywordRecord, Handle, IssuerKeywordRecord } from '../types.js';
+import type { Allocation } from '../types-index.js';
+/**
+ * @see {@link https://github.com/sindresorhus/type-fest/blob/main/source/is-any.d.ts}
+ */
+type IsAny<T> = 0 extends 1 & NoInfer<T> ? true : false;
+/**
+ * Zoe provides a framework for deploying and working with smart
+ * contracts. It is accessed as a long-lived and well-trusted service
+ * that enforces offer safety for the contracts that use it. Zoe has a
+ * single `invitationIssuer` for the entirety of its lifetime. By
+ * having a reference to Zoe, a user can get the `invitationIssuer`
+ * and thus validate any `invitation` they receive from someone else.
+ *
+ * Zoe has two different facets: the public Zoe service and the
+ * contract facet (ZCF). Each contract instance has a copy of ZCF
+ * within its vat. The contract and ZCF never have direct access to
+ * the users' payments or the Zoe purses.
+ */
+export type ZoeService = {
+    /**
+     * Zoe has a single `invitationIssuer` for the entirety of its
+     * lifetime. By having a reference to Zoe, a user can get the
+     * `invitationIssuer` and thus validate any `invitation` they receive
+     * from someone else. The mint associated with the invitationIssuer
+     * creates the ERTP payments that represent the right to interact with
+     * a smart contract in particular ways.
+     */
+    getInvitationIssuer: GetInvitationIssuer;
+    install: InstallBundle;
+    installBundleID: InstallBundleID;
+    startInstance: import('./utils.js').StartInstance;
+    offer: Offer;
+    getPublicFacet: <I extends Instance>(instance: ERef<I>) => Promise<IsAny<I> extends true ? any : I extends import('./utils.js').Instance<infer SF extends ContractStartFunction> ? IsAny<SF> extends true ? unknown : EReturn<SF>['publicFacet'] : never>;
+    getIssuers: GetIssuers;
+    getBrands: GetBrands;
+    getTerms: <I extends ERef<Instance>>(instance: I) => IsAny<I> extends true ? Promise<any> : I extends ERef<import('./utils.js').Instance<infer SF extends ContractStartFunction>> ? IsAny<SF> extends true ? Promise<unknown> : Promise<StartParams<SF>['terms']> : never;
+    getOfferFilter: (instance: ERef<Instance>) => Promise<string[]>;
+    getInstallationForInstance: GetInstallationForInstance;
+    getInstance: GetInstance;
+    getInstallation: GetInstallation;
+    /**
+     *   Return an object with the instance, installation, description, invitation
+     *   handle, and any custom properties specific to the contract.
+     */
+    getInvitationDetails: GetInvitationDetails;
+    getFeeIssuer: GetFeeIssuer;
+    getConfiguration: GetConfiguration;
+    getBundleIDFromInstallation: GetBundleIDFromInstallation;
+    /**
+     *   Return the pattern (if any) associated with the invitationHandle that a
+     *   proposal is required to match to be accepted by zoe.offer().
+     */
+    getProposalShapeForInvitation: (invitationHandle: InvitationHandle) => import('@endo/patterns').Pattern | undefined;
+};
+type GetInvitationIssuer = () => Promise<Issuer<'set', InvitationDetails>>;
+type GetFeeIssuer = () => Promise<Issuer<'nat'>>;
+type GetConfiguration = () => {
+    feeIssuerConfig: FeeIssuerConfig;
+};
+export type GetIssuers = (instance: import('./utils.js').Instance<any>) => Promise<IssuerKeywordRecord>;
+export type GetBrands = (instance: import('./utils.js').Instance<any>) => Promise<BrandKeywordRecord>;
+type GetInstallationForInstance = (instance: import('./utils.js').Instance<any>) => Promise<Installation>;
+export type GetInstance = (invitation: ERef<import('../types-index.js').Invitation>) => Promise<import('./utils.js').Instance<any>>;
+export type GetInstallation = (invitation: ERef<import('../types-index.js').Invitation>) => Promise<Installation>;
+export type GetInvitationDetails = (invitation: ERef<import('../types-index.js').Invitation<any, any>>) => Promise<InvitationDetails>;
+/**
+ * Create an installation by safely evaluating the code and
+ * registering it with Zoe. Returns an installation.
+ */
+export type InstallBundle = (bundle: Bundle | SourceBundle, bundleLabel?: string | undefined) => Promise<Installation>;
+/**
+ * Create an installation from a Bundle ID. Returns an installation.
+ */
+export type InstallBundleID = (bundleID: BundleID, bundleLabel?: string | undefined) => Promise<Installation>;
+/**
+ * Verify that an alleged Installation is real, and return the Bundle ID it
+ * will use for contract code.
+ */
+export type GetBundleIDFromInstallation = (allegedInstallation: ERef<Installation>) => Promise<string>;
+/**
+ * To redeem an invitation, the user normally provides a proposal (their
+ * rules for the offer) as well as payments to be escrowed by Zoe.  If
+ * either the proposal or payments would be empty, indicate this by
+ * omitting that argument or passing undefined, rather than passing an
+ * empty record.
+ *
+ * The proposal has three parts: `want` and `give` are used by Zoe to
+ * enforce offer safety, and `exit` is used to specify the particular
+ * payout-liveness policy that Zoe can guarantee. `want` and `give`
+ * are objects with keywords as keys and amounts as values.
+ * `paymentKeywordRecord` is a record with keywords as keys, and the
+ * values are the actual payments to be escrowed. A payment is
+ * expected for every rule under `give`.
+ */
+export type Offer = <Result, Args = undefined>(invitation: ERef<import('../types-index.js').Invitation<Result, Args>>, proposal?: Proposal, paymentKeywordRecord?: PaymentPKeywordRecord, offerArgs?: Args) => Promise<UserSeat<Result>>;
+/**
+ * Zoe uses seats to access or manipulate offers. They let contracts and users
+ * interact with them. Zoe has two kinds of seats. ZCFSeats are used within
+ * contracts and with zcf methods. UserSeats represent offers external to Zoe
+ * and the contract. The party who exercises an invitation and sends the offer()
+ * message to Zoe gets a UserSeat that can check payouts' status or retrieve the
+ * result of processing the offer in the contract. This varies, but examples are
+ * a string and an invitation for another seat.
+ *
+ * Also, a UserSeat can be handed to an agent outside Zoe and the contract,
+ * letting them query or monitor the current state, access the payouts and
+ * result, and, if it's allowed for this seat, call tryExit().
+ *
+ * Since anyone can attempt to exit the seat if they have a reference to it, you
+ * should only share a UserSeat with trusted parties.
+ *
+ * UserSeat includes queries for the associated offer's current state and an
+ * operation to request that the offer exit, as follows:
+ */
+export type UserSeat<OR = unknown> = {
+    getProposal: () => Promise<ProposalRecord>;
+    /**
+     * returns a promise for a KeywordPaymentRecord containing all the payouts from
+     * this seat. The promise will resolve after the seat has exited.
+     */
+    getPayouts: () => Promise<PaymentPKeywordRecord>;
+    /**
+     * returns a promise for the Payment corresponding to the indicated keyword.
+     * The promise will resolve after the seat has exited. If there is no payment
+     * corresponding to the keyword, an error will be thrown. (It used to return
+     * undefined.)
+     */
+    getPayout: (keyword: Keyword) => Promise<Payment<any, any>>;
+    getOfferResult: () => Promise<OR>;
+    /**
+     * Note: Only works if the seat's `proposal` has an `OnDemand` `exit` clause. Zoe's
+     * offer-safety guarantee applies no matter how a seat's interaction with a
+     * contract ends. Under normal circumstances, the participant might be able to
+     * call `tryExit()`, or the contract might do something explicitly. On exiting,
+     * the seat holder gets its current `allocation` and the `seat` can no longer
+     * interact with the contract.
+     */
+    tryExit?: (() => void) | undefined;
+    /**
+     * Returns true if the seat has exited, false if it is still active.
+     */
+    hasExited: () => Promise<boolean>;
+    /**
+     * returns 1 if the proposal's
+     * want clause was satisfied by the final allocation, otherwise 0. This is
+     * numeric to support a planned enhancement called "multiples" which will allow
+     * the return value to be any non-negative number. The promise will resolve
+     * after the seat has exited.
+     */
+    numWantsSatisfied: () => Promise<0 | 1>;
+    /**
+     * return a promise for the final allocation. The promise will resolve after the
+     * seat has exited.
+     */
+    getFinalAllocation: () => Promise<Allocation>;
+    /**
+     * returns a subscriber that
+     * will be notified when the seat has exited or failed.
+     */
+    getExitSubscriber: () => Subscriber<import('../types-index.js').Completion>;
+};
+export type Proposal = Partial<ProposalRecord>;
+export type ProposalRecord = {
+    give: AmountKeywordRecord;
+    want: AmountKeywordRecord;
+    exit: ExitRule;
+};
+/**
+ * The keys are keywords, and the values are amounts. For example:
+ * { Asset: AmountMath.make(assetBrand, 5n), Price:
+ * AmountMath.make(priceBrand, 9n) }
+ */
+export type AmountKeywordRecord = Record<Keyword, AnyAmount>;
+export type Waker = {
+    wake: () => void;
+};
+export type OnDemandExitRule = {
+    onDemand: null;
+};
+export type WaivedExitRule = {
+    waived: null;
+};
+export type AfterDeadlineExitRule = {
+    afterDeadline: {
+        timer: import('@agoric/time').TimerService;
+        deadline: import('@agoric/time').Timestamp;
+    };
+};
+/**
+ * The possible keys are 'waived', 'onDemand', and 'afterDeadline'.
+ * `timer` and `deadline` only are used for the `afterDeadline` key.
+ * The possible records are:
+ * `{ waived: null }`
+ * `{ onDemand: null }`
+ * `{ afterDeadline: { timer :Timer<Deadline>, deadline :Deadline } }`
+ */
+export type ExitRule = OnDemandExitRule | WaivedExitRule | AfterDeadlineExitRule;
+export type Instance<SF = any> = import('./utils.js').Instance<SF>;
+export type ZCFSpec = {
+    bundleCap: import('@agoric/swingset-vat').BundleCap;
+} | {
+    name: string;
+} | {
+    /** Bundle ID */
+    id: string;
+};
+/**
+ * Opaque type for a JSONable source bundle
+ */
+export type SourceBundle = Record<string, any>;
+export type PaymentPKeywordRecord = Record<Keyword, ERef<Payment<any>>>;
+export type PaymentKeywordRecord = Record<Keyword, Payment<any>>;
+export type InvitationDetails = {
+    installation: Installation;
+    instance: import('./utils.js').Instance<any>;
+    handle: InvitationHandle;
+    description: string;
+    customDetails?: Record<string, any> | undefined;
+};
+export type Installation<SF = any> = import('./utils.js').Installation<SF>;
+export type InstallationStart<I extends Installation> = import('./utils.js').InstallationStart<I>;
+export type FeeIssuerConfig = {
+    name: string;
+    assetKind: AssetKind;
+    displayInfo: DisplayInfo;
+};
+export type ZoeFeesConfig = {
+    getPublicFacetFee: NatValue;
+};
+export type FeeMintAccess = Handle<'feeMintAccess'>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/src/zoeService/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,MAAM,EACN,QAAQ,EACR,OAAO,EACR,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,EACN,mBAAmB,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;OAOG;IACH,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,eAAe,CAAC;IACjC,aAAa,EAAE,OAAO,YAAY,EAAE,aAAa,CAAC;IAClD,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,CAAC,CAAC,SAAS,QAAQ,EACjC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,KACd,OAAO,CACV,KAAK,CAAC,CAAC,CAAC,SAAS,IAAI,GACjB,GAAG,GACH,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,CACnC,MAAM,EAAE,SAAS,qBAAqB,CACvC,GACD,KAAK,CAAC,EAAE,CAAC,SAAS,IAAI,GACpB,OAAO,GACP,OAAO,CAAC,EAAE,CAAC,CAAC,aAAa,CAAC,GAC5B,KAAK,CACZ,CAAC;IACF,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,CAAC,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,EACjC,QAAQ,EAAE,CAAC,KACR,KAAK,CAAC,CAAC,CAAC,SAAS,IAAI,GACtB,OAAO,CAAC,GAAG,CAAC,GACZ,CAAC,SAAS,IAAI,CACV,OAAO,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,CAAC,CACtE,GACD,KAAK,CAAC,EAAE,CAAC,SAAS,IAAI,GACpB,OAAO,CAAC,OAAO,CAAC,GAChB,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GACnC,KAAK,CAAC;IACZ,cAAc,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,0BAA0B,EAAE,0BAA0B,CAAC;IACvD,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,YAAY,EAAE,YAAY,CAAC;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,2BAA2B,EAAE,2BAA2B,CAAC;IACzD;;;OAGG;IACH,6BAA6B,EAAE,CAC7B,gBAAgB,EAAE,gBAAgB,KAC/B,OAAO,gBAAgB,EAAE,OAAO,GAAG,SAAS,CAAC;CACnD,CAAC;AACF,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAC3E,KAAK,YAAY,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACjD,KAAK,gBAAgB,GAAG,MAAM;IAC5B,eAAe,EAAE,eAAe,CAAC;CAClC,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,CACvB,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,KACzC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAClC,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,KACzC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AACjC,KAAK,0BAA0B,GAAG,CAChC,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,KACzC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B,MAAM,MAAM,WAAW,GAAG,CACxB,UAAU,EAAE,IAAI,CAAC,OAAO,mBAAmB,EAAE,UAAU,CAAC,KACrD,OAAO,CAAC,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,MAAM,MAAM,eAAe,GAAG,CAC5B,UAAU,EAAE,IAAI,CAAC,OAAO,mBAAmB,EAAE,UAAU,CAAC,KACrD,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B,MAAM,MAAM,oBAAoB,GAAG,CACjC,UAAU,EAAE,IAAI,CAAC,OAAO,mBAAmB,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAC/D,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAChC;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,KAC7B,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,QAAQ,EAAE,QAAQ,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,KAC7B,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,mBAAmB,EAAE,IAAI,CAAC,YAAY,CAAC,KACpC,OAAO,CAAC,MAAM,CAAC,CAAC;AACrB;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,EAC3C,UAAU,EAAE,IAAI,CAAC,OAAO,mBAAmB,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,EACtE,QAAQ,CAAC,EAAE,QAAQ,EACnB,oBAAoB,CAAC,EAAE,qBAAqB,EAC5C,SAAS,CAAC,EAAE,IAAI,KACb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,GAAG,OAAO,IAAI;IACnC,WAAW,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C;;;OAGG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5D,cAAc,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACnC;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC;;;OAGG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9C;;;OAGG;IACH,iBAAiB,EAAE,MAAM,UAAU,CAAC,OAAO,mBAAmB,EAAE,UAAU,CAAC,CAAC;CAC7E,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AACF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAC7D,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,IAAI,CAAC;CACd,CAAC;AACF,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE;QACb,KAAK,EAAE,OAAO,cAAc,EAAE,YAAY,CAAC;QAC3C,QAAQ,EAAE,OAAO,cAAc,EAAE,SAAS,CAAC;KAC5C,CAAC;CACH,CAAC;AACF;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAChB,gBAAgB,GAChB,cAAc,GACd,qBAAqB,CAAC;AAC1B,MAAM,MAAM,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,OAAO,YAAY,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnE,MAAM,MAAM,OAAO,GACf;IACE,SAAS,EAAE,OAAO,sBAAsB,EAAE,SAAS,CAAC;CACrD,GACD;IACE,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AACN;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC/C,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxE,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AACjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;CACjD,CAAC;AACF,MAAM,MAAM,YAAY,CAAC,EAAE,GAAG,GAAG,IAAI,OAAO,YAAY,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AAC3E,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,IAClD,OAAO,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAC5C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;CAC1B,CAAC;AACF,MAAM,MAAM,aAAa,GAAG;IAC1B,iBAAiB,EAAE,QAAQ,CAAC;CAC7B,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/src/zoeService/types.ts

@@ -0,0 +1,307 @@
+import type {
+  AnyAmount,
+  AssetKind,
+  DisplayInfo,
+  Issuer,
+  NatValue,
+  Payment,
+} from '@agoric/ertp';
+import type { Subscriber } from '@agoric/notifier';
+import type { ERef, EReturn } from '@endo/eventual-send';
+import type { Bundle, BundleID } from '@agoric/swingset-vat';
+import type { ContractStartFunction, StartParams } from './utils.js';
+import type {
+  Keyword,
+  InvitationHandle,
+  BrandKeywordRecord,
+  Handle,
+  IssuerKeywordRecord,
+} from '../types.js';
+import type { Allocation } from '../types-index.js';
+
+/**
+ * @see {@link https://github.com/sindresorhus/type-fest/blob/main/source/is-any.d.ts}
+ */
+type IsAny<T> = 0 extends 1 & NoInfer<T> ? true : false;
+
+/**
+ * Zoe provides a framework for deploying and working with smart
+ * contracts. It is accessed as a long-lived and well-trusted service
+ * that enforces offer safety for the contracts that use it. Zoe has a
+ * single `invitationIssuer` for the entirety of its lifetime. By
+ * having a reference to Zoe, a user can get the `invitationIssuer`
+ * and thus validate any `invitation` they receive from someone else.
+ *
+ * Zoe has two different facets: the public Zoe service and the
+ * contract facet (ZCF). Each contract instance has a copy of ZCF
+ * within its vat. The contract and ZCF never have direct access to
+ * the users' payments or the Zoe purses.
+ */
+export type ZoeService = {
+  /**
+   * Zoe has a single `invitationIssuer` for the entirety of its
+   * lifetime. By having a reference to Zoe, a user can get the
+   * `invitationIssuer` and thus validate any `invitation` they receive
+   * from someone else. The mint associated with the invitationIssuer
+   * creates the ERTP payments that represent the right to interact with
+   * a smart contract in particular ways.
+   */
+  getInvitationIssuer: GetInvitationIssuer;
+  install: InstallBundle;
+  installBundleID: InstallBundleID;
+  startInstance: import('./utils.js').StartInstance;
+  offer: Offer;
+  getPublicFacet: <I extends Instance>(
+    instance: ERef<I>,
+  ) => Promise<
+    IsAny<I> extends true
+      ? any
+      : I extends import('./utils.js').Instance<
+            infer SF extends ContractStartFunction
+          >
+        ? IsAny<SF> extends true
+          ? unknown
+          : EReturn<SF>['publicFacet']
+        : never
+  >;
+  getIssuers: GetIssuers;
+  getBrands: GetBrands;
+  getTerms: <I extends ERef<Instance>>(
+    instance: I,
+  ) => IsAny<I> extends true
+    ? Promise<any>
+    : I extends ERef<
+          import('./utils.js').Instance<infer SF extends ContractStartFunction>
+        >
+      ? IsAny<SF> extends true
+        ? Promise<unknown>
+        : Promise<StartParams<SF>['terms']>
+      : never;
+  getOfferFilter: (instance: ERef<Instance>) => Promise<string[]>;
+  getInstallationForInstance: GetInstallationForInstance;
+  getInstance: GetInstance;
+  getInstallation: GetInstallation;
+  /**
+   *   Return an object with the instance, installation, description, invitation
+   *   handle, and any custom properties specific to the contract.
+   */
+  getInvitationDetails: GetInvitationDetails;
+  getFeeIssuer: GetFeeIssuer;
+  getConfiguration: GetConfiguration;
+  getBundleIDFromInstallation: GetBundleIDFromInstallation;
+  /**
+   *   Return the pattern (if any) associated with the invitationHandle that a
+   *   proposal is required to match to be accepted by zoe.offer().
+   */
+  getProposalShapeForInvitation: (
+    invitationHandle: InvitationHandle,
+  ) => import('@endo/patterns').Pattern | undefined;
+};
+type GetInvitationIssuer = () => Promise<Issuer<'set', InvitationDetails>>;
+type GetFeeIssuer = () => Promise<Issuer<'nat'>>;
+type GetConfiguration = () => {
+  feeIssuerConfig: FeeIssuerConfig;
+};
+export type GetIssuers = (
+  instance: import('./utils.js').Instance<any>,
+) => Promise<IssuerKeywordRecord>;
+export type GetBrands = (
+  instance: import('./utils.js').Instance<any>,
+) => Promise<BrandKeywordRecord>;
+type GetInstallationForInstance = (
+  instance: import('./utils.js').Instance<any>,
+) => Promise<Installation>;
+export type GetInstance = (
+  invitation: ERef<import('../types-index.js').Invitation>,
+) => Promise<import('./utils.js').Instance<any>>;
+export type GetInstallation = (
+  invitation: ERef<import('../types-index.js').Invitation>,
+) => Promise<Installation>;
+export type GetInvitationDetails = (
+  invitation: ERef<import('../types-index.js').Invitation<any, any>>,
+) => Promise<InvitationDetails>;
+/**
+ * Create an installation by safely evaluating the code and
+ * registering it with Zoe. Returns an installation.
+ */
+export type InstallBundle = (
+  bundle: Bundle | SourceBundle,
+  bundleLabel?: string | undefined,
+) => Promise<Installation>;
+/**
+ * Create an installation from a Bundle ID. Returns an installation.
+ */
+export type InstallBundleID = (
+  bundleID: BundleID,
+  bundleLabel?: string | undefined,
+) => Promise<Installation>;
+/**
+ * Verify that an alleged Installation is real, and return the Bundle ID it
+ * will use for contract code.
+ */
+export type GetBundleIDFromInstallation = (
+  allegedInstallation: ERef<Installation>,
+) => Promise<string>;
+/**
+ * To redeem an invitation, the user normally provides a proposal (their
+ * rules for the offer) as well as payments to be escrowed by Zoe.  If
+ * either the proposal or payments would be empty, indicate this by
+ * omitting that argument or passing undefined, rather than passing an
+ * empty record.
+ *
+ * The proposal has three parts: `want` and `give` are used by Zoe to
+ * enforce offer safety, and `exit` is used to specify the particular
+ * payout-liveness policy that Zoe can guarantee. `want` and `give`
+ * are objects with keywords as keys and amounts as values.
+ * `paymentKeywordRecord` is a record with keywords as keys, and the
+ * values are the actual payments to be escrowed. A payment is
+ * expected for every rule under `give`.
+ */
+export type Offer = <Result, Args = undefined>(
+  invitation: ERef<import('../types-index.js').Invitation<Result, Args>>,
+  proposal?: Proposal,
+  paymentKeywordRecord?: PaymentPKeywordRecord,
+  offerArgs?: Args,
+) => Promise<UserSeat<Result>>;
+/**
+ * Zoe uses seats to access or manipulate offers. They let contracts and users
+ * interact with them. Zoe has two kinds of seats. ZCFSeats are used within
+ * contracts and with zcf methods. UserSeats represent offers external to Zoe
+ * and the contract. The party who exercises an invitation and sends the offer()
+ * message to Zoe gets a UserSeat that can check payouts' status or retrieve the
+ * result of processing the offer in the contract. This varies, but examples are
+ * a string and an invitation for another seat.
+ *
+ * Also, a UserSeat can be handed to an agent outside Zoe and the contract,
+ * letting them query or monitor the current state, access the payouts and
+ * result, and, if it's allowed for this seat, call tryExit().
+ *
+ * Since anyone can attempt to exit the seat if they have a reference to it, you
+ * should only share a UserSeat with trusted parties.
+ *
+ * UserSeat includes queries for the associated offer's current state and an
+ * operation to request that the offer exit, as follows:
+ */
+export type UserSeat<OR = unknown> = {
+  getProposal: () => Promise<ProposalRecord>;
+  /**
+   * returns a promise for a KeywordPaymentRecord containing all the payouts from
+   * this seat. The promise will resolve after the seat has exited.
+   */
+  getPayouts: () => Promise<PaymentPKeywordRecord>;
+  /**
+   * returns a promise for the Payment corresponding to the indicated keyword.
+   * The promise will resolve after the seat has exited. If there is no payment
+   * corresponding to the keyword, an error will be thrown. (It used to return
+   * undefined.)
+   */
+  getPayout: (keyword: Keyword) => Promise<Payment<any, any>>;
+  getOfferResult: () => Promise<OR>;
+  /**
+   * Note: Only works if the seat's `proposal` has an `OnDemand` `exit` clause. Zoe's
+   * offer-safety guarantee applies no matter how a seat's interaction with a
+   * contract ends. Under normal circumstances, the participant might be able to
+   * call `tryExit()`, or the contract might do something explicitly. On exiting,
+   * the seat holder gets its current `allocation` and the `seat` can no longer
+   * interact with the contract.
+   */
+  tryExit?: (() => void) | undefined;
+  /**
+   * Returns true if the seat has exited, false if it is still active.
+   */
+  hasExited: () => Promise<boolean>;
+  /**
+   * returns 1 if the proposal's
+   * want clause was satisfied by the final allocation, otherwise 0. This is
+   * numeric to support a planned enhancement called "multiples" which will allow
+   * the return value to be any non-negative number. The promise will resolve
+   * after the seat has exited.
+   */
+  numWantsSatisfied: () => Promise<0 | 1>;
+  /**
+   * return a promise for the final allocation. The promise will resolve after the
+   * seat has exited.
+   */
+  getFinalAllocation: () => Promise<Allocation>;
+  /**
+   * returns a subscriber that
+   * will be notified when the seat has exited or failed.
+   */
+  getExitSubscriber: () => Subscriber<import('../types-index.js').Completion>;
+};
+export type Proposal = Partial<ProposalRecord>;
+export type ProposalRecord = {
+  give: AmountKeywordRecord;
+  want: AmountKeywordRecord;
+  exit: ExitRule;
+};
+/**
+ * The keys are keywords, and the values are amounts. For example:
+ * { Asset: AmountMath.make(assetBrand, 5n), Price:
+ * AmountMath.make(priceBrand, 9n) }
+ */
+export type AmountKeywordRecord = Record<Keyword, AnyAmount>;
+export type Waker = {
+  wake: () => void;
+};
+export type OnDemandExitRule = {
+  onDemand: null;
+};
+export type WaivedExitRule = {
+  waived: null;
+};
+export type AfterDeadlineExitRule = {
+  afterDeadline: {
+    timer: import('@agoric/time').TimerService;
+    deadline: import('@agoric/time').Timestamp;
+  };
+};
+/**
+ * The possible keys are 'waived', 'onDemand', and 'afterDeadline'.
+ * `timer` and `deadline` only are used for the `afterDeadline` key.
+ * The possible records are:
+ * `{ waived: null }`
+ * `{ onDemand: null }`
+ * `{ afterDeadline: { timer :Timer<Deadline>, deadline :Deadline } }`
+ */
+export type ExitRule =
+  | OnDemandExitRule
+  | WaivedExitRule
+  | AfterDeadlineExitRule;
+export type Instance<SF = any> = import('./utils.js').Instance<SF>;
+export type ZCFSpec =
+  | {
+      bundleCap: import('@agoric/swingset-vat').BundleCap;
+    }
+  | {
+      name: string;
+    }
+  | {
+      /** Bundle ID */
+      id: string;
+    };
+/**
+ * Opaque type for a JSONable source bundle
+ */
+export type SourceBundle = Record<string, any>;
+export type PaymentPKeywordRecord = Record<Keyword, ERef<Payment<any>>>;
+export type PaymentKeywordRecord = Record<Keyword, Payment<any>>;
+export type InvitationDetails = {
+  installation: Installation;
+  instance: import('./utils.js').Instance<any>;
+  handle: InvitationHandle;
+  description: string;
+  customDetails?: Record<string, any> | undefined;
+};
+export type Installation<SF = any> = import('./utils.js').Installation<SF>;
+export type InstallationStart<I extends Installation> =
+  import('./utils.js').InstallationStart<I>;
+export type FeeIssuerConfig = {
+  name: string;
+  assetKind: AssetKind;
+  displayInfo: DisplayInfo;
+};
+export type ZoeFeesConfig = {
+  getPublicFacetFee: NatValue;
+};
+export type FeeMintAccess = Handle<'feeMintAccess'>;

package/src/zoeService/utils.d.ts

@@ -1,13 +1,10 @@
-// Ambient types
-import '../types-ambient.js';
-import '../contractFacet/types-ambient.js';
-
 import type { Issuer } from '@agoric/ertp/src/types.js';
 import type { TagContainer } from '@agoric/internal/src/tagged.js';
 import type { Baggage } from '@agoric/swingset-liveslots';
 import type { VatUpgradeResults } from '@agoric/swingset-vat';
 import type { RemotableObject } from '@endo/marshal';
 import type { FarRef } from '@endo/far';
+import type { AnyTerms, Handle, Keyword, ZCF } from '../types-index.js';
 
 // XXX https://github.com/Agoric/agoric-sdk/issues/4565
 type SourceBundle = Record<string, any>;
@@ -29,7 +26,7 @@ export type InstallationStart<I> =
   I extends Installation<infer SF> ? SF : never;
 
 export type ContractStartFunction = (
-  zcf?: ZCF,
+  zcf?: ZCF<any>,
   privateArgs?: object,
   baggage?: Baggage,
 ) => ERef<{ creatorFacet?: object; publicFacet?: object }>;
@@ -66,6 +63,8 @@ type ZcfOf<SF extends ContractStartFunction> = Parameters<SF>[0] extends ZCF
   : ZCF<any>;
 
 /**
+ * @deprecated use the SF to pass the type
+ *
  * Convenience record for contract start function, merging its result with params.
  */
 export type ContractOf<S extends (...args: any) => any> = StartParams<S> &
@@ -125,3 +124,12 @@ export type GetTerms = <SF>(instance: Instance<SF>) => Promise<
     : // XXX returning `any` in this case
       any
 >;
+
+export type InstanceRecord = {
+  installation: Installation<any>;
+  instance: Instance<any>;
+  /**
+   * - contract parameters
+   */
+  terms: AnyTerms;
+};

package/src/zoeService/utils.test-d.ts

@@ -1,5 +1,6 @@
 import { E } from '@endo/far';
 import type { StartedInstanceKit } from './utils.js';
+import type { ZCF } from '../types-index.js';
 
 const someContractStartFn = (
   zcf: ZCF,

package/src/zoeService/zoe.d.ts

@@ -1,5 +1,10 @@
+export * from "../types-index.js";
 export type ZoeKit = ReturnType<typeof makeDurableZoeKit>;
-/** @import {Baggage} from '@agoric/vat-data' */
+/**
+ * @import {VatAdminSvc} from '@agoric/swingset-vat';
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {FeeIssuerConfig, FeeMintAccess, ZCFSpec, ZoeService} from './types.js';
+ */
 /**
  * Create a durable instance of Zoe.
  *
@@ -55,4 +60,9 @@ export function makeZoeKit(vatAdminSvc?: Promise<VatAdminSvc> | VatAdminSvc, shu
     setVatAdminService: ((lateVatAdminSvc: any) => void) & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, (lateVatAdminSvc: any) => void>;
 };
 import type { Baggage } from '@agoric/vat-data';
+import type { VatAdminSvc } from '@agoric/swingset-vat';
+import type { FeeIssuerConfig } from './types.js';
+import type { ZCFSpec } from './types.js';
+import type { ZoeService } from './types.js';
+import type { FeeMintAccess } from './types.js';
 //# sourceMappingURL=zoe.d.ts.map

package/src/zoeService/zoe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zoe.d.ts","sourceRoot":"","sources":["zoe.js"],"names":[],"mappings":"qBAiSa,UAAU,CAAC,OAAO,iBAAiB,CAAC;AAnQjD,gDAAgD;AAEhD;;;;;;;;;;;;;GAaG;AACH,0GAVG;IAAyB,UAAU,EAA3B,OAAO;IACsC,WAAW;IAGK,cAAc;IAGjD,eAAe;IACvB,OAAO;CACnC;;;;;IAgNG,4BAA4B;mBAAjB,aAAa;;EAK3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,yCATW,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,mBAGlC,OAAO,sBAAsB,EAAE,mBAAmB,oBAGlD,eAAe,YACf,OAAO;;;;;IArBd,4BAA4B;mBAAjB,aAAa;;EA8BxB;6BA7PuB,kBAAkB"}
+{"version":3,"file":"zoe.d.ts","sourceRoot":"","sources":["zoe.js"],"names":[],"mappings":";qBAqSa,UAAU,CAAC,OAAO,iBAAiB,CAAC;AAvQjD;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,0GAVG;IAAyB,UAAU,EAA3B,OAAO;IACsC,WAAW;IAGK,cAAc;IAGjD,eAAe;IACvB,OAAO;CACnC;;;;;IAgNG,4BAA4B;mBAAjB,aAAa;;EAK3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,yCATW,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,mBAGlC,OAAO,sBAAsB,EAAE,mBAAmB,oBAGlD,eAAe,YACf,OAAO;;;;;IArBd,4BAA4B;mBAAjB,aAAa;;EA8BxB;6BA/PsB,kBAAkB;iCADd,sBAAsB;qCAEkB,YAAY;6BAAZ,YAAY;gCAAZ,YAAY;mCAAZ,YAAY"}

package/src/zoeService/zoe.js

@@ -28,7 +28,11 @@ import { getZcfBundleCap } from './createZCFVat.js';
 import { defaultFeeIssuerConfig, prepareFeeMint } from './feeMint.js';
 import { ZoeServiceI } from '../typeGuards.js';
 
-/** @import {Baggage} from '@agoric/vat-data' */
+/**
+ * @import {VatAdminSvc} from '@agoric/swingset-vat';
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {FeeIssuerConfig, FeeMintAccess, ZCFSpec, ZoeService} from './types.js';
+ */
 
 /**
  * Create a durable instance of Zoe.
@@ -289,3 +293,6 @@ export { makeDurableZoeKit, makeZoeKit };
 /**
  * @typedef {ReturnType<typeof makeDurableZoeKit>} ZoeKit
  */
+
+// eslint-disable-next-line import/export -- no named value exports; only types
+export * from '../types-index.js';

package/src/zoeService/zoeSeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zoeSeat.d.ts","sourceRoot":"","sources":["zoeSeat.js"],"names":[],"mappings":"AAmDO,iDAFI,OAAO,kBAAkB,EAAE,OAAO,uBA0WhC,UAAU,YACV,cAAc,uBACd,mBAAmB,iBACnB,aAAa,YACb,IAAI,CAAC,OAAO,CAAC,2BACb,OAAO;;;;;;;;;;;;;;;;QA3IZ,wCAAwC;8DAA5B,iBAAiB;;;;EAoKpC"}
+{"version":3,"file":"zoeSeat.d.ts","sourceRoot":"","sources":["zoeSeat.js"],"names":[],"mappings":"AAkDO,iDAFI,OAAO,kBAAkB,EAAE,OAAO,uBA0WhC,UAAU,YACV,cAAc,uBACd,mBAAmB,iBACnB,aAAa,YACb,IAAI,CAAC,OAAO,CAAC,2BACb,OAAO;;;;;;;;;;;;;;;;QA3IZ,wCAAwC;8DAA5B,iBAAiB;;;;EAoKpC"}

package/src/zoeService/zoeSeat.js

@@ -7,8 +7,7 @@ import { makePromiseKit } from '@endo/promise-kit';
 import { NonNullish } from '@agoric/internal';
 
 import { satisfiesWant } from '../contractFacet/offerSafety.js';
-import '../types-ambient.js';
-import '../internal-types.js';
+
 import {
   declareOldZoeSeatAdminKind,
   OriginalZoeSeatIKit,