add workflows

.github/workflows/build-docs.yml

@@ -0,0 +1,28 @@
+name: 'build-docs'
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger mintlify workflow
+        if: github.event_name == 'push'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.DOCS_CHILDREN_ACTIONS_TRIGGER_TOKEN }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'mintlify-onboarding',
+              repo: 'skip',
+              workflow_id: 'mintlify-action.yml',
+              ref: 'main',
+            });

docs/incentivize-slashing.mdx

@@ -0,0 +1,88 @@
+---
+title: 'Incentivization & Slashing'
+---
+
+## 🤝 Validators and Slinky[​](#-validators-and-slinky 'Direct link to heading')
+
+✅ **Validators are the lifeblood of Slinky operation** - Slinky 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 Slinky to operate.
+
+✅ **Validators do this by running the Slinky Sidecar** - Slinky 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 Slinky** - Validators can (should!) be rewarded for doing more for the chains they operate on. To accomplish this, Slinky 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, Slinky has two prebuilt mechanisms to enable slashing.
+
+## 💰 Reward Mechanism[​](#-reward-mechanism 'Direct link to heading')
+
+- When Slinky 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, Slinky also can support sharing of trading-fees and any arbitrary source of revenue.
+
+<Note>
+
+We Share Everything
+
+Skip is dedicated to rewarding validators. For any fees a chain agrees to pay Skip for Slinky operation, we share 20% of this with the validators who operate it.
+
+</Note>
+
+With fee sharing, a fixed amount of fees is shared **per-block** to validators that correctly operate Slinky.
+
+- This means, if `$1000` was allocated for a certain block, and only 10 validators correctly operated Slinky that block, each validator would recieve an additional `$100` on top of their block rewards.
+
+Note that the Slinky reward is **additional** to normal validator commission.
+
+## 📉 Downtime slashing[​](#-downtime-slashing 'Direct link to heading')
+
+Slinky 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](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[​](#-incorrect-price-slashing 'Direct link to heading')
+
+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.
+
+![](/images/slinky-town-crier.png)