From 6dd2d1686471c465d7740c6d8e95b489f1f2f404 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Thu, 21 Mar 2024 15:13:46 -0500 Subject: [PATCH 1/2] style: markdown lint --- main/guides/zoe/actual-contracts/index.md | 32 +++--- main/reference/zoe-api/index.md | 59 +++++----- main/reference/zoe-api/price-authority.md | 128 +++++++++++++--------- main/reference/zoe-api/zoe-data-types.md | 57 +++++----- 4 files changed, 147 insertions(+), 129 deletions(-) diff --git a/main/guides/zoe/actual-contracts/index.md b/main/guides/zoe/actual-contracts/index.md index 929bbe24d..28d2a9699 100644 --- a/main/guides/zoe/actual-contracts/index.md +++ b/main/guides/zoe/actual-contracts/index.md @@ -2,19 +2,19 @@ In the [mainnet-1B release of agoric-sdk](https://github.com/Agoric/agoric-sdk/releases/tag/mainnet1B-rc3), the chain is configured to automatically deploy the following Zoe contracts. A [community post on Inter Protocol Vaults Contract Implementations](https://community.agoric.com/t/inter-protocol-vaults-contract-implementations/261) has a high level description. -| Contract | Description | -| --- | --- | -| centralSupply | used to initialize the vbank IST purse balance based on supply reported from the cosmos x/bank module | -| mintHolder | use to hold mints for BLD as well as inter-chain assets such as ATOM, USDC, and USDT | -| committee | represents the Economic Committee that governs Inter Protocol parameters | -| binaryVoteCounter | instantiated once for each question that a committee votes on | -| econCommitteeCharter | controls what questions can be put to the economic committee | -| contractGovernor | each governed contract is started by starting its governor | -| [PSM](./PSM) | The Parity Stability Module (PSM) supports efficiently minting and burning Inter Stable Tokens (ISTs) in exchange for approved external stable tokens. | -| vaultFactory| allows users to mint IST backed by collateral such as ATOM; hands off vaults to auctioneer when value of collateral in a vault falls below a governed threshold | -| auctioneer | auctions collateral from liquidated vaults | -| fluxAggregator | aggregates prices from oracle oeprators | -| scaledPriceAuthoriy | provides prices for tradeable assets such as ATOM in terms of idealized "oracle ATOM" prices from oracle operators | -| feeDistributor | collects fees from Inter Protocol contracts and distributes to reserve and/or stakers | -| assetReserve | holds assets in reserve to back IST | -| walletFactory | executes Zoe offers on behalf of users | +| Contract | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| centralSupply | used to initialize the vbank IST purse balance based on supply reported from the cosmos x/bank module | +| mintHolder | use to hold mints for BLD as well as inter-chain assets such as ATOM, USDC, and USDT | +| committee | represents the Economic Committee that governs Inter Protocol parameters | +| binaryVoteCounter | instantiated once for each question that a committee votes on | +| econCommitteeCharter | controls what questions can be put to the economic committee | +| contractGovernor | each governed contract is started by starting its governor | +| [PSM](./PSM) | The Parity Stability Module (PSM) supports efficiently minting and burning Inter Stable Tokens (ISTs) in exchange for approved external stable tokens. | +| vaultFactory | allows users to mint IST backed by collateral such as ATOM; hands off vaults to auctioneer when value of collateral in a vault falls below a governed threshold | +| auctioneer | auctions collateral from liquidated vaults | +| fluxAggregator | aggregates prices from oracle oeprators | +| scaledPriceAuthoriy | provides prices for tradeable assets such as ATOM in terms of idealized "oracle ATOM" prices from oracle operators | +| feeDistributor | collects fees from Inter Protocol contracts and distributes to reserve and/or stakers | +| assetReserve | holds assets in reserve to back IST | +| walletFactory | executes Zoe offers on behalf of users | diff --git a/main/reference/zoe-api/index.md b/main/reference/zoe-api/index.md index 6de53437b..d97d63b16 100644 --- a/main/reference/zoe-api/index.md +++ b/main/reference/zoe-api/index.md @@ -2,8 +2,7 @@ - -The Zoe framework provides a way to write smart contracts without having to worry about [offer safety](/guides/zoe/offer-safety). +The Zoe framework provides a way to write smart contracts without having to worry about [offer safety](/guides/zoe/offer-safety). To use Zoe, we put things in terms of "offers". An offer proposal is a statement about what you want and what you're willing to offer. It turns out, many smart contracts (apart from gifts and one-way payments) involve an exchange of digital assets that can be put in terms of offer proposals. @@ -13,39 +12,35 @@ Explore our [pre-built contracts](/guides/zoe/contracts/index). The Zoe API supports the following objects: -| Object | Description | -| --- | --- | -| [Zoe Service](./zoe) | Deploys and works with smart contracts. | -| [UserSeat](./user-seat) | Used outside contracts to access or manipulate offers. | -| [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. | -| [Price Authority](./price-authority) | Gives quotes for prices. | - +| Object | Description | +| ------------------------------------------ | ------------------------------------------------------ | +| [Zoe Service](./zoe) | Deploys and works with smart contracts. | +| [UserSeat](./user-seat) | Used outside contracts to access or manipulate offers. | +| [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. | +| [Price Authority](./price-authority) | Gives quotes for prices. | The Zoe API provides the following libraries: -| Library | Description | -| --- | --- | -| [ZoeHelpers](./zoe-helpers) | Functions that extract common contract code and patterns into reusable helpers. | -| [Ratio Math](./ratio-math) | Functions that let you create and manipulate **[Ratios](./zoe-data-types#ratio)**. | - +| Library | Description | +| --------------------------- | ---------------------------------------------------------------------------------- | +| [ZoeHelpers](./zoe-helpers) | Functions that extract common contract code and patterns into reusable helpers. | +| [Ratio Math](./ratio-math) | Functions that let you create and manipulate **[Ratios](./zoe-data-types#ratio)**. | The Zoe API introduces and uses the following data types: -| Data Type | Description | -| --- | --- | -| [Allocation](./zoe-data-types#allocation) | The **[Amounts](/reference/ertp-api/ertp-data-types#amount)** to be paid out to each seat upon exiting an **Offer**. | -| [AmountKeywordRecord](./zoe-data-types#keywordrecord) | A record in which the property names are **Keywords** and the values are **[Amounts](/reference/ertp-api/ertp-data-types#amount)**. | -| [Handle](./zoe-data-types#handle) | A **Far** object without any methods whose only useful property is its unique identity. | -| [Instance](./zoe-data-types#instance) | A handle to an opaque object that represents a contract instance. | -| [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) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when multiple calls, replacing the trigger value, are expected. | -| [ParsableNumber](./zoe-data-types#parsablenumber) | Defined as a **bigint**, **number**, or **string**. | -| [PriceQuote](./zoe-data-types#pricequote) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when only a single calls is expected. | -| [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. | - - +| Data Type | Description | +| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Allocation](./zoe-data-types#allocation) | The **[Amounts](/reference/ertp-api/ertp-data-types#amount)** to be paid out to each seat upon exiting an **Offer**. | +| [AmountKeywordRecord](./zoe-data-types#keywordrecord) | A record in which the property names are **Keywords** and the values are **[Amounts](/reference/ertp-api/ertp-data-types#amount)**. | +| [Handle](./zoe-data-types#handle) | A **Far** object without any methods whose only useful property is its unique identity. | +| [Instance](./zoe-data-types#instance) | A handle to an opaque object that represents a contract instance. | +| [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) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when multiple calls, replacing the trigger value, are expected. | +| [ParsableNumber](./zoe-data-types#parsablenumber) | Defined as a **bigint**, **number**, or **string**. | +| [PriceQuote](./zoe-data-types#pricequote) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when only a single calls is expected. | +| [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/price-authority.md b/main/reference/zoe-api/price-authority.md index 1bbba0bad..082eff604 100644 --- a/main/reference/zoe-api/price-authority.md +++ b/main/reference/zoe-api/price-authority.md @@ -3,46 +3,51 @@ We rely on **PriceAuthority** oracles. A **PriceAuthority** gives reliable quotes for prices. The quotes might be based on broad surveys of prices across the ecosystem, or might come directly from an AMM (Automatic -Market Maker). A **PriceAuthority** can either give a quote for the current price -across any pair of currencies it knows about, or can immediately return a -**Promise** resolved when a condition is true. For example, a price -crossing some threshold, or at a particular time. It can also provide a +Market Maker). A **PriceAuthority** can either give a quote for the current price +across any pair of currencies it knows about, or can immediately return a +**Promise** resolved when a condition is true. For example, a price +crossing some threshold, or at a particular time. It can also provide a price feed that updates with every price change. - ## E(PriceAuthority).getQuoteIssuer(brandIn, brandOut) + - **brandIn**: **[Brand](/reference/ertp-api/brand)** - **brandOut**: **Brand** - Returns: **[Issuer](/reference/ertp-api/issuer) | Promise<Issuer>** -Gets the ERTP **Issuer** of **[PriceQuotes](./zoe-data-types#pricequote)** for a -given *brandIn*/*brandOut* pair. +Gets the ERTP **Issuer** of **[PriceQuotes](./zoe-data-types#pricequote)** for a +given _brandIn_/_brandOut_ pair. ```js const quoteIssuer = await E(PriceAuthority).getQuoteIssuer( - collateralKit.brand, - loanKit.brand - ); + collateralKit.brand, + loanKit.brand, +); ``` ## E(PriceAuthority).getTimerService(brandIn, brandOut) + - **brandIn**: **[Brand](/reference/ertp-api/brand)** - **brandOut**: **Brand** - Returns: **TimerService | Promise<TimerService>** -Gets the timer used in **[PriceQuotes](./zoe-data-types#pricequote)** for a -given *brandIn*/*brandOut* pair. +Gets the timer used in **[PriceQuotes](./zoe-data-types#pricequote)** for a +given _brandIn_/_brandOut_ pair. ```js -const myTimer = E(PriceAuthority).getTimerService(collateral.brand, loanKit.brand); +const myTimer = E(PriceAuthority).getTimerService( + collateral.brand, + loanKit.brand, +); ``` ## E(PriceAuthority).makeQuoteNotifier(amountIn, brandOut) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **brandOut**: **[Brand](/reference/ertp-api/brand)** - Returns: **ERef<Notifier<[PriceQuote](./zoe-data-types#pricequote)>>** -Be notified of the latest **PriceQuotes** for a given *amountIn*. The issuing +Be notified of the latest **PriceQuotes** for a given _amountIn_. The issuing rate may be very different between **PriceAuthorities**. ```js @@ -50,151 +55,166 @@ const myNotifier = E(PriceAuthority).makeQuoteNotifier(quatloos100, usdBrand); ``` ## E(PriceAuthority).quoteGiven(amountIn, brandOut) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **brandOut**: **[Brand](/reference/ertp-api/brand)** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Gets a quote on-demand corresponding to *amountIn*. +Gets a quote on-demand corresponding to _amountIn_. ```js const quote = await E(PriceAuthority).quoteGiven(moola500, quatloosBrand); ``` ## E(PriceAuthority).quoteWanted(brandIn, amountOut) + - **brandIn**: **[Brand](/reference/ertp-api/brand)** - **amountOut**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Gets a quote on-demand corresponding to *amountOut*. +Gets a quote on-demand corresponding to _amountOut_. ```js const quote = await E(PriceAuthority).quoteWanted(quatloosBrand, moola500); ``` ## E(PriceAuthority).quoteAtTime(deadline, amountIn, brandOut) + - **deadline**: **Timestamp** - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **brandOut**: **[Brand](/reference/ertp-api/brand)** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Resolves after *deadline* passes on the **PriceAuthority**’s **timerService** with the -**PriceQuote** of *amountIn* at that time. Note that *deadline*'s value is a **BigInt**. +Resolves after _deadline_ passes on the **PriceAuthority**’s **timerService** with the +**PriceQuote** of _amountIn_ at that time. Note that _deadline_'s value is a **BigInt**. ```js -const priceQuoteOnThisAtTime = E(PriceAuthority).quoteAtTime(7n, quatloosAmount34, usdBrand); +const priceQuoteOnThisAtTime = E(PriceAuthority).quoteAtTime( + 7n, + quatloosAmount34, + usdBrand, +); ``` ## E(PriceAuthority).quoteWhenGT(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Resolves when a **PriceQuote** of *amountIn* exceeds *amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ exceeds _amountOutLimit_. ```js const quote = E(PriceAuthority).quoteWhenGT( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).quoteWhenGTE(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Resolves when a **PriceQuote** of *amountIn* reaches or exceeds *amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ reaches or exceeds _amountOutLimit_. ```js const quote = E(PriceAuthority).quoteWhenGTE( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).quoteWhenLT(amountIn, amountOutLimit) + - **amountIn** **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit** **Amount** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Resolves when a **PriceQuote** of *amountIn* drops below *amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ drops below _amountOutLimit_. ```js const quote = E(PriceAuthority).quoteWhenLT( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).quoteWhenLTE(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[PriceQuote](./zoe-data-types#pricequote)>** -Resolves when a **PriceQuote** of *amountIn* reaches or drops below *amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ reaches or drops below _amountOutLimit_. ```js const quote = E(PriceAuthority).quoteWhenLTE( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).mutableQuoteWhenGT(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[MutableQuote](./zoe-data-types#mutablequote)>** -Resolves when a **PriceQuote** of *amountIn* exceeds *amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ exceeds _amountOutLimit_. ```js const quote = E(PriceAuthority).mutableQuoteWhenGT( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).mutableQuoteWhenGTE(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[MutableQuote](./zoe-data-types#mutablequote)>** -Resolves when a **PriceQuote** of *amountIn* reaches or exceeds -*amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ reaches or exceeds +_amountOutLimit_. ```js const quote = E(PriceAuthority).mutableQuoteWhenGTE( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).mutableQuoteWhenLT(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[MutableQuote](./zoe-data-types#mutablequote)>** -Resolves when a **PriceQuote** of *amountIn* drops below -*amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ drops below +_amountOutLimit_. ```js const quote = E(PriceAuthority).mutableQuoteWhenLT( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` ## E(PriceAuthority).mutableQuoteWhenLTE(amountIn, amountOutLimit) + - **amountIn**: **[Amount](/reference/ertp-api/ertp-data-types#amount)** - **amountOutLimit**: **Amount** - Returns: **Promise<[MutableQuote](./zoe-data-types#mutablequote)>** -Resolves when a **PriceQuote** of *amountIn* reaches or drops below -*amountOutLimit*. +Resolves when a **PriceQuote** of _amountIn_ reaches or drops below +_amountOutLimit_. ```js const quote = E(PriceAuthority).mutableQuoteWhenLTE( - AmountMath.make(brands.In, 29n), - AmountMath.make(brands.Out, 974n) - ); + AmountMath.make(brands.In, 29n), + AmountMath.make(brands.Out, 974n), +); ``` diff --git a/main/reference/zoe-api/zoe-data-types.md b/main/reference/zoe-api/zoe-data-types.md index 6d7d5d931..f63526720 100644 --- a/main/reference/zoe-api/zoe-data-types.md +++ b/main/reference/zoe-api/zoe-data-types.md @@ -7,12 +7,12 @@ Zoe introduces and uses several data types. **Allocations** represent the **[Amounts](/reference/ertp-api/ertp-data-types#amount)** to be paid out to each seat upon exiting a **Proposal**. -For example, if a seat expected to be paid 5 *Quatloos* and 3 *Widgets* after successfully exiting a **Proposal**, the **Allocation** would look like: +For example, if a seat expected to be paid 5 _Quatloos_ and 3 _Widgets_ after successfully exiting a **Proposal**, the **Allocation** would look like: ```js { - Quatloos: 5n - Widgets: 3n + Quatloos: 5n; + Widgets: 3n; } ``` @@ -58,7 +58,7 @@ is exclusively yours and no one else has access to it. ## Keyword -A **Keyword** is a unique identifier string within a contract for tying together the +A **Keyword** is a unique identifier string within a contract for tying together the **issuers** in its **proposals**, **payments**, and **payouts**. It must be an ASCII-only [identifier](https://developer.mozilla.org/en-US/docs/Glossary/Identifier) and start with an upper case letter in order to avoid collisions with JavaScript properties @@ -67,6 +67,7 @@ such as `toString` when used as a property name in a record. `NaN` and `Infinity` are also not allowed as keywords. + ## KeywordRecord A **KeywordRecord** is a [CopyRecord](/glossary/#copyrecord) in which every property name @@ -78,6 +79,7 @@ Subtypes further constrain property values (for example, an **[Payment](/reference/ertp-api/payment)** or a Promise for a Payment). Users submit their **payments** as **KeywordRecords**: + ```js const aFistfulOfQuatloos = AmountMath.make(quatloosBrand, 1000n); const paymentKeywordRecord = { @@ -87,8 +89,8 @@ const paymentKeywordRecord = { ## 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 +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. @@ -96,7 +98,7 @@ in the **[Payment](/reference/ertp-api/payment)** for veracity. 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 +A **MutableQuote** is an **Amount**-**Payment** pair, where the **Amount** is also the current balance of the **Payment**. ## ParsableNumber @@ -105,28 +107,29 @@ 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 +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 +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: +**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. +- **PriceDescription** wrapped as a **QuoteAuthority** issued payment. + - This lets quotes be shared in a format letting others verify the time and values. ## Ratio **Ratios** are pass-by-value records that consist of a -*numerator* and a *denominator*. Both of these consist of a +_numerator_ and a _denominator_. Both of these consist of a **[AmountValue](/reference/ertp-api/ertp-data-types#amountvalue)** and a **[Brand](/reference/ertp-api/brand)**, just like **[Amounts](/reference/ertp-api/ertp-data-types#amount)**. A **Ratio** cannot have a denominator value of 0. @@ -139,26 +142,26 @@ hour or US dollars for Swiss francs (i.e., an exchange rate ratio). ## TransferPart -**TransferParts** are the individual elements of the *transfer* array passed into the +**TransferParts** are the individual elements of the _transfer_ array passed into the **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** function. Each **TransferPart** represents one or two **[Allocation](#allocation)** changes among existing **[ZCFSeats](./zcfseat)**. Each **TransferPart** consists of 4 elements, each of which can be elided in some cases: -* **fromSeat**?: **ZCFSeat** - The seat from which **amounts** are being taken. -* **toSeat**?: **ZCFSeat** - The seat to which **amounts** are being given. -* **fromAmounts**?: **[AmountKeywordRecord](#keywordrecord)** - The **amounts** which will be taken from the *fromSeat*. -* **toAmounts**?: **AmountKeywordRecord** - The **amounts** which will be given to the *toSeat*. +- **fromSeat**?: **ZCFSeat** - The seat from which **amounts** are being taken. +- **toSeat**?: **ZCFSeat** - The seat to which **amounts** are being given. +- **fromAmounts**?: **[AmountKeywordRecord](#keywordrecord)** - The **amounts** which will be taken from the _fromSeat_. +- **toAmounts**?: **AmountKeywordRecord** - The **amounts** which will be given to the _toSeat_. -If a *fromSeat* is specified, then a *fromAmounts* is required. When you specify a *toSeat* without -specifying a *toAmounts*, it means that the *fromAmount* will be taken from *fromSeat* and given to -*toSeat*. +If a _fromSeat_ is specified, then a _fromAmounts_ is required. When you specify a _toSeat_ without +specifying a _toAmounts_, it means that the _fromAmount_ will be taken from _fromSeat_ and given to +_toSeat_. **TransferParts** that represent one side of a transfer can be created using the helper functions **[fromOnly()](./zoe-helpers#fromonly-fromseat-fromamounts)** or **[toOnly()](./zoe-helpers#toonly-toseat-toamounts)**. Of course, as with any JavaScript datatype, you can also manually create **TransferParts**. -If you manually create a **TransferPart** and don't include the *fromSeat*, *toSeat*, and/or -*fromAmounts* fields, you'll need to set the missing fields to **undefined**. (Note that if you don't -include the *toAmounts* field, there's no need to set it to **undefined**; you can simply omit it.) +If you manually create a **TransferPart** and don't include the _fromSeat_, _toSeat_, and/or +_fromAmounts_ fields, you'll need to set the missing fields to **undefined**. (Note that if you don't +include the _toAmounts_ field, there's no need to set it to **undefined**; you can simply omit it.) From d5e8189ad38c6e72630adf7463189b792dab2224 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Thu, 21 Mar 2024 15:14:11 -0500 Subject: [PATCH 2/2] docs: price authority clean-up - PriceAuthorityRegistryAdmin reference - selected BootstrapPermissions += priceAuthority - prune chainlink integration; dup API - prune out-dated / redundant Board docs - refine price authority API link - nav: move price authority under deployed contracts - move price quote data types from zoe to price-authority - add vats to deployed contracts; esp priceAuthority --- main/.vitepress/config.mjs | 12 +- main/guides/chainlink-integration.md | 66 +--------- main/guides/coreeval/permissions.md | 12 +- main/guides/zoe/actual-contracts/index.md | 19 ++- main/guides/zoe/price-authority.md | 3 +- main/reference/repl/board.md | 96 +------------- main/reference/repl/priceAuthority.md | 118 +----------------- main/reference/zoe-api/index.md | 3 - .../zoe-api/price-authority-admin.md | 19 +++ main/reference/zoe-api/price-authority.md | 35 ++++++ main/reference/zoe-api/zoe-data-types.md | 35 ------ 11 files changed, 91 insertions(+), 327 deletions(-) create mode 100644 main/reference/zoe-api/price-authority-admin.md diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index de0c82bb8..53ccb3296 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -289,14 +289,14 @@ export default defineConfig({ link: '/guides/zoe/actual-contracts/', collapsed: true, items: [ - { - text: 'Deployed Zoe Contracts', - link: '/guides/zoe/actual-contracts/', - }, { text: 'PSM Contract', link: '/guides/zoe/actual-contracts/PSM', }, + { + text: 'PriceAuthority Object', + link: '/reference/zoe-api/price-authority', + }, ], }, { @@ -396,10 +396,6 @@ export default defineConfig({ }, { text: 'ZCFSeat Object', link: '/reference/zoe-api/zcfseat' }, { text: 'ZCFMint Object', link: '/reference/zoe-api/zcfmint' }, - { - text: 'PriceAuthority Object', - link: '/reference/zoe-api/price-authority', - }, { text: 'ZoeHelper Functions', link: '/reference/zoe-api/zoe-helpers', diff --git a/main/guides/chainlink-integration.md b/main/guides/chainlink-integration.md index 17ec863c0..5045ed3fc 100644 --- a/main/guides/chainlink-integration.md +++ b/main/guides/chainlink-integration.md @@ -1,63 +1,5 @@ -# Chainlink Integration +See -This document explains how to consume [Chainlink -oracles](https://chain.link) when unit testing, integration testing, and -actually on-chain. - -## Overview - -Using Chainlink on Agoric provides two main features: -- Price feeds are exposed on Agoric via the on-chain `home.priceAuthority`. This is an - officially-sponsored [price authority](/guides/zoe/price-authority) built - from aggregating several Chainlink nodes. -- [Chainlink's Any API](https://docs.chain.link/docs/request-and-receive-data) - can initiate a job on a single oracle and return its results - -We have tested these features with [actual Chainlink oracle -software](https://github.com/Agoric/dapp-oracle/blob/HEAD/chainlink-agoric/README.md). - -**Note**: Chainlink has not yet (as of Nov 16, 2020) finished setting up an incentivized testnet for established Chainlink node operators to connect to Agoric. - -## Price Authority - -To test your contract against a locally-simulated price authority, just follow -the instructions in [the Price Authority API](/reference/zoe-api/price-authority). - -To use the curated on-chain price authority, see `home.priceAuthority`. For -example, to get a quote for selling `30 Testnet.$LINK` in `Testnet.$USD`: - -(Note that this is a mock price until there are actual Chainlink nodes on the -testnet). - -```js -const linkIssuer = E(home.wallet).getIssuer('Testnet.$LINK'); -const linkBrand = await E(linkIssuer).getBrand(); -const linkAmount = AmountMath.make(linkBrand, 30 * 10 ** 18); -const usdBrand = await E(E(home.wallet).getIssuer('Testnet.$USD')).getBrand(); -const { quoteAmount: { value: [{ amountOut: usdAmount, timestamp }] } } = await E(home.priceAuthority).quoteGiven(linkAmount, usdBrand); -``` - -## Any API - -To use Chainlink's Any API, you need to get an instance of the -[Low-level Oracle Query Contract](/guides/zoe/contracts/oracle) and submit a -query of the form: - -```js -{ - jobId: , - params: { ... } -} -``` - -The oracle node returns its result, which is a JSONable value such as a string. -This is sent as your query's reply. - -You can test these queries against a locally-running Chainlink node that you -control. Follow [the Chainlink integration -instructions](https://github.com/Agoric/dapp-oracle/blob/HEAD/chainlink-agoric/README.md) -to set it up. - -There is also a more limited local node that emulates part of the Chainlink API -without having to run Docker containers. This is the [local (mock) builtin -oracle](https://github.com/agoric/dapp-oracle#running-a-local-builtin-oracle). +- [Price Authorty Guide](./zoe/price-authority) +- [PriceAuthority API](../reference/zoe-api/price-authority) +- [Deployed Zoe Contracts](./zoe/actual-contracts/) diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index 56730f990..402c67f52 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -36,6 +36,12 @@ In the top level promise space, we have: - **agoricNames**: read-only access to the [agoricNames](../integration/name-services.md#agoricnames-agoricnamesadmin-well-known-names) name service. +- **agoricNamesAdmin**: admin / update access to **agoricNames** and the name hubs it contains. + **Warning: this includes the right to over-write existing bindings to instances, brands, etc.** + +- **bankManager**: to manage reflection of cosmos + assets as ERTP assets: to register an issuer to correspond to a denom or to get a bank of purses for any address. **Warning: this includes the right to spend assets for any account.** + - **board**: the [board](../integration/name-services.md#the-board-publishing-under-arbitrary-names) name service. **Note: the board only grows; no mechanism to reclaim storage has been established.** @@ -45,10 +51,8 @@ In the top level promise space, we have: - **chainTimerService**: for getting the current timer and setting timer wake-ups; for example, at the conclusion of a governance vote. **Note: this includes the right to schedule infinitely repeating events.** -- **agoricNamesAdmin**: admin / update access to **agoricNames** and the name hubs it contains. - **Warning: this includes the right to over-write existing bindings to instances, brands, etc.** +- **priceAuthority**: access to get price quotes and triggers; see [Price Authority Guide](../zoe/price-authority). -- **bankManager**: to manage reflection of cosmos - assets as ERTP assets: to register an issuer to correspond to a denom or to get a bank of purses for any address. **Warning: this includes the right to spend assets for any account.** +- **priceAuthorityAdmin**: access to add and replace sources of price quotes using [E(priceAuthorityAdmin).registerPriceAuthority()](../../reference/zoe-api/price-authority-admin#e-priceauthorityregistryadmin-registerpriceauthority-priceauthority-brandin-brandout-force) - **zoe**: the Zoe service diff --git a/main/guides/zoe/actual-contracts/index.md b/main/guides/zoe/actual-contracts/index.md index 28d2a9699..bc6acd884 100644 --- a/main/guides/zoe/actual-contracts/index.md +++ b/main/guides/zoe/actual-contracts/index.md @@ -13,8 +13,25 @@ In the [mainnet-1B release of agoric-sdk](https://github.com/Agoric/agoric-sdk/r | [PSM](./PSM) | The Parity Stability Module (PSM) supports efficiently minting and burning Inter Stable Tokens (ISTs) in exchange for approved external stable tokens. | | vaultFactory | allows users to mint IST backed by collateral such as ATOM; hands off vaults to auctioneer when value of collateral in a vault falls below a governed threshold | | auctioneer | auctions collateral from liquidated vaults | -| fluxAggregator | aggregates prices from oracle oeprators | +| fluxAggregator | a [Price Authority](../price-authority) that aggregates prices from oracle oeprators | | scaledPriceAuthoriy | provides prices for tradeable assets such as ATOM in terms of idealized "oracle ATOM" prices from oracle operators | | feeDistributor | collects fees from Inter Protocol contracts and distributes to reserve and/or stakers | | assetReserve | holds assets in reserve to back IST | | walletFactory | executes Zoe offers on behalf of users | + +## Deployed Vat Services + +Other services run in vats that are not contracts. + +| vat | services | +| -------------- | -------------------------------------------------------------------------------------- | +| bootstrap | initial vat. also runs [core eval scripts](../../coreeval/) | +| vatAdmin | creates, [upgrades](../../zoe/contract-upgrade), and terminates vats | +| agoricNames | the `agoricNames` [name service](../../integration/name-services) | +| bank | connects cosmos denoms with ERTP Brands/Issuers/Mints | +| board | the `board` [name service](../../integration/name-services) | +| bridge | chainStorage etc. | +| priceAuthority | registers [Price Authorities](../price-authority) and routes requests for price quotes | +| provisioning | `namesByAddress` [name service](../../integration/name-services) | +| timer | `chainTimerService` | +| zoe | the Zoe Service | diff --git a/main/guides/zoe/price-authority.md b/main/guides/zoe/price-authority.md index 73bedaa3e..37ac1a530 100644 --- a/main/guides/zoe/price-authority.md +++ b/main/guides/zoe/price-authority.md @@ -56,5 +56,4 @@ by changing its trigger levels or by cancelling it. ## API Reference -The Price Authority API reference is a section of the [Zoe API reference](/reference/zoe-api/price-authority) - +See [Price Authority API](/reference/zoe-api/price-authority). diff --git a/main/reference/repl/board.md b/main/reference/repl/board.md index 8944cf601..43ffac314 100644 --- a/main/reference/repl/board.md +++ b/main/reference/repl/board.md @@ -1,95 +1 @@ -# The Agoric Board - -## Introduction - -The Board is a shared, on-chain location that is where users post an object as a value and make -it accessible to others. When a user posts a value, they receive a unique ID -for that value. Others can get the value just by knowing the ID. You can make -an ID known by any communication method; private email, a DM or other private -message, an email blast to a mailing list or many individuals, listing it on a website, etc. - -In particular, the Board is frequently used to give others access to deposit -facets. After you post a deposit facet object to the Board, you distribute its -Board ID string as widely as you'd like. Anyone who has that ID can use it to -get access to its value, the deposit facet object. They can then safely deposit -assets into the facet's associated purse without being able to withdraw assets -from the purse or check its balance. - -The `ids()` method returns all of the Board's currently used IDs. -This means anyone can access any Board-stored value. The Board is public, -not private. - -Note that when calling from the REPL's `home` object, you must use -the [`E` syntax](/guides/js-programming/eventual-send) -as shown below. - -## `E(home.board).getId(value)` -- `value` `{ any }` -- Returns: `{ string }` - -If the `value` is present in the Board, this method returns its Board-associated ID value. - -If the `value` is **not** present in the Board, this method adds it to the Board and assigns it -an associated ID value. It returns the new ID value. - -```js -// Create an ID for an object that you want to make public -command[1] E(home.board).getId(auctionInvitation) -history[1] "1403739213" -// The value auctionInvitation (an Invitation object) now has the ID "1403739213" -command[2] E(home.board).getId(auctionInvitation) -history[2] "1403739213" -``` - -## `E(home.board).getValue(id)` -- `id` `{ string }` -- Returns: `{ any }` - -Looks up the `id` value in the Board and returns the Board-associated value for that ID. - -With respect to the `CRC` used in an error message below, an ID has two parts, the raw id -and a [CRC](https://en.wikipedia.org/wiki/Cyclic_redundancy_check). The CRC error -happens when the passed-in id's CRC value is checked. The alleged ID is split into its -two parts, and if the CRC in the alleged ID doesn't match the CRC produced at this time -from the raw ID value, it throws the error. - -Errors: -- If the `id` value is not a string, errors with the message "id must be string" and a log of the failing `id` that was passed in. -- If the `id` value has too few digits, errors with the message "id must consist of at least 3 digits". -- If the `id` value has a different CRC value than the stored one, errors with the message "id is probably a typo, cannot verify CRC". -- If the `id` value is not in the Board, errors with the message "board does not have id: [id]". -```js -// Continuing from the example above in getValue(), the id returns its associated value -command[3] E(home.board).getValue("1403739213") -// Returns the "abc" value -history[3] [Alleged: presence o-102]{} -``` - -## `E(home.board).has(value)` -- `value` `{ any }` -- Returns `{ boolean }` - -Returns `true` if the specified value has an associated Board ID. - -```js -// Pass an id, not a value, so returns false -command[4] E(home.board).has("1403739213") -history[4] false -// Pass a value that does have an id in the Board, so returns true -command[5] E(home.board).has(auctionInvitation) -history[5] true -``` - -## `E(home.board).ids()` -- Returns: `{ Array of strings }` - -Returns an array of all IDs in the Board. Remember, the Board is public, so -anyone can access anything in it. - -```js -command[6] E(home.board).ids() -history[6] ["604346717","381205908","1667979430","1576549616","1532665031", - "727995140","371571443","1456154132","500716545","815824725", - "262188032","1265655452","1202180815","813441138","605437304", - "1403739213"] -``` +see [Board Name Service](../../guides/integration/name-services#the-board-publishing-under-arbitrary-names) diff --git a/main/reference/repl/priceAuthority.md b/main/reference/repl/priceAuthority.md index 54460e613..8617dc9bf 100644 --- a/main/reference/repl/priceAuthority.md +++ b/main/reference/repl/priceAuthority.md @@ -1,117 +1 @@ -# Price Authority - -`PriceAuthority` is an object that mints `PriceQuotes` and handles -triggers and notifiers for changes in the price. - -`PriceAuthority` objects use timer services. You should be familiar with the objects -and methods in the [REPL TimerService document](./timerServices) - -## Price quote objects - -Before discussing `PriceAuthority` and `PriceAuthorityAdmin` methods, we need to -cover the other price-based objects and methods they interact with. - -A `PriceQuote` is an object with two properties: -- `quoteAmount`: An `Amount` whose value is a `PriceQuoteValue`. -- `quotePayment`: The `quoteAmount` wrapped as a `Payment`. It is either an `ERef` or `null`. - -The `quoteAmount` describes a price available at a particular time. So that price can be shared by -recipients with others, its associated `quotePayment` is the same value wrapped as a payment from the QuoteIssuer. -This lets other recipients validate the quote is from the intended source. - -Accessing the `quotePayment` value requires a round trip, so `quoteAmount`is included for the original recipient's -convenience. They know who they received it from and don't need to validate provenance. - -A `PriceQuoteValue` is the `Value` part of a `quoteAmount`. Its properties are: -- `amountIn` `{ 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` `{ any= }`: Additional conditions for the quote - -## `getQuoteIssuer(brandIn, brandOut)` - - `brandIn` `{ Brand }` - - `brandOut` `{ Brand }` - - Returns: `{ ERef }` - -Returns the ERTP `PriceQuote` issuer for the specified brands pair. - -## `getTimerService(brandIn, brandOut)` - - `brandIn` `{ Brand }` - - `brandOut` `{ Brand }` - - Returns: `{ ERef }` - -Returns the timer used in `PriceQuotes` for the specified brands. - -## `makeQuoteNotifier(amountIn, brandOut)` -- `amountIn` `{ Amount }` -- `brandOut` `{ Brand }` -- Returns: `{ ERef> }` - -Be notified of the latest `PriceQuotes` for the given `amountIn`. -Different `PriceAuthories` may issue these at very different rates. - -## `getPriceNotifier(brandIn, brandOut)` - - `brandIn` `{ Brand }` - - `brandOut` `{ Brand }` - - Returns: `{ Notifier }` - -Returns a notifier for the specified brands. Different `PriceAuthories` may -issue these at very different rates. - -## `quoteGiven(amountIn, brandOut)` - - `amountIn` `{ Amount }` - - `brandOut` `{ Brand }` - - Returns: `{ Promise }` - -Returns a price quote corresponding to the specified amount in the specified brand. -`quoteGiven() essentially asks "how much `brandOut` would I get for `amountIn`. - -Note that `quoteGiven()` and `quoteWanted()` can give different answers for not-trivial amounts. - -## `quoteWanted(brandIn, amountOut)` - - `brandIn` `{ Brand }` - - `amountOut` `{ Amount }` - - Returns: `{ Promise }` - -Returns a price quote for the specified amount in the specified brand. -`quoteWanted() essentially asks "how much `brandIn` would I have to pay to get `amountOut`. - -Note that `quoteGiven()` and `quoteWanted()` can give different answers for not-trivial amounts. - -## `quoteAtTime(deadline, amountIn, brandOut)` - - `deadline` `{ Timestamp }` - - `amountIn` `{ Amount }` - - `brandOut` `{ Brand }` - - Returns: `{ Promise }` - -Resolves after `deadline` passes on the Price Authority's `timerService` -with `amountIn`'s price quote at that time. - -## `quoteWhenGT(amountIn, amountOutLimit)` -- `amountIn` `{ Amount }` -- `amountOutLimit `{ Amount }` -- Returns: `{ Promise }` - -Resolve when a price quote of `amountIn` exceeds `amountOutLimit` - -## `quoteWhenGTE(amountIn, amountOutLimit)` -- `amountIn` `{ Amount }` -- `amountOutLimit `{ Amount }` -- Returns: `{ Promise }` - -Resolve when a price quote of `amountIn` reaches or exceeds `amountOutLimit` - -## `quoteWhenLTE(amountIn, amountOutLimit)` -- `amountIn` `{ Amount }` -- `amountOutLimit `{ Amount }` -- Returns: `{ Promise }` - -Resolve when a price quote of `amountIn` reaches or drops below `amountOutLimit` - -## `quoteWhenLT(amountIn, amountOutLimit)` -- `amountIn` `{ Amount }` -- `amountOutLimit `{ Amount }` -- Returns: `{ Promise }` - -Resolve when a price quote of `amountIn` drops to below `amountOutLimit`. +see [Price Authority Guide](../../guides/zoe/price-authority), [PriceAuthority API](../zoe-api/price-authority) diff --git a/main/reference/zoe-api/index.md b/main/reference/zoe-api/index.md index d97d63b16..877a815e7 100644 --- a/main/reference/zoe-api/index.md +++ b/main/reference/zoe-api/index.md @@ -19,7 +19,6 @@ 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. | -| [Price Authority](./price-authority) | Gives quotes for prices. | The Zoe API provides the following libraries: @@ -39,8 +38,6 @@ 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) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when multiple calls, replacing the trigger value, are expected. | | [ParsableNumber](./zoe-data-types#parsablenumber) | Defined as a **bigint**, **number**, or **string**. | -| [PriceQuote](./zoe-data-types#pricequote) | Statement from a **[PriceAuthority](./price-authority)** as to the current price level at a particular time when only a single calls is expected. | | [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/price-authority-admin.md b/main/reference/zoe-api/price-authority-admin.md new file mode 100644 index 000000000..5bc35623d --- /dev/null +++ b/main/reference/zoe-api/price-authority-admin.md @@ -0,0 +1,19 @@ +## E(PriceAuthorityRegistryAdmin).registerPriceAuthority(priceAuthority, brandIn, brandOut, force) + +• **registerPriceAuthority**: (`pa`: `ERef`\<`PriceAuthority`\>, `brandIn`: `Brand`\<`AssetKind`\>, `brandOut`: `Brand`\<`AssetKind`\>, `force?`: `boolean`) => `Promise`\<`Deleter`\> + +Add a unique price authority for a given pair. + +If the pair is already registered, throw unless `force` is `true`. + +##### Returns + +`Promise`\<`Deleter`\> + +#### Defined in + +[priceAuthorityRegistry.js:27](https://github.com/Agoric/agoric-sdk/blob/a8c322206/packages/vats/src/priceAuthorityRegistry.js#L27) + +## E(Deleter).delete() + +• **delete**: () => `void` diff --git a/main/reference/zoe-api/price-authority.md b/main/reference/zoe-api/price-authority.md index 082eff604..39cbc8038 100644 --- a/main/reference/zoe-api/price-authority.md +++ b/main/reference/zoe-api/price-authority.md @@ -218,3 +218,38 @@ const quote = E(PriceAuthority).mutableQuoteWhenLTE( AmountMath.make(brands.Out, 974n), ); ``` + +## 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. diff --git a/main/reference/zoe-api/zoe-data-types.md b/main/reference/zoe-api/zoe-data-types.md index f63526720..d1ffba631 100644 --- a/main/reference/zoe-api/zoe-data-types.md +++ b/main/reference/zoe-api/zoe-data-types.md @@ -87,45 +87,10 @@ const paymentKeywordRecord = { }; ``` -## 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**. - ## 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 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. - ## Ratio **Ratios** are pass-by-value records that consist of a