Merge branch 'main' into bapp-example-page

Author: taylorferran

.github/renovate.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "github>ssvlabs/shared-configs//renovate/renovate.json"
+  ]
+}

docs/based-applications/user-guides/create-strategy.md

@@ -23,23 +23,34 @@ This page will display a list of the Strategies you already created.
 
 Once you clicked on "Create Strategy" you will see a list of available bApps you can choose from. 
 
-In this example, we will skip this step and choose "I'll do it later" on the bottom of the page.
+In this example, we will choose MNT-Receiver bApp by clicking "Select" on the right side of the list.
 
 <div style={{ textAlign: 'center' }}>
   <img src="/img/create-strategy-2.png" alt="" />
 </div>
 
-## 3. Set Fee and Obligations
+## 3. Set Obligations
 
-You will be prompted to set the Obligations and the Fees for your strategy. If you did not choose any bApp on the previous step, the Obligations step will be skipped and you will go to the "Set Fee" stage.
+You will be prompted to set the Obligations and add Data for your strategy. If you did not choose any bApp on the previous step, the Obligations step will be skipped and you will go to the "Set Fee" stage.
 
-Enter an amount for your Fee, and click the Continue button.
+- `Obligations` is % of the strategy to be obligated to chosen bApp. In the example on screenshot below, 30% of the strategy's MNT balance will be obligated to the bApp.
+You can later update your obligations by modifying existing ones or adding a new token obligation.
 
