diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 8f0cc45..befdb1a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -68,32 +68,17 @@ module.exports = { auto: false, nav: [ { - title: 'Using the Oracle Module', + title: 'Documentation', children: [ { - title: 'Tutorial', + title: 'Atom/USD Tutorial', directory: true, path: '/tutorial', }, - ], - }, - { - title: 'Oracle Module Docs', - children: [ - { - title: 'Modules', - directory: true, - path: '/modules', - }, - ], - }, - { - title: 'Test with Starport', - children: [ { - title: 'Demo app guide', + title: 'Oracle Module Docs', directory: true, - path: '/starport', + path: '/modules/oracle', }, ], }, diff --git a/docs/README.md b/docs/README.md index 73a9289..b9c2872 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,19 +10,23 @@ aside: true The Oracle module allows validators to run arbitrary off-chain worker processes and report the results for inclusion in the on-chain state. -For example, you can fetch data from external exchange apis and use it inside on-chain smart contracts. +Unlike onchain smart contracts, offchain workers are able to run non-deterministic code, like fetching exchange price data via an api call, and long-running computations, i.e. AI alogrithms or graph analysis. All of the validators are expected to run the workers and come to a consensus on the results. Exactly how consensus is reached can be decided by the app developer. -## Getting Started +The module is inspired by the [Terra Oracle Module](https://docs.terra.money/dev/spec-oracle.html#concepts) as well as a more recent iteration of it by [Sommelier](https://github.com/PeggyJV/sommelier/tree/main/x/oracle). -- **[The Tutoral](./tutorial/)** is a good place to get started. +## Getting Started -## Module Documentation +- **[The Tutoral](./tutorial)** goes through the steps required to incorporate the Oracle module into your codebase. As an example, we fetch the Atom/USDC price data from Binance and write it on-chain. - **[Module Documentation](./modules/oracle)**: Describes the high-level architecture and module apis. +## Learn More About Oracles + +- This [Terra Blog Post](https://medium.com/stakewithus/terra-oracle-voter-by-stakewith-us-d54a1321beb9) has a nice general overview of core concepts. +- [Terra Oracle Module Docs](https://docs.terra.money/dev/spec-oracle.html#concepts) are also very insightful +- A useful [talk about oracles by Chainlink's Sergey Nazarov](https://youtu.be/UAP6--JTAlU) +- [Sommelier Oracle Module](https://github.com/PeggyJV/sommelier/tree/b2f81e9007db479ac5c88bf4d6edbc17a27120fc/x/oracle) + ## Other Resources -- **[Module Directory](../x/)**: Module implementations and their respective documentation. -- **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK. -- **[SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. -- **[REST API spec](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node through REST. +- **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. diff --git a/docs/starport/README.md b/docs/starport/README.md deleted file mode 100644 index ad4e360..0000000 --- a/docs/starport/README.md +++ /dev/null @@ -1,219 +0,0 @@ -# Bootstrap an Interchain Accounts Testnet using Starport - -Interchain Accounts currently experimentally supports [Starport v0.13.1](https://github.com/tendermint/starport/releases/tag/v0.13.1). However, it should be noted that stability is not guaranteed as the module import functionality is an experimental feature. - -## Testing ICA with Starport - -### 1. Start two chains with Starport - -Open two [Gitpod](https://gitpod.io/#https://github.com/chainapsis/cosmos-sdk-interchain-account) workspaces (Create fresh workspace → create) to start two instances of Starport chains: `foo` and `bar`. - -**Workspace 1** - -```bash -starport app github.com/foo/foo --sdk-version stargate - -cd foo -``` - -**Workspace 2** - -```bash -starport app github.com/bar/bar --sdk-version stargate - -cd bar -``` - -### 2. Import the IBC Account module to the two chains - -**Workspace 1/2** - -```bash -starport-ica module import -starport-ica module import mock -``` - -### 3. Start the two chains - -**Workspace 1/2** - -```bash -starport serve -``` - -### 4. Check the relayer information - -After bootstrapping each chain, each workspace terminal will display the relayer information as follows. Note that the value displayed will be different from the example. - -**Workspace 1/2 Console** - -```bash -✨ Relayer info: eyJDaGFpbklEIjoiYmFyIiwiTW5lbW9uaWMiOiJmcm9zdCByYXpvciBoYWxmIGxhdW5kcnkgcHJvZml0IHdpc2UgdG9uZSBibHVzaCBzdXJnZSBrZWVwIHRvZ2V0aGVyIHNsaWNlIHlvdXRoIHRydXRoIGVubGlzdCBjdXBib2FyZCBhYnNvcmIgc2VlZCBzZXJpZXMgZG91YmxlIHZpbGxhZ2UgdG9uZ3VlIGZsYXNoIGdvcmlsbGEiLCJSUENBZGRyZXNzIjoiaHR0cHM6Ly8yNjY1Ny1jNzllNDk2ZC1kZDk4LTQ4MWQtOTlmZi1jZGQ4OTA2NWQ4MWIud3MtZXUwMS5naXRwb2QuaW86NDQzIn0 -``` - -### 5. Add Chain Foo - -Head over to Workspace 2 and open a new terminal window. Input the following code to add the IBC connected chain. Make sure to use the relayer information shown in step 4 instead of the value provided in the example. - -**Workspace 2** - -```bash -cd ../bar -starport chain add {workspace1-relayer-info} -``` - -### 6. Modify the configuration - -At this stage, IBC transfers connections are open. However, as Starport currently only natively supports IBC transfers we need to change the relayer configuration. - -Refer to the bar-foo IBC path by checking the `config.yaml` file as follows: - -**Workspace 2** - -```bash -vi ~/.relayer/config/config.yaml -``` - -Manually add a new path by appending the following example path information underneath the existing `bar-foo` path (Note that the `client-id` and `connection-id` doesn't have to be changed from the example below, but you must change the `channel-id` name): - -```yaml -global: - timeout: 10s - lite-cache-size: 20 -chains: -- key: testkey - chain-id: bar - rpc-addr: https://26657-b444783c-780f-4b19-ad73-aa02cf4309df.ws-us03.gitpod.io:443 - account-prefix: cosmos - gas-adjustment: 1.5 - trusting-period: 336h -- key: testkey - chain-id: foo - rpc-addr: https://26657-e8783cc5-17eb-44b5-990c-584a9705271e.ws-us03.gitpod.io:443 - account-prefix: cosmos - gas-adjustment: 1.5 - trusting-period: 336h -paths: - bar-foo: - src: - chain-id: bar - client-id: b4f6056a-1344-4e5d-9d20-93ea896dfb6c - connection-id: f3cab589-db3e-4e19-8108-4ea4c39a32f7 - channel-id: test - port-id: transfer - order: unordered - version: ics20-1 - dst: - chain-id: foo - client-id: 75284422-ec2a-447d-9764-c59fdc744e1a - connection-id: e683f7bb-a49b-4c97-83a5-d342ad17d28e - channel-id: test - port-id: transfer - order: unordered - version: ics20-1 - strategy: - type: naive -//append the bar-foo-ica path information as shown here -//but change the channel-id - bar-foo-ica: - src: - chain-id: bar - client-id: 1599fbea-43a0-4e8b-9c04-3f7e5cd11f94 - connection-id: 1f397527-e94e-4362-90cc-bc58e5aabffd - channel-id: {your-channel-id-name} - port-id: ibcaccount - order: ordered - version: ics27-1 - dst: - chain-id: foo - client-id: 15da2512-e2b3-4607-8355-74c994925cc9 - connection-id: 1f4c0fc3-0479-43a7-84c4-21d602c7ed98 - channel-id: {your-channel-id-name} - port-id: ibcaccount - order: ordered - version: ics27-1 - strategy: - type: naive -``` - -Link the paths: - -```bash -rly tx link bar-foo-ica -``` - -Once the linking is successful, you can use the `mock` module to run some test transactions that use interchain accounts. - -### 7. Running test transactions - -First, you need to register an IBCAccount on chain `foo` that chain `bar` manages. Use the destination chain's `channel-id` as shown in `config.yaml`. - -**Workspace 2** - -```bash -bard tx ibcaccount register ibcaccount {dst.channel-id} test --from bar --absolute-timeouts --packet-timeout-height "0-1000000" --packet-timeout-timestamp 0 -``` - -Now you can use the relayer to send over the packet information to the chain that the IBC account will be created on. - -**Workspace 2** - -```bash -rly tx relay-packets bar-foo-ica -rly tx relay-acknowledgements bar-foo-ica -``` - -Now let's check if the IBC account has been registered on chain `foo`. - -Open a new terminal window in workspace 1 - -Use the `src.channel-id` in the relayer's `config.yaml` for the next command. - -**Workspace 1** - -```bash -food q ibcaccount ibcaccount test ibcaccount {src.channel-id} -``` - -Send a small amount of tokens to the IBC account address. - -**Workspace 1** - -```bash -food tx bank send user2 {ibc_account_address} 100token -``` - -Check the balance of the IBC account. - -**Workspace 1** - -```bash -food q bank balances {ibc_account_address} -``` - -Now move to workspace 2 to use the `bar` chain to send a token from the interchain account on `foo` chain. - -**Workspace 2** - -```bash -bard tx ibcaccount send ibcaccount {src.channel-id} {ibc-account-address} {receiving-account-address} 50token --from bar --absolute-timeouts --packet-timeout-height "0-1000000" --packet-timeout-timestamp 0 -``` - -Relay the packet through the relayer. - -**Workspace 2** - -```bash -rly tx relay-packets bar-foo-ica -rly tx relay-acknowledgements bar-foo-ica -``` - -Check the balance of the interchain account on chain `foo`. - -**Workspace 1** - -```bash -food q bank balances {ibc_account_address} -``` - -Congratulations! You have now successfully sent a local transaction from an interchain account on chain `bar` through the interchain accounts IBC message. diff --git a/readme.md b/readme.md index cca0790..71caa0b 100644 --- a/readme.md +++ b/readme.md @@ -35,6 +35,8 @@ After some time, check the on-chain Atom-USD price: $ oracled query atom atomUsd ``` +You should see the latest Atom/USD price and the blockHeight at which it was captured. + --- ## Starport Docs: diff --git a/x/README.md b/x/README.md deleted file mode 100644 index cfdefa3..0000000 --- a/x/README.md +++ /dev/null @@ -1,8 +0,0 @@ - - -# List of Modules - -- [Oracle](oracle/spec/README.md) diff --git a/x/atom/keeper/atom.go b/x/atom/keeper/atom.go index 5d2bef2..94cfe7a 100644 --- a/x/atom/keeper/atom.go +++ b/x/atom/keeper/atom.go @@ -17,12 +17,11 @@ func (k Keeper) SetAtomUsd(ctx sdk.Context, atomUsd types.AtomUsd) { func (k Keeper) GetAtomUsd(ctx sdk.Context) *types.AtomUsd { store := ctx.KVStore(k.storeKey) bz := store.Get(types.AtomUsdKey) - - var atomUsd types.AtomUsd if len(bz) == 0 { return nil } + var atomUsd types.AtomUsd k.cdc.MustUnmarshalBinaryBare(bz, &atomUsd) return &atomUsd } diff --git a/x/atom/keeper/grpc_query.go b/x/atom/keeper/grpc_query.go index d0b23d1..27a5f07 100644 --- a/x/atom/keeper/grpc_query.go +++ b/x/atom/keeper/grpc_query.go @@ -19,6 +19,9 @@ func (k Keeper) AtomUsd(c context.Context, req *types.QueryAtomUsdRequest) (*typ ctx := sdk.UnwrapSDKContext(c) atomUsd := k.GetAtomUsd(ctx) + if atomUsd == nil { + return nil, status.Errorf(codes.NotFound, "No results") + } return &types.QueryAtomUsdResponse{AtomUsd: atomUsd}, nil } diff --git a/x/oracle/spec/README.md b/x/oracle/spec/README.md index 794632b..6bbe86b 100644 --- a/x/oracle/spec/README.md +++ b/x/oracle/spec/README.md @@ -11,15 +11,11 @@ parent: This document specifies the Oracle module for the Cosmos SDK. -The Oracle module allows validators to run arbitrary off-chain worker processes and report the results for inclusion in the on-chain state. +The Oracle module accepts and stores arbitrary `Claims` submitted by the chain validators. Multiple oracly types can run simultaniously. -Unlike onchain smart contracts, offchain workers are able to run non-deterministic code, like fetching exchange price data via an api call, and long-running computations, i.e. AI alogrithms or graph analysis. All of the validators are expected to run the workers and come to a consensus on the results. Exactly how consensus is reached can be decided by the app developer. +The module includes helper methods to design off-chain workers that supply data to the Oracle module. -The module is inspired by the [Terra Oracle Module](https://docs.terra.money/dev/spec-oracle.html#concepts) as well as a more recent iteration of it by [Sommelier](https://github.com/PeggyJV/sommelier/tree/main/x/oracle). - -### Hi-Level Overview - -At its core, the Oracle module accepts and stores arbitrary `Claims`. When submitting a claim, a validator casts a vote for the particular claim. The oracle module tracks all Claims by `ClaimType` and voting `Round`. The module includes some helper methods to tally the votes for each round, however it is the responsibility of external modules to implement this logic as needed. +The Oracle modules assists with deciding how a consensus is reached on oracle results, however it is the responsibility of external modules to implement this logic as needed. ## Contents