Skip to content

docs: add beginner validator guide, correct stale mainnet status #21

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

Open
atomdbc wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add beginner validator guide, correct stale mainnet status #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
75098a6
docs: add beginner validator guide, correct stale mainnet status
atomdbc Jul 16, 2026
5be14dc
docs: restore keys-show lookup, fix the actual keyring bug
atomdbc Jul 16, 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
2 changes: 1 addition & 1 deletion docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ predictable fees, and IBC rails to the wider Cosmos ecosystem.
- **Token**: **SAF**
- **Supply**: **1,000,000,000 SAF** (fixed)
- **Denom**: `usaf` (`1 SAF = 1_000_000 usaf`)
- **Mainnet target**: **Q3 2026**
- **Mainnet**: **live** — `safrochain-1`, genesis `2026-06-25T10:00:00Z`

## External links

Expand Down
7 changes: 5 additions & 2 deletions docs/resources/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ Safrochain is an Africa-first Layer 1 blockchain built on the Cosmos SDK. It pri

SAF is the native token used for fees, staking, and governance. Total fixed supply is **1 billion SAF**.

## When is mainnet launching?
## Is mainnet live?

Mainnet is planned for **Q3 2026**.
Yes. `safrochain-1` has been producing blocks since its genesis time of
**2026-06-25T10:00:00Z**. See [Mainnet endpoints](../networks/mainnet-endpoints)
for RPC, REST, and seed details, or [Join mainnet](../run-a-node/join-mainnet)
to run a node.

4 changes: 2 additions & 2 deletions docs/run-a-node/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ This section covers running a Safrochain full node with **`safrochaind`**.

- Run a **local single-node sandbox** for development.
- Join the **public testnet** (live) for end-to-end testing.
- Join the **mainnet** (Q3 2026) as a full or pruned node.
- Join the **mainnet** (live) as a full or pruned node.
- Become a **validator** and help secure the network.

## Decision matrix
Expand All @@ -39,7 +39,7 @@ This section covers running a Safrochain full node with **`safrochaind`**.
2. [Hardware requirements](./hardware): sizing per role (validator, sentry, RPC, archive).
3. [Local devnet](./local-devnet): single-node `safro-devnet-1` on localhost.
4. [Join testnet](./join-testnet): live `safro-testnet-1`.
5. [Join mainnet](./join-mainnet): `safrochain-1` (opens Q3 2026).
5. [Join mainnet](./join-mainnet): live `safrochain-1`.
6. [Snapshots](./snapshots): fast catch-up via tarballs.
7. [Statesync](./statesync): cryptographic light-client sync.
8. [Upgrades](./upgrades): cosmovisor flow for chain upgrades.
Expand Down
42 changes: 38 additions & 4 deletions docs/validators/become-a-validator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ sign blocks, and earn block rewards plus commission from delegations. This
guide walks you through the entire lifecycle: prerequisites → key generation
→ `create-validator` → post-launch checks → going live.

:::tip First time?
This page assumes you're comfortable with Cosmos tooling and moves fast.
[Launch your first validator](./validator-walkthrough) covers the same ground
step by step, explaining what each command does and the mistakes that commonly
trip people up.
:::

## 1 · Prerequisites

| Requirement | Value |
Expand Down Expand Up @@ -102,9 +109,19 @@ keyring to a public machine or repository.
Verify the balance:

```bash
safrochaind query bank balances "$(safrochaind keys show validator -a)"
safrochaind query bank balances "$(safrochaind keys show validator -a --keyring-backend file)"
```

:::note Keep `--keyring-backend` consistent
You created the key with `--keyring-backend file` in step 2, so the nested
lookup needs the same flag. Without it the CLI falls back to the default `os`
backend, where the key doesn't exist, and the command fails with a confusing
`key not found` even though the key is fine.

If you're checking a balance from a machine that has no keyring at all, pass
the `addr_safro1…` address literally instead.
:::

Comment on lines +115 to +124

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Apply the --keyring-backend file fix to downstream commands.