-<div style={{ textAlign: 'center', width: '60%', margin: '0 auto' }}>
+- `Add Data` is an optional field for off-chain information required by some bApps for participation. Please check this bApp’s documentation [before opting-in](../developers/get-started/#4-opting-in). 
+
+<div style={{ textAlign: 'center' }}>
+  <img src="/img/create-strategy-7.png" alt="" />
+</div>
+
+## 4. Set Fee
+
+You can choose the fee rate on bApp rewards. Enter an amount for your Fee, and click the Continue button.
+
+<div style={{ textAlign: 'center', width: '100%', margin: '0 auto' }}>
   <img src="/img/create-strategy-3.png" alt="" />
 </div>
 
-## 4. Provide Metadata
+## 5. Provide Metadata
 
 Metadata for your Strategy and your Account will have to be set with `.json` files.
 
@@ -67,7 +78,7 @@ Once you provided URI to those files, you will see that information on the page.
 
 After you verified the information, click on Continue.
 
-## 5. Sign transactions
+## 6. Sign transactions
 
 To create your Strategy you will need to sign 2 transactions.
 
@@ -84,7 +95,7 @@ After the first one is completed, another pop-up will appear to sign Registratio
 </div>
 
 
-## 6. Check the created Strategy
+## 7. Check the created Strategy
 
 Once both of the transactions are completed, you will be redirected to the page of your newly created Strategy.
 

docs/developers/tools/ssv-dkg-client/ceremony-output-summary.md

@@ -24,5 +24,89 @@ ceremony-[timestamp]
 ```
 ### Files:
 * `deposit_data.json` - this file contains the deposit data necessary to perform the transaction on the Deposit contract and activate the validator on the Beacon layer
-* `keyshares.json` - this file contains the keyshares necessary to register the validator on the ssv.network
-* `proof.json` - contains the signed proofs that a DKG client participated in a DKG ceremony, generating key shares for a certain owner. This file is crucial for [resharing your validator to a different set of operators](change-operator-set-and-reshare-validator-key-shares.md), or to [regenerate the signature portion of key shares](update-owner-nonce-in-key-shares.md) in the future.
+* [`keyshares.json`](#keyshares) - this file contains the keyshares necessary to register the validator on the ssv.network
+* [`proof.json`](#proofs) - contains the signed proofs that a DKG client participated in a DKG ceremony, generating key shares for a certain owner. This file is crucial for [resharing your validator to a different set of operators](change-operator-set-and-reshare-validator-key-shares.md), or to [regenerate the signature portion of key shares](update-owner-nonce-in-key-shares.md) in the future.
+
+### Proofs
+#### An example of `proofs.json` structure:
+```json
+[
+  {
+  "proof": {
+    "validator": "VALIDATOR_PUBKEY",
+    "encrypted_share": "ENCRYPTED_SHARE_FOR_I-TH_OPERATOR_IN_CEREMONY",
+    "share_pub": "PUB_KEY_OF_OPERATOR_THAT_ENCRYPTED_THE_SHARE",
+    "owner": "OWNER_ADDRESS_USED_IN_CEREMONY"
+  },
+  "signature": "CONTENT_OF_PROOF_SIGNED_BY_OPERATOR_PRIVATE_KEY"
+  },
+  {
+  "proof": {...},
+  "signature": "..."
+  },
+...
+]
+```
+#### Details about the structure:
+- Each validator will have X proofs, where X is the number of operators in the cluster
+- X proofs of a validator are in an array `[]`
+- One file can contain proofs for multiple validators, by having nested arrays `[[],[],[]]`
+- Each proof has 4 parameters:
+  - `validator` - validator's public key, not encrypted
+  - `encrypted_share`- validator share for i-th operator, encrypted by operator's private key
+  - `share_pub` - Public key of i-th operator, not encrypted
+  - `owner` - Address of validator owner, not encrypted
+- Last parameter `signature` is the content of `proof` signed by private key of i-th operator.
+
+#### How `proofs` secure the ceremony for both parties:
+- Owner/initiator can't change their owner address, because the address is part of proof's content and this is signed by operator's private key.
+- Operator signs the proof with their private key and the proof itself has their public key which can be used to verify the signature.
+
+### Keyshares
+#### An example of `keyshares.json` structure:
+```json
+{
+  "version": "v1.1.0",
+  "createdAt": "2025-05-14T10:23:43.794Z",
+  "shares": [
+    {
+      "data": {
+        "ownerNonce": 0,
+        "ownerAddress": "OWNER_ADDRESS",
+        "publicKey": "VALIDATOR_PUBKEY",
+        "operators": [
+          {
+            "id": 1,
+            "operatorKey": "OPERATOR_PUBKEY"
+          },
+          {...},
+          {...},
+          {...}
+        ]
+      },
+      "payload": {
+        "publicKey": "VALIDATOR_PUBKEY",
+        "operatorIds": [1,2,3,4],
+        "sharesData": "ENCRYPTED_SHARES_DATA"
+      }
+    }
+  ]
+}
+```
+
+#### Details about `sharesData` field
+Below is an example of `sharesData` from a Hoodi validator with 4 operators. Each segment is highlighted with color:
+
+<div style={{ textAlign: 'center', width: '100%', margin: '0 auto' }}>
+  <img src="/img/sharesData.png" alt="" />
+</div>
+
+#### Explanation of each segment:
+- <span style={{ color: 'black', backgroundColor: '#d4d4d4', fontWeight: 'bold' }}>Signature</span>  - First 192 characters (excluding `0x`) is a serialized BLS signed message ([read more about SSZ here](https://ethereum.org/en/developers/docs/data-structures-and-encoding/ssz/)). The message itself is `ownerAddress:ownerNonce`, it's signed by the validator private key and consequently can be verified using validator's `publicKey`.
+- <span style={{ color: 'black', backgroundColor: '#bad6a7', fontWeight: 'bold' }}>Share</span><span style={{ color: 'black', backgroundColor: '#fbe6a2', fontWeight: 'bold' }}>s' pu</span><span style={{ color: 'black', backgroundColor: '#de9d9b', fontWeight: 'bold' }}>blic </span><span style={{ color: 'black', backgroundColor: '#aac1f0', fontWeight: 'bold' }}>keys</span> - An array of concatenated BLS public keys. Each element is a public share of a validator's key and is 96 characters long. The number of shares depends on the number of chosen operators.
+- <span style={{ color: 'black', backgroundColor: '#dce9d5', fontWeight: 'bold' }}>Encr</span><span style={{ color: 'black', backgroundColor: '#fcf5d9', fontWeight: 'bold' }}>ypte</span><span style={{ color: 'black', backgroundColor: '#edcece', fontWeight: 'bold' }}>d sh</span><span style={{ color: 'black', backgroundColor: '#d5e0f5', fontWeight: 'bold' }}>ares</span> - An array of concatenated BLS encrypted keys. Each element is a private share of a validator's key and is 512 characters long. The number of shares depends on the number of chosen operators. Shares are encrypted with each operator's public key and can only be decrypted with the respective private key.
+
+**If you want to learn more about keyshare verification**, you can dissect [verify-keyshare repository  on GitHub](https://github.com/RaekwonIII/verify-keyshares):
+- `validateSingleShares` function in `ssv-keys.ts`  does the signature verification.
+- `buildSharesFromBytes` function breaks down each operators' keyshare.
+- `areKeysharesValid` function then checks the signature and operators' keyshares agains the validator public key.

docs/operators/operator-node/node-setup/README.md

@@ -114,10 +114,11 @@ Git is needed to download the SSV Node stack on your machine.
 
 #### 4. Adjust Firewall
 
-Make sure to expose the ports on your SSV node machine's firewall, otherwise your node won't be able to run correctly. The default ports are :
+Make sure to expose the ports on your SSV node machine's firewall, otherwise your node won't be able to run correctly. The default ports are:
 - P2P - **12001 UDP** and **13001 TCP** 
 - Metrics - **15000 TCP** 
 - Health endpoint - **16000 TCP**
+- DKG port - **3030 TCP**
 
 If you don't want to use the default ports, they can be changed on the next step.
 
@@ -143,21 +144,31 @@ Edit the `ssv.env` file and adjust the settings to your needs. The minimum you n
 * `BEACON_NODE_ADDR` - HTTP address of the Beacon node (e.g. `http://1.2.3.4:5052`)
 * `ETH_1_ADDR` - WebSocket address of the Execution node (e.g. `ws://1.2.3.4:8546`)
 * `NETWORK` - The network you are running on (`mainnet`, `hoodi`)
-:::info
+
+All existing settings are listed on the [Configuration Reference page](./node-configuration-reference.md).
+:::info Multiple Endpoints
 Both `BEACON_NODE_ADDR` and `ETH_1_ADDR` support multiple endpoints. Separate them with `;`.
 
 Example: `BEACON_NODE_ADDR=http://1.2.3.4:5052;http://1.2.3.4:5053`
 :::
-***
-If you already have encrypted key and password files: 
+
+### Password and private key
+On the first start the Node will generate a random `password` and encrypted `private_key` files. You can find the files under `~/ssv-stack/ssv-node-data` directory. 
+
+**If you already have encrypted key and password files**: 
 * Copy/move them to `/ssv-stack/ssv-node-data` 
 * Edit the environment variables to the correct file names, e.g.:
     * `PRIVATE_KEY_FILE=/data/encrypted_private_key.json`
     * `PASSWORD_FILE=/data/password`
 
 **If this is done incorrectly**, new keys will be automatically generated, and you will see a message in the console indicating this.
 
-All existing settings are listed on the [Configuration Reference page](./node-configuration-reference.md).
+
+:::info Backup your files
+Both password and private key are needed to run SSV and DKG Nodes. 
+
+**Backup those files** on a separate device, if any of the two are lost — you will lose access to your operator without a chance to recover.
+:::
 
 ### Custom ports
 
@@ -171,24 +182,20 @@ Changes to those files will be applied after a restart of the node (_if you alre
 ## Start the Node
 
 To start your node use the following command
-
 ```bash
 docker compose up
 ```
 
 Or you can start it in the background, so there won't be logs in your CLI
-
 ```bash
 docker compose up -d
 ```
 
-:::info Backup your files
-On the first start the Node will generate a random `password` and encrypted `private_key` files. 
+## Start DKG Node
+You can also run the stack with DKG, simplifying the setup process. 
 
-Both files are needed to run SSV Node and DKG Node. You can find them under `~/ssv-stack/ssv-node-data` directory. 
+The instructions are on the ["Enablind DKG" section](./enabling-dkg/start-dkg-node/README.md).
 
-**Backup those files** on a separate device, if any of the two are lost — you will lose access to your operator without a chance to recover.
-:::
 
 ## Other setup options
 

docs/operators/operator-node/node-setup/best-practices.md

@@ -7,10 +7,11 @@ sidebar_position: 3
 
 This guide outlines key recommendations to ensure the best Performance and Correctness of your node. The guide will be updated as we get new information.
 
-The page is divided into three parts:
-- [**Introduction**](#introduction) - understanding the Performance, Correctness, and their key factors.
-- [**Major impact**](#major-impact) - vital tips, more obvious.
-- [**Minor impact**](#minor-impact) - fine-tuning tips, nice-to-have, less obvious.
+The page is divided into four parts:
+- [**Introduction**](#introduction) - Understanding the Performance, Correctness, and their key factors.
+- [**SSV-specific**](#ssv-specific) - Features of SSV that will improve Performance or Correctness.
+- [**Major impact**](#major-impact) - Vital tips, more obvious.
+- [**Minor impact**](#minor-impact) - Fine-tuning tips, nice-to-have, less obvious.
 
 
 ## **Introduction**
@@ -22,6 +23,52 @@ Several key factors influence this:
 - **Network Throughput & Latency:** Minimal network delay is critical, especially for production setups.
 - **Hardware Resources:** Adequate CPU, sufficient RAM, and fast, reliable storage are necessary.
 
+## **SSV-specific**
+
+#### Failover for EL and CL clients 
+```yaml
+eth2:
+  # HTTP URL of the Beacon node to connect to.
+  BeaconNodeAddr: http://example.url:5052;http://example.url:5053
+
+eth1:
+  # WebSocket URL of the Execution node to connect to.
+  ETH1Addr: ws://example.url:8546/ws;ws://example.url:8547/ws
+```
+- When the first node goes offline or out of sync, SSV will switch to the next endpoint.
+- Endpoints should be set in the order you want them to be used. The first node will be the primary one.
+- Failover works in round-robin way, so once SSV circled through all of the endpoints it will start from the first one again.
+- When SSV node restarts it will always start with the first endpoint from the list.
+
+
+#### Weighted Attestation Data
+```yaml
+eth2:
+  WithWeightedAttestationData: true   # Enables WAD
+```
+- The feature only works with 2+ CL endpoints (`BeaconNodeAddr`) configured.
+- Improves attestation accuracy by scoring responses from multiple Beacon nodes based on epoch and slot proximity. Adds slight latency to duties but includes safeguards (timeouts, retries). 
+
+#### Parallel Data Submission
+```yaml
+eth2:
+  WithParallelSubmissions: true   # Sends duties to all nodes concurrently
+```
+- The feature only works with 2+ CL endpoints (`BeaconNodeAddr`) configured.
+- SSV will submit duty data to all Beacon nodes in parallel. This built-in configuration ensures high availability and improves performance.
+
+
+#### Doppelganger Protection
+```yaml
+EnableDoppelgangerProtection: true # Enables Doppelganger Protection
+```
+- Doppelganger Protection (DG) checks if the managed validators are attesting elsewhere at the moment of SSV node start. That prevents double signature which is a slashable event.
+- SSV with DG enabled will be offline for the first 3 epochs after the node start.
+- If enough nodes in the cluster have DG enabled and are online - a restarted node will not wait for 3 epochs. Node can identify that there's a DG quorum going on and will join it. This process is almost as quick as restart of a node without DG.
+- If you manage all nodes in the cluster — it is recommended to restart one by one. Otherwise, it will take 3 epochs to do the DG checks.
+- To learn more technical details please refer to [our documentation page on GitHub](https://github.com/ssvlabs/ssv/blob/v2.3.0/doppelganger/README.md).
+
+
 ## **Major impact**
 High‑priority practices that ensure reliable, on‑time duty submissions. Might sound obvious, but are often overlooked.
 
@@ -32,7 +79,7 @@ Most of hardware-related suggestions below are for Execution (EL) and Consensus
 ### **For Home Setups**
 - **Hardware:** Usual setup has 4- to 8-core CPU (focus on single-thread performance) and 32GB RAM.
 - **Disk:** NVMe SSDs are strongly recommended. If you're unsure with filesystem to use, stick to `ext4`, as it is performant and the easiest to maintain. 
-- **Reliability:** Use a UPS and ensure the machine is well-ventilated. Sudden power loss or thermal throttling can cause downtime or result in missed duties
+- **Reliability:** Use a UPS and ensure the machine is well-ventilated. Sudden power loss or thermal throttling can cause downtime or result in missed duties.
 - **Internet Connectivity:** Ensure your ISP doesn't impose strict data caps. Choose a plan with at least 10 Mbps upload speed, but latency and reliability make the difference.
 - **[Follow EthStaker hardware section](https://ethstaker.org/staking-hardware)** as their guides are focused on running Execution and Consensus nodes.
 
@@ -62,8 +109,8 @@ Ensure your hardware meets or exceeds [SSV recommended specifications](./hardwar
 Ensure all required ports are open and correctly configured on your setup.
 
 **Critical Ports:**
-  - **SSV P2P:** Typically 12001 UDP and 13001 TCP (or as specified in your configuration)
-  - **Execution P2P:** Typically 30303 TCP and UDP (for Geth and Nethermind)
+  - **SSV P2P:** Typically 12001 UDP and 13001 TCP (or as specified in your configuration).
+  - **Execution P2P:** Typically 30303 TCP and UDP (for Geth and Nethermind).
   - **Execution RPC:** HTTP 8545 and WS 8546 (for Geth and Nethermind), **open only to SSV Node!**.
   - **Consensus P2P:** Depends on your client, make sure to follow your client's documentation to open the correct ports.
   - **Consensus RPC:** Depends on your client (e.g. 3500 for Prysm, 5052 for Lighthouse), **open only to SSV Node!**.
@@ -84,9 +131,6 @@ Location of your clients plays a direct role in performance. Co-hosting Executio
 
 ### Network Throughput and Latency
 
-**Recommendation:**  
-  Optimize your overall network performance by implementing the following best practices:
-
 **Minimizing Intermediate Layers**
     - Reduce the number of intermediate hops (such as redundant routers, proxies, or firewalls) between your nodes and connected services.
     - Simplify your firewall configuration by using minimal, direct rule sets (e.g., UFW with straightforward rules) to avoid delays.
@@ -145,36 +189,6 @@ Keep your clients updated, while prioritizing stability over following every upg
 **TCP Congestion Control**
   - Set your TCP congestion control to BBR by [following this guide](https://www.cyberciti.biz/cloud-computing/increase-your-linux-server-internet-speed-with-tcp-bbr-congestion-control/), if supported by your kernel version.
 
-### SSV-Specific
-
-**Failover for EL and CL clients:**  
-
-```yaml
-eth2:
-  # HTTP URL of the Beacon node to connect to.
-  BeaconNodeAddr: http://example.url:5052;http://example.url:5053
-
-eth1:
-  # WebSocket URL of the Eth1 node to connect to.
-  ETH1Addr: ws://example.url:8546/ws;ws://example.url:8547/ws
-```
-
-**Weighted Attestation Data**
-- The feature only works with 2+ CL endpoints configured
-- Improves attestation accuracy by scoring responses from multiple Beacon nodes based on epoch and slot proximity. Adds slight latency to duties but includes safeguards (timeouts, retries). 
-```yaml
-eth2:
-  WithWeightedAttestationData: true   # Enables WAD
-```
-
-**Parallel Data Submission**
-- The feature only works with 2+ CL endpoints (`BeaconNodeAddr`) configured
-- Take advantage of the SSV client's native ability to submit duty data in parallel. This built-in configuration helps ensure high availability and improve performance:
-```yaml
-eth2:
-  WithParallelSubmissions: true   # Sends duties to all nodes concurrently
-```
-
 ### Containerization Trade-offs
 
 **Recommendation:**