docs(node): document filtering and released operator features (#876)

* docs(node): document filtering and released operator features

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

* docs(node): address operator guide review feedback

* Revert "docs(node): address operator guide review feedback"

This reverts commit 40d7c99.

* docs(node): address validator guide review comments

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

* docs(node): clarify snapshot updates and share recovery risks

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

---------

Co-authored-by: Max <227239059+max-digi@users.noreply.github.com>
Co-authored-by: Max <maxime@ithaca.xyz>
Co-authored-by: Richard Janis Goldschmidt <701177+SuperFluffy@users.noreply.github.com>

Author: 3 people

src/pages/docs/cli/download.mdx

@@ -6,7 +6,7 @@ description: Download chain snapshots for faster initial sync of a Tempo node.
 
 # `tempo download`: CLI command reference
 
-Download chain snapshots for faster initial sync. Fetches MDBX state and static files, and generates a `reth.toml` prune config for the target data directory.
+Download chain snapshots for faster initial sync. Fetches execution state, static files, and consensus data, and generates a `reth.toml` prune config for the target data directory. Current releases resolve the default data directory and snapshot manifest from the selected chain.
 
 Running `tempo download` without a snapshot profile opens an interactive component selector. Passing a profile flag such as `--minimal` or `--archive` skips the selector. Validators should use `--minimal`. RPC providers, indexers, and other workloads that need complete historical data should use `--archive`.
 
@@ -22,9 +22,11 @@ tempo download [flags]
 | --- | --- |
 | `--chain <network>` | Target network (`mainnet`, `moderato`) |
 | `--datadir <path>` | Data directory for downloaded state |
+| `--consensus.datadir <path>` | Destination for consensus snapshot data. Defaults to `<datadir>/consensus`; match this to the node's `--consensus.datadir` when using a separate volume. |
 | `-u, --url <url>` | Download a single legacy snapshot archive URL |
 | `--manifest-url <url>` | Download a specific modular snapshot manifest URL |
 | `--list` | List available snapshots |
+| `--print-plan-json` | Print the selected execution and consensus archive plan without downloading archives or modifying the data directory. Select a profile such as `--minimal`. |
 | `--resumable[=<bool>]` | Download to disk before extraction so interrupted downloads can resume. Enabled by default. |
 | `--minimal` | Download the minimal component set without opening the interactive selector. Validators should use this profile. |
 | `--full` | Download the full node component set. |
@@ -73,6 +75,14 @@ If you are unsure which pruning configuration your validator is running, reach o
 
 ## `tempo download` examples
 
+Preview a validator snapshot download before making changes:
+
+```bash
+tempo download --chain mainnet --minimal --print-plan-json
+```
+
+The JSON plan includes archive URLs, sizes, and checksums when supplied by the manifest. It includes the consensus archive from v1.12.0 onward. Planning still fetches snapshot metadata.
+
 Open the interactive selector for mainnet:
 
 ```bash

src/pages/docs/cli/node.mdx

@@ -38,13 +38,20 @@ Flags grouped by function:
 | --- | --- |
 | `--consensus.signing-key <path>` | Path to validator signing key |
 | `--consensus.secret <path>` | Path to the secret used to decrypt an encrypted validator signing key. Prefer a named pipe (FIFO) or shell process substitution. |
-| `--consensus.fee-recipient <addr>` | Deprecated validator fee-recipient flag. Migrate to on-chain fee-recipient management via Validator Config V2. |
 | `--consensus.datadir <path>` | Separate volume for consensus data |
 
 :::warning
-`--consensus.fee-recipient` is deprecated as of `v1.5.2` and will be removed in an upcoming release. See [updating the fee recipient](/docs/guide/node/validator-lifecycle#update-the-fee-recipient).
+`--consensus.fee-recipient` was removed in `v1.7.0`. Remove it from startup commands and [update the fee recipient on-chain](/docs/guide/node/validator-lifecycle#update-the-fee-recipient).
 :::
 
+### Transaction pool
+
+| Flag | Description |
+| --- | --- |
+| `--txpool.filter <ADDRESSES_OR_FILE>` | Optional address filter, available since v1.14.0. Accepts comma-separated addresses or a plain-text file with comma/newline-separated addresses. Rejects transactions matching the sender or any direct call target at pool admission. |
+
+See [Transaction address filtering](/docs/guide/node/validator-setup#transaction-address-filtering) for examples, file reload behavior, and the limits of this local policy.
+
 ### Observability
 
 | Flag | Description |
@@ -70,8 +77,7 @@ Start a validator:
 tempo node --datadir /data/tempo \
   --chain mainnet \
   --consensus.signing-key /etc/tempo/key \
-  --consensus.secret /run/tempo/consensus-secret \
-  --consensus.fee-recipient 0x...
+  --consensus.secret /run/tempo/consensus-secret
 ```
 
 ## Learn more about Tempo node operations

src/pages/docs/guide/node/installation.mdx

@@ -76,6 +76,22 @@ tempo download --chain moderato --archive
 
 Use [snapshots.tempo.xyz](https://snapshots.tempo.xyz/) to compare snapshot profiles or copy generated `tempo download` commands.
 
+### Preview a snapshot download
+
+Inspect the execution and consensus archives before downloading them or changing your data directory:
+
+```bash
+tempo download --chain mainnet --minimal --print-plan-json
+```
+
+This fetches snapshot metadata and prints a JSON plan. See the [`tempo download` reference](/docs/cli/download) for flags, including `--consensus.datadir` when consensus data lives on a separate volume.
+
+Current validators require consensus finalization certificates at startup. Official Tempo snapshots include the required consensus archive, and `tempo download` restores it by default.
+
+:::info[Keep execution and consensus data in sync]
+Restore execution and consensus data from the same snapshot and update them in lockstep, even when stored on separate volumes. Independent updates can work but are brittle. Tempo is working on making this flow possible.
+:::
+
 :::note[Replacing existing snapshot data]
 When replacing snapshot data in an existing data directory, add `--force` after selecting the right profile. `--force` removes the execution databases, static files, `reth.toml`, and the entire consensus directory before installing the new snapshot. It preserves `discovery-secret` and `known-peers.json`.
 :::
@@ -86,20 +102,25 @@ All release artifacts are cryptographically signed. We recommend verifying signa
 
 ### Binary Signatures (GPG)
 
-Release binaries are signed with GPG. The `tempoup` installer verifies signatures automatically when `gpg` is available.
+Release binaries are signed with GPG. The `tempoup` installer checks the archive checksum, then verifies GitHub release provenance when authenticated `gh` is available, or falls back to GPG signature verification. Install and authenticate `gh`, or install `gpg`, before using the installer.
 
-To verify manually:
+For GPG verification, [`tempoup`](https://github.com/tempoxyz/tempo/blob/main/tempoup/tempoup) embeds the expected fingerprint, not the public key. It uses the key in your local GPG keyring if present; otherwise, it fetches it from `keyserver.ubuntu.com` over HTTPS. The public key is also included below.
+
+To verify manually, import the key and compare its full fingerprint with the one below before checking the signature. To independently confirm that the fingerprint belongs to Tempo, confirm it with the Tempo team through a trusted channel.
 
 ```bash
 # Import the Tempo release signing key
 gpg --keyserver keyserver.ubuntu.com --recv-keys EE3C5D41EA963E896F310EC3CBBFA54B20D33446
 
+# Inspect the imported key fingerprint
+gpg --fingerprint EE3C5D41EA963E896F310EC3CBBFA54B20D33446
+
 # Verify a downloaded binary
-gpg --verify tempo-v1.1.0-x86_64-unknown-linux-gnu.tar.gz.asc \
-    tempo-v1.1.0-x86_64-unknown-linux-gnu.tar.gz
+gpg --verify tempo-v1.13.2-x86_64-unknown-linux-gnu.tar.gz.asc \
+    tempo-v1.13.2-x86_64-unknown-linux-gnu.tar.gz
 ```
 
-A successful verification will show `Good signature from "Tempo Release Signing Key"`.
+A successful verification reports `Good signature`. Confirm that the signing key matches the fingerprint below.
 
 **Fingerprint:** `EE3C 5D41 EA96 3E89 6F31 0EC3 CBBF A54B 20D3 3446`
 

src/pages/docs/guide/node/security.mdx

@@ -48,7 +48,7 @@ An unsynchronized clock can cause your node to reject valid blocks or produce bl
 
 ## Data integrity
 
-- **Never delete the data directory and re-sync with the same signing key** — this risks double-signing and will require [rotating to a new identity](/docs/guide/node/validator-lifecycle#resetting-your-validators-data). Deleting only the `consensus` subdirectory is safe; the signing share will be [automatically recovered](/docs/guide/node/validator-keys#signing-share-recovery).
+- **Never delete the data directory and re-sync with the same signing key** — this risks double-signing and will require [rotating to a new identity](/docs/guide/node/validator-lifecycle#resetting-your-validators-data). Deleting the `consensus` subdirectory also removes certificates required at startup; coordinate snapshot recovery with the Tempo team. [Signing-share recovery](/docs/guide/node/validator-keys#signing-share-recovery) does not replace those certificates.
 - **Back up your signing key** — if the key file is lost and no backup exists, you will need to rotate to a new key and coordinate with the Tempo team.
 
 ## Staying up to date

src/pages/docs/guide/node/validator-keys.mdx

@@ -133,6 +133,10 @@ The validator identity signature and the transaction signer are different:
 
 ## Signing share recovery
 
+:::warning[Deleting consensus data can halt the network]
+A node eventually recovers its signing share, but do not delete the consensus directory lightly. If too many validators delete their shares in the same epoch, the network halts.
+:::
+
 If the signing share is lost — for example by deleting `<datadir>/consensus` — the node will recover a new share in the following epochs from the network when it restarts.
 
 ## ValidatorConfig V2 precompile

src/pages/docs/guide/node/validator-lifecycle.mdx

@@ -35,7 +35,11 @@ Self-service data resets are coming soon. Once available, you will be able to ro
 
 ## Managing your validator
 
-The lifecycle commands below submit transactions to the validator contract. The transaction signer must control the validator operator address, but it does not need to be a plaintext EOA key. Use the CLI signer backend that matches your custody setup; see [validator operator address custody](/docs/guide/node/validator-keys#validator-operator-address-custody).
+ValidatorConfig operations below submit transactions from the validator operator address, which does not need to be a plaintext EOA key. Use the CLI signer backend that matches your custody setup; see [validator operator address custody](/docs/guide/node/validator-keys#validator-operator-address-custody). [Fee-token selection](#choose-the-validator-fee-token) uses the fee-recipient address instead.
+
+:::info[Preview or confirm transactions]
+Use `--dry-run` to print the target and calldata without signing or sending; it does not simulate execution. Use `--yes` to skip the confirmation prompt when sending.
+:::
 
 ### Rotate validator identity
 
@@ -125,6 +129,33 @@ tempo consensus set-validator-fee-recipient <address/pubkey/index> \
 ```
 ::::
 
+### Choose the validator fee token
+
+From [v1.12.0](https://github.com/tempoxyz/tempo/releases/tag/v1.12.0), `tempo consensus set-validator-token` lets you select the USD-denominated TIP-20 token used for validator fees. This calls the FeeManager and sets the preference for the **transaction sender**. Submit from your validator's configured fee-recipient address, which can differ from the validator operator address used by the other lifecycle commands.
+
+List verified tokens on your network without a signer:
+
+::::code-group
+```bash [Mainnet]
+tempo consensus set-validator-token --list --rpc-url https://rpc.tempo.xyz
+```
+```bash [Testnet]
+tempo consensus set-validator-token --list --rpc-url https://rpc.testnet.tempo.xyz
+```
+::::
+
+Preview a selection using a token address, symbol, or name from the list:
+
+```bash
+tempo consensus set-validator-token <TOKEN> \
+  --rpc-url https://rpc.tempo.xyz \
+  --dry-run
+```
+
+For a raw token address, `--no-fetch-verified-tokens` skips the metadata lookup; on-chain token validation still applies.
+
+The token must be a deployed USD-denominated TIP-20. The FeeManager rejects a preference change in a block whose fee recipient is the caller. This command changes the preferred token, not the fee-recipient address; see [Update the fee recipient](#update-the-fee-recipient) to change that address.
+
 ### Transfer validator ownership
 
 Rebind your validator entry to a new control address:

src/pages/docs/guide/node/validator-setup.mdx

@@ -140,6 +140,35 @@ Once your node is up, it may not start syncing immediately. This is because your
 | `--telemetry-metrics-interval <DURATION>` | Interval for pushing metrics (default: `10s`). |
 | `--consensus.datadir <PATH>` | Store consensus data on a separate volume (e.g., AWS EBS) while keeping execution state on high-performance local disks. Migrate by copying `<datadir>/consensus` to the new location. |
 | `--consensus.secret <PATH>` | Read the encrypted signing-key secret from a FIFO, process-substitution path, or regular file. Prefer FIFO or process substitution so the secret is streamed just in time and kept out of the process environment. |
+| `--txpool.filter <ADDRESSES_OR_FILE>` | Reject transactions whose sender or direct call target matches an operator-supplied address list. See [Transaction address filtering](#transaction-address-filtering). |
+
+### Transaction address filtering
+
+From [v1.14.0](https://github.com/tempoxyz/tempo/releases/tag/v1.14.0), you can configure `--txpool.filter` to exclude addresses from your node's transaction pool without maintaining a custom node build. Filtering is optional and disabled by default. You supply and maintain the address list.
+
+Append one of these forms to your existing `tempo node` command:
+
+::::code-group
+```bash [Comma-separated addresses]
+--txpool.filter "0x0000000000000000000000000000000000000001,0x0000000000000000000000000000000000000002"
+```
+```bash [Address file]
+--txpool.filter /etc/tempo/filtered-addresses.txt
+```
+::::
+
+The file is plain text, with addresses separated by commas, newlines, or both:
+
+```text
+0x0000000000000000000000000000000000000001
+0x0000000000000000000000000000000000000002
+```
+
+Whitespace, blank entries, and duplicate addresses are ignored. An empty list, an invalid address, or an unreadable file prevents startup. The file is read at startup; restart the node after changing its contents. Remove the flag to disable filtering.
+
+The node rejects the entire transaction at pool admission when its recovered sender or any direct call target appears in the list. For batched Tempo transactions, every direct call target is checked. A rejection reports `Transaction address check failed for {address}`.
+
+This is a local pool policy. It does not change consensus validation or reject otherwise-valid blocks proposed by other validators. It does not inspect internal contract calls or addresses encoded in calldata, such as a token transfer's recipient. Contract-creation calls have no direct target to check; their sender is still checked.
 
 ### Telemetry endpoint
 
@@ -157,17 +186,10 @@ The URL must include credentials: `--telemetry-url https://user:pass@metrics.exa
 | Execution metrics | Block processing times, transaction pool size, peer count, sync status, database stats |
 | Consensus metrics | Epoch and view progress, DKG ceremony status, proposal and finalization counts |
 | Operational logs | Consensus state transitions, block proposals, sync progress, error events |
+| Hardware metadata | CPU vendor, model and frequency, physical and logical core counts, total memory, and filesystem types for node storage, reported by `tempo_hardware_info` since v1.11.0 |
 
 All consensus metrics are namespaced under a `consensus` prefix.
 
 #### What is **not** collected
 
-The telemetry endpoint does **not** collect any ambient information about the host machine. Specifically:
-
-- No hostname, IP address, or machine identifiers
-- No operating system, CPU, memory, or disk information
-- No information about other processes or services running on the machine
-- No file paths or directory structures beyond the node's own data directory references in logs
-- No network topology or firewall configuration
-
-The data is strictly limited to the node's own operational metrics and logs.
+The `tempo_hardware_info` metric omits hostnames, IP addresses, disk names, mount sources, and filesystem paths. Node operational logs are exported separately and can include the node's configured paths and peer information; the hardware metric's exclusions do not apply to all logs.

src/pages/docs/guide/node/validator-troubleshooting.mdx

@@ -77,7 +77,7 @@ See [Time Synchronization](/docs/guide/node/system-requirements#time-synchroniza
 
 ## I accidentally deleted my consensus data directory
 
-If you deleted `<datadir>/consensus`, your signing share is lost but will be [automatically recovered](/docs/guide/node/validator-keys#signing-share-recovery) from the network when the node restarts. Your node will re-join the committee after the next successful DKG ceremony.
+Current validators require consensus finalization certificates to start. Contact the Tempo team to coordinate restoring a consistent snapshot; do not assume restarting with an empty consensus directory is sufficient. Once startup data is restored, [signing-share recovery](/docs/guide/node/validator-keys#signing-share-recovery) can reconstruct a missing share, or the node can obtain one in a future successful DKG ceremony.
 
 :::danger
 Do **not** delete the entire data directory and attempt to re-sync with the same signing key. This risks double-signing and will require [rotating to a new identity](/docs/guide/node/validator-lifecycle#resetting-your-validators-data).