This note accurately explains why the flag is necessary, but the downstream commands in Step 7 (## 7 · Verify the validator was created) were not updated to include it. As a result, the VALADDR assignments at lines 227 and 236 will fall back to the os backend and fail with a key not found error, breaking the validator query script.

Please update the downstream lines to include the flag so the script executes successfully.

🐛 Proposed fix for the downstream script 
--- docs/validators/become-a-validator.md
+++ docs/validators/become-a-validator.md
@@ -226,3 +226,3 @@
 ```bash
-VALADDR=$(safrochaind keys show validator --bech val -a)
+VALADDR=$(safrochaind keys show validator --bech val -a --keyring-backend file)
 safrochaind query staking validator "$VALADDR" \
@@ -235,3 +235,3 @@
 ```bash
-VALADDR=$(safrochaind keys show validator --bech val -a)
+VALADDR=$(safrochaind keys show validator --bech val -a --keyring-backend file)
 safrochaind query staking validator "$VALADDR" \
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/validators/become-a-validator.md` around lines 115 - 124, Update both
VALADDR assignments in Step 7’s validator verification commands to pass
--keyring-backend file to safrochaind keys show, matching the backend used when
the key was created; leave the surrounding validator query commands unchanged.

## 4 · Get your consensus pubkey

Each validator process generates `priv_validator_key.json` on first init.
Expand Down Expand Up @@ -161,21 +178,21 @@ EOF
safrochaind tx staking create-validator validator.json \
--from validator \
--chain-id safro-testnet-1 \
--gas auto --gas-adjustment 1.3 \
--gas 250000 \
--gas-prices 0.05usaf \
--keyring-backend file \
--node https://rpc.testnet.safrochain.com:443 \
--yes
```

</TabItem>
<TabItem value="mainnet" label="Mainnet (Q3 2026)">
<TabItem value="mainnet" label="Mainnet (live)">

```bash
safrochaind tx staking create-validator validator.json \
--from validator \
--chain-id safrochain-1 \
--gas auto --gas-adjustment 1.3 \
--gas 250000 \
--gas-prices 0.05usaf \
--keyring-backend file \
--node https://rpc.safrochain.network:443 \
Expand All @@ -185,6 +202,22 @@ safrochaind tx staking create-validator validator.json \
</TabItem>
</Tabs>

:::warning Prefer a flat `--gas` over `--gas auto` here
`--gas auto --gas-adjustment 1.3` can under-estimate `create-validator` and
fail with `out of gas` — **and the fee is still charged**, because it is
deducted before execution. Use a flat, generous `--gas`, or raise
`--gas-adjustment` to `1.8`+ if you prefer simulation.

Then confirm the result rather than trusting the broadcast response, which
only reports acceptance into the mempool:

```bash
safrochaind query tx <TXHASH> --node https://rpc.safrochain.network:443
# code: 0 → success
# code: 11 → out of gas; raise --gas and retry
```
:::

## 7 · Verify the validator was created

<Tabs groupId="network" defaultValue="testnet">
Expand Down Expand Up @@ -251,6 +284,7 @@ production-ready Docker images and detailed migration guides.
| Action | Command |
| --- | --- |
| Edit description / commission | `safrochaind tx staking edit-validator --commission-rate 0.06 …` |
| Rename the validator | `safrochaind tx staking edit-validator --new-moniker "new-name" …` (the flag is `--new-moniker`; there is no `--moniker`) |
| Self-delegate more | `safrochaind tx staking delegate $VALADDR 5000000usaf …` |
| Unjail after downtime | `safrochaind tx slashing unjail --from validator …` |
| Unbond (begin exit) | `safrochaind tx staking unbond $VALADDR <amount>usaf …` |
Expand Down
5 changes: 3 additions & 2 deletions docs/validators/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,9 @@ day-2 operations to graceful exit.

| If you want to… | Read |
| --- | --- |
| Launch a validator for the first time | [Launch your first validator](./validator-walkthrough) |
| Understand operator vs consensus keys | [Key management](./key-management) |
| Stand up your first validator end-to-end | [Become a validator](./become-a-validator) |
| Stand up your first validator end-to-end (concise) | [Become a validator](./become-a-validator) |
| Move signing off the validator host | [Remote signing](./remote-signing) |
| Lay out sentries and validator topology | [Sentry architecture](./sentry-architecture) |
| Set up Prometheus + Grafana | [Monitoring](./monitoring) |
Expand Down Expand Up @@ -104,7 +105,7 @@ same six pillars.

| Network | Chain ID | Status | Validator slots |
| --- | --- | --- | --- |
| Mainnet | `safrochain-1` | upcoming (Q3 2026) | confirmed in genesis |
| Mainnet | `safrochain-1` | **live** since `2026-06-25T10:00:00Z` | open via `MsgCreateValidator` |
| Testnet | `safro-testnet-1` | live | open, faucet-funded |

Always validate on testnet first. Every page in this section assumes you
Expand Down
Loading
Loading