From 78fe336f81516959f432927aa55ab24b969e8411 Mon Sep 17 00:00:00 2001 From: Jared-dz Date: Wed, 20 May 2026 16:16:41 -0400 Subject: [PATCH 1/2] validator rewards claim --- docs/Configure Validator Publisher Rewards.md | 148 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 149 insertions(+) create mode 100644 docs/Configure Validator Publisher Rewards.md diff --git a/docs/Configure Validator Publisher Rewards.md b/docs/Configure Validator Publisher Rewards.md new file mode 100644 index 0000000..0fbaec1 --- /dev/null +++ b/docs/Configure Validator Publisher Rewards.md @@ -0,0 +1,148 @@ +# Configure Validator Publisher Rewards +!!! warning "By connecting to DoubleZero I agree to the [DoubleZero Terms of Service](https://doublezero.xyz/terms-protocol)" + +Validators that publish leader shreds to DoubleZero Edge earn rewards each epoch. Before rewards can be paid, each validator must register **where** rewards go by configuring a `ValidatorPublisherRewards` account on Solana. That account stores: + +- the **rewards mint** — the token rewards are paid in (default `2z`) +- the **rewards owner** — the wallet that owns the Associated Token Account (ATA) receiving rewards + +You can re-run `configure` later to change either field. + +!!! info "If you have not yet completed [Setup](setup.md) and [Validator Mainnet-Beta Connection](DZ%20Mainnet-beta%20Connection.md), do that first." + +## Prerequisites + +- A validator publishing leader shreds via `doublezero connect multicast --publish edge-solana-shreds` (see [Validator Multicast Connection](Validator%20Multicast%20Connection.md)). +- The latest `doublezero-solana` CLI: `sudo apt update && sudo apt install doublezero-solana`. +- Access to the **validator identity keypair**, either on the same box or kept offline with the ability to sign a message. +- A destination wallet pubkey that will own the rewards ATA. + +--- + +## 1. Choose an Auth Path + +Configuring the rewards account requires authorization from the validator identity key. There are two ways to provide it: + +| Path | When to use | +|---|---| +| **Direct** | The validator identity keypair is on the box you're running commands from. The transaction signature itself satisfies the on-chain identity check. | +| **Offchain** | The validator identity keypair is kept offline or on a separate machine from the fee-payer wallet. The identity authorization is carried as an ed25519 envelope (signature + deadline slot) produced separately. | + +--- + +## 2a. Direct Path + +Run `configure` with the validator identity keypair as `-k`. No separate message-signing step is needed — the transaction signature is the proof. + +```bash +doublezero-solana shreds publisher-rewards configure \ + --node-id \ + --rewards-token-owner \ + --rewards-token-mint 2z \ + -k +``` + +| Flag | Description | +|---|---| +| `--node-id` | Validator node identity pubkey. Seed for the PDA. | +| `--rewards-token-owner` | Wallet that will own the receiving ATA. Must be non-default. | +| `--rewards-token-mint` | Mint for rewards. Accepts a pubkey or one of the aliases `2z`, `usdc`, `wsol` (resolved against the connected network environment). Default: `2z`. | +| `-k` | Path to the validator identity keypair. On the direct path, the keypair's pubkey must equal `--node-id` or the command will error out and tell you to switch to the offchain path. | + +The PDA is auto-initialized in the same transaction if it doesn't yet exist. + +Skip ahead to [step 3](#3-verify-the-configuration). + +--- + +## 2b. Offchain Path + +Three sub-steps: prepare, sign, configure. + +### 2b.i. Prepare the offchain message + +Run this anywhere — it's read-only and does not need the validator identity keypair. It prints the hex blob to sign and the absolute slot the signature expires at. + +```bash +doublezero-solana shreds publisher-rewards prepare-offchain-message \ + --node-id \ + --rewards-token-owner \ + --rewards-token-mint 2z \ + --valid-for 1h +``` + +| Flag | Description | +|---|---| +| `--node-id` | Validator node identity pubkey. | +| `--rewards-token-owner` | Wallet that will own the receiving ATA. | +| `--rewards-token-mint` | Mint for rewards. Accepts a pubkey or `2z` / `usdc` / `wsol`. Default: `2z`. | +| `--valid-for` | Signature lifetime relative to the current slot. Accepts `s`, `m`, or `h`. Default: `1h`. | +| `--deadline-slot` | Alternative to `--valid-for`: absolute slot the authorization expires at. Mutually exclusive with `--valid-for`. | +| `--json` | Emit JSON (`{ hex, deadline_slot }`) instead of the human summary. | + +The command prints the hex-encoded auth message, the resolved deadline slot, and ready-to-run shell snippets for the next two steps. + +### 2b.ii. Sign the message + +On the machine that holds the validator identity keypair: + +```bash +solana sign-offchain-message --keypair +``` + +This prints a base58 signature. + +### 2b.iii. Submit `configure` + +Back on the machine with your fee-payer wallet: + +```bash +doublezero-solana shreds publisher-rewards configure \ + --node-id \ + --rewards-token-owner \ + --rewards-token-mint 2z \ + --signature \ + --deadline-slot +``` + +`--signature` and `--deadline-slot` must be passed together. The values must match those produced in steps 2b.i and 2b.ii. + +The PDA is auto-initialized in the same transaction if it doesn't yet exist. + +--- + +## 3. Verify the Configuration + +```bash +doublezero-solana shreds publisher-rewards show --node-id +``` + +The command prints the `Node ID`, `Rewards owner`, `Rewards mint`, the resolved ATA address, and the ATA status. The **Resolved ATA** is the deterministic address derived from the rewards owner + rewards mint — it's where rewards will be deposited each epoch. + +If the ATA does not exist, `show` exits with a hard error and suggests the command to create it: + +```bash +spl-token create-account --owner +``` + +Rewards are not distributed until the ATA exists. Run `show` again after creating it to confirm. + +--- + +## Troubleshooting + +### Direct path: `-k` pubkey does not match `--node-id` + +The fee-payer keypair you passed isn't the validator identity. Either pass the validator identity keypair as `-k`, or switch to the [offchain path](#2b-offchain-path). + +### Unknown or disabled reward mint + +`configure` requires the `ShredRewardToken` PDA for the chosen mint to exist and be enabled. Use `2z` (default) unless you have explicit confirmation a different mint is supported in your environment. + +### Signature expired + +Each offchain signature has a deadline slot. If too much time passes between `prepare-offchain-message` and `configure`, re-run `prepare-offchain-message`, re-sign, and re-submit. Default validity is 1 hour — extend with `--valid-for 4h` or similar if you need more time for an offline signing flow. + +### Rewards aren't arriving + +Run `doublezero-solana shreds publisher-rewards show --node-id ` and confirm the ATA exists. If `show` reports a missing ATA, create it with `spl-token create-account` as shown above. diff --git a/mkdocs.yml b/mkdocs.yml index eff2bdd..39a1b61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,6 +58,7 @@ nav: - Validator Testnet Connection: DZ Testnet Connection.md - Permissioned Connection: Permissioned Connection.md - Validator Multicast Connection: Validator Multicast Connection.md + - Configure Validator Publisher Rewards: Configure Validator Publisher Rewards.md - Other Multicast Connection: Other Multicast Connection.md - Edge Subscriber Connection: Edge Subscriber Connection.md - Troubleshooting: troubleshooting.md From 555d2304a6983f80c16551bbbab890ac3dd49e33 Mon Sep 17 00:00:00 2001 From: Jared-dz Date: Fri, 29 May 2026 10:36:13 -0400 Subject: [PATCH 2/2] cleanup --- ...lisher Rewards.md => Validator Rewards.md} | 100 ++++++++++++------ mkdocs.yml | 2 +- 2 files changed, 66 insertions(+), 36 deletions(-) rename docs/{Configure Validator Publisher Rewards.md => Validator Rewards.md} (55%) diff --git a/docs/Configure Validator Publisher Rewards.md b/docs/Validator Rewards.md similarity index 55% rename from docs/Configure Validator Publisher Rewards.md rename to docs/Validator Rewards.md index 0fbaec1..74d5eeb 100644 --- a/docs/Configure Validator Publisher Rewards.md +++ b/docs/Validator Rewards.md @@ -1,4 +1,4 @@ -# Configure Validator Publisher Rewards +# Validator Rewards !!! warning "By connecting to DoubleZero I agree to the [DoubleZero Terms of Service](https://doublezero.xyz/terms-protocol)" Validators that publish leader shreds to DoubleZero Edge earn rewards each epoch. Before rewards can be paid, each validator must register **where** rewards go by configuring a `ValidatorPublisherRewards` account on Solana. That account stores: @@ -8,12 +8,12 @@ Validators that publish leader shreds to DoubleZero Edge earn rewards each epoch You can re-run `configure` later to change either field. -!!! info "If you have not yet completed [Setup](setup.md) and [Validator Mainnet-Beta Connection](DZ%20Mainnet-beta%20Connection.md), do that first." +!!! info "If you have not yet completed [Setup](setup.md), [Validator Mainnet-Beta Connection](DZ%20Mainnet-beta%20Connection.md), and [Validator Multicast Connection](Validator%20Multicast%20Connection.md), do that first." ## Prerequisites -- A validator publishing leader shreds via `doublezero connect multicast --publish edge-solana-shreds` (see [Validator Multicast Connection](Validator%20Multicast%20Connection.md)). -- The latest `doublezero-solana` CLI: `sudo apt update && sudo apt install doublezero-solana`. +- A validator publishing leader shreds see [Validator Multicast Connection](Validator%20Multicast%20Connection.md). +- The latest `doublezero-solana` CLI: `sudo apt update && sudo apt install doublezero-solana`, at a minimum `0.5.6-rc1`. - Access to the **validator identity keypair**, either on the same box or kept offline with the ability to sign a message. - A destination wallet pubkey that will own the rewards ATA. @@ -25,31 +25,42 @@ Configuring the rewards account requires authorization from the validator identi | Path | When to use | |---|---| -| **Direct** | The validator identity keypair is on the box you're running commands from. The transaction signature itself satisfies the on-chain identity check. | -| **Offchain** | The validator identity keypair is kept offline or on a separate machine from the fee-payer wallet. The identity authorization is carried as an ed25519 envelope (signature + deadline slot) produced separately. | +| **Direct** | The validator identity keypair is on the box you're running commands from.| +| **Offchain** | The validator identity keypair is kept offline or on a separate machine from the fee-payer wallet. | --- ## 2a. Direct Path -Run `configure` with the validator identity keypair as `-k`. No separate message-signing step is needed — the transaction signature is the proof. +Run `configure` with the validator identity keypair as `-k`. ```bash doublezero-solana shreds publisher-rewards configure \ - --node-id \ - --rewards-token-owner \ + --node-id \ + --rewards-token-owner \ --rewards-token-mint 2z \ -k ``` +Example Output +```bash +Shred subscription - Configure Validator Publisher Rewards +Node ID: ValidatorIdentity111111111111111111111111111 +Rewards owner: ValidatorIdentity111111111111111111111111111 +Rewards mint: J6pQQ3FAcJQeWPPGppWRb4nM8jU3wLyYbRrLh7feMfvd +Rewards ATA: 11111111111Pt3PatTj59dG5BhYuqPb9QJDUr1111111 +Auth path: direct +Configured validator publisher rewards: 41111111ntmoBTnvcKcP1g2a1111111HPoN3z5uf11111112jjzBJsr1B2JrTRff4dSGe1pdM1111111TMADi3Nz +``` +`Configured validator publisher rewards: ` outputs the txt you can view in a block explorer. | Flag | Description | |---|---| -| `--node-id` | Validator node identity pubkey. Seed for the PDA. | -| `--rewards-token-owner` | Wallet that will own the receiving ATA. Must be non-default. | -| `--rewards-token-mint` | Mint for rewards. Accepts a pubkey or one of the aliases `2z`, `usdc`, `wsol` (resolved against the connected network environment). Default: `2z`. | +| `--node-id` | Validator node identity pubkey. | +| `--rewards-token-owner` | Wallet that will own the receiving ATA. | +| `--rewards-token-mint` | The wallet token rewards will be received in. Allowed tokens are `2z`, `usdc`, `wsol`. Default: `2z`. | | `-k` | Path to the validator identity keypair. On the direct path, the keypair's pubkey must equal `--node-id` or the command will error out and tell you to switch to the offchain path. | -The PDA is auto-initialized in the same transaction if it doesn't yet exist. +The ATA is auto-initialized in the same transaction if it doesn't yet exist. Skip ahead to [step 3](#3-verify-the-configuration). @@ -65,17 +76,32 @@ Run this anywhere — it's read-only and does not need the validator identity ke ```bash doublezero-solana shreds publisher-rewards prepare-offchain-message \ - --node-id \ - --rewards-token-owner \ + --node-id \ + --rewards-token-owner \ --rewards-token-mint 2z \ --valid-for 1h ``` +Example Output + +```bash +Hex message: 123457fc138f556a2578bdb079dc923342cc4e4a376683dc4c6cb923051e0be3 +Deadline slot: 422954444 + +Sign with: + solana sign-offchain-message 123457fc138f556a2578bdb079dc923342cc4e4a376683dc4c6cb923051e0be3 --keypair + +Then submit: + doublezero-solana shreds publisher-rewards configure \ + --node-id ValidatorIdentity111111111111111111111111111 --rewards-token-mint J6pQQ3FAcJQeWPPGppWRb4nM8jU3wLyYbRrLh7feMfvd --rewards-token-owner Wallet567Identity111111111111111111111111111 \ + --deadline-slot 422954444 --signature +``` + | Flag | Description | |---|---| | `--node-id` | Validator node identity pubkey. | | `--rewards-token-owner` | Wallet that will own the receiving ATA. | -| `--rewards-token-mint` | Mint for rewards. Accepts a pubkey or `2z` / `usdc` / `wsol`. Default: `2z`. | +| `--rewards-token-mint` | The wallet token rewards will be received in. Allowed tokens are `2z`, `usdc`, `wsol`. Default: `2z`. | | `--valid-for` | Signature lifetime relative to the current slot. Accepts `s`, `m`, or `h`. Default: `1h`. | | `--deadline-slot` | Alternative to `--valid-for`: absolute slot the authorization expires at. Mutually exclusive with `--valid-for`. | | `--json` | Emit JSON (`{ hex, deadline_slot }`) instead of the human summary. | @@ -87,45 +113,57 @@ The command prints the hex-encoded auth message, the resolved deadline slot, and On the machine that holds the validator identity keypair: ```bash -solana sign-offchain-message --keypair +solana sign-offchain-message <123457fc138f556a2578bdb079dc923342cc4e4a376683dc4c6cb923051e0be3> \ +--keypair ``` This prints a base58 signature. +Example Output + +```bash +SignatureTBUwGq511mPLMCEE4f5fNsmX1PQrozXBBJeCdSrcbhqSX1MwFp8NsNZbhCNMZ1kPWakjsLL9e3GUxxp +``` + ### 2b.iii. Submit `configure` Back on the machine with your fee-payer wallet: ```bash doublezero-solana shreds publisher-rewards configure \ - --node-id \ + --node-id \ --rewards-token-owner \ --rewards-token-mint 2z \ - --signature \ + --signature \ --deadline-slot ``` `--signature` and `--deadline-slot` must be passed together. The values must match those produced in steps 2b.i and 2b.ii. -The PDA is auto-initialized in the same transaction if it doesn't yet exist. +The ATA is auto-initialized in the same transaction if it doesn't yet exist. ---- -## 3. Verify the Configuration +Example Output ```bash -doublezero-solana shreds publisher-rewards show --node-id +Shred subscription - Configure Validator Publisher Rewards +Node ID: ValidatorIdentity111111111111111111111111111 +Rewards owner: ValidatorIdentity111111111111111111111111111 +Rewards mint: J6pQQ3FAcJQeWPPGppWRb4nM8jU3wLyYbRrLh7feMfvd +Rewards ATA: 11111111111Pt3PatTj59dG5BhYuqPb9QJDUr1111111 +Auth path: offchain +Configured validator publisher rewards: 41111111ntmoBTnvcKcP1g2a1111111HPoN3z5uf11111112jjzBJsr1B2JrTRff4dSGe1pdM1111111TMADi3Nz ``` -The command prints the `Node ID`, `Rewards owner`, `Rewards mint`, the resolved ATA address, and the ATA status. The **Resolved ATA** is the deterministic address derived from the rewards owner + rewards mint — it's where rewards will be deposited each epoch. +--- -If the ATA does not exist, `show` exits with a hard error and suggests the command to create it: +## 3. Verify the Configuration ```bash -spl-token create-account --owner +doublezero-solana shreds publisher-rewards show --node-id ``` -Rewards are not distributed until the ATA exists. Run `show` again after creating it to confirm. +The command prints the `Node ID`, `Rewards owner`, `Rewards mint`, the resolved ATA address, and the ATA status. The **Resolved ATA** is the deterministic address derived from the rewards owner + rewards mint — it is where rewards will be deposited each epoch. --- @@ -135,14 +173,6 @@ Rewards are not distributed until the ATA exists. Run `show` again after creatin The fee-payer keypair you passed isn't the validator identity. Either pass the validator identity keypair as `-k`, or switch to the [offchain path](#2b-offchain-path). -### Unknown or disabled reward mint - -`configure` requires the `ShredRewardToken` PDA for the chosen mint to exist and be enabled. Use `2z` (default) unless you have explicit confirmation a different mint is supported in your environment. - ### Signature expired Each offchain signature has a deadline slot. If too much time passes between `prepare-offchain-message` and `configure`, re-run `prepare-offchain-message`, re-sign, and re-submit. Default validity is 1 hour — extend with `--valid-for 4h` or similar if you need more time for an offline signing flow. - -### Rewards aren't arriving - -Run `doublezero-solana shreds publisher-rewards show --node-id ` and confirm the ATA exists. If `show` reports a missing ATA, create it with `spl-token create-account` as shown above. diff --git a/mkdocs.yml b/mkdocs.yml index 39a1b61..174add5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,7 +58,7 @@ nav: - Validator Testnet Connection: DZ Testnet Connection.md - Permissioned Connection: Permissioned Connection.md - Validator Multicast Connection: Validator Multicast Connection.md - - Configure Validator Publisher Rewards: Configure Validator Publisher Rewards.md + - Validator Rewards: Validator Rewards.md - Other Multicast Connection: Other Multicast Connection.md - Edge Subscriber Connection: Edge Subscriber Connection.md - Troubleshooting: troubleshooting.md