diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index 89fd8414d..698600b79 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -349,6 +349,18 @@ export default defineConfig({ text: 'Zoe Data Types', link: '/reference/zoe-api/zoe-data-types', }, + { + text: 'PriceAuthority Object', + link: '/reference/zoe-api/price-authority', + }, + { + text: 'PriceAuthority Admin Object', + link: '/reference/zoe-api/price-authority-admin', + }, + { + text: 'MutableQuote Object', + link: '/reference/zoe-api/mutable-quote', + }, ], }, { @@ -494,10 +506,6 @@ export default defineConfig({ text: 'PSM Contract', link: '/guides/zoe/actual-contracts/PSM', }, - { - text: 'PriceAuthority Object', - link: '/reference/zoe-api/price-authority', - }, ], }, diff --git a/main/reference/zoe-api/index.md b/main/reference/zoe-api/index.md index 877a815e7..9677ea62c 100644 --- a/main/reference/zoe-api/index.md +++ b/main/reference/zoe-api/index.md @@ -19,6 +19,9 @@ The Zoe API supports the following objects: | [Zoe Contract Facet](./zoe-contract-facet) | Accesses a running contract instance. | | [ZCFSeat](./zcfseat) | Used within contracts to access or manipulate offers. | | [ZCFMint](./zcfmint) | Used by a contract to issue digital assets. | +| [PriceAuthority](./price-authority) | Gives reliable price quotes for pairs of currencies. | +| [PriceAuthority Admin](./price-authority-admin) | Registers and deletes **PriceAuthorities**. | +| [MutableQuote](./mutable-quote) | Returned by **PriceAuthority**'s **mutableQuoteWhen\*()** methods; lets you update the trigger level of an outstanding quote. | The Zoe API provides the following libraries: @@ -38,6 +41,8 @@ The Zoe API introduces and uses the following data types: | [Invitation](./zoe-data-types#invitation) | A non-fungible eright that can be held in **[Payments](/reference/ertp-api/payment)** or **[Purses](/reference/ertp-api/purse)**, just like any other eright. | | [InvitationIssuer](./zoe-data-types#invitationissuer) | An **[Issuer](/reference/ertp-api/issuer)** for **[Invitations](./zoe-data-types#invitation)**, which grant the right to participate in a contract. | | [Keyword](./zoe-data-types#keyword) | An ASCII identifier string that must begin with an upper case letter. | +| [MutableQuote](./zoe-data-types#mutablequote) | A **[PriceQuote](./zoe-data-types#pricequote)**-yielding **Promise** whose trigger level can be changed after it's created. | | [ParsableNumber](./zoe-data-types#parsablenumber) | Defined as a **bigint**, **number**, or **string**. | +| [PriceQuote](./zoe-data-types#pricequote) | A statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time. | | [Ratio](./zoe-data-types#ratio) | Pass-by-value record that consists of a _numerator_ **[Amount](/reference/ertp-api/ertp-data-types#amount)** and a _denominator_ **Amount**. | | [TransferPart](./zoe-data-types#transferpart) | **[Allocation](./zoe-data-types#allocation)** changes for one or two existing **[ZCFSeats](./zcfseat)**. **TransferParts** are the individual elements of the _transfer_ array passed into the **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** function. | diff --git a/main/reference/zoe-api/mutable-quote.md b/main/reference/zoe-api/mutable-quote.md index c1d21dbac..28e197997 100644 --- a/main/reference/zoe-api/mutable-quote.md +++ b/main/reference/zoe-api/mutable-quote.md @@ -1,12 +1,8 @@ -# NOT CURRENTLY INCLUDED IN THE PUBLISHED DOCS; PLEASE IGNORE - # MutableQuote Object -Use a **MutableQuote** when you expect to make multiple calls, replacing the trigger -value. If you just need a single quote, and won't change the trigger level, then use -a non-mutable quote. - -There are four _mutable quote_ methods, which return a **MutableQuote** object with the methods: +A **[MutableQuote](./zoe-data-types#mutablequote)** is what the +**[E(PriceAuthority).mutableQuoteWhen\*()](./price-authority#e-priceauthority-mutablequotewhengt-amountin-amountoutlimit)** +methods resolve to. It has the following methods: ## aMutableQuote.cancel(e) diff --git a/main/reference/zoe-api/price-authority-admin.md b/main/reference/zoe-api/price-authority-admin.md index 5bc35623d..6959886fc 100644 --- a/main/reference/zoe-api/price-authority-admin.md +++ b/main/reference/zoe-api/price-authority-admin.md @@ -12,7 +12,7 @@ If the pair is already registered, throw unless `force` is `true`. #### Defined in -[priceAuthorityRegistry.js:27](https://github.com/Agoric/agoric-sdk/blob/a8c322206/packages/vats/src/priceAuthorityRegistry.js#L27) +[priceAuthorityRegistry.js:189](https://github.com/Agoric/agoric-sdk/blob/1db3919939eacd3194c4f07baf507612900ec754/packages/vats/src/priceAuthorityRegistry.js#L189) ## E(Deleter).delete() diff --git a/main/reference/zoe-api/price-authority.md b/main/reference/zoe-api/price-authority.md index cd2811aa6..d9d43c677 100644 --- a/main/reference/zoe-api/price-authority.md +++ b/main/reference/zoe-api/price-authority.md @@ -219,37 +219,7 @@ const quote = E(PriceAuthority).mutableQuoteWhenLTE( ); ``` -## MutableQuote - -A **MutableQuote** represents a statement from a **[PriceAuthority](./price-authority)** as to the -current price level at a particular time. The significant content (prices -and time) is packaged in the **[Amount](/reference/ertp-api/ertp-data-types#amount)**, and repeated -in the **[Payment](/reference/ertp-api/payment)** for veracity. - -**MutableQuotes** should be used when you expect to make multiple calls, replacing the trigger -value. If you just need a single quote, and won't change the trigger level, you should use -**PriceQuotes**. - -A **MutableQuote** is an **Amount**-**Payment** pair, where the **Amount** is also the current -balance of the **Payment**. - -## PriceQuote - -A **PriceQuote** represents a statement from a **[PriceAuthority](./price-authority)** as to the -current price level at a particular time. The significant content (prices -and time) is packaged in the **[Amount](/reference/ertp-api/ertp-data-types#amount)** and repeated -in the **[Payment](/reference/ertp-api/payment)** for veracity. -A **PriceQuote** is an **Amount**-**Payment** pair, where the **Amount** is also the current -balance of the **Payment**. - -```js -const { quoteAmount, quotePayment } = priceQuote; -``` - -**PriceQuotes** are returned in two forms: - -- **PriceDescription** - - Always includes **amountIn**, **amountOut**, the quote's **Timestamp**, - and the **TimerService** the **Timestamp** is relative to. -- **PriceDescription** wrapped as a **QuoteAuthority** issued payment. - - This lets quotes be shared in a format letting others verify the time and values. +See the **[PriceQuote](./zoe-data-types#pricequote)** and **[MutableQuote](./zoe-data-types#mutablequote)** +data type entries for the shape of the values these methods return. The object a +**mutableQuoteWhen\*()** call resolves to has its own **cancel()**, **getPromise()**, and +**updateLevel()** methods, documented on the **[MutableQuote object](./mutable-quote)** page. diff --git a/main/reference/zoe-api/ratio-math.md b/main/reference/zoe-api/ratio-math.md index da626357b..260ddfcbd 100644 --- a/main/reference/zoe-api/ratio-math.md +++ b/main/reference/zoe-api/ratio-math.md @@ -397,6 +397,21 @@ Creates and returns a new **Ratio** that's equivalent to the _ratio_ argument, b Creates a **Ratio** from the _numeric_ argument, and returns that **Ratio**. +## ratioToNumber(ratio) + +- **ratio**: **[Ratio](./zoe-data-types#ratio)** +- Returns: **Number** + +Converts a **Ratio** to a JavaScript **number** by dividing its numerator's value by its +denominator's value. Since **numbers** don't have the precision of **BigInts**, only use this for +approximations, such as for display purposes; don't use it for further exact computation. + +```js +const halfRatio = makeRatio(1n, quatloosBrand, 2n); +// 0.5 +const half = ratioToNumber(halfRatio); +``` + ## assertParsableNumber(specimen) - **specimen**: **Object** diff --git a/main/reference/zoe-api/zoe-contract-facet.md b/main/reference/zoe-api/zoe-contract-facet.md index 3aa33e69f..4669fd2c2 100644 --- a/main/reference/zoe-api/zoe-contract-facet.md +++ b/main/reference/zoe-api/zoe-contract-facet.md @@ -34,11 +34,12 @@ transfers that only include one seat, you can use the helper functions **[toOnly()](./zoe-helpers#toonly-toseat-toamounts)** to create **TransferParts** that only use a subset of the fields. -## zcf.makeZCFMint(keyword, assetKind?, displayInfo?) +## zcf.makeZCFMint(keyword, assetKind?, displayInfo?, options?) - **keyword**: **[Keyword](./zoe-data-types#keyword)** - **assetKind**: **[AssetKind](/reference/ertp-api/ertp-data-types#assetkind)** - Optional, defaults to **AssetKind.NAT**. - **displayInfo**: **[DisplayInfo](/reference/ertp-api/ertp-data-types#displayinfo)** - Optional, defaults to **undefined**. +- **options**: **IssuerOptionsRecord** - Optional, defaults to **undefined**. - Returns: **Promise<[ZCFMint](./zcfmint)>** Creates a synchronous Zoe mint, allowing users to mint and reallocate digital assets synchronously @@ -47,6 +48,10 @@ The optional _displayInfo_ parameter takes values like **decimalPlaces: 16** that tell the UI how to display values associated with the created mint's brand. It defaults to undefined. +The optional _options_ parameter is an **IssuerOptionsRecord**. Its only currently supported field is +**elementShape**, which constrains the shape of each element when _assetKind_ is one of the set-like +kinds (**AssetKind.SET**, **AssetKind.COPY_SET**, **AssetKind.COPY_BAG**). + **Important**: **ZCFMints** do **not** have the same methods as an ERTP **Mint**. Do not try to use ERTP methods on a **ZCFMint** or vice versa. @@ -65,6 +70,40 @@ const { brand, issuer } = mySynchronousMint.getIssuerRecord(); mySynchronousMint.mintGains({ myKeyword: amount }, seat); ``` +## zcf.registerFeeMint(keyword, feeMintAccess) + +- **keyword**: **[Keyword](./zoe-data-types#keyword)** +- **feeMintAccess**: **FeeMintAccess** +- Returns: **Promise<[ZCFMint](./zcfmint)>** + +Registers the contract's synchronous access to the fee mint, allowing the contract to mint and +reallocate assets of the fee **[Brand](/reference/ertp-api/brand)** (currently **IST**) synchronously, +the same way **[zcf.makeZCFMint()](#zcf-makezcfmint-keyword-assetkind-displayinfo-options)** does for +a mint the contract creates itself. Unlike **makeZCFMint()**, this reuses the existing fee issuer +instead of minting a new asset kind. + +_feeMintAccess_ is a credential only obtainable by contracts explicitly granted permission to mint fees; +most contracts never receive one, and calling this method without a valid _feeMintAccess_ fails. + +```js +const feeZCFMint = await zcf.registerFeeMint('Fee', feeMintAccess); +``` + +## zcf.setTestJig(testFn?) + +- **testFn**: **() => Object** - Optional. +- Returns: None. + +Provides a jig object for testing purposes only. The supplied _testFn_ callback is only ever called +in a testing context (specifically, only if a **testJigSetter** was supplied when the contract's vat +was set up), never in production. If no _testFn_ is supplied, an empty jig is used. Whatever object +_testFn_ returns has a **zcf** property appended, set to the contract's current **ZCF**, overriding +any **zcf** property _testFn_ may have provided. + +```js +zcf.setTestJig(() => ({ someState })); +``` + ## zcf.getInvitationIssuer() - Returns: **Promise<[InvitationIssuer](./zoe-data-types#invitationissuer)>** @@ -208,16 +247,20 @@ interface PatternMatchers { } ``` -## zcf.makeEmptySeatKit() +## zcf.makeEmptySeatKit(exit?) -- Returns: **[ZCFSeat](./zcfseat), Promise<[UserSeat](./user-seat)>** +- **exit**: **[ExitRule](./zoe-data-types#exitrule)** - Optional. +- Returns: **{ zcfSeat: [ZCFSeat](./zcfseat), userSeat: Promise<[UserSeat](./user-seat)> }** -Returns an empty **ZCFSeat** and a **Promise** for a **UserSeat** +Returns an empty **ZCFSeat** and a **Promise** for a **UserSeat**. Zoe uses **seats** to represent offers, and has two seat facets (a particular view or API of an object; there may be multiple such facets per object) a **ZCFSeat** and a **UserSeat**. +The optional _exit_ argument is an **ExitRule**, the same shape used in a **Proposal**'s **exit** +clause; it defaults to **{ onDemand: null }**. + ```js const { zcfSeat: mySeat } = zcf.makeEmptySeatKit(); ``` diff --git a/main/reference/zoe-api/zoe-data-types.md b/main/reference/zoe-api/zoe-data-types.md index ce11fc578..42ce39207 100644 --- a/main/reference/zoe-api/zoe-data-types.md +++ b/main/reference/zoe-api/zoe-data-types.md @@ -16,6 +16,19 @@ For example, if a seat expected to be paid 5 _Quatloos_ and 3 _Widgets_ after su } ``` +## ExitRule + +An **ExitRule** specifies how and when a seat can exit a contract, voluntarily or otherwise. It's +one of: + +- **{ onDemand: null }** - The default. The seat can exit whenever it wants by calling + **[zcfSeat.exit()](./zcfseat#zcfseat-exit-completion)**. +- **{ waived: null }** - The seat gives up its right to exit; only the contract can exit it. +- **{ afterDeadline: { timer, deadline } }** - The seat is exited automatically when _timer_ reaches + _deadline_. + - **timer**: **TimerService** + - **deadline**: **Timestamp** + ## Handle **Handles** are **Far** objects without any methods whose only useful property are their @@ -38,6 +51,17 @@ You can get information about the contract instance via these methods: An **Invitation** is a non-fungible asset created by the **[InvitationIssuer](#invitationissuer)**. An **Invitation Payment** is a **[Payment](/reference/ertp-api/payment)** holding an **Invitation**. +## InvitationDetails + +**InvitationDetails** is the value carried by an **[Invitation](#invitation)**'s +**[Amount](/reference/ertp-api/ertp-data-types#amount)**. It consists of: + +- **installation**: **Installation** - The **Installation** the **Invitation**'s **Instance** was started from. +- **instance**: **Instance** - The contract **Instance** the **Invitation** is for. +- **handle**: **Handle** - A unique **Handle** identifying this **Invitation**. +- **description**: **String** - The description passed to **[zcf.makeInvitation()](./zoe-contract-facet#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape)**. +- **customDetails**: **Object** - Optional. The _customDetails_ passed to **zcf.makeInvitation()**, if any. + ## InvitationIssuer The **InvitationIssuer** is an **[Issuer](/reference/ertp-api/issuer)** that plays a @@ -87,10 +111,46 @@ const paymentKeywordRecord = { }; ``` +## MutableQuote + +A **MutableQuote** is a **[PriceQuote](#pricequote)**-yielding **Promise** whose trigger levels can be +changed after it's created, instead of needing a new call for each new trigger. It's returned by the +**[E(PriceAuthority).mutableQuoteWhen*()](./price-authority#e-priceauthority-mutablequotewhengt-amountin-amountoutlimit)** +methods, and has its own **cancel()**, **getPromise()**, and **updateLevel()** methods, documented on +the **[MutableQuote object](./mutable-quote)** page. + +Use a **MutableQuote** when you expect to make multiple calls that just replace the trigger value. If +you only need a single quote and won't change the trigger level, use a plain **PriceQuote**. + ## ParsableNumber A **ParsableNumber** is defined as a **bigint**, **number**, or **string**. +## PriceQuote + +A **PriceQuote** represents a statement from a **[PriceAuthority](./price-authority)** as to the +current price level at a particular time. The significant content (prices and time) is packaged in +the **[Amount](/reference/ertp-api/ertp-data-types#amount)** and repeated in the +**[Payment](/reference/ertp-api/payment)** for veracity. A **PriceQuote** is a +**quoteAmount**/**quotePayment** pair, where **quoteAmount** is also the current balance of +**quotePayment**: + +```js +const { quoteAmount, quotePayment } = priceQuote; +``` + +- **quoteAmount**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** whose value is a + one-element array holding a **PriceDescription**. +- **quotePayment**: **ERef<[Payment](/reference/ertp-api/payment)>** wrapping **quoteAmount**. + +A **PriceDescription** consists of: + +- **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - The amount supplied to a trade. +- **amountOut**: **Amount** - The quoted result of trading _amountIn_. +- **timer**: **TimerService** - The service that gave the _timestamp_. +- **timestamp**: **Timestamp** - A timestamp according to _timer_ for the quote. +- **conditions**: **Object** - Optional. Additional conditions for the quote. + ## Ratio **Ratios** are pass-by-value records that consist of a diff --git a/main/reference/zoe-api/zoe-helpers.md b/main/reference/zoe-api/zoe-helpers.md index bfc107a86..ff07a188f 100644 --- a/main/reference/zoe-api/zoe-helpers.md +++ b/main/reference/zoe-api/zoe-helpers.md @@ -21,6 +21,9 @@ import { - **transfers**: **Array<[TransferPart](./zoe-data-types#transferpart)>** - Returns: None. +**Deprecated**: use **[zcf.atomicRearrange()](./zoe-contract-facet#zcf-atomicrearrange-transfers)** +directly instead of this helper. + Asks Zoe to rearrange the **[Allocations](./zoe-data-types#allocation)** among the seats mentioned in _transfers_. _transfers_ are a set of changes to **Allocations** that must satisfy several constraints. If these constraints are all met, then the reallocation happens atomically. Otherwise an @@ -105,10 +108,10 @@ assertIssuerKeywords(zcf, harden(['Asset', 'Price'])); - **zcf**: **[ZoeContractFacet](./zoe-contract-facet)** - **seat**: **[ZCFSeat](./zcfseat)** - **update**: **[AmountKeywordRecord](./zoe-data-types#keywordrecord)** -- Returns: **Boolean** +- Returns: **0 | 1** -Returns **true** if an update to a **seat**'s **currentAllocation** satisfies its -**proposal.want**. Note this is half of the offer safety check; +Returns **1** if an update to a **seat**'s **currentAllocation** satisfies its +**proposal.want**, and **0** otherwise. Note this is half of the offer safety check; it does not check if the **[Allocation](./zoe-data-types#allocation)** constitutes a refund. The update is merged with **currentAllocation** such that _update_'s values prevail if the **[Keywords](./zoe-data-types#keyword)** are the same. If they diff --git a/main/reference/zoe-api/zoe.md b/main/reference/zoe-api/zoe.md index eb002c62b..13c1d6bfa 100644 --- a/main/reference/zoe-api/zoe.md +++ b/main/reference/zoe-api/zoe.md @@ -267,7 +267,7 @@ to **[Issuers](/reference/ertp-api/issuer)**, such as **FirstCurrency: quatlooIs Parties to the contract will use the **Keywords** to index their proposal and their payments. The **terms** are values used by this contract instance, such as the -number of bids an auction w ill wait for before closing. These values may +number of bids an auction will wait for before closing. These values may be different for different instances of the same contract, but the contract defines what variables need their values passed in as **terms**. @@ -426,4 +426,9 @@ Each contract can define the properties it supports and which are required. - **installation**: **Installation** - Returns: **Promise<BundleId>** -Reserved for future use. +Returns the **BundleId** of the contract bundle the _installation_ argument was installed from. +Throws if _installation_ isn't a valid, currently-known **Installation**. + +```js +const bundleId = await E(zoe).getBundleIDFromInstallation(installation); +```