diff --git a/Makefile b/Makefile index 6fc726bc2..5128336c6 100644 --- a/Makefile +++ b/Makefile @@ -306,3 +306,15 @@ deploy-dev: .PHONY: deploy-dev +############################################################################### +## Docs ## +############################################################################### + +docs: + @if which mintlify > /dev/null 2>&1; then \ + echo "Starting Mintlify dev server..."; \ + cd docs && mintlify dev; \ + else \ + echo "Mintlify not found. Install at https://mintlify.com/docs/quickstart"; \ + fi +.PHONY: docs diff --git a/docs/integrations/dydx.mdx b/docs/integrations/dydx.mdx deleted file mode 100644 index 2b18f329e..000000000 --- a/docs/integrations/dydx.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -description: dYdX -title: dYdX ---- - -## FAQs - -### **Q: How do I get up and running?** - -**A:** Here is a quick (5-10 minutes) step-by-step breakdown. Please reach out to us at [skip.money/discord](http://skip.money/discord) if you have questions! - -#### **Download the Connect binary.** - -The best way to get the Connect binary is in the GitHub releases page for Connect. - -https://github.com/skip-mev/slinky/releases - -The **minimum** connect version required for dYdX is [`v1.0.1`](https://github.com/skip-mev/slinky/releases/tag/v1.0.1) - -We also provide a container image at [ghcr.io/skip-mev/slinky-sidecar](https://github.com/skip-mev/slinky/pkgs/container/slinky-sidecar/230279145?tag=v1.0.1) - -This will include the Connect binary, `slinky`. - -#### **Integrate Connect into your setup.** - -The configuration of your validator setup requires you to tackle a few problems which we’ll mention here. - -**_Configure the Connect process_** - -To run connect with stable defaults defined by the skip team - -```bash -slinky --marketmap-provider dydx_api --market-map-endpoint https:// -``` - -> Notice, some default values may need to change depending on how you've setup your node + connect instance. See the **marketmap-provider** [section](/validator/flags-guide#marketmap-provider) of the [flags-guide](/validator/flags-guide) - -Before you complete your connect setup it is important that you setup your raydium API-keys + configure your connect instance to use these, see [here](#get-your-free-api-keys-and-configure-your-decentralized-provider-endpoints) for directions. - -#### **Point your chain binary at your Connect instance** - -> Notice if you are using a remote signer, please see [this](/validator/troubleshooting#can-i-use-a-remote-signer) - -The dYdX binary has been altered to accept new options which are used to configure your application. The following options in `app.toml` are relevant to operating Connect. -The top level config fields are as follows: - -```toml -# This is a top level field which controls connect vote extension enablement. -# It should always be set to true. -slinky-vote-extension-oracle-enabled = "true" -``` - -The following fields are specific to the oracle config section: - -```toml -############################################################################### -### Oracle ### -############################################################################### -[oracle] -# Enabled indicates whether the oracle is enabled. -enabled = "true" - -# Oracle Address is the URL of the out of process oracle sidecar. This is used to -# connect to the oracle sidecar when the application boots up. Note that the address -# can be modified at any point, but will only take effect after the application is -# restarted. This can be the address of an oracle container running on the same -# machine or a remote machine. -oracle_address = "localhost:8080" - -# Client Timeout is the time that the client is willing to wait for responses from -# the oracle before timing out. -client_timeout = "2s" - -# MetricsEnabled determines whether oracle metrics are enabled. Specifically -# this enables intsrumentation of the oracle client and the interaction between -# the oracle and the app. -metrics_enabled = "true" -``` - -#### **Get your free API Keys and configure your decentralized provider endpoints** - -Connect supports the addition of state-RPCs to gather data directly from Solana and EVM chains. The Skip and dYdX -team have already set up relationships and pre-paid for API endpoints you can use to get this data. - -For each RPC URL, you will need an API key unique to your validator. To get this, go to the dYdX validator slack channel -(which you should already be invited to once you make it into the active set), and request API keys from Helius, Polkachu, -KingNodes, LavenderFive, and RhinoStake. Each of these are necessary to load into your config so your decentralized providers -can work properly. - -Once you have your 5 API keys, create an `oracle.json` and populate it as follows with your API keys. You should use the URLs listed below, and ask on the Slack `#ext-dydx-validators-discussion` or `#v-dydx-private-testnet-discussion` channels: -for API keys to fill in below. - -``` -{ - "providers": { - "raydium_api": { - "api": { - "endpoints": [ - { - "url": "https://solana.polkachu.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "API KEY YOU'VE RETRIEVED FROM SLACK" - } - }, - { - "url": "https://slinky-solana.kingnodes.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "API KEY YOU'VE RETRIEVED FROM SLACK" - } - }, - { - "url": "https://solana.lavenderfive.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "API KEY YOU'VE RETRIEVED FROM SLACK" - } - }, - { - "url": "https://solana-rpc.rhino-apis.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "API KEY YOU'VE RETRIEVED FROM SLACK" - } - }, - { - "url": "https://dydx.helius-rpc.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "API KEY YOU'VE RETRIEVED FROM SLACK" - } - } - ] - } - } - } -} -``` - -Once you've created this file, you may run your connect sidecar as follows: - -``` -slinky --marketmap-provider dydx_api --market-map-endpoint https:// --oracle-config -``` - -### **Q: How do I know if my validator is properly fetching prices and posting them to the chain?** - -**A:** A full set of prometheus metrics are integrated into both connect and the dYdX application binary. - -A comprehensive overview of the relevant connect metrics is hosted in the root [metrics.md](https://github.com/skip-mev/slinky/blob/main/metrics.md). This document includes a grafana dashboard that can be utilized to monitor the sidecar. Apart from the Connect SideCar Dashboard, we highly recommend the [LavenderFive](https://github.com/LavenderFive/slinky-monitoring) and [RhinoStake](https://github.com/RhinoStake/slinky_monitoring_dashboard) monitoring dashboards which are built to be used with Connect. - -To check if connect is properly fetching prices, you can run `curl localhost:8080/slinky/oracle/v1/prices | jq` - where localhost:8080 is the default address of the sidecar. This will return a JSON object with the prices the sidecar has fetched. - -To check if the dYdX application is properly fetching prices from your connect instance, you can run `curl -s http://localhost:26660 | grep 'app_oracle_responses'` - where localhost:26660 is the local prometheus endpoint of the dYdX application. - -Additionally, the logs from your dYdX node binary will contain the following error if it is unable to connect to your connect instance to grab prices: - -`Failed to run fetch prices for slinky daemon` - -If you are having issues, please read over the live support section below. - -### **Q: How do I upgrade the connect binary?** - -**A:** Upgrading your connect instance can be done out of band of the chain’s binary. If you have a load balancer, CNAME, etc., in front of your sidecar you can simply start up the new version and switch out which version traffic is being directed to during live chain validation. - -If you are running the Connect sidecar in a container you can shut down the container, pull the updated container image and relaunch your container to update. - -If you are running the binary via systemd or other management tool, you will need to stop the process and re-launch using the newly released binary. - -The dydx node will still be able to participate in consensus without the sidecar, and will begin attaching prices to blocks once Connect is available. In the worst case, an upgrade in any of these manners will cause you to miss including vote extensions for a single block which should have no negative effects on you or the network. - -### **Q: Which version of the sidecar binary should I be running?** - -**A:** We are currently in the process of designing solutions around giving validators reliable signals for exactly the minimum version of sidecar they need to be running. - -In the short term, sidecar version bumps will be scheduled well in advance of any required upgrade and comms will be sent out in the relevant validator channels with the exact version required, and any changes which are relevant to the operator experience. - -For future releases we are working with the dYdX team and validators to build automation around version bumps and reasoning about compatibility based on on-chain data. We plan to increase the cadence of updates in line with feature additions, as opposed to batching for larger releases on a longer timeline. - -### **Q: Is there a place I can go to get live support?** - -**A:** For Connect related issues, join the Skip discord [skip.money/discord](http://skip.money/discord). Follow the onboarding prompts and get certified as a validator—you will be able to join dedicated discord channels based on which chain you are a validator for (dYdX). - -For general issues related to dYdX, your normal support channels remain the same. If you can’t reach anyone from the Skip team for some reason which is critical, the dYdX team will be able to pull us in quickly as well. diff --git a/docs/integrations/neutron.mdx b/docs/integrations/neutron.mdx deleted file mode 100644 index 2a69f8f3f..000000000 --- a/docs/integrations/neutron.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -description: Neutron -title: Neutron ---- - -## FAQs - -### **Q: How do I get up and running?** - -**A:** Here is a quick (5-10 minutes) step-by-step breakdown. Please reach out to us at [skip.money/discord](http://skip.money/discord) if you have questions! - -1. **Download the Connect binary.** - - The best way to get the Connect binary is in the GitHub releases page for Connect. - - https://github.com/skip-mev/slinky/releases/tag/v1.0.3 - - The initial version required for Neutron is [`v1.0.3+`](https://github.com/skip-mev/slinky/releases/tag/v1.0.3) - - We also provide a container image at [ghcr.io/skip-mev/slinky-sidecar](https://github.com/skip-mev/slinky/pkgs/container/slinky-sidecar/232941439?tag=v1.0.3) - - This will include the Connect binary, `slinky` - -2. **Integrate the Connect sidecar into your setup.** - - To run connect with stable defaults defined by the skip team - - ```bash - slinky - ``` - - > Notice, some default values may need to change depending on how you've setup your node + connect-sidecar. See the **marketmap-provider** [section](/validator/flags-guide#marketmap-provider) of the [flags-guide](/validator/flags-guide). An example config that over-rides relevant Connect defaults is [here](/validator/validator-connect-config#overriding-the-market-map-oracle-server-endpoint) - -3. **Point your chain binary at your Connect instance** - - > Notice if you are using a remote signer, please see [this](/validator/troubleshooting#can-i-use-a-remote-signer) - - - The chain binary has been altered to accept new options which are used to configure your application. The following options in `app.toml` are relevant to Connect operation. - - ```toml - ############################################################################### - ### Oracle ### - ############################################################################### - [oracle] - # Enabled indicates whether the oracle is enabled. - enabled = "true" - - # Oracle Address is the URL of the out of process oracle sidecar. This is used to - # connect to the oracle sidecar when the application boots up. Note that the address - # can be modified at any point, but will only take effect after the application is - # restarted. This can be the address of an oracle container running on the same - # machine or a remote machine. - oracle_address = "localhost:8080" - - # Client Timeout is the time that the client is willing to wait for responses from - # the oracle before timing out. - client_timeout = "2s" - - # MetricsEnabled determines whether oracle metrics are enabled. Specifically - # this enables intsrumentation of the oracle client and the interaction between - # the oracle and the app. - metrics_enabled = "true" - ``` - -# FAQ - -### **Q: How do I know if my validator is properly fetching prices and posting them to the chain?** - -**A:** A full set of prometheus metrics are integrated into both the sidecar and the chain application binary. - -A comprehensive overview of the relevant metrics is hosted in the root [metrics.md](https://github.com/skip-mev/slinky/blob/262fddc8ff1335c87886cf7aacce2efea8164246/metrics.md). - -A further breakdown of metrics are listed in the Connect repo, categorized by subsystem: - -- [Application-Side Metrics](https://github.com/skip-mev/slinky/blob/a6577aa779f1f98c47ec95d626e4af70949af7b1/service/metrics/README.md) -- [General Oracle Sidecar Metrics](https://github.com/skip-mev/slinky/blob/a6577aa779f1f98c47ec95d626e4af70949af7b1/oracle/metrics/README.md) -- [Sidecar Provider Metrics](https://github.com/skip-mev/slinky/blob/a6577aa779f1f98c47ec95d626e4af70949af7b1/providers/base/metrics/README.md) -- [API Provider Metrics](https://github.com/skip-mev/slinky/blob/a6577aa779f1f98c47ec95d626e4af70949af7b1/providers/base/api/metrics/README.md) -- [Websocket Provider Metrics](https://github.com/skip-mev/slinky/blob/a6577aa779f1f98c47ec95d626e4af70949af7b1/providers/base/websocket/metrics/README.md) - -Additionally, the logs from your chain node binary will contain the following error if it is unable to connect to the sidecar to grab prices: - -`Failed to run fetch prices for slinky daemon` - -### **Q: How do I upgrade the sidecar binary?** - -**A:** Upgrading the sidecar can be done out of band of the chain’s binary. If you have a load balancer, CNAME, etc., in front of your sidecar you can simply start up the new version and switch out which version traffic is being directed to during live chain validation. - -If you are running the Connect sidecar in a container you can shut down the container, pull the updated container image and relaunch your container to update. - -If you are running the binary via systemd or other management tool, you will need to stop the process and re-launch using the newly released binary. - -### **Q: Can I reuse my sidecar if other ICS chains, or the Cosmos Hub, uses Connect?** - -**A:** Yes! We don't currently have docs on how to do this, but as soon as another ICS chain or the Hub votes to include Connect, it will be as simple as pointing your chain binary to the same sidecar over gRPC. - -### **Q: Will I be rewarded for running Connect?** - -**A:** Yes! The Neutron team has committed to offering rewards in $NTRN to validators that operate Connect reliably and honestly. This will be coming from the Neutron SubDAO, which will release further details independently. - -### **Q: Can I get slashed by using Connect?** - -**A:** Not right now - in the first version, there is no slashing or punishment for not running Connect. However, this will change, and the Neutron team has stated that validators that do not run Connect will be jailed. - -Right now, the chain node will still be able to participate in consensus without the sidecar, and will begin attaching prices to blocks once Connect is available. - -### **Q: Which version of the sidecar binary should I be running?** - -**A:** We are currently in the process of designing solutions around giving validators reliable signals for exactly the minimum version of sidecar they need to be running. - -In the short term, sidecar version bumps will be scheduled well in advance of any required upgrade and comms will be sent out in the relevant validator channels with the exact version required, and any changes which are relevant to the operator experience. - -For future releases we are working with other teams and validators to build automation around version bumps and reasoning about compatibility based on on-chain data. We plan to increase the cadence of updates in line with feature additions, as opposed to batching for larger releases on a longer timeline. - -### **Q: Is there a place I can go to get live support?** - -**A:** For Connect related issues, join the Skip discord [skip.money/discord](http://skip.money/discord). Follow the onboarding prompts and get certified as a validator—you will be able to join dedicated discord channels based on which chain you are a validator for. - -For general issues related to Neutron, your normal support channels remain the same (Neutron Slack and Discord). If you can’t reach anyone from the Skip team for some reason which is critical, the Neutron team will be able to pull us in quickly as well. diff --git a/docs/introduction.mdx b/docs/introduction.mdx new file mode 100644 index 000000000..cb0ae7f62 --- /dev/null +++ b/docs/introduction.mdx @@ -0,0 +1,40 @@ +--- +title: Introduction +icon: crystal-ball +--- + +## What is Connect? + +**Connect** is an oracle that securely delivers offchain data to onchain applications using a chain's native validator set and security. This documentation will guide you through using Connect; whether you're a **validator** or **developer**. + + + + Learn how to setup and run Connect with your infrastructure. + + + Learn how to use the Connect API to access data. + + + +### Features + +#### Security + +Connect leverages the chain’s security, giving the fastest updates possible, and removing the requirements for any 3rd party systems. + +#### Performance + +Connect can support over 2000 currency pairs and price feeds, allowing the launch of thousands of permissionless on-chain markets. Ultimately, the speed of Connect is determined by the speed of your application. + +#### Support + +Connect comes with a 1-day SLAs for adding new feeds, and 24/7 on-call support and maintenance by the Skip team. + +#### UX + +By leveraging new advancements in consensus like vote extensions & ABCI++, Connect guarantees a millisecond-fresh oracle update every block, allowing applications to build without sacrificing UX for safety. + + +## Ready to Connect? + +If you're interested in using Connect, please check out our [website](https://skip.build) and reach out to us on [discord](https://discord.gg/PeBGE9jrbu) to get started. \ No newline at end of file diff --git a/docs/overview.mdx b/docs/learn/architecture.mdx similarity index 53% rename from docs/overview.mdx rename to docs/learn/architecture.mdx index c69f72aae..aab12ae84 100644 --- a/docs/overview.mdx +++ b/docs/learn/architecture.mdx @@ -1,49 +1,17 @@ --- -description: Skip's In-Protocol Oracle -title: ✨ Overview +description: Learn how Connect works with ABCI++ +title: Architecture +icon: cars --- - - - - - - -**Licensing** - -Connect is **business-licensed software** under BSL. It is source viewable, but [**reach out to us**](https://skip.money/contact) to us if you are interested in integrating! We are limiting the number of chains we work with in 2024. We apologize if we run out of capacity. - -Visit the GitHub repo [here](https://github.com/skip-mev/slinky). - -For support, [**join our discord**](https://skip.money/discord)! - - - - - - - -## 🦾 Connect Features - -✅ **Runs on the chain validator set** - Connect leverages the chain’s security, giving the fastest updates possible, and removing the requirements for any 3rd party systems. - -✅ **Highly performant** - Connect can support over 2000 currency pairs and price feeds, allowing the launch of thousands of permissionless on-chain markets. - -✅ **Full operational support** - comes with a 1-day SLAs for adding new feeds, and 24/7 on-call support and maintenance by the Skip team. - -✅ **Better Application UX** - by leveraging new advancements in consensus like vote extensions & ABCI++, Connect guarantees a millisecond-fresh oracle update every block, allowing applications to build without sacrificing UX for safety. - -## 🏎️ The Connect Sidecar - -- The Connect sidecar is an out-of-process service that efficiently fetches prices from various data sources and runs aggregation logic - to combine them into a single price for each feed. -- Validators use GRPC requests to the sidecar to fetch the latest updates to update on-chain prices from over 20+ providers. +The Connect sidecar is an out-of-process service that efficiently fetches prices from various data sources and runs aggregation logic +to combine them into a single price for each feed. The application uses GRPC requests to the sidecar to fetch the latest updates to update on-chain prices from over 20+ providers. ![Sidecar](/img/sidecar.svg) -## ⚡️ On-chain aggregation +## On-chain aggregation -Connect uses [ABCI++](https://docs.cometbft.com/v0.37/spec/abci/) to separate Oracle aggregation into secure and efficient steps. +Connect uses [ABCI++](https://docs.cometbft.com/v0.38/spec/abci/) to separate Oracle aggregation into secure and efficient steps. ![Connect Architecture](/img/connect-arch.png) @@ -64,7 +32,7 @@ During `PrepareProposal`, the vote extensions from the previous block are aggreg - It also ensures that the vote extensions are valid and can be understood by the application. - Finally, it encodes the vote extensions and injects them into the top of the block proposal as a pseudo-transaction ignored by the chain. - ![Prepare Proposal](/img/prepare.svg) +![Prepare Proposal](/img/prepare.svg) For more information on vote extensions in general, refer to [the Cosmos SDK docs](https://docs.cosmos.network/main/build/abci/vote-extensions). @@ -85,4 +53,4 @@ The end of a price's journey is in the `Preblock` step. ### Full Flow - This full set of steps repeats on every block resulting in a continuous stream of guaranteed prices. The oracle is enshrined in the application by the - validator set, and so is fundamentally equivalent to chain liveness (i.e. the oracle can't go down without the chain going down) +validator set, and so is fundamentally equivalent to chain liveness (i.e. the oracle can't go down without the chain going down) diff --git a/docs/security-properties.mdx b/docs/learn/security.mdx similarity index 69% rename from docs/security-properties.mdx rename to docs/learn/security.mdx index 72a4f8eac..69d2a5f3f 100644 --- a/docs/security-properties.mdx +++ b/docs/learn/security.mdx @@ -1,30 +1,27 @@ --- description: Connect Security Properties -title: 🔒 Security Properties +title: Security +icon: shield-keyhole --- - - - +## Basics -## ⛓️ Overall Assumptions - -✅ **Connect is as secure as the chain it is deployed on** - This is the meaning of a "restaked" oracle - Connect leverages all available +**Connect is as secure as the chain it is deployed on** - This is the meaning of a "restaked" oracle - Connect leverages all available security that the chain can provide by using the existing validator set and tying updates to consensus via vote extensions. -✅ **Prices require 2/3 participation from validators to be posted on chain** - We require a minimum of 2/3 of stake weight to contribute +**Prices require 2/3 participation from validators to be posted on chain** - We require a minimum of 2/3 of stake weight to contribute to a price aggregation for that price to actually update chain state. This is the same stake weight required to commit blocks. -✅ **Connect avoids any external dependencies** - Connect injects price data directly into the chain it's deployed on. This means there's no +**Connect avoids any external dependencies** - Connect injects price data directly into the chain it's deployed on. This means there's no additional chain, token, relayer, or other outside actor dependency. The same operators that run the chain run the oracle. -✅ **Connect price updates are atomic with liveness** - Since Connect data is signed atomically with `PreCommit` votes via Vote Extensions, chains can +**Connect price updates are atomic with liveness** - Since Connect data is signed atomically with `PreCommit` votes via Vote Extensions, chains can configure their application (or parts of their application) to depend on per-block price updates. This makes almost all forms of oracle attacks impossible, and allows applications to avoid having to build their own UX roadblocks to ensure safety. -## 🔀 Impact of Vote Extensions +## Impact of Vote Extensions -Connect updates by having over 2/3 of the validator set (by stake weight) suggest a series of prices, and then aggregates across +Connect updates when over 2/3 of the validator set (by stake weight) suggest a series of prices, and then aggregates across them using a stake-weighted median. This price data is committed to the chain by validators through [vote extensions](https://docs.cosmos.network/main/build/abci/vote-extensions). Vote extensions are arbitrary metadata that is signed atomically with a validator's `PreCommit` vote. In Connect's case, that metadata is @@ -34,7 +31,7 @@ Given blocks cannot progress without 2/3 of stake weight submitting votes, block Additionally, the `x/oracle` module (where prices are stored on chain) requires at least 2/3 of voting power to have contributed to individual price updates. This means that every price update has the same participation as block validity itself. -## 👺 Manipulation Thresholds +## Manipulation Thresholds In the standard configuration of Connect, it requires `1/3` of stake to be manipulated to post an incorrect oracle price. This is because: @@ -46,8 +43,6 @@ However, Connect can support additional constraints to increase this level to `2 There are tradeoffs to increasing the security to this level. Validators may reject proposals more often if there is high volatility in price updates between them, which could result in longer periods of oracle downtime in periods of crypto market instability. -## 🎖️ Importance of Operational Excellence - -Security assumptions, no matter how good, are no substitute for the oracle operators (the chain's validator set) keeping high uptime, reliable, and accurate price updates. Connect makes this easy for validators, providing an ample amount of operational support and tooling for alerting, upgrading, and maintaining a Connect instance. We work with operators from respected oracles like [ChainLink](https://chain.link/) to ensure validators replicate best practices. +## Importance of Operational Excellence -Operational excellence is heavily tied to incentivization and disincentivization mechanisms imposed on operators. Please read our section on [Incentivization & Slashing](/slashing) for more info. +Security assumptions, no matter how good, are no substitute for the oracle operators (the chain's validator set) keeping high uptime, reliable, and accurate price updates. Connect makes this easy for validators, providing an ample amount of operational support and tooling for alerting, upgrading, and maintaining a Connect instance. \ No newline at end of file diff --git a/docs/mint.json b/docs/mint.json index 27985da5b..03f8014e6 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -7,13 +7,19 @@ }, "favicon": "/favicon.png", "colors": { - "primary": "#0E0E0E", - "light": "#FAFAFA", - "dark": "#0E0E0E", + "primary": "#0061ff", + "light": "#0061ff", + "dark": "#66A0FF", "background": { "dark": "#151617" } }, + "metadata": { + "og:image": "https://github.com/skip-mev/slinky/blob/main/docs/img/connect-banner.png?raw=True", + "og:description": "Connect is an enshrined, in-protocol oracle built for high performance applications.", + "og:site_name": "Connect Docs", + "twitter:site": "@skipprotocol" + }, "topbarLinks": [ { "name": "Skip:Go", @@ -33,42 +39,39 @@ }, "navigation": [ { - "group": "🔮 General", + "group": "General", "pages": [ - "overview", - "security-properties", - "slashing", - "upcoming-work" + "introduction" ] }, { - "group": "👾 Validators", + "group": "Validators", "pages": [ - "validator/quickstart", - "validator/validator-app-config", - "validator/validator-connect-config", - "validator/troubleshooting", - "validator/rpc-providers", - "validator/flags-guide" + "validators/quickstart", + "validators/advanced-setups", + "validators/configuration", + "validators/faq" ] }, { - "group": "⛓ Chain Integrations", + "group": "Learn", "pages": [ - "integrations/dydx", - "integrations/neutron" + "learn/architecture", + "learn/security" ] }, - { - "group": "🛠️ Integrators", - "pages": [ - "using-connect/high-level", - "using-connect/neutron-sdk" - ] - } + { + "group": "Developers", + "pages": [ + "using-connect/high-level", + "using-connect/neutron-sdk", + "using-connect/providers" + ] + } ], "footerSocials": { "twitter": "https://twitter.com/skipprotocol", - "discord": "https://discord.com/invite/hFeHVAE26P" + "discord": "https://discord.com/invite/hFeHVAE26P", + "github": "https://github.com/skip-mev/slinky" } } diff --git a/docs/slashing.mdx b/docs/slashing.mdx deleted file mode 100644 index 4c84e68d1..000000000 --- a/docs/slashing.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Connect Incentivization Method -title: ⚖️ Incentivization & Slashing ---- - -## 🤝 Validators and Connect - -✅ **Validators are the lifeblood of Connect operation** - Connect is a restaking product. This means it reuses all available network stake of a protocol to secure oracle operation. To do this, validators need to run the infrastructure required for Connect to operate. - -✅ **Validators do this by running the Connect Sidecar** - Connect comes with a highly optimized and reliable piece of software called the Sidecar, which validators run in tandem with chain binaries to fetch prices safely and reliably. - -✅ **Validators benefit from running Connect** - Validators can (should!) be rewarded for doing more for the chains they operate on. To accomplish this, Connect can providet `fee-sharing` for validators who honestly operate the oracle. Fees can come from trading activity, inflation, or other mechanisms. - -✅ **Validators can be punished for misuse** - As they are with the consensus process, validators can be punished if they don't report prices or report incorrect prices. As long as validators follow the correct operation guides and act honestly, this should never happen. To ensure its accuracy, Connect has two prebuilt mechanisms to enable slashing. - -## 💰 Reward Mechanism - -- When Connect is integrated, it can assign per-block rewards to validators who operate it correctly. Correct operation means: - - posting prices reliably - - posting correct prices - -Rewards can come from various sources. The easiest to implement is an additional share of inflation yield. However, Connect also can support sharing of trading-fees and any arbitrary source of revenue. - - - -We Share Everything - -Skip is dedicated to rewarding validators. For any fees a chain agrees to pay Skip for Connect operation, we share 20% of this with the validators who operate it. - - - -With fee sharing, a fixed amount of fees is shared per-block to validators that correctly operate Connect. - -- This means, if `$1000` was allocated for a certain block, and only 10 validators correctly operated Connect that block, each validator would receive an additional `$100` on top of their block rewards. - -Note that the Connect reward is additional to normal validator commission. - -## 📉 Downtime slashing - -Connect comes prebuilt with the optional `x/sla` module, which enforces a minimum Service-Level Agreement (SLA) on validators and is verified on-chain. - -See the code [here](https://github.com/skip-mev/slinky/tree/main/x/sla) - -The SLA module is designed to issue a (small) slash whenever a validator doesn't meet the uptime SLA for a specific price feed over a moving window of blocks. For example, with an SLA set to `80%` for a currency pair (e.g. `ETH/USDC`) over a block-window of `100`, then: - -- Every block, the `x/sla` module will find how many blocks in the past `100` each validator posted a price. -- If the percentage of blocks with prices is less than `80%`, then the validator is issued a small slash, proportional to their stake-weight. -- This process repeats until the validator is hitting the SLA. -- All these parameters, and the module itself, are initiated and set by governance. They are `OFF` by default. - -For new currency pairs, there is a "grace period" that can be configured in case validators need to make updates. Correct operation should be simple and heavily assisted by Skip: our intention is for downtime slashing to never impact any validator. - -Here is a rundown of the parameters for `x/sla`: - -- `MaximumViableWindow` (e.g. `100` ) - - This is the **window of blocks from head** that are evaluated to determine the uptime a validator had. - - For example, if set to `100` , the chain will look at every rolling window of `100` blocks to determine what percentage of the blocks the validator included a price update in their vote extension -- `ExpectedUptime` (e.g. `0.8` ) - - This is the percentage of uptime expected from all validators for a specific currency pair. This is evaluated every `Frequency` number of blocks, and the check will be roughly `ExpectedUptime >= (NumBlocksWithUpdates / MaximumViableWindow)` -- `SlashConstant` (e.g. `6` ) - - This is a constant amount of stake to slash every `Frequency` of blocks if the SLA is not being kept. - - In the case of SLA breach, the final amount to be slashed would be roughly `SlashConstant * StakeWeight(Validator)` . This would repeat every `Frequency` number of blocks that a specific validator breached the SLA -- `MinimumBlockUpdates` (e.g. `20` ) - - This is a safety mechanism to avoid double-slashing validators experiencing overall downtime. - - This value represents the minimum number of blocks within the `MaximumViableWindow` that a validator needs to sign before the overall Oracle SLA kicks in. - - For example, if in `100` blocks a validator was only live & signing for `10` , if the `MinimumBlockUpdates` is set to `20` , then the validator will not be subject to Oracle SLA slashing penalties. - - This is useful for preventing slashing around chain upgrades, when multiple validators might be offline at once. -- `Frequency` (e.g. `10` ) - - This is the number-of-block cadence when the SLA is checked for every validator for a specific price feed. - - This is mostly used to save computation resources - with a long `MaximumViableWindow` , we recommend increasing the `Frequency` to be upwards of `1` to save node resources. -- `MinStakeWeightToSlash` (e.g. `0.66` = 66% of stake weight) - - This is the minimum cumulative stake weight of validator price reports that is required before **any** slashing happens. This constitutes the "grace period" when a new currency pair is added and validators are getting set up. - -## ❌ Incorrect-price slashing - -Downtime is serious, but not as serious as the network reporting incorrect prices. To prevent this, we have an exact replica of the [ChainLink Town Crier](https://blog.chain.link/town-crier-and-chainlink/) mechanism implemented as the `x/alerts` module. - -The `x/alerts` module does not slash individual mistakes or one-off errors. It activates when a permissionless `alerter` raises an alarm that the **entire network** has reported an incorrect price. The `alerter` has to post a `bond`, which is money they put up and legitimizes their claim. - -The `alert` raised is then forwarded to a `Concluder` network of trusted actors who can verify the validity of the `alert`. - -- If the `alert` is deemed invalid (i.e. the network's prices **were** close enough to the best-effort prices that the `concluder` network can fetch), then the `alerter` bond is seized and distributed to validators. -- If the `alert` is deemed valid (i.e. the network's prices are **very different** from the best-effort prices that the `concluder` network can fetch), then all participating validators in the incorrect price are slashed, and the alerter receives the slashed amount. - -This process is not designed to be even a remotely common occurrence. Slashing is a serious event, and the network should only slash in the event network prices are completely incorrect. As with the `x/sla` module, everything is defaulted to `OFF`, and all parameters are decided by governance. - -For chains that wish to enable `x/alerts`, please contact us so we can help you implement it correctly. It is a highly sophisticated and nuanced system. - - diff --git a/docs/snippets/start-connect-dydx-snippet.mdx b/docs/snippets/start-connect-dydx-snippet.mdx new file mode 100644 index 000000000..52dcddf7f --- /dev/null +++ b/docs/snippets/start-connect-dydx-snippet.mdx @@ -0,0 +1,59 @@ +The dYdX blockchain requires some additional steps to start Connect. + +**The minimum required version for Connect with dYdX is `v1.0.1+`.** + +First, please ensure you've received your API keys for Raydium markets. If you have not received API keys, please reach out to the team in the relevant channels. + +Next, place your API keys under their corresponding URLs in the following file and save it to your system. Keep the file path handy as we will pass it into a flag when running Connect. +```json oracle.json +{ + "providers": { + "raydium_api": { + "api": { + "endpoints": [ + { + "url": "https://solana.polkachu.com", + "authentication": { + "apiKeyHeader": "x-api-key", + "apiKey": "API KEY" + } + }, + { + "url": "https://slinky-solana.kingnodes.com", + "authentication": { + "apiKeyHeader": "x-api-key", + "apiKey": "API KEY" + } + }, + { + "url": "https://solana.lavenderfive.com", + "authentication": { + "apiKeyHeader": "x-api-key", + "apiKey": "API KEY" + } + }, + { + "url": "https://solana-rpc.rhino-apis.com", + "authentication": { + "apiKeyHeader": "x-api-key", + "apiKey": "API KEY" + } + }, + { + "url": "https://dydx.helius-rpc.com", + "authentication": { + "apiKeyHeader": "x-api-key", + "apiKey": "API KEY" + } + } + ] + } + } + } +} +``` +With your dYdX node's REST API endpoint and the `oracle.json` file path, enter the following command to run Connect. + +```shell +slinky --marketmap-provider dydx_api --market-map-endpoint https:// --oracle-config path/to/oracle.json +``` \ No newline at end of file diff --git a/docs/snippets/start-connect-snippet.mdx b/docs/snippets/start-connect-snippet.mdx new file mode 100644 index 000000000..67af68782 --- /dev/null +++ b/docs/snippets/start-connect-snippet.mdx @@ -0,0 +1,5 @@ +To run Connect, which starts the service on the default port of `8080`, enter the following command: + +```shell +slinky --market-map-endpoint=":" +``` \ No newline at end of file diff --git a/docs/style.css b/docs/style.css index e48449464..a35a0f7ea 100644 --- a/docs/style.css +++ b/docs/style.css @@ -1,9 +1,3 @@ -@import url('https://fonts.googleapis.com/css2?family=Inconsolata:wght@200..900&display=swap'); - -h1, h2, h3, #navbar { - font-family: "Inconsolata", monospace; -} - .dark #navbar { background-color: #121213; } diff --git a/docs/upcoming-work.mdx b/docs/upcoming-work.mdx deleted file mode 100644 index a237a46f9..000000000 --- a/docs/upcoming-work.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: 🤫 Upcoming Features -title: 🤫 Upcoming Features ---- - -## What's next for Connect? - -Connect has a number of major releases already in the works. Below, we outline a couple of the research and product directions we're building. - -
- -### 🔀 New Types of Data - -**_Estimated: April 2024_** - -As a fast follow to our support for prices, Connect will be able to provide chains with Verifiable Randomness Functions, offchain asset reserve proofs (to support RWA tokens), and light client support (to borrow security and post data to other protocols, like EigenLayer or Celestia). - -### 🤝 Validator Subsetting - -**_Estimated: June 2024_** - -In it's standard implementation, all validators running Connect are expected and accountable for posting prices for **_all_** currency pairs every block. Although Connect is optimized to do this for over a thousand currency pairs, it can scale further if **_subsets_** of validators are selected to report specific prices. - -Our excitement is for this feature to enable an active marketplace, with users and traders creating incentive pools for validators that support their desired currency pair, and validators opting-into additional commitments to do so. - -### 🌈 Rollup Support - -**_Estimated: August 2024_** - -Already, Connect integrators are using the oracle to gossip prices to rollups that use their chain as a settlement or DA layer. We plan to expand the tooling to more easily support rollups in general, and help our integrators become hubs for fast, verifiable data provisioning across the L2 landscape. - -Currently, we are working with Celestia and RollKit team to build out a first version. - -### 💻 Sidecar Restaking Services - -**_Estimated: November 2024_** - -Connect is a restaked operation by design. However, the incentive and slashing mechanisms tied to the operation of the Connect oracle can be extended to other services that validators can offer chains. For example, this would include: - -1. Running IBC-relayers within Connect in an on-chain, verifiable way, and rewarding validators on a per-packet basis. -2. Running indexers and servers within the sidecar to service decentralized frontends. -3. Running bridge software (e.g. "Peggo") to give chains guaranteed interoperability with outside networks. -4. Running generalized offchain computation and posting ZK proofs (e.g. optimal routing, fee markets) to lighten node binary computation burden while still having verifiable ways of posting computation results. -5. Running an external transaction gossip network to lower bandwidth load on Comet/Tendermint, allowing chains to finalize significantly faster. - -Our integration partners will be invited to test and influence these features, effectively leveraging their existing operator set for greater and greater value. diff --git a/docs/using-connect/high-level.mdx b/docs/using-connect/high-level.mdx index c78d04809..2cc79ae48 100644 --- a/docs/using-connect/high-level.mdx +++ b/docs/using-connect/high-level.mdx @@ -1,40 +1,41 @@ --- -description: 🏖️ Accessing Connect Prices -title: 🏖️ Accessing Connect Prices +description: Getting prices from the Connect oracle +title: Getting Prices +icon: tag --- - **Building with Connect? First step is to join our [Discord](https://discord.gg/amAgf9Z39w)** + **Building with Connect? Join our [Discord](https://discord.gg/amAgf9Z39w)**! ## Summary -Connect prices are stored within the [`x/oracle`](https://github.com/skip-mev/slinky/tree/main/x/oracle) module by default. +Connect prices are stored within the [x/oracle](https://github.com/skip-mev/slinky/tree/main/x/oracle) module. On very specific chains - right now only dYdX - they live in a different storage module (in dYdX's case, `x/prices`). -These prices are updated on a per-block basis, when there is sufficient difference from the last block's price. They can be accessed natively by CosmWasm smart contracts, by other modules, or by anyone else who has access to chain state. +These prices are updated on a per-block basis when there is a sufficient delta from the last block's price. They can be accessed natively by CosmWasm smart contracts, other modules, or those with access to chain state. -Connect market configuration is stored in the [`x/marketmap`](https://github.com/skip-mev/slinky/tree/main/x/marketmap). This module, unlike `x/oracle`, does **not** store price data. Instead, it stores which currency pairs are supported and how they are configured. +Connect's market configuration is stored in the [x/marketmap](https://github.com/skip-mev/slinky/tree/main/x/marketmap). This module, unlike `x/oracle`, does **not** store price data. Instead, it stores which currency pairs are supported and how they are configured. ### Getting Supported Assets Every chain will have a different set of supported assets. You can find out which assets are supported on your chain by either running: -1. (via a local running chain): `curl http://localhost:1317/slinky/marketmap/v1/marketmap` -2. (via chain app CLI): `d q marketmap marketmap` -3. (via gRPC): `grpcurl -plaintext localhost:9090 slinky.marketmap.v1.Query/MarketMap` +1. (REST): `curl http://localhost:1317/slinky/marketmap/v1/marketmap` +2. (application cli): `appd q marketmap marketmap` +3. (gRPC): `grpcurl -plaintext localhost:9090 slinky.marketmap.v1.Query/MarketMap` This will return a JSON list of supported assets with associated metadata. ### Accessing Connect Prices over node APIs and RPC -To access **all** Connect prices (as of the last committed block), you can run: +To access **all** Connect prices (as of the last committed block): -1. (via a local running chain): `curl http://localhost:1317/slinky/oracle/v1/get_prices` -2. (via gRPC): `grpcurl -plaintext localhost:9090 slinky.oracle.v1.Query/GetPrices` +1. (REST): `curl http://localhost:1317/slinky/oracle/v1/get_prices` +2. (gRPC): `grpcurl -plaintext localhost:9090 slinky.oracle.v1.Query/GetPrices` -To get a **specific** currency pair, you can call: +To get a **specific** currency pair: 1. (Get all currency pairs request) `appd q oracle currency-pairs` 2. (Get price request) `appd q oracle price [base] [quote]` @@ -50,7 +51,7 @@ When calling `getPrices` via the above methods, you are returned an array of `Ge `GetPriceResponse` looks like this: -``` +```protobuf query.proto // GetPriceResponse is the response from the GetPrice grpc method exposed from // the x/oracle query service. @@ -77,7 +78,7 @@ Inside `QuotePrice`, you can fetch for the currency-pair: `QuotePrice` looks like this: -``` +```protobuf query.proto // QuotePrice is the representation of the aggregated prices for a CurrencyPair, // where price represents the price of Base in terms of Quote message QuotePrice { @@ -96,20 +97,4 @@ Inside `QuotePrice`, you can fetch for the currency-pair: // BlockHeight is height of block mentioned above uint64 block_height = 3; } -``` - -### Connect Price Update Timing - -Prices within Connect committed on a one-block delay, since validators use the vote extensions from block `n-1` to securely submit their price data for block `n`. - -Most of the time, Connect feeds will update every single block. This happens when there is a non-insignificant update to the price, and over 66% of validators are correctly running their price-fetching sidecar. - -However, an individual Connect feed will not update on any given block if: - -1. (More common) There was not a sufficient enough change from last block's price to surpass the Connect `min_price_change` parameter. To save network bandwidth, the price won't update. -2. (Less common) The market is disabled (i.e. not updating) within `x/marketmap` -3. (Less common) Less than 2/3s of validators (by stake weight) contributed to a price update. This can happen if not enough validators run Connect, or there is a massive, widespread outage across providers. - -### Q: Can I get historical prices in Connect? - -**A:** No, the `x/oracle` module only stores the most recently posted price. However, you can use blockchain indexers or inspect past blocks to see the prices committed on previous heights. +``` \ No newline at end of file diff --git a/docs/using-connect/neutron-sdk.mdx b/docs/using-connect/neutron-sdk.mdx index cca97ed7b..b967b0c1d 100644 --- a/docs/using-connect/neutron-sdk.mdx +++ b/docs/using-connect/neutron-sdk.mdx @@ -1,17 +1,18 @@ --- -description: ⚛️ Connect with CosmWasm using Neutron-SDK -title: ⚛️ Connect with CosmWasm using Neutron-SDK +description: Querying Connect prices using CosmWasm and Neutron SDK +title: CosmWasm +icon: atom-simple --- -**Building with Connect? First step is to join our [Discord](https://discord.gg/amAgf9Z39w)** +**Building with Connect? Join our [Discord](https://discord.gg/amAgf9Z39w)**! ## Summary -Connect prices, since they're stored on-chain in `x/oracle`, are accessible locally via CosmWasm smart contracts. `x/marketmap` has configuration information that may also be helpful in your development. +Connect prices are stored on-chain in `x/oracle`, enabling price data to be locally accessible via CosmWasm smart contracts. `x/marketmap` has configuration information that may also be helpful in your development. -Here's a couple code snippets on how to get started: +Here's how to get started: ## How to access Connect prices safely @@ -22,15 +23,13 @@ There are a number of highly-recommended checks we suggest developers use before 1. Check to make sure the `block_timestamp` of the last updated is **less than 20 seconds** from the most recent committed block timestamp. I.e. `current_block_timestamp - block_timestamp < 20s` 1. Check to make sure the price is not returning `nil` (i.e. has not been initialized) -Instructions on how to do these steps are outlined below. +### Example -### The complete example - -In the snippets below some details might be omitted. Please check out the complete smart contract [example](https://github.com/kubiklabs/neutron-dev-contracts/tree/slinky_contracts/contracts/neutron_slinky) for a complete implementation. +The snippets below are not a complete implementation. Please check out the complete smart contract [example](https://github.com/kubiklabs/neutron-dev-contracts/tree/slinky_contracts/contracts/neutron_slinky) for a complete implementation. ### Install dependencies and import the libraries -In order to start using the Connect modules, you need to install some dependencies. Add the following libraries to your dependencies section: +Add the following libraries to your dependencies section: ```toml [dependencies] @@ -42,7 +41,7 @@ cosmwasm-std = "1.3.1" neutron-sdk = { package = "neutron-sdk", git = "https://github.com/neutron-org/neutron-sdk", branch = "feat/sdk-50" } ``` -Now you can import the libraries: +Import the libraries: ```rust use neutron_sdk::bindings::marketmap::query::{ @@ -56,7 +55,7 @@ use neutron_sdk::bindings::oracle::query::{ }; ``` -### Getting all supported markets on Connect, and checking to see if an individual market is included +### Getting all supported markets on Connect, and ensuring an individual market is included ```rust // create a CurrencyPair object @@ -87,7 +86,7 @@ if marketmap_currency_pairs_response.market_map.markets.contains_key(&base_symbo } ``` -### Checking to make sure a market is `enabled` within `x/marketmap` +### Checking if a market is `enabled` within `x/marketmap` ```rust // fetch market for currency_pair in x/marketmap module @@ -106,7 +105,7 @@ if marketmap_market_response.market.ticker.enabled == false { } ``` -### Checking to make sure `block_timestamp` is recent enough +### Checking if `block_timestamp` is recent enough ```rust // get current_block_height @@ -130,9 +129,9 @@ if (current_block_height - oracle_price_response.price.block_height) > max_block ### Nil-checking a price response -Connect may sometimes return a "nil" Price if it has not been written to. This means, within the `GetPriceResponse`, the price will have `Nonce = 0` +Connect may sometimes return a "nil" Price if it has not been written to. This means within the `GetPriceResponse`, the price will have `Nonce = 0` -The safest way to check for a nil price is to check if the `Nonce == 0`, here's a code snippet below: +To check for a nil price, see if `Nonce == 0` in the `GetPrice` response. ```rust // fetch price for currency_pair from x/oracle module @@ -166,6 +165,6 @@ let market_price: Int128 = oracle_price_response.price.price; ### Fetching a set of prices -Fetching multiple prices at once requires using `OracleQuery::GetPrices { currency_pair_ids: Vec }` in place of `OracleQuery::GetPrice { currency_pair: CurrencyPair }`, other steps are as same as when fetching one price as shown above. +Fetching multiple prices at once requires using `OracleQuery::GetPrices { currency_pair_ids: Vec }` in place of `OracleQuery::GetPrice { currency_pair: CurrencyPair }`. Apply the same logic from the instructions above. -The complete example can be found [here](https://github.com/kubiklabs/neutron-dev-contracts/blob/slinky_contracts/contracts/neutron_slinky/src/contract.rs#L140-L242). +For a complete example see the [full example](https://github.com/kubiklabs/neutron-dev-contracts/blob/slinky_contracts/contracts/neutron_slinky/src/contract.rs#L140-L242). diff --git a/docs/using-connect/providers.mdx b/docs/using-connect/providers.mdx new file mode 100644 index 000000000..ca5b5ad17 --- /dev/null +++ b/docs/using-connect/providers.mdx @@ -0,0 +1,39 @@ +--- +title: Providers +icon: book-sparkles +--- + +Connect pulls data from `Providers`. `Providers` utilize public REST APIs, RPCs, and websockets from either centralized or decentralized exchanges. Below is a list of all available `Providers` in Connect. + +# Centralized Exchange Providers + +### REST API + +- binance_api +- bitstamp_api +- coinbase_api +- kraken_api + + +### Websocket + +- binance_ws +- bitfinex_ws +- bitstamp_ws +- bybit_ws +- coinbase_ws +- crypto_dot_com_ws +- gate_ws +- huobi_ws +- kraken_ws +- kucoin_ws +- mexc_ws +- okx_ws + +# Decentralized Exchange Providers + +### REST API + +- uniswapv3_api-ethereum +- uniswapv3_api-base +- raydium_api \ No newline at end of file diff --git a/docs/validator/flags-guide.mdx b/docs/validator/flags-guide.mdx deleted file mode 100644 index fad8b74cd..000000000 --- a/docs/validator/flags-guide.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -description: Overviewing the flags available in Connect -title: 🏁 Flags Guide ---- - -# Overview - -Flags allow you to customize the behavior of the Connect sidecar, `slinky`, to suit your needs. - -## Connecting to a Node - -### marketmap-provider - -> If you are serving prices for the `dydx` network, you should be using the `dydx_api` provider. Otherwise, you should be using the `marketmap_api` provider. - -This flag allows you to specify how `slinky` should be looking for the markets it will be serving prices for. There are two options available: - -**If your sidecar is serving prices for the `dydx` network**, run your sidecar with the following argument - -```bash -# If your sidecar is serving prices for the dydx network -slinky --marketmap-provider dydx_api -``` - -By default this assumes that the dydx node's REST endpoint is running at `http://localhost:1317`. If you need to change this, please utilize the [market-map-endpoint](#market-map-endpoint) flag. - -If you are serving prices for any other network, you should be using the `marketmap_api` (which is the default `slinky` is using). - -```bash -# If you are serving prices for any other network -slinky -``` - -By default this assumes that the node's app GRPC endpoint is running at `localhost:9090`. If you need to change this, please utilize the [market-map-endpoint](#market-map-endpoint) flag. - -### market-map-endpoint - -> The `marketmap_api` provider must always point to the app GRPC endpoint (typically port 9090), while the `dydx_api` provider must always point to the REST endpoint (typically port 1317). - -This flag allows you to specify where `slinky` should be looking for the markets it will be serving prices for. By default, `slinky` assumes `localhost:9090` for the `marketmap_api` provider and `http://localhost:1317` for the `dydx_api` provider. - -To change the default behavior, you can run `slinky` with the following arguments: - -```bash -# Pointing your sidecar to a custom node's app GRPC/REST endpoint -slinky --market-map-endpoint : -``` - -## Logging - -### log-std-out-level - -> By default, `slinky` prints logs at the `info` level. - -This flag allows you to specify the level of logs that should be printed to the standard output. By default, `slinky` prints logs at the `info` level. To change this, you can run `slinky` with the following arguments: - -```bash -slinky --log-std-out-level -``` - -Accepted levels are `debug`, `info`, `warn`, `error`, and `fatal`. **Note that debug logs are verbose and should only be used for debugging purposes.** - -### log-file-level - -> By default, `slinky` writes logs at the `info` level. - -This flag allows you to specify the level of logs that should be written to the log file. By default, `slinky` writes logs at the `info` level. To change this, you can run `slinky` with the following arguments: - -```bash -slinky --log-file-level -``` - -Accepted levels are `debug`, `info`, `warn`, `error`, and `fatal`. **Note that debug logs are verbose and should only be used for debugging purposes.** - -### log-file - -> By default, `slinky` writes logs to `stdout` and to a rotating log file - `sidecar.log` - located in the same directory as the binary. - -This flag allows you to specify the path to the log file where logs should be written. By default, `slinky` writes logs to `stdout` and to a rotating log file located in the same directory as the binary (e.g., `sidecar.log`). To change this, you can run `slinky` with the following arguments: - -```bash -slinky --log-file -``` - -### log-max-size - -> By default, `slinky` rotates the log file when it reaches 100MB. - -This flag allows you to specify the maximum size of the log file before it is rotated. By default, `slinky` rotates the log file when it reaches 100MB. To change this, you can run `slinky` with the following arguments: - -```bash -# Rotates the log file when it reaches 200MB -slinky --log-max-size 200 -``` - -### log-max-backups - -> By default, `slinky` keeps 1 backup of the log file. - -This flag allows you to specify the maximum number of log file backups that should be kept. By default, `slinky` keeps 1 backup of the log file. To change this, you can run `slinky` with the following arguments: - -```bash -# Keeps 3 backups of the log file -slinky --log-max-backups 3 -``` - -### log-max-age - -> By default, `slinky` keeps log files for 3 days. - -This flag allows you to specify the maximum number of days that log files should be kept. By default, `slinky` keeps log files for 3 days. To change this, you can run `slinky` with the following arguments: - -```bash -# Keeps log files for 7 days -slinky --log-max-age 7 -``` - -### log-file-disable-compression - -> By default, `slinky` compresses log files after rotation. Meaning backups are compressed. - -This flag allows you to specify whether log files should be compressed after rotation. By default, `slinky` compresses log files after rotation. To disable this behavior, you can run `slinky` with the following arguments: - -```bash -# Disables log file compression -slinky --log-file-disable-compression -``` - -### log-disable-file-rotation - -> By default, `slinky` stores logs in a rotating log file on disk. - -This flag allows you to specify whether logs should be stored in a rotating log file on disk. By default, `slinky` stores logs in a rotating log file. To disable this behavior, you can run `slinky` with the following arguments: - -```bash -# Disables log file rotation -slinky --log-disable-file-rotation -``` - -## Miscellaneous - -### update-market-config-path - -> By default, `slinky` does not write the markets it is serving prices for to a file. - -This flag allows you to specify the path to a file where `slinky` should write the markets it is serving prices for. By default, `slinky` does not write the markets it is serving prices for to a file. To change this, you can run `slinky` with the following arguments: - -```bash -# Writes the markets to a file located at /path/to/file -slinky --update-market-config-path /path/to/file -``` diff --git a/docs/validator/quickstart.mdx b/docs/validator/quickstart.mdx deleted file mode 100644 index bd321778d..000000000 --- a/docs/validator/quickstart.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -description: Connect Validator Quickstart -title: ☝️ Quickstart ---- - - -**Running Connect? First step is to join our [Discord](https://discord.gg/amAgf9Z39w)** - - -## Summary of Steps - -**Estimated Time**: 10 mins - -In this walkthrough, we'll be going through the 5 steps to set up Connect. - -1. Install the binary of a support chain application. -2. Install the connect binary. -3. Configure your connect sidecar process. -4. Run the connect sidecar. -5. Start the chain application. - -## 1. Install the Chain Binary ✅ - -**🚨** Please visit the chain's validator-specific instructions to install and configure the node binary for the desired chain. - -For the purposes of this guide we'll use `testappd` as our example application binary, but it will be the same for any chain! - -## 2. Install the Connect binary, `slinky` ✅ - -You can install the Connect binary either by building from source or by downloading a pre-built binary. - -- Install the latest binary from the [releases page](https://github.com/skip-mev/slinky/releases) -- Build from source by cloning the [repo](https://github.com/skip-mev/slinky) and running `make install` - -```shell -git clone git@github.com:skip-mev/slinky.git -cd slinky -make install -``` - -Connect's binary, `slinky`, should now be in your path. Check to make sure with: - -```shell -which slinky -``` - -## 3. Configure your Connect Sidecar Process ✅ - -The Connect binary sets sane defaults for as many values as possible. Depending on the chain you're operating for, you may need to override some of the default values. - -Please see our [connect config](/validator/validator-connect-config) page for a complete reference on configurable values. Additionally, our [chain config](/validator/validator-app-config) has references for particular integrations. - -## 4. Run the Connect Sidecar ✅ - -You can run connect by running the following command: - -```shell -slinky -``` - -You can verify whether prices are being retrieved by running the following command: - -```shell -curl 'http://localhost:8080/slinky/oracle/v1/prices' | jq . -``` - -You should see output similar to the following: - -```JSON -{ - "prices": { - "ATOM/USD": "920650000", - "BITCOIN/USD": "3980283250000", - "DYDX/USD": "273682500", - "ETHEREUM/BITCOIN": "5842000", - "ETHEREUM/USD": "232550500000", - "POLKADOT/USD": "638800000", - "SOLANA/USD": "8430350000" - }, - "timestamp": "2024-01-23T01:15:09.776890Z" -} -``` - -## 5. Start the chain application ✅ - -Starting the chain application should be no different than starting the application without the sidecar. - -```shell -testappd start -``` - -## Troubleshooting - -If you are having issues running the oracle sidecar, please see the [Troubleshooting section](validator/troubleshooting.mdx) for more information. diff --git a/docs/validator/rpc-providers.mdx b/docs/validator/rpc-providers.mdx deleted file mode 100644 index f5cc9979e..000000000 --- a/docs/validator/rpc-providers.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: Setting up Additional RPCs within Connect -title: ⛓️ Setting up Additional RPCs within Connect ---- - -### Setting up Additional RPCs within Connect - -Within Connect, validators can add more authenticated RPC endpoints to report decentralized price data from supported blockchains (e.g. Solana, Ethereum, Base...). - -To do this, head over to your `oracle.json` config and add or update your provider entry for `endopints`. Make sure that the RPC you are adding supports authentication via adding a `x-api-key` field within the header. - -For example, if you wanted to add a new RPC with the URL `skiprpc.com` with the API key `skip123` for the Raydium Solana API provider, you would end up with a config like so: - -```json -{ - "providers": { - "raydium_api": { - "api": { - "endpoints": [ - { - "url": "https://api.devnet.solana.com" - }, - { - "url": "skiprpc.com", - "authentication": { - "apiKeyHeader": "x-api-key", - "apiKey": "skip123" - } - } - ] - } - } - } -} -``` - -After this is completed, save your config file, and restart your node! - -The supported decentralized providers for which this is applicable are: - -- `raydium_api` -- `uniswapv3_api-ethereum` -- `uniswapv3_api-base` diff --git a/docs/validator/troubleshooting.mdx b/docs/validator/troubleshooting.mdx deleted file mode 100644 index 4961c6f4f..000000000 --- a/docs/validator/troubleshooting.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -description: Connect Sidecar Troubleshooting -title: ❓ Connect Troubleshooting ---- - -## Troubleshooting FAQs - -We are in the process of building up our core documentation around operational issues and troubleshooting. For now, we are available 24/7 for any questions. -The fastest way to reach us is by emailing support@skip.money - -Can I run Connect on the same machine as my validator? - -Yes, you can run it anywhere - but please defer to any chain-specific recommendations if there are any! - -Can I get slashed for running Connect? - -Not usually. If a chain uses Connect and requires oracle prices to be posted, running the Connect sidecar is the best way to avoid downtime or incorrect prices. -For more information, check out the [Incentivization Docs](/slashing). - -Many chains will reward good operation of Connect with additional validator yield, make sure to ask the team! - -Does Connect take up a lot of resources? - -No, it's a very lightweight binary. - -Can I contribute to Connect? - -Yes - feel free to contribute via opening an issue in [our repo](https://github.com/skip-mev/slinky)! - -### I do not see an issue addressing my question. - -Please reach out to us using your preferred method. We are available on [our website](https://skip.money/contact) or via a [Github issue](https://github.com/skip-mev/slinky/issues/new). - -### Can I use a remote signer? - -The following remote signers with the specified versions are supported - -- [Horcrux](https://github.com/strangelove-ventures/horcrux/releases/tag/v3.3.0): v3.3.0+ is compatible with Connect + vote-extensions - - If you are using [horcrux-proxy](https://github.com/strangelove-ventures/horcrux-proxy/releases/tag/v1.0.0) be sure to use v1.0.0+ so that the `maxReadSize` can be configured in accordance with larger vote-extension payloads - -- [TMKMS](https://github.com/iqlusioninc/tmkms/tree/v0.13.1): v0.13.1+ is compatible with Connect + vote-extensions \ No newline at end of file diff --git a/docs/validator/validator-app-config.mdx b/docs/validator/validator-app-config.mdx deleted file mode 100644 index 844e92886..000000000 --- a/docs/validator/validator-app-config.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -description: Connect Validator App Configuration -title: 🗃️ Validator App Configuration Reference ---- - -# Application Configurations - -This page gives an overview of the configuration options for the applications' oracle service and its corresponding metrics instrumentation. - - - Validators running on a network that supports the oracle **must** run the oracle side-car. - - -## Example App Configuration - -The `app.toml` file is the configuration file that is consumed by the application. This file contains over-arching configurations for your entire Cosmos SDK application, as well as a few new configurations for the oracle. You must use this template to add the oracle configurations to your `app.toml` file: - -```toml -# Other configurations - -... - -############################################################################### -### Oracle ### -############################################################################### -[oracle] -# Enabled indicates whether the oracle is enabled. -enabled = "{{ .Oracle.Enabled }}" - -# Oracle Address is the URL of the out of process oracle sidecar. This is used to -# connect to the oracle sidecar when the application boots up. Note that the address -# can be modified at any point, but will only take effect after the application is -# restarted. This can be the address of an oracle container running on the same -# machine or a remote machine. -oracle_address = "{{ .Oracle.OracleAddress }}" - -# Client Timeout is the time that the client is willing to wait for responses from -# the oracle before timing out. -client_timeout = "{{ .Oracle.ClientTimeout }}" - -... - -# More configurations -``` diff --git a/docs/validator/validator-connect-config.mdx b/docs/validator/validator-connect-config.mdx deleted file mode 100644 index aeec6ae76..000000000 --- a/docs/validator/validator-connect-config.mdx +++ /dev/null @@ -1,308 +0,0 @@ ---- -description: Configuring Your Connect Instance -title: Validator Connect Configuration Reference ---- - -# Oracle Side-Car Configuration - -This page gives an overview of the configurations options available in Connect, what the default values are, and how to override them. - -## Overriding Defaults - -Configurations in Connect have sane defaults in each release which can optionally be overridden in the following ways. - -1. A JSON file can be supplied to the Connect binary via `slinky --oracle-config oracle.json` which should contain the set - of options to be overridden. - -2. Each config option can be set in environment variables where the prefix is `SLINKY_CONFIG` and the separator for - each path element is `_` e.g. `export SLINKY_CONFIG_FOO_BAR_BAZ=false`. - -## Configurable Values in Connect - -The following is a list of configurable options in Connect along with their defaults and the supported methods of -overriding each option. - -### Base Options - -| Name | Type | Default | Environment Variable | Description | -| --------- | ---------------------------------------- | --------- | -------------------- | -------------------------------------------------------------------------------- | -| providers | \{"ProviderName": [Provider](#providers)} | | | The configuration values for each of the configured providers running in Connect. | -| metrics | [Metrics](#metrics) | | | The configuration values for prometheus metrics setup in Connect. | -| host | String | "0.0.0.0" | SLINKY_CONFIG_HOST | The host address which the Connect API server will listen on. | -| port | String | "8080" | SLINKY_CONFIG_PORT | The port which the Connect API server will listen on. | - -### Providers - -Each provider has a unique name which is used as the namespace for its configuration values. -Providers generally fall into a category based on the type of data it retrieves or the method used to retrieve that data. - - -Note that not all providers listed here will be used on every chain. The chain's module contains the set of Providers -required to fetch relevant data. - - -#### API Providers - -Currently supported API Providers: - -- binance_api -- bitstamp_api -- coinbase_api -- coingecko_api -- gecko_terminal_api -- kraken_api - -| Name | Type | Default | Environment Variable | Description | -| ---- | ------------------------- | ---------------- | ------------------------------------------ | ------------------------------------------------------------------------ | -| name | String | $\{PROVIDER}\_api | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_NAME | The name of the Provider. This should never be changed from the default. | -| api | [API Config](#api-config) | | | The configuration options for API Providers. | - -#### API Config - -The API Config applies to all API Providers including those listed above as well as DeFi and Market Map Providers. - -| Name | Type | Environment Variable | Description | -| ---------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| timeout | [Duration](#durations) | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_API_TIMEOUT | The amount of time the Provider will wait for a response from its API endpoint before timing out. | -| interval | [Duration](#durations) | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_API_INTERVAL | The cadence at which the Provider attempts to fetch new data from its endpoint(s). | -| reconnectTimeout | [Duration](#durations) | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_API_RECONNECTTIMEOUT | The time duration to wait before attempting to reconnect to an endpoint. | -| maxQueries | Int | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_API_MAXQUERIES | | -| endpoints | Array[[Endpoint](#endpoints)] | | | -| batchSize | Int | SLINKY_CONFIG_PROVIDERS\_$\{PROVIDER}\_API_BATCHSIZE | | - -#### Market Map Providers - -The market map provider is a unique concept within Connect. It fetches the set of Providers each chain needs data from and -updates Connect based on the response. - - -The endpoint of your configured market map provider should be set to your validating node's endpoint. - - -Currently supported Market Map Providers: - -- marketmap_api - This is the default Provider from which Connect will determine which data to fetch. It uses the GRPC port of the validating node. - -- dydx_api - This is a custom-built Provider which reads from dYdX version 5 in order to determine which markets to fetch. It uses the REST port of the validating node. - -#### DeFi Providers - -Currently supported DeFi Providers: - -- uniswapv3_api-ethereum -- uniswapv3_api-base -- raydium_api - -#### Websocket Providers - -Currently supported websocket Providers: - -- binance_ws -- bitfinex_ws -- bitstamp_ws -- bybit_ws -- coinbase_ws -- crypto_dot_com_ws -- gate_ws -- huobi_ws -- kraken_ws -- kucoin_ws -- mexc_ws -- okx_ws - -### Metrics - -| Name | Type | Default | Environment Variable | Description | -| ----------------------- | ------- | -------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| enabled | Boolean | true | SLINKY_CONFIG_METRICS_ENABLED | Enabling metrics will attempt to serve Prometheus metrics at the provided Prometheus metrics address. | -| prometheusServerAddress | String | "0.0.0.0:8002" | SLINKY_CONFIG_METRICS_PROMETHEUSSERVERADDRESS | The address at which Connect's Prometheus metrics will be exposed. | - -### Durations - -A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". -Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". - -The default unit is ns. i.e. `250000000 = 250ms = .25s` - -### Endpoints - -Endpoints are used in every provider as a uniform way of specifying connection data. -The endpoints configuration for a Provider is an array of Endpoint objects with the following properties. - -Note that only some Providers support multiple Endpoints (such as Uniswap or Raydium). - -| Name | Type | Description | -| -------------- | --------------------------------- | ------------------------------------------------------- | -| url | String | The URL used by the Provider. | -| authentication | [Authentication](#authentication) | The Authentication object associated with the Endpoint. | - -### Authentication - -Authentication allows configuration of auth-related request details. Currently supports injecting HTTP header info for -auth support. - -| Name | Type | Default | Description | -| ------------ | ------ | ----------- | ---------------------------------------------------------------------------------- | -| apiKey | String | "" | The value portion of the HTTP header for requests made to the associated provider. | -| apiKeyHeader | String | "X-Api-Key" | The HTTP header key which will be sent with requests. | - -## Sample Configuration: - -### Overriding the market-map / oracle server endpoint - -```json -{ - "port": 8080, - "metrics": { - "prometheusServerAddress": "0.0.0.0:26662" - }, - "providers": { - "marketmap_api": { - "api": { - "endpoints": [ - { - "url": "127.0.0.1:9090" - } - ] - } - } - } -} -``` - -### Overriding Prometheus Server Endpoint - -```json -{ - "metrics": { - "enabled": true, - "prometheusServerAddress": "0.0.0.0:1111" - } -} -``` - -### Overriding MarketMap Provider Endpoint - -```json -{ - "providers": { - "marketmap_api": { - "api": { - "endpoints": [{ "url": "localhost:99999" }] - } - } - } -} -``` - -### Adding DeFi Provider Endpoints - -```json -{ - "providers": { - "raydium_api": { - "api": { - "endpoints": [ - { - "url": "solana-rpc1.com", - "authentication": { - "apiKey": "abc123" - } - }, - { - "url": "solana-rpc2.com", - "authentication": { - "apiKey": "123abc" - } - } - ] - } - }, - "uniswapv3-base_api": { - "api": { - "endpoints": [ - { - "url": "base-rpc1.com", - "authentication": { - "apiKey": "abc123" - } - }, - { - "url": "base-rpc2.com", - "authentication": { - "apiKey": "123abc" - } - } - ] - } - } - } -} -``` - -### A Typical dYdX Connect Config (as of dYdX protocol version 5) - -A Typical dYdX Connect Config (as of dYdX protocol version 5) -Note that you can also set the dydx_api endpoint via a flag on the Connect binary instead of overriding it in the json config. - -``` -slinky --marketmap-provider dydx_api --market-map-endpoint "http://localhost:1317" -``` - -```json -{ - "providers": { - "dydx_api": { - "api": { - "endpoints": [ - { - "url": "localhost:1317" - } - ] - } - }, - "raydium_api": { - "api": { - "endpoints": [ - { - "url": "solana-rpc1.com", - "authentication": { - "apiKey": "abc123", - "apiKeyHeader": "x-api-key" - } - }, - { - "url": "solana-rpc2.com", - "authentication": { - "apiKey": "123abc", - "apiKeyHeader": "x-api-key" - } - } - ] - } - }, - "uniswapv3_api-base": { - "api": { - "endpoints": [ - { - "url": "base-rpc1.com", - "authentication": { - "apiKey": "abc123", - "apiKeyHeader": "x-api-key" - } - }, - { - "url": "base-rpc2.com", - "authentication": { - "apiKey": "123abc", - "apiKeyHeader": "x-api-key" - } - } - ] - } - } - } -} -``` \ No newline at end of file diff --git a/docs/validators/advanced-setups.mdx b/docs/validators/advanced-setups.mdx new file mode 100644 index 000000000..9c3a071b4 --- /dev/null +++ b/docs/validators/advanced-setups.mdx @@ -0,0 +1,27 @@ +--- +description: Using Connect with Advanced Validator Infrastructure +title: Advanced Setups +icon: plug +--- + +## Using Remote Signers + +Remote signers can be used with Connect, however only certain versions are compatible. + +### Horcrux + +**Required Version:** v3.3.0+ https://github.com/strangelove-ventures/horcrux/releases + +#### With `Horcrux-Proxy` + +**Required Version:** v1.0.0+ https://github.com/strangelove-ventures/horcrux-proxy/releases + +### TMKMS + +**Required Version:** v0.13.1+ https://github.com/iqlusioninc/tmkms/tags + + +## Using Distributed Validators + +Connect can be used within a distributed validator setup. To do so, simply apply the same `app.toml` changes to _each_ validator node. +Head over to [configuration](configuration#application) to see the necessary application-side configurations. diff --git a/docs/validators/configuration.mdx b/docs/validators/configuration.mdx new file mode 100644 index 000000000..11af273fc --- /dev/null +++ b/docs/validators/configuration.mdx @@ -0,0 +1,72 @@ +--- +description: Reference document for configurable values in Connect and Applications. +title: Configuration +icon: gear +--- + +This document serves as a reference for ways to further configure the Connect sidecar, as well as in depth explanations of the application node's configuration. + +## Connect Sidecar + +Connect can be configured by both flags and environment variables. + +### Env Vars + +Please remember to change the `oracle_address` in your [application config](#application) if you change any of the env vars below. + +| Key | Default | Description | +|----------------------|-------------|-----------------------------------------------| +| `SLINKY_CONFIG_HOST` | `"0.0.0.0"` | The address Connect will serve requests from. | +| `SLINKY_CONFIG_PORT` | `"8080"` | The port Connect will serve requests from. | + +### Flags + +| Flag | Default Value | Description | +|----------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--market-map-endpoint` | `""` | The listen-to endpoint for market-map. This is typically the blockchain node's gRPC endpoint. | +| `--oracle-config` | `""` | Overrides part of the Oracle configuration. This does not override the _entire_ configuration, only the part of the configuration specified in the json file passed in. | +| `--run-pprof` | `false` | Run pprof server. | +| `--pprof-port` | `"6060"` | Port for the pprof server to listen on. | +| `--log-std-out-level` | `"info"` | Log level (debug, info, warn, error, dpanic, panic, fatal). | +| `--log-file-level` | `"info"` | Log level for the file logger (debug, info, warn, error, dpanic, panic, fatal). | +| `--log-file` | `"sidecar.log"` | Write logs to a file. | +| `--log-max-size` | `100` | Maximum size in megabytes before log is rotated. | +| `--log-max-backups` | `1` | Maximum number of old log files to retain. | +| `--log-max-age` | `3` | Maximum number of days to retain an old log file. | +| `--log-file-disable-compression` | `false` | Compress rotated log files. | +| `--log-disable-file-rotation` | `false` | Disable writing logs to a file. | + +## Application Node + +The blockchain application is configured under the `[oracle]` heading in your application's `app.toml` file. + +```toml app.toml +# ... other sections + +[oracle] +# Enabled indicates whether the oracle is enabled. +enabled = "true" + +# Oracle Address is the URL of the out of process oracle sidecar. This is used to +# connect to the oracle sidecar when the application boots up. +oracle_address = "CONNECT_ADDRESS_HERE:CONNECT_PORT_HERE" # default Connect port is 8080. + +# Client Timeout is the time that the application is willing to wait for responses from +# the oracle before timing out. +client_timeout = "250ms" + +# MetricsEnabled determines whether oracle metrics are enabled. Specifically, +# this enables instrumentation of the oracle client and the interaction between +# the oracle and the app. +metrics_enabled = "true" + +# PriceTTL is the maximum age of the latest price response before it is considered stale. +# The recommended max age is 10 seconds (10s). If this is greater than 1 minute (1m), the app +# will not start. +price_ttl = "10s" + +# Interval is the time between each price update request. The recommended interval +# is the block time of the chain. Otherwise, 1.5 seconds (1500ms) is a good default. If this +# is greater than 1 minute (1m), the app will not start. +interval = "1500ms" +``` \ No newline at end of file diff --git a/docs/validators/faq.mdx b/docs/validators/faq.mdx new file mode 100644 index 000000000..1834c405e --- /dev/null +++ b/docs/validators/faq.mdx @@ -0,0 +1,55 @@ +--- +description: Frequently asked questions about Connect. +title: FAQs +icon: circle-question +--- + + + + Yes, you can run it anywhere - but please defer to any chain-specific recommendations if there are any! + + + + We are currently working on supporting this feature. It will be available in a future release. + + + + No. Prices are stored in `x/oracle` module, and only stores the most recently posted price. However, you can use blockchain indexers or inspect past blocks to see the prices committed on previous heights. + + + + Prices within Connect are committed on a one-block delay, since validators use the vote extensions from block n-1 to securely submit their price data for block n. + + Most of the time, prices will update every single block. Price updates happen when over 2/3 of validators are correctly running the Connect sidecar. + + Prices will not update on any given block if: + + - The market is disabled within x/marketmap + - Less than 2/3s of validators (by stake weight) contributed to a price update. This can happen if not enough validators run Connect, or there is a massive, widespread outage across providers. + + + + Upgrading the Connect binary can be done out of band of the chain’s binary. If you have a load balancer, CNAME, etc., in front of your sidecar you can simply start up the new version and switch out which version traffic is being directed to during live chain validation. + + If you are running the Connect sidecar in a container you can shut down the container, pull the updated container image and relaunch your container to update. + + If you are running the binary via systemd or other management tool, you will need to stop the process and re-launch using the newly released binary. + + The node will still be able to participate in consensus without the sidecar, and will begin attaching prices to blocks once Connect is available. In the worst case, an upgrade in any of these manners will cause you to miss including vote extensions for a single block which should have no negative effects on you or the network. + + + + No. + + + + No, it's a very lightweight binary. + + + + If you're a validator and need help getting your infrastructure setup, head over to our [discord](https://discord.com/invite/hFeHVAE26P) and let us know what chain you're validating for in the `#waiting-room` channel. + + + + +If you don't see your question here, please reach out to us on [discord](https://discord.com/invite/hFeHVAE26P). \ No newline at end of file diff --git a/docs/validators/quickstart.mdx b/docs/validators/quickstart.mdx new file mode 100644 index 000000000..e06abe3e7 --- /dev/null +++ b/docs/validators/quickstart.mdx @@ -0,0 +1,107 @@ +--- +description: Connect Validator Quickstart +title: Quickstart +icon: person-running-fast +--- + +import QuickStartSnippet from '/snippets/start-connect-snippet.mdx'; +import QuickStartDYDXSnippet from '/snippets/start-connect-dydx-snippet.mdx'; + + + + The following instructions assumes you are running a single validator full node with a remote instance of Connect. If you are not running a full node, you do not need to run Connect. + + +This document will guide you through setting up and running Connect, as well as configuring your node to receive data from Connect. + +## Installation + +### From GitHub Releases + +Head over to our [GitHub Releases](https://github.com/skip-mev/slinky/releases) page and download the binary that matches your machine's architecture. + +### From Source + +To install from source, you'll need [Git](https://git-scm.com/) and [Go](https://go.dev/). + +Enter the commands below to install the binary. +```shell +git clone git@github.com:skip-mev/slinky.git +cd slinky +make install +``` + +## Verify Installation + +Let's check Connect is properly installed on your machine. +You should see the version printed in your terminal after running the following command: +```shell +slinky version +``` + +## Run Connect Sidecar + + + + + + + + + + **The minimum required Connect version for the Neutron chain is `v1.0.3+`.** + + + + + + +### Verify Connect + +To verify Connect is working, run the following command: + +```shell +curl 'http://localhost:8080/slinky/oracle/v1/prices' | jq . +``` + +The output of the command should look similar to this: + +```json +{ + "prices": { + "ATOM/USD": "920650000", + "BITCOIN/USD": "3980283250000", + "DYDX/USD": "273682500", + "ETHEREUM/BITCOIN": "5842000", + "ETHEREUM/USD": "232550500000", + "POLKADOT/USD": "638800000", + "SOLANA/USD": "8430350000" + }, + "timestamp": "2024-01-23T01:15:09.776890Z" +} + +``` + +## Run Application Node + +In order for the application to get prices from Connect, we need to add the following lines under the `[oracle]` heading in the `app.toml`. + +Remember to change the `oracle_address` value to the address of your Connect sidecar. + +```toml app.toml +# ... other sections + +[oracle] +enabled = "true" # if you are not running a full node, set this to "false" +oracle_address = ":8080" +client_timeout = "250ms" +metrics_enabled = "true" +interval = "1500ms" +price_ttl = "10s" +``` + +Once your `app.toml` is configured, you may start your node as normal. + +## Additional Steps + +Using a remote signer? Have a distributed validator setup? Check out the [advanced setups](advanced-setups) to learn how to properly configure your validator infrastructure. \ No newline at end of file