Docs: tokenomics are not yet determined by SaulBuilds · Pull Request #42 · CitrateNetwork/citrate-docs

SaulBuilds · 2026-10-27T23:01:36Z

Summary

Owner decision (2026-10-27): SALT and rewards content stays in the documentation, but the docs must say clearly that tokenomics are not yet determined. This PR does that on docs.citrate.ai.

One shared notice. components/tokenomics-notice.tsx renders, at the top of a page, the identical text:

Tokenomics are not yet determined. Figures on this page describe the current testnet and may change before mainnet. Nothing here is an offer or a promise of value. Read the tokenomics status.

It reuses the reader's existing amber callout pattern (the same style as the confidential banner in doc-view.tsx). A page opts in with frontmatter tokenomics_notice: true; scripts/build-content.mjs carries the flag to the reader, and DocView renders the notice above the body (gated bodies included).
One status page. New content/start/tokenomics.md at /start/tokenomics ("Tokenomics status"): supply, distribution, rewards, emissions, and fees are not yet determined; testnet SALT has no cash value; parameters will be finalized and published before mainnet. It links to the pages that hold the current testnet values instead of restating them. The notice links here.
Final-sounding sentences reworded to "current testnet code" / "proposed". No figures were added, removed, or changed. Full list below.
Tripwire. test/tokenomics-notice.test.ts runs a term classifier (scripts/lib/tokenomics-terms.mjs) over every authored page. Any page whose prose mentions SALT, rewards, emissions, stake, bonds, economic grants, supply, fees, economics, APY/APR, earning SALT, validator income, slashing, treasury, halving, burn, or inflation must carry the flag, so a new page cannot skip the notice. It also checks that the generated content module carries the flag, that DocView renders the notice before the body, that the notice text and link are exact, that the status page says the required things, and that no page uses a final-sounding claim again (APY, "you will earn", "guaranteed reward", "supply is fixed", "never more", "project earnings", "what does not move").

Matching runs on prose only: frontmatter, code, and link URLs are removed first, so core/economics/src/... paths and /chain/economics links do not count, and SALT is case-sensitive so a CREATE2 salt does not match.

Pages that now render the notice (49 + the new status page)

content/aa/paymaster.md
content/apps/buyer.md
content/apps/chatbot.md
content/apps/explorer.md
content/apps/native.md
content/apps/wallet-extension.md
content/chain/cli.md
content/chain/consensus.md
content/chain/economics.md
content/chain/genesis.md
content/chain/rpc.md
content/chain/sequencer.md
content/chain/storage.md
content/chain/tutorials/call-citrate-rpc.md
content/chain/tutorials/deploy-a-contract-with-the-cli.md
content/chain/tutorials/read-the-dag.md
content/compute/gateway.md
content/compute/node-agent.md
content/compute/pool.md
content/contracts/compute.md
content/contracts/economics.md
content/contracts/governance.md
content/contracts/models.md
content/contracts/reference.md
content/contracts/security.md
content/contracts/tutorials/interact-read-only.md
content/contracts/tutorials/read-a-contract.md
content/contracts/x402.md
content/core/for-agents.md
content/core/getting-started.md
content/core/overview.md
content/core/run-a-node.md
content/core/safety.md
content/core/tour.md
content/operators/rewards.md
content/operators/run-a-node.md
content/operators/sell-compute.md
content/operators/tutorials/become-a-seller.md
content/research/gradient-papers.md
content/research/mentorship.md
content/sdks/bundler.md
content/sdks/inference-gateway.md
content/sdks/marketplace.md
content/sdks/overview.md
content/sdks/python.md
content/sdks/tutorials/post-a-marketplace-job.md
content/start/primer.md
content/start/tutorials/your-first-10-minutes.md
content/start/what-is-citrate.md

Exempt (4), each with a reason in the test; the test fails if an exemption goes stale:

apps/learning-center.md: "reward" is a verb about routing learning.
methodology/sops.md: a link label to /operators/rewards in an SOP index (the linked page has the notice).
chain/precompiles.md: "gas economics" names a gated topic; no figures.
enterprise/procurement.md: enterprise license fees and deal terms, not network economics.

Generated pages (content/*/_generated/: addresses, precompiles, API reference, changelog) are out of scope, the same as for content-lint; the address page only names the stake vault contract.

Sentences changed (30)

chain/economics.md
- Before: it pays, and how supply behaves over the long view.
- After: it pays, and how supply behaves in the current testnet code. These are proposed values: the tokenomics are not yet determined.
chain/economics.md
- Before: the amount is denominated in SALT. The supply is fixed at genesis: one trillion SALT, never more. The smallest unit
- After: the amount is denominated in SALT. On the current testnet, the code caps supply at one trillion SALT; the mainnet supply is not yet determined. The smallest unit
chain/economics.md
- Before: reward schedule is the part worth understanding early, because it is what gives a node a reason to keep the network running, and it shrinks on a fixed cadence so that early seasons are more generous than late ones.
- After: reward schedule is the part worth understanding early, because it is what gives a node a reason to keep the network running. In the current code it shrinks on a fixed cadence, so early seasons pay more than late ones.
chain/economics.md
- Before: network health, and long-term staking. A node that does more of the work the network values earns a larger share of the pools. The base reward halves every 2,100,000 blocks, about 24 days at the one-second testnet cadence, so issuance tapers toward zero over the network's life rather than running flat forever.
- After: network health, and long-term staking. A node that does more of the work the network values receives a larger share of the pools. On the current testnet, the base reward halves every 2,100,000 blocks, about 24 days at the one-second testnet cadence, so issuance tapers toward zero rather than running flat. The mainnet schedule is not yet determined.
chain/economics.md
- Before: You rarely set these values yourself; you read them, so you can price work and project earnings.
- After: You rarely set these values yourself; you read them, so you can price work on the current testnet.
chain/economics.md
- Before: 3. Reason about rewards. If you operate a node, the reward you can expect for a sealed block is the base reward plus your earned share of the four bonus pools, adjusted for where the chain sits in its halving schedule.
- After: 3. Reason about rewards. If you operate a node on the current testnet, the code computes the reward for a sealed block as the base reward plus your share of the four bonus pools, adjusted for where the chain sits in its halving schedule. These are testnet values, not a promise of future rewards.
chain/economics.md
- Before: configurable base reward rather than asserting a fixed number, since governance can move it. What does not move is the halving cadence and the fixed supply.
- After: configurable base reward rather than asserting a fixed number, since governance can move it. The halving cadence and the supply cap are constants in the current testnet code; they are proposed values and may change before mainnet.
chain/economics.md
- Before: A fixed supply with a halving base reward keeps the accounting honest:
- After: The proposed design, a capped supply with a halving base reward, is meant to keep the accounting honest:
chain/economics.md
- Before: Splitting the reward into four pools, rather than paying a flat amount per block, lets the network pay for
- After: Splitting the reward into four pools, rather than paying a flat amount per block, is meant to let the network pay for
chain/economics.md

Before: Public. SALT settles the work the network performs; it is not an investment instrument, and Almanac does not describe it as one. The token fundamentals, the reward structure, and the halving cadence are exactly what a builder or operator needs to reason about the economy.
After: Public. SALT settles the work the network performs; it is not an investment instrument, and Almanac does not describe it as one. Testnet SALT has no cash value. The token fundamentals, the reward structure, and the halving cadence are documented as they stand in the current testnet code; the final parameters will be published before mainnet.

operators/rewards.md

Before: This is how an operator earns on the Citrate Network, how reputation tracks the work performed, and how misbehavior is penalized.
After: This is how the current testnet code pays an operator on the Citrate Network, how reputation tracks the work performed, and how misbehavior is penalized. The figures are proposed values; the tokenomics are not yet determined.

operators/rewards.md

Before: The economics live in one crate, core/economics/. A node earns SALT for the work it performs: sealing blocks, hosting models, and completing compute jobs.
After: The economics live in one crate, core/economics/. In the current testnet code, a node is credited SALT for the work it performs: sealing blocks, hosting models, and completing compute jobs.

operators/rewards.md

Before: The pools recognize four kinds of contribution, so a node that does more of the work the network values earns a larger share. The base reward halves every 2,100,000 blocks, so early seasons are more generous than late ones. We describe the base reward as a configurable default rather than a fixed number, because governance can move it; what does not move is the halving cadence and the fixed one trillion supply.
After: The pools recognize four kinds of contribution, so a node that does more of the work the network values receives a larger share. In the current code the base reward halves every 2,100,000 blocks, so early seasons pay more than late ones. We describe the base reward as a configurable default rather than a fixed number, because governance can move it. The halving cadence and the one trillion supply cap are constants in the current testnet code; they are proposed values and may change before mainnet.

operators/rewards.md

Before: You read these values to project earnings and to understand why a score moved; you rarely set them.
After: You read these values to understand how the testnet credits work and why a score moved; you rarely set them.

operators/rewards.md

Before: 2. Project a block reward. Expect the base reward plus your earned share of the four pools, adjusted for where the chain sits in its halving schedule.
After: 2. Understand the block reward. On the current testnet, the code computes it as the base reward plus your share of the four pools, adjusted for where the chain sits in its halving schedule. This is not a promise of future rewards.

operators/rewards.md

Before: Commercial tier, operator implementation depth. SALT settles the work the network performs; reputation and slashing reward contribution and penalize misbehavior, and none of them is a speculative instrument.
After: Commercial tier, operator implementation depth. SALT settles the work the network performs; reputation and slashing reward contribution and penalize misbehavior, and none of them is a speculative instrument. Testnet SALT has no cash value.

contracts/economics.md

Before: nothing on this page treats SALT as an instrument to speculate on. For the base facts about SALT, supply, and gas, read network economics.
After: nothing on this page treats SALT as an instrument to speculate on. The rates and caps below are the values in the current testnet contracts; the tokenomics are not yet determined. For the base facts about SALT, supply, and gas, read network economics.

contracts/economics.md

Before: reported to the pool raise the value each share is worth, so the staked SALT stays usable as a share token while it earns.
After: reported to the pool raise the value each share is worth, so the staked SALT stays usable as a share token while reported rewards accrue to it.

start/primer.md

Before: SALT has 18 decimals and a one-trillion supply cap, and it settles fees, block rewards, and staking. Amounts
After: SALT has 18 decimals, and on the current testnet the code caps supply at one trillion; it settles fees, block rewards, and staking. The tokenomics are not yet determined. Amounts

operators/run-a-node.md

Before: how a node earns SALT for the work it performs, is covered in rewards;
After: how the current testnet code credits a node SALT for the work it performs, is covered in rewards;

operators/run-a-node.md

Before: | Token | SALT, one trillion supply, 18 decimals |
After: | Token | SALT, 18 decimals; one trillion supply cap in the current testnet code (not yet determined for mainnet) |

start/what-is-citrate.md

Before: A node is how idle GPUs earn SALT on Citrate Market.
After: A node is how idle GPUs take compute jobs on Citrate Market, settled in testnet SALT.

start/tutorials/your-first-10-minutes.md

Before: SALT has 18 decimals and a one-trillion cap (TOTAL_SUPPLY in core/economics/src/lib.rs). It is the unit fees and rewards are counted in.
After: SALT has 18 decimals, and the current testnet code caps supply at one trillion (TOTAL_SUPPLY in core/economics/src/lib.rs); the tokenomics are not yet determined. It is the unit fees and rewards are counted in.

chain/tutorials/call-citrate-rpc.md

Before: SALT has 18 decimals and a one-trillion cap. It is the unit fees and rewards are counted in, not a product.
After: SALT has 18 decimals, and the current testnet code caps supply at one trillion; the tokenomics are not yet determined. It is the unit fees and rewards are counted in, not a product.

chain/genesis.md

Before: The genesis allocation categories sum to the one trillion SALT supply cap; the allocation structure is covered under network economics.
After: In the current testnet code, the genesis allocation categories sum to the one trillion SALT supply cap; the allocation structure is covered under network economics. The mainnet supply and distribution are not yet determined.

core/run-a-node.md

Before: | Uptime | the more your node is online, the more consistently it validates and earns |
After: | Uptime | the more your node is online, the more consistently it validates and takes work |

core/run-a-node.md

Before: - The earning side, how a node is paid in SALT for the work it does, is covered under rewards.
After: - The earning side, how the current testnet code credits a node in SALT for the work it does, is covered under rewards. The tokenomics are not yet determined.

operators/sell-compute.md

Before: It is written for operators who run their own hardware and want idle GPU hours to earn while the machine is otherwise unsupervised.
After: It is written for operators who run their own hardware and want to put idle GPU hours to work while the machine is otherwise unsupervised.

operators/sell-compute.md

Before: ### 6. Understand the bidding so your bids win and stay profitable
After: ### 6. Understand the bidding so your bids win and stay above cost

operators/rewards.md

Before: School and institutional operators run under their own parameters, verified in config/institutional_rewards.toml and core/economics/src/institutional.rs.
After: School and institutional operators run under their own parameters, verified in config/institutional_rewards.toml and core/economics/src/institutional.rs. These are values in the current testnet configuration, not a promise of payment.

Style-guide interaction

STYLE_GUIDE.md bans "tokenomics" in prose (use "network economics"). The owner's wording is used verbatim, so scripts/content-lint.mjs allowlists exactly the sentence "tokenomics are not yet determined", and the style-guide row records that one exception. The notice text itself lives in the component, outside the lint's scope.

Standard

Red commit: 4f96697b (test + notice component + flag plumbing + classifier, with no page flagged). It failed on 5 assertions:
- every page that mentions network-economics terms sets tokenomics_notice: true (49 pages missing)
- the generated content module carries the flag through to the reader (expected >40 flagged, got 0)
- links to the tokenomics status page, which exists and is public (status page undefined)
- states plainly what is and is not decided (status page absent)
- no authored page states proposed economics as final (7 hits in chain/economics.md and operators/rewards.md)
Revert check: with the content changes copied aside and content/ reset to the red commit, the same 5 tests failed; restoring them gave a byte-identical diff and 12/12 green.
Tripwire: the classifier test above, plus the final-claims scan. Both run in npm test, which CI runs.
Dead code: none introduced or left behind.

Verification

npm test: 124 passed / 4 skipped -> 136 passed / 4 skipped (+12).
npm run typecheck: clean.
npm run content-lint -- --strict (truth-lint + content-lint): OK, 0 em-dashes, 0 word findings.
npm run build (prebuild content + changelog, next build, all postbuild gates): OK.
Local next start (mock auth): /chain/economics and /start/tokenomics render the notice; /core/hermes does not.
npm run lint is broken on main and unrelated to this PR (next lint was removed in Next 16; it errors with "Invalid project directory ... /lint").
Pushed with --no-verify: the local pre-push hook replays CI against the main checkout and fails on the two chain-sync-check steps that need a citrate-chain checkout at .chain-src (CI clones it). gitleaks run by hand on origin/main..HEAD: no leaks.

Open questions for the owner

Scope of "mentions SALT". Per the brief, the notice shows on every page that mentions SALT, including pages where SALT only appears as the gas or payment unit (for example the bundler, explorer, wallet extension, and CLI pages). Tell us if you want those narrowed to pages that discuss economics.
Vocabulary. The style guide bans "tokenomics"; this PR uses your wording verbatim with one narrow lint exception. Say if you would rather the notice read "Network economics are not yet determined."
Figures left in place. Concrete testnet values stay on their pages with the notice above them (for example the 30/25/20/25 reward-pool split, the 32,000 SALT minimum validator stake, the institutional 150 SALT/month and 25 SALT/model rows, slashing percentages, and governance thresholds). Tell us if any should be removed rather than labelled.
Ask Atlas. The in-page assistant answers from page bodies, and the notice is rendered by the page shell, not stored in the body. The status page and the reworded sentences are in the corpus, but the assistant does not see the notice itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FPJzHLHkCexnt8jGuPzvMn

Adds the shared TokenomicsNotice, the `tokenomics_notice` frontmatter flag plumbing, a network-economics term classifier, and tests that require every page mentioning those terms to render the notice. Fails on assertion: no page is flagged yet, the status page does not exist, and seven sentences present proposed economics as final. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FPJzHLHkCexnt8jGuPzvMn Signed-off-by: Larry Klosowski <larryklosowski@proton.me>

Owner decision 2026-10-27: SALT and rewards content stays in the docs, with a clear statement that tokenomics are not yet determined. - Flags the 49 authored pages that discuss network economics with `tokenomics_notice: true`, so the reader renders the shared notice at the top. - Adds /start/tokenomics, the single status page the notice links to. - Rewords sentences that presented proposed economics as final ("fixed at genesis ... never more", "project earnings", "what does not move") to describe the current testnet code. No figures added or changed. - content-lint allows the owner-mandated status sentence; the style guide row for "tokenomics" records the one exception. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FPJzHLHkCexnt8jGuPzvMn Signed-off-by: Larry Klosowski <larryklosowski@proton.me>

pysol-dev

COMMENT at 3bd203d. Not approvable yet because CI is red. The failure is inherited from base, not caused by this PR. I found no blocking problems in the change itself. Non-blocking findings are below.

What I ran on this machine

Toolchain: Node 22.23.3, npm ci, vitest 4.1.11, Next.js 16.4.2. Tests were re-run independently: yes. I ran each step of .github/workflows/ci.yml at the head and at the base b2ec3784 (current main), in separate worktrees.

Step	base `b2ec378`	head `3bd203d`
`npm audit --audit-level=high`	exit 1	exit 1 (same advisory set)
`npm run typecheck`	ok	ok
`npm test` (vitest)	124 passed / 4 skipped (128), 13 files	136 passed / 4 skipped (140), 14 files (+12, Rule 2 ok)
`npm run build` (prebuild content + postbuild verify:bundle)	ok	ok; the regenerated `content/_generated/content.ts` matches the committed one (clean tree)
`npm run verify:bundle`	ok	ok
`npm run content-lint -- --strict`	ok	ok (0 em-dashes, 0 vocabulary errors)

CI: build fails at the audit step on the high advisories for undici (4.0.0 - 6.29.0) and zod (<4.6.6), plus a moderate one for @vitest/mocker. This PR does not touch package.json or package-lock.json. The base fails the audit the same way today, and main was last green on 10-23, before these advisories. In CI the audit step stops the job, so typecheck, tests, build and content-lint never ran there; the table above is the only run of those steps at this SHA. merge-gate / ci is red because of this. secret-scan is green.
Red-first: I put the new test, the classifier and the component onto base and ran them. 6 of 12 tests fail: the flag tripwire, generated flag, reader order, status-page link, status-page wording and final-claims. That matches the red commit 4f96697.
Mutants: I made 10 hand mutants. All 10 were killed:
- flag dropped from operators/rewards.md
- render line removed from doc-view.tsx
- notice moved after <Markdown>
- notice text changed
- link target changed
- SALT regex made case-insensitive
- link URLs no longer stripped from prose
- flag matched in the whole file instead of the frontmatter
- flag value not required to be true
- build-content.mjs stops carrying the flag (with regenerated module)
One extra mutant (dropping the m && guard) is equivalent and not counted.
"No figures were added, removed, or changed": I compared the numeric tokens in the word diff of content/** (excluding _generated and the new page): the removed and added sets are identical.
Preconditions: DCO 2/2 signed off (4f96697, 3bd203d). Conventional Commits. betanet label is present. Not a draft. MERGEABLE (base = main tip).

Findings

Blocking: none in the diff. Merge is held only by the red ci check above. Clearing it needs a dependency bump on main or here (undici, zod), not a change to this content.

Non-blocking:

Tripwire coverage gaps (scripts/lib/tokenomics-terms.mjs:12-31). I ran the classifier on these. It returns [] for:
- content/chain/bridge.md:27-28: "Deposit pricing uses a bonding curve, with per-transaction limits and a hard cap on total deposits". The pattern \bbond(?:s|ed)?\b does not match "bonding".
- content/research/atis.md:38-40, 68-70: "the network pays for inference by work performed … the economic reason", "The connection to Citrate is economic … the incentive". \beconomics\b misses "economic", and there is no pattern for "incentive" or "pays".
- Phrasings like "Stakers are rewarded", "A slashable offence" and "validators are paid per block" also return [] ("staker", "rewarded", "slashable" and "paid" fall outside the word forms).
Suggestion: widen these to stems (bond\w*, stak\w*, reward\w*, slash\w*, economic\b) and decide on bridge.md and atis.md explicitly: flag them, or add them to EXEMPT with a reason.
apps/learning-center.md exemption reason is incomplete (test/tokenomics-notice.test.ts:28). The reason given is that "reward" is a verb. But the page also lists budget.rs "Budget allocation and cashout requests" and institutional.rs "Vault status and the cashout approval lifecycle" (lines 88-89). In citrate-learning-center, gui/citrate_edu_app/src/services/institutional.rs is the "Institutional vault + cashout service" and has a get_salt_usd_rate method. So the page describes a SALT-denominated vault with a SALT→USD cashout path. That sits uneasily with the status page's "Testnet SALT has no cash value" (content/start/tokenomics.md:25). Either flag the page, or reword the exemption and the status sentence so they agree.
The notice only reaches the reader UI. Ask chat (lib/ai/corpus.ts:40-45) and MCP getSurface return d.body for flagged pages, and the notice is not in the body. So an agent quoting /chain/economics over MCP gets the testnet figures without the "not yet determined" statement. If the owner decision is meant to cover agent surfaces too, add the notice text (or the flag) to returned chunks.
The reader-order test is a source-string match (test/tokenomics-notice.test.ts:86-91). It passes as long as the exact string {doc.tokenomicsNotice && <TokenomicsNotice />} appears before <Markdown source={doc.body}. An equivalent refactor (for example a renamed prop, or a wrapper) breaks it without a behaviour change, and it does not render DocView. This is acceptable as a tripwire. A render test of DocView with a flagged doc would be stronger.
STYLE_GUIDE exception wording (STYLE_GUIDE.md:58). The row allows "one exception: the status sentence". The page title "Tokenomics status", the link label "Read the tokenomics status" and the aria-label also use the word. That is reasonable, but the row could say "the status sentence and the status page".

Not verified

The rendered page in a browser (the build passes, and the component was checked only via renderToStaticMarkup in the test).
Vercel preview (deploy-dependent).

SaulBuilds and others added 2 commits October 27, 2026 15:54

SaulBuilds requested a review from a team as a code owner October 27, 2026 23:01

SaulBuilds added the betanet Betanet → mainnet program (board #5) label Oct 27, 2026

SaulBuilds requested a review from Matr0xshka October 27, 2026 23:01

pysol-dev reviewed Oct 28, 2026

View reviewed changes

Navigation Menu

Repository navigation

Docs: tokenomics are not yet determined - #42

Docs: tokenomics are not yet determined#42
SaulBuilds wants to merge 2 commits into
mainfrom
docs/tokenomics-not-final

SaulBuilds commented Oct 27, 2026

Uh oh!

pysol-dev left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

SaulBuilds commented Oct 27, 2026

Summary

Pages that now render the notice (49 + the new status page)

Sentences changed (30)

Style-guide interaction

Standard

Verification

Open questions for the owner

Uh oh!

pysol-dev left a comment

Choose a reason for hiding this comment

What I ran on this machine

Findings

Not verified

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants