Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Price Authority updates #1022

Merged
merged 2 commits into from
Mar 22, 2024
Merged

Price Authority updates #1022

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6dd2d16
style: markdown lint
dckc Mar 21, 2024
d5e8189
docs: price authority clean-up
dckc Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions main/.vitepress/config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
],
},
{
Expand Down Expand Up @@ -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',
Expand Down
66 changes: 4 additions & 62 deletions main/guides/chainlink-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: <Chainlink JobId>,
params: { ...<job parameters> }
}
```

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/)
12 changes: 8 additions & 4 deletions main/guides/coreeval/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.**

Expand All @@ -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
49 changes: 33 additions & 16 deletions main/guides/zoe/actual-contracts/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,36 @@

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 | 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 |
3 changes: 1 addition & 2 deletions main/guides/zoe/price-authority.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
96 changes: 1 addition & 95 deletions main/reference/repl/board.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading