Skip to content

Add Slinky sections #433

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
kzdydx merged 4 commits into from
Jan 28, 2026
Merged

Add Slinky sections #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4002b6f
add Slinky sections
2dpetkov Jan 14, 2026
0e7d93b
address PR comments
2dpetkov Jan 19, 2026
3f128ec
fix: wrong link in upgrading-sidecar page
2dpetkov Jan 21, 2026
ee31eba
fix workflow warnings
2dpetkov Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion docs/pages/concepts/onboarding-faqs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,14 +334,32 @@
<summary>1. How is the oracle price computed?</summary>

- The oracle price has five parts:
- Skip Protocol Sidecar: side car that pulls price data from external sources and caches them for the validator to use [link](https://docs.skip.build/connect/validators/quickstart).
- Slinky: sidecar that pulls price data from external sources and caches them for the validator to use [link](https://github.com/dydxprotocol/slinky).
- Vote Extensions: Every block during the Precommit stage, all validators will submit vote extensions for what they believe the oracle price of all tracked assets should be.
- Consensus: The block after VE are submitted, Slinky deterministically aggregates all VE from the previous block and proposes a new updated price which is voted into consensus.
- `x/prices` Module: updates the state based on the new price, also has logic for validation and etc. [link](https://github.com/dydxprotocol/v4-chain/tree/main/protocol/x/prices).
- Params: determines the external sources and sensitivity [link](https://github.com/dydxprotocol/v4-testnets/blob/aa1c7ac589d6699124942a66c2362acad2e6f50d/dydx-testnet-4/genesis.json#L6106), these are configured per network (testnet genesis example), but should query the network config for these `dydxprotocold query prices list-market-param`.

</details>

<details>
<summary>2. How often are prices updated on-chain?</summary>

- Prices within Slinky 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 Slinky 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 Slinky, or there is a massive, widespread outage across providers.

</details>

<details>
<summary>3. Does Slinky store historical prices?</summary>

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

</details>

## Rewards

<details>
Expand Down
70 changes: 70 additions & 0 deletions docs/pages/nodes/running-node/required-node-configs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,73 @@ enable = true
# with either of the following flags: `--grpc.enable`, `--grpc.address`.
address = "0.0.0.0:9090"
```

#### Oracle Configuration

```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 = "SLINKY_ADDRESS_HERE:SLINKY_PORT_HERE" # default Slinky 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, 0.6 seconds (600ms) is a good default. If this
# is greater than 1 minute (1m), the app will not start.
interval = "600ms"
```

## Slinky Configs

Sidecar can be configured by both flags and environment variables.

### Env Vars

| Key | Default | Description |
|---------------------------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `CONNECT_CONFIG_HOST` | `"0.0.0.0"` | The address Slinky will serve requests from. For single-machine deployments, consider using `127.0.0.1` for enhanced security. WARNING: changing this value requires updating the oracle_address in the app.toml configuration. |
| `CONNECT_CONFIG_PORT` | `"8080"` | The port Slinky will serve requests from. WARNING: changing this value requires updating the oracle_address in the app.toml configuration. |
| `CONNECT_CONFIG_METRICS_ENABLED` | `"true"` | Enables prometheus metrics. |
| `CONNECT_CONFIG_METRICS_PROMETHEUSSERVERADDRESS` | `"0.0.0.0:8002"` | The address of your prometheus server instance. |


### 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 specified part. |
| `--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. |
| `--metrics-enabled` | `true` | Enables the Oracle client metrics. |
| `--metrics-prometheus-address` | `"0.0.0.0:8002"` | Sets the Prometheus server address for the Oracle client metrics. |
| `--host` | `"0.0.0.0"` | The address the Oracle will serve from. |
| `--port` | `"8080"` | The port the Oracle will serve from. |
| `--update-interval` | `250000000` | The interval at which the oracle will fetch prices from providers. |
| `--max-price-age` | `120000000000` | Maximum age of a price that the oracle will consider valid. |
224 changes: 220 additions & 4 deletions docs/pages/nodes/running-node/running-a-validator.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,228 @@ For the chain to process bridge transactions from Ethereum, Ethereum testnet, or

As a validator run the flags `--bridge-daemon-enabled=false` in the command you run when starting the node, since the bridge has been disabled

## Connect Sidecar
## Slinky

Starting in `v5.0.0`, running a validating full node requires a Skip Protocol's Connect Sidecar to be run in order to fetch Oracle prices. The sidecar should be started before upgrading from `v4` to `v5`. Instructions to start Connect Sidecar can be found [here](https://docs.skip.build/connect/validators/quickstart).
Starting in [`v5.0.0`](https://www.mintscan.io/dydx/proposals/59), running a validating full node requires the Slinky sidecar to be running in order to fetch Oracle prices. Slinky is a sidecar that pulls price data from external sources and caches them for the validator to use.

Support issues with Skip's Sidecar should be directed [here](https://discord.gg/7hxEThEaRQ).
### Running Slinky

You can find the required version of the Connect sidecar listed in the `dYdX Blockchain` section [here](https://docs.skip.build/connect/validators/quickstart#run-connect-sidecar).
First, please ensure you have received your API keys for the relevant decentralized provider nodes. If you have not received API keys, please reach out to the provider team in the relevant communication channels.

Next, place your API keys under their corresponding URLs in the example file below and save it to your system. Keep the file path handy as it needs to be passed into a flag when running Slinky.

The `oracle.json` file also supplies an edited configuration for the `dydx_migration_api` which facilitates graceful migration from dydx's `x/prices` module to `x/marketmap` module.
For the `dydx_migration_api` provider, make sure to fill in the URL for the REST endpoint and gRPC endpoint of your node (in that order). The migration API will not work unless the REST API endpoint is the first endpoint in the endpoints list.

<details>
<summary>Example `oracle.json` file</summary>

```json
{
"providers": {
"dydx_migration_api": {
"api": {
"endpoints": [
{
"url": "http://<YOUR NODE REST API ENDPOINT>"
},
{
"url": "<YOUR NODE GRPC ENDPOINT>:<YOUR NODE GRPC PORT>"
}
]
}
},
"raydium_api": {
"api": {
"endpoints": [
{
"url": "https://solana.polkachu.com",
"authentication": {
"apiKeyHeader":"x-api-key",
"apiKey":"API KEY"
}
},
{
"url": "https://connect-solana.kingnodes.com",
"authentication": {
"apiKeyHeader":"x-api-key",
"apiKey":"API KEY"
}
},
{
"url": "https://dydx.helius-rpc.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
}
]
}
},
"uniswapv3_api-ethereum": {
"api": {
"endpoints": [
{
"url": "https://ethereum.polkachu.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
},
{
"url": "https://connect-eth.kingnodes.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
},
{
"url": "https://ethereum-rpc.rhino-apis.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
}
]
}
},
"uniswapv3_api-base": {
"api": {
"endpoints": [
{
"url": "https://base-rpc.rhino-apis.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
},
{
"url": "https://connect-base.kingnodes.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
},
{
"url": "https://base.polkachu.com",
"authentication": {
"apiKeyHeader": "x-api-key",
"apiKey": "API KEY"
}
}
]
}
}
}
}
```

</details>

With the `oracle.json` file path, enter the following command to run Slinky.

```bash
connect \
--marketmap-provider dydx_migration_api \
--oracle-config path/to/oracle.json
```

For more information on the available configuration parameters for Slinky, please refer to the [Slinky Configuration](/nodes/running-node/required-node-configs.mdx#slinky-configs) section.

### Verifying Slinky is Running

To verify that Slinky is running, enter the following command.

```bash
curl 'http://localhost:8080/connect/oracle/v2/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"
}
```

### Connecting a dYdX Validator node to Slinky

In order for the application to get prices from Slinky, 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 Slinky instance.
```toml (app.toml)
# ... other sections

[oracle]
enabled = "true" # if you are not running a full node, set this to "false"
oracle_address = "<YOUR_SLINKY_SIDECAR_ADDRESS>:8080"
client_timeout = "250ms"
metrics_enabled = "true"
interval = "1500ms"
price_ttl = "10s"
```

For more information on the available configuration parameters for the oracle, please refer to the [Oracle Configuration](/nodes/running-node/required-node-configs.mdx#oracle-configuration) section.

### Advanced Slinky Configuration

In case you are using a remote signer or have another distributed validator setup, you may need to configure Slinky differently.

#### Using Remote Signers
Remote signers can be used with Connect, however only certain versions are compatible

**Horcrux**
Required Version: `v3.3.0+` [link](https://github.com/strangelove-ventures/horcrux/releases)

**With `Horcrux-Proxy`**
Required Version: `v1.0.0+` [link](https://github.com/strangelove-ventures/horcrux-proxy/releases)

**TMKMS**
Required Version: `v0.13.1+` [link](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](/nodes/running-node/required-node-configs.mdx) to see the necessary application-side configurations.

### Upgrading Slinky

The recommended version of Slinky is the latest released version in the GitHub repository [link](https://github.com/dydxprotocol/slinky).

Instructions on upgrading sidecar can be found [here](/nodes/upgrades/upgrading-sidecar).

### Slinky FAQ
<details>
<summary>Can I run Slinky on the same machine as my validator?</summary>

- Yes, you can run it anywhere - but please defer to any chain-specific recommendations if there are any!

</details>

<details>
<summary>Can I use IPv6?</summary>

- No, IPv6 is currently not supported for sidecar-node communication.

</details>

<details>
<summary>Can I get slashed for running Connect?</summary>

- No.

</details>

<details>
<summary>Does Connect take up a lot of resources?</summary>

- No, the Connect binary is very lightweight. On a 36 GB Macbook Pro M3, a Connect instance fetching 125 markets took up only 50MB of memory, and 6% of the CPU.

</details>
11 changes: 9 additions & 2 deletions docs/pages/nodes/upgrades/upgrading-sidecar.mdx
View file
Open in desktop
Copy link
Contributor

@kzdydx kzdydx Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link in the running node section is causing the linter to fail, also when clicking sidecar on the vercel page it 404s

Copy link
Contributor Author

@2dpetkov 2dpetkov Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kzdydx I think I fixed this, can you have a look?
(seems like the link was broken before this change)

Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
Starting in `v5.0.0`, all validating full nodes should be running the [Sidecar](../running-node/optimize.mdx#slinky-sidecar). Non validating full nodes do not need to run the sidecar.
Starting in [`v5.0.0`](https://www.mintscan.io/dydx/proposals/59), all validating full nodes should be running the [Sidecar](/nodes/running-node/running-a-validator#slinky). Non validating full nodes do not need to run the sidecar.

Upgrading the Slinky 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 Slinky 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 Slinky 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 Slinky 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.

Follow instructions [here](https://docs.skip.build/connect/validators/faq#how-do-i-upgrade-the-connect-binary) to upgrade the sidecar.