Skip to content

Commit d495bc1

Browse files
dckcdckc
authored
Merge pull request #1022 from Agoric/dc-price-authority
Price Authority updates
2 parents 8d909e6 + d5e8189 commit d495bc1

File tree

11 files changed

+222
-440
lines changed

11 files changed

+222
-440
lines changed

‎main/.vitepress/config.mjs

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -289,14 +289,14 @@ export default defineConfig({
289289
link: '/guides/zoe/actual-contracts/',
290290
collapsed: true,
291291
items: [
292-
{
293-
text: 'Deployed Zoe Contracts',
294-
link: '/guides/zoe/actual-contracts/',
295-
},
296292
{
297293
text: 'PSM Contract',
298294
link: '/guides/zoe/actual-contracts/PSM',
299295
},
296+
{
297+
text: 'PriceAuthority Object',
298+
link: '/reference/zoe-api/price-authority',
299+
},
300300
],
301301
},
302302
{
@@ -396,10 +396,6 @@ export default defineConfig({
396396
},
397397
{ text: 'ZCFSeat Object', link: '/reference/zoe-api/zcfseat' },
398398
{ text: 'ZCFMint Object', link: '/reference/zoe-api/zcfmint' },
399-
{
400-
text: 'PriceAuthority Object',
401-
link: '/reference/zoe-api/price-authority',
402-
},
403399
{
404400
text: 'ZoeHelper Functions',
405401
link: '/reference/zoe-api/zoe-helpers',

‎main/guides/chainlink-integration.md

Lines changed: 4 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,5 @@
1-
# Chainlink Integration
1+
See
22

3-
This document explains how to consume [Chainlink
4-
oracles](https://chain.link) when unit testing, integration testing, and
5-
actually on-chain.
6-
7-
## Overview
8-
9-
Using Chainlink on Agoric provides two main features:
10-
- Price feeds are exposed on Agoric via the on-chain `home.priceAuthority`. This is an
11-
officially-sponsored [price authority](/guides/zoe/price-authority) built
12-
from aggregating several Chainlink nodes.
13-
- [Chainlink's Any API](https://docs.chain.link/docs/request-and-receive-data)
14-
can initiate a job on a single oracle and return its results
15-
16-
We have tested these features with [actual Chainlink oracle
17-
software](https://github.com/Agoric/dapp-oracle/blob/HEAD/chainlink-agoric/README.md).
18-
19-
**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.
20-
21-
## Price Authority
22-
23-
To test your contract against a locally-simulated price authority, just follow
24-
the instructions in [the Price Authority API](/reference/zoe-api/price-authority).
25-
26-
To use the curated on-chain price authority, see `home.priceAuthority`. For
27-
example, to get a quote for selling `30 Testnet.$LINK` in `Testnet.$USD`:
28-
29-
(Note that this is a mock price until there are actual Chainlink nodes on the
30-
testnet).
31-
32-
```js
33-
const linkIssuer = E(home.wallet).getIssuer('Testnet.$LINK');
34-
const linkBrand = await E(linkIssuer).getBrand();
35-
const linkAmount = AmountMath.make(linkBrand, 30 * 10 ** 18);
36-
const usdBrand = await E(E(home.wallet).getIssuer('Testnet.$USD')).getBrand();
37-
const { quoteAmount: { value: [{ amountOut: usdAmount, timestamp }] } } = await E(home.priceAuthority).quoteGiven(linkAmount, usdBrand);
38-
```
39-
40-
## Any API
41-
42-
To use Chainlink's Any API, you need to get an instance of the
43-
[Low-level Oracle Query Contract](/guides/zoe/contracts/oracle) and submit a
44-
query of the form:
45-
46-
```js
47-
{
48-
jobId: <Chainlink JobId>,
49-
params: { ...<job parameters> }
50-
}
51-
```
52-
53-
The oracle node returns its result, which is a JSONable value such as a string.
54-
This is sent as your query's reply.
55-
56-
You can test these queries against a locally-running Chainlink node that you
57-
control. Follow [the Chainlink integration
58-
instructions](https://github.com/Agoric/dapp-oracle/blob/HEAD/chainlink-agoric/README.md)
59-
to set it up.
60-
61-
There is also a more limited local node that emulates part of the Chainlink API
62-
without having to run Docker containers. This is the [local (mock) builtin
63-
oracle](https://github.com/agoric/dapp-oracle#running-a-local-builtin-oracle).
3+
- [Price Authorty Guide](./zoe/price-authority)
4+
- [PriceAuthority API](../reference/zoe-api/price-authority)
5+
- [Deployed Zoe Contracts](./zoe/actual-contracts/)

‎main/guides/coreeval/permissions.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,12 @@ In the top level promise space, we have:
3636

3737
- **agoricNames**: read-only access to the [agoricNames](../integration/name-services.md#agoricnames-agoricnamesadmin-well-known-names) name service.
3838

39+
- **agoricNamesAdmin**: admin / update access to **agoricNames** and the name hubs it contains.
40+
**Warning: this includes the right to over-write existing bindings to instances, brands, etc.**
41+
42+
- **bankManager**: to manage reflection of cosmos
43+
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.**
44+
3945
- **board**: the [board](../integration/name-services.md#the-board-publishing-under-arbitrary-names) name service.
4046
**Note: the board only grows; no mechanism to reclaim storage has been established.**
4147

@@ -45,10 +51,8 @@ In the top level promise space, we have:
4551
- **chainTimerService**: for getting the current timer and setting timer wake-ups; for example, at the conclusion of a governance vote.
4652
**Note: this includes the right to schedule infinitely repeating events.**
4753

48-
- **agoricNamesAdmin**: admin / update access to **agoricNames** and the name hubs it contains.
49-
**Warning: this includes the right to over-write existing bindings to instances, brands, etc.**
54+
- **priceAuthority**: access to get price quotes and triggers; see [Price Authority Guide](../zoe/price-authority).
5055

51-
- **bankManager**: to manage reflection of cosmos
52-
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.**
56+
- **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)
5357

5458
- **zoe**: the Zoe service

‎main/guides/zoe/actual-contracts/index.md

Lines changed: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,36 @@
22

33
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.
44

5-
| Contract | Description |
6-
| --- | --- |
7-
| centralSupply | used to initialize the vbank IST purse balance based on supply reported from the cosmos x/bank module |
8-
| mintHolder | use to hold mints for BLD as well as inter-chain assets such as ATOM, USDC, and USDT |
9-
| committee | represents the Economic Committee that governs Inter Protocol parameters |
10-
| binaryVoteCounter | instantiated once for each question that a committee votes on |
11-
| econCommitteeCharter | controls what questions can be put to the economic committee |
12-
| contractGovernor | each governed contract is started by starting its governor |
13-
| [PSM](./PSM) | The Parity Stability Module (PSM) supports efficiently minting and burning Inter Stable Tokens (ISTs) in exchange for approved external stable tokens. |
14-
| 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 |
15-
| auctioneer | auctions collateral from liquidated vaults |
16-
| fluxAggregator | aggregates prices from oracle oeprators |
17-
| scaledPriceAuthoriy | provides prices for tradeable assets such as ATOM in terms of idealized "oracle ATOM" prices from oracle operators |
18-
| feeDistributor | collects fees from Inter Protocol contracts and distributes to reserve and/or stakers |
19-
| assetReserve | holds assets in reserve to back IST |
20-
| walletFactory | executes Zoe offers on behalf of users |
5+
| Contract | Description |
6+
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7+
| centralSupply | used to initialize the vbank IST purse balance based on supply reported from the cosmos x/bank module |
8+
| mintHolder | use to hold mints for BLD as well as inter-chain assets such as ATOM, USDC, and USDT |
9+
| committee | represents the Economic Committee that governs Inter Protocol parameters |
10+
| binaryVoteCounter | instantiated once for each question that a committee votes on |
11+
| econCommitteeCharter | controls what questions can be put to the economic committee |
12+
| contractGovernor | each governed contract is started by starting its governor |
13+
| [PSM](./PSM) | The Parity Stability Module (PSM) supports efficiently minting and burning Inter Stable Tokens (ISTs) in exchange for approved external stable tokens. |
14+
| 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 |
15+
| auctioneer | auctions collateral from liquidated vaults |
16+
| fluxAggregator | a [Price Authority](../price-authority) that aggregates prices from oracle oeprators |
17+
| scaledPriceAuthoriy | provides prices for tradeable assets such as ATOM in terms of idealized "oracle ATOM" prices from oracle operators |
18+
| feeDistributor | collects fees from Inter Protocol contracts and distributes to reserve and/or stakers |
19+
| assetReserve | holds assets in reserve to back IST |
20+
| walletFactory | executes Zoe offers on behalf of users |
21+
22+
## Deployed Vat Services
23+
24+
Other services run in vats that are not contracts.
25+
26+
| vat | services |
27+
| -------------- | -------------------------------------------------------------------------------------- |
28+
| bootstrap | initial vat. also runs [core eval scripts](../../coreeval/) |
29+
| vatAdmin | creates, [upgrades](../../zoe/contract-upgrade), and terminates vats |
30+
| agoricNames | the `agoricNames` [name service](../../integration/name-services) |
31+
| bank | connects cosmos denoms with ERTP Brands/Issuers/Mints |
32+
| board | the `board` [name service](../../integration/name-services) |
33+
| bridge | chainStorage etc. |
34+
| priceAuthority | registers [Price Authorities](../price-authority) and routes requests for price quotes |
35+
| provisioning | `namesByAddress` [name service](../../integration/name-services) |
36+
| timer | `chainTimerService` |
37+
| zoe | the Zoe Service |

‎main/guides/zoe/price-authority.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,5 +56,4 @@ by changing its trigger levels or by cancelling it.
5656

5757
## API Reference
5858

59-
The Price Authority API reference is a section of the [Zoe API reference](/reference/zoe-api/price-authority)
60-
59+
See [Price Authority API](/reference/zoe-api/price-authority).

‎main/reference/repl/board.md

Lines changed: 1 addition & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1 @@
1-
# The Agoric Board
2-
3-
## Introduction
4-
5-
The Board is a shared, on-chain location that is where users post an object as a value and make
6-
it accessible to others. When a user posts a value, they receive a unique ID
7-
for that value. Others can get the value just by knowing the ID. You can make
8-
an ID known by any communication method; private email, a DM or other private
9-
message, an email blast to a mailing list or many individuals, listing it on a website, etc.
10-
11-
In particular, the Board is frequently used to give others access to deposit
12-
facets. After you post a deposit facet object to the Board, you distribute its
13-
Board ID string as widely as you'd like. Anyone who has that ID can use it to
14-
get access to its value, the deposit facet object. They can then safely deposit
15-
assets into the facet's associated purse without being able to withdraw assets
16-
from the purse or check its balance.
17-
18-
The `ids()` method returns all of the Board's currently used IDs.
19-
This means anyone can access any Board-stored value. The Board is public,
20-
not private.
21-
22-
Note that when calling from the REPL's `home` object, you must use
23-
the [`E` syntax](/guides/js-programming/eventual-send)
24-
as shown below.
25-
26-
## `E(home.board).getId(value)`
27-
- `value` `{ any }`
28-
- Returns: `{ string }`
29-
30-
If the `value` is present in the Board, this method returns its Board-associated ID value.
31-
32-
If the `value` is **not** present in the Board, this method adds it to the Board and assigns it
33-
an associated ID value. It returns the new ID value.
34-
35-
```js
36-
// Create an ID for an object that you want to make public
37-
command[1] E(home.board).getId(auctionInvitation)
38-
history[1] "1403739213"
39-
// The value auctionInvitation (an Invitation object) now has the ID "1403739213"
40-
command[2] E(home.board).getId(auctionInvitation)
41-
history[2] "1403739213"
42-
```
43-
44-
## `E(home.board).getValue(id)`
45-
- `id` `{ string }`
46-
- Returns: `{ any }`
47-
48-
Looks up the `id` value in the Board and returns the Board-associated value for that ID.
49-
50-
With respect to the `CRC` used in an error message below, an ID has two parts, the raw id
51-
and a [CRC](https://en.wikipedia.org/wiki/Cyclic_redundancy_check). The CRC error
52-
happens when the passed-in id's CRC value is checked. The alleged ID is split into its
53-
two parts, and if the CRC in the alleged ID doesn't match the CRC produced at this time
54-
from the raw ID value, it throws the error.
55-
56-
Errors:
57-
- 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.
58-
- If the `id` value has too few digits, errors with the message "id must consist of at least 3 digits".
59-
- 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".
60-
- If the `id` value is not in the Board, errors with the message "board does not have id: [id]".
61-
```js
62-
// Continuing from the example above in getValue(), the id returns its associated value
63-
command[3] E(home.board).getValue("1403739213")
64-
// Returns the "abc" value
65-
history[3] [Alleged: presence o-102]{}
66-
```
67-
68-
## `E(home.board).has(value)`
69-
- `value` `{ any }`
70-
- Returns `{ boolean }`
71-
72-
Returns `true` if the specified value has an associated Board ID.
73-
74-
```js
75-
// Pass an id, not a value, so returns false
76-
command[4] E(home.board).has("1403739213")
77-
history[4] false
78-
// Pass a value that does have an id in the Board, so returns true
79-
command[5] E(home.board).has(auctionInvitation)
80-
history[5] true
81-
```
82-
83-
## `E(home.board).ids()`
84-
- Returns: `{ Array of strings }`
85-
86-
Returns an array of all IDs in the Board. Remember, the Board is public, so
87-
anyone can access anything in it.
88-
89-
```js
90-
command[6] E(home.board).ids()
91-
history[6] ["604346717","381205908","1667979430","1576549616","1532665031",
92-
"727995140","371571443","1456154132","500716545","815824725",
93-
"262188032","1265655452","1202180815","813441138","605437304",
94-
"1403739213"]
95-
```
1+
see [Board Name Service](../../guides/integration/name-services#the-board-publishing-under-arbitrary-names)

0 commit comments

Comments
 (0)