CLAUDE.md · diff
git:20260728.eed64be to git:20260923.81920a9
1 added, 1 removed. Audit A to A.
# Chainstack Developer Portal project context, structure, and formatting
## Public repo — no internal info
This repository is public, and every page renders publicly at [docs.chainstack.com](https://docs.chainstack.com) (and is republished as `llms-full.txt`, per-page `.md`, and through the MCP server). The PR itself — description, screenshots, commit messages, sample payloads — is public too, and gets indexed and cached. Never include:
- **Secrets** — API keys, tokens, private keys, credentials. Use placeholders like `YOUR_API_KEY`.
- **Internal infrastructure** — internal hostnames, cluster names, dashboards (Grafana, BetterStack), admin/backoffice URLs.
- **Customer data** — names, PII, account or usage details.
- **Unreleased material** — features, pricing, or roadmap that isn't public yet.
- **Internal references** — YouTrack ticket links, internal Slack threads, internal-only notes.
A secret committed to a public repo is compromised even after you delete or force-push it — rotate it.
### Exception — public demo endpoints
The Chainstack node endpoints that appear in the API reference specs and in some tutorials are **intentional public demo endpoints**. They exist so the Try it playground works and so readers can run an example by copy-paste. They look like credentials because they are node auth tokens, but they are published deliberately and maintained on purpose.
Leave them as they are. Do not replace them with placeholders, and do not open an issue or PR reporting them as leaked secrets.
Two places you will see them:
- API reference — the token is the `paths` key in `openapi/`, and it must match the one in the corresponding `reference/` page frontmatter. Changing one without the other breaks the Try it button.
- Tutorials — a small number of guides call a demo endpoint directly so the example is runnable as written.
Everything else in the list above still applies. A node endpoint from your own account, a Chainstack platform API key, or a private key is a real secret and must never be committed — use a placeholder such as `YOUR_CHAINSTACK_ENDPOINT`, `YOUR_AUTH_TOKEN`, or `YOUR_API_KEY`.
## Project context
- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter
- Navigation is configured in `docs.json`
- When creating a new article as an *.mdx file, always remember to add the file name to the appropriate section in the navigation file `docs.json`
- The docs use Mintlify's product switcher with two products:
- **Cloud** — managed blockchain infrastructure (docs in `docs/`)
- **Self-Hosted** — deploy on your own infrastructure (docs in `docs/self-hosted/`)
## Directory structure
```
dev-portal/
├── docs/ # Cloud documentation
│ ├── page-name.mdx
│ └── self-hosted/ # Self-Hosted documentation
│ ├── page-name.mdx
│ └── changelog/ # Self-Hosted release notes
├── images/ # Cloud images
│ └── self-hosted/ # Self-Hosted images
├── changelog/ # Cloud release notes
├── openapi/ # Cloud API specifications
└── docs.json # Navigation configuration for both products
```
## Navigation structure (docs.json)
The navigation uses a product-based hierarchy:
```
products
└── product (Cloud | Self-Hosted)
├── description
├── icon
└── tabs
├── tab: "Guides"
│ └── groups
│ ├── group: "Group name"
│ └── pages: ["docs/page", ...]
└── tab: "Release notes"
└── pages: ["changelog/entry", ...]
```
When adding a new page:
1. Create the `.mdx` file in the appropriate directory
2. Add the page path to the correct product → tab → group in `docs.json`
Example for Cloud:
```json
{
"product": "Cloud",
"tabs": [{
"tab": "Guides",
"groups": [{
"group": "Platform",
"pages": ["docs/new-page"]
}]
}]
}
```
Example for Self-Hosted:
```json
{
"product": "Self-Hosted",
"tabs": [{
"tab": "Guides",
"groups": [{
"group": "Installation",
"pages": ["docs/self-hosted/new-page"]
}]
}]
}
```
## Internal linking
Use relative paths with the `/docs/` prefix:
- Cloud pages: `/docs/page-name`
- Self-Hosted pages: `/docs/self-hosted/page-name`
Examples:
```markdown
See [System requirements](/docs/self-hosted/requirements) for details.
Learn more about [Global Nodes](/docs/global-elastic-node).
```
Cross-product linking is supported—you can link from Self-Hosted docs to Cloud docs and vice versa.
## Required page structure
Every page must start with frontmatter:
```yaml
---
title: "Clear, specific title"
description: "Concise description for SEO and navigation"
---
```
## Mintlify components
### Callouts
- `<Note>` for helpful supplementary information
- `<Warning>` for important cautions and breaking changes
- `<Tip>` for best practices and expert advice
- `<Info>` for neutral contextual information
- `<Check>` for success confirmations
Keep callouts short — one or two sentences. A callout is a glanceable alert, not a container for long explanations. If the content runs to a paragraph or more, put it in normal prose and keep only the single key takeaway in the callout.
### Code examples
- When appropriate, include complete, runnable examples
- Use `<CodeGroup>` for multiple language examples
- Specify language tags on all code blocks
- Include realistic data, not placeholders
- Use `<RequestExample>` and `<ResponseExample>` for API docs
### Procedures
- Use `<Steps>` component for sequential instructions
- Include verification steps with `<Check>` components when relevant
- Break complex procedures into smaller steps
### Content organization
- Use `<Tabs>` when deemed appropriate to show information in tabs-style next to each other in one row
- Use `<Accordion>` for progressive disclosure
- Use `<Card>` and `<CardGroup>` for highlighting content
- Wrap images in `<Frame>` components with descriptive alt text
## Release notes
The documentation has two products with separate release notes:
- **Cloud** — managed blockchain infrastructure (`changelog.mdx` + `changelog/` directory)
- **Self-Hosted** — deploy on your own infrastructure (`docs/self-hosted/release-notes.mdx` + `docs/self-hosted/changelog/`)
### Cloud release notes
#### Structure
```
dev-portal/
├── changelog.mdx
├── docs.json
└── changelog/
├── chainstack-updates-may-30-2025.mdx
├── chainstack-updates-april-1-2025.mdx
└── [previous entries...]
```
#### Process
1. **Update `changelog.mdx`**: Copy the previous entry within `<Update...> </Update>` tags and paste it on top of the previous entry. Edit dates and content appropriately.
Example:
```
<Update label="Chainstack updates: May 30, 2025" description=" by Ake" >
**Protocols**. Now, you can deploy [Global Nodes](/docs/global-elastic-node) for Unichain Mainnet. See also [Unichain tooling](/docs/unichain-tooling) and a [tutorial](/docs/unichain-collecting-uniswapv4-eth-usdc-trades).
<Button href="/changelog/chainstack-updates-may-30-2025">Read more</Button>
</Update>
```
2. **Create file in `changelog/` directory**: Use format `chainstack-updates-may-30-2025.mdx`. Paste the same entry content (without the `<Update>` tags) from step 1.
3. **Update `docs.json`**: In the `Release notes` section, add the newly created file name (without `.mdx`) between `changelog` and the previous release notes entries.
Example:
```
"tab": "Release notes",
"pages": [
"changelog",
"changelog/chainstack-updates-may-30-2025",
"changelog/chainstack-updates-may-16-2025",
```
### Self-Hosted release notes
#### Structure
```
dev-portal/
└── docs/self-hosted/
├── release-notes.mdx
└── changelog/
├── chainstack-self-hosted-v1-0-0-january-28-2026.mdx
└── [version entries...]
```
#### Process
1. **Update `release-notes.mdx`**: Add a new `<Update>` entry at the top.
Example:
```
<Update label="Chainstack Self-Hosted v1.0.0: January 28, 2026" description="">
**Initial beta release**. Deploy Ethereum Mainnet, Sepolia, and Hoodi full nodes on your own Kubernetes infrastructure using Reth execution client and Prysm consensus client.
<Button href="/docs/self-hosted/changelog/chainstack-self-hosted-v1-0-0-january-28-2026">Read more</Button>
</Update>
```
2. **Create file in `docs/self-hosted/changelog/` directory**: Use format `chainstack-self-hosted-v1-0-0-month-day-year.mdx`.
The page title should match the label: `"Chainstack Self-Hosted v1.0.0: January 28, 2026"`
3. **Update `docs.json`**: In the Self-Hosted product's `Release notes` tab, add the new changelog page.
## Node options master list
`node-options-master-list.json` is the main file for this Developer Portal where all the available node options are kept up to date. If you need a custom table with whatever options you want, you feed the master list to an LLM and generate your own table.
Relevant tables (updated on every master list change):
- `nodes-clouds-regions-and-locations.mdx`
- `protocols-networks.mdx`
When updating the master list:
1. Edit `node-options-master-list.json`
2. Regenerate dependent tables
3. Verify changes display correctly
**Node-type naming in the generated tables:** use the current product names — **Global Node** (the `global` node type), **Dedicated Node**, and **Trader Node**. Do **not** emit **Elastic** (the deprecated name for Global Node). In `protocols-networks.mdx` the **Support** column reads `Global Node, Dedicated` and the availability headers are `Global Node Mainnet Support` / `Global Node Testnet Support`.
## Self-Hosted deployments master list
`self-hosted-deployments.json` is the single source of truth for every Chainstack Self-Hosted deployment — protocols, networks, clients, client versions, CPU/RAM/storage, presets, and exposed ports. It is hand-maintained from the upstream sources:
- Resource and client data — upstream preset and network definitions
- Port constants — upstream client port definitions
Pages with generated tables (regenerate on every master list change):
- `docs/self-hosted/supported-clients-and-protocols.mdx` — the catalog (matrix + per-family sections)
- `docs/self-hosted/requirements.mdx` — the per-family resource summary
Pages that mention protocols in prose (update the protocol names when a deployment is added or removed):
- `docs/self-hosted/introduction.mdx` — the multi-protocol feature bullet
- `docs/self-hosted/faq.mdx` — the production-readiness answer
- `docs/self-hosted/deploying-nodes.mdx` — the supported-deployments pointer
When a preset changes upstream:
1. Update `self-hosted-deployments.json`
2. Regenerate the dependent tables
3. Verify changes display correctly
## API documentation requirements (Cloud only)
These guidelines apply to Cloud API documentation. Self-Hosted does not have API reference docs.
- Document all parameters with `<ParamField>`
- Show response structure with `<ResponseField>`
- Include both success and error examples
- Use `<Expandable>` for nested object properties
- Always include authentication examples
### OpenAPI 3.0 nullability (important for Try it)
When documenting JSON-RPC via OpenAPI 3.0, do not use `type: null` anywhere in schemas. OpenAPI 3.0 does not support a standalone null type and specs using it can cause Mintlify to fail matching the operation (e.g., removing the Try it button with an error about missing path/method).
Preferred pattern:
```json
"result": {
"type": "object",
"nullable": true
}
```
Avoid patterns like:
```json
"result": {
"oneOf": [ { "type": "null" }, { "type": "object" } ]
}
```
If a page is missing the Try it button and logs show "no matching OpenAPI operation object" for a valid path/method, check and replace any `type: null` usages with `nullable: true`.
## Quality standards
- Test all code examples before publishing whenever possible
- Use relative paths for internal links
- Include alt text for all images
- Ensure proper heading hierarchy (start with h2)
- Check existing patterns for consistency
## Content patterns
### Single source of truth
Avoid duplicating information across pages. Instead, maintain one authoritative source and link to it:
- System requirements → link to `/docs/self-hosted/requirements`
- Supported protocols → link to `/docs/self-hosted/supported-clients-and-protocols`
- Sync times and hardware recommendations → link to requirements page
- Snapshot timeline → keep in FAQ, link from other pages
Example:
```markdown
<!-- Instead of duplicating a table of requirements -->
See [System requirements](/docs/self-hosted/requirements) for specifications and a community-maintained list of hardware recommendations.
```
### Troubleshooting page structure
For troubleshooting pages, use this hierarchy:
```markdown
## Category (e.g., Installation troubleshooting)
### Problem heading (describes the symptom)
Brief description of the problem.
#### Cause or check 1
Diagnostic steps or solution.
#### Cause or check 2
Diagnostic steps or solution.
```
Avoid numbered lists for independent troubleshooting items—use subheadings instead.
# Chainstack Developer Portal project writing style guide
## Tone of voice
At Chainstack, we build complex tools for a primarily technical audience, displayed in a clear and intuitive way. Individuals and organizations use Chainstack as a stable foundation to support the infrastructure behind complex Web3 applications.
For these reasons, we always aim to:
1. Be clear, concise, and specific, not vague or convoluted.
2. Use correct terminology, while avoiding unnecessarily complex technical jargon.
3. Provide useful and true information.
4. Be friendly but not unprofessional.
## Style tips
Use active voice. Avoid passive voice.
In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
- Correct: Chainstack created a new network.
- Incorrect: A new network was created by Chainstack.
Use positive language rather than negative language.
- Correct: You need to delete all nodes to cancel your subscription.
- Incorrect: You can't cancel your subscription because you have active nodes on your account.
## Grammar
### Spelling
We write using American English spelling.
### Capitalization
We never use **Title case**. We use **sentence case** for everything, including titles.
**Sentence case** capitalizes the first letter of the first word, plus any proper nouns.
When writing out an email address or website URL, use all lowercase.
Example:
- [support@chainstack.com](mailto:support@chainstack.com)
- [chainstack.com](http://chainstack.com/)
We keep the proper spelling and capitalization of project names.
### Dates and time
Always use abbreviated months and days on forms, tables, lists and other condensed product elements. Non-abbreviated dates should be used in formal writing.
#### Date formats
Use abbreviated months for most contexts.
Correct:
- Jul 28, 2019
- July 2019
For formal writing, use full month names:
- July 28, 2019
#### Date ranges
Date ranges must be written using an unspaced en-dash.
Correct:
- Jul 28, 2019–Aug 29, 2019
- Monday–Friday
#### Time formats
Use 24-hour format with colons, include timezone when relevant. Use en-dash for time ranges.
Correct:
- 09:00–23:59
- 09:00–23:59 (UTC+08:00)
#### Consistency rules
Never mix abbreviated and non-abbreviated formats in the same context.
### Numbering format
We use the US-English number format.
When labeling million we use "M" instead of "MM." When labeling thousands, we use "K".
Example:
- 4,294,967,295.00
- 1,000,000 = 1M
### Pricing
Use commas (`,`) to separate thousands of pricing units. Cents are shown using periods (`.`) not commas (`,`).
The currency symbol always falls before the number. Three-letter currency codes can be denoted before the currency symbol if ambiguous.
Example:
- $99
- $9,999.99
- USD $0
### Punctuation
#### Hyphens and dashes
Use a hyphen (-) without spaces to link words into single phrase:
Example:
- first-time user, top-up amount
Use en-dash to indicate a span or range for dates, times, and other ranges.
Examples:
- Jul 23, 2023–Aug 1, 2023
- Monday–Friday
- 09:00–17:00
#### Em dash
Em dashes can function as an alternative to parentheses, commas, or a colon.
##### In sentences and paragraphs
Use an em dash *without* spaces to indicate a break in flow or set off parenthetical information.
Examples:
- It was a revival of the most potent image in modern democracy—the revolutionary idea.
- My friends—that is, my former friends—ganged up on me.
- Chainstack—a platform to manage decentralized networks and services—is actually the easiest to use.
##### In lists and technical documentation
Use an em dash *with* spaces when creating lists that explain or define terms, parameters, or concepts.
Examples:
- Ethereum — a public distributed computing platform.
- CHAINSTACK_NODE_ENDPOINT — your deployed Chainstack node.
- code-level-variable — lowercase description of the variable.
#### Commas
We make use of the Oxford comma. In a series of 3 or more items, use a comma before the final "and" or "or".
- Correct: You need to delete all projects, networks, and nodes.
- Incorrect: You need to delete all projects, networks and nodes.
#### Exclamation marks
Use exclamation marks sparingly, and never more than one at a time. They should be almost non-existent in product elements. Do not use them in failures or alert messages.
#### Dollar signs
Always escape dollar signs with a backslash in MDX files to prevent them from being interpreted as LaTeX/math delimiters.
Correct:
- \$1 USDC
- \$5M volume
- \$10,000
Incorrect:
- $1 USDC
- $5M volume
- $10,000
### Abbreviation
Use full naming in first mention of term in text. Abbreviate later instances.
Example:
- You can deploy BNB Smart Chain (BSC) node endpoints on any Chainstack subscription plan.
Do not abbreviate Chainstack product names. Always use the full product name with proper capitalization.
## Text elements
### Navigation and menu items
Use sentence case.
Limit to one or two words.
No periods.
Example:
- Documentation
- Support
- Settings
- Sign out
### Headings
Use sentence case.
Don't write in full sentences.
No periods.
Example:
- Deploy your first blockchain node
- Edit project
- Network details
### Descriptive text, paragraphs & subheadings
Use sentence case.
Use periods.
Example:
- View your project members, and invite organizations to become project members.
- Specify basic details. Note that these cannot be changed once the network is created.
### Linking
Can be up to 5-10 words in length.
Use sentence case.
No periods if text link is on its own.
Use periods if link falls at the end of a regular sentence.
Don't link the punctuation at the end of a link.
Don't link the preceding article before the link.
Avoid one-word linking.
Use full links only for external resources.
Incorrect:
- see our [Terms of Service].
- visit the [documentation site]
Correct:
- [Contact us]
- [Review and rename nodes]
- View the [Terms of Service] and [Privacy Policy].
#### Linking the words Chainstack and Chainstack account
Correct:
- Use `[Chainstack account](link)` to link to console.chainstack.com
- Use `[Chainstack](link)` for chainstack.com
Do not mix these two.
### List items
Use sentence case and capitalize the first letter of each list item.
Keep all items in a list consistent—use either complete sentences or phrases throughout the entire list.
#### Punctuation rules for lists
Use periods when:
- List items are complete sentences
Do not use periods when:
- List items are single words, phrases, or sentence fragments
Bold text must never be the first element of a list item.
A list item may contain bold text later in the sentence (for example, to highlight a UI element), but the bullet or dash itself must start with plain text.
Exception: If the list item is a UI element name (per the UI‑elements rule), that name is allowed to appear in bold at the start of the line.
Correct:
- Listed item — listed item explanation
- Click **Members** — opens the project members page
Incorrect:
- **Listed item** — listed item explanation
#### Examples
**Complete sentences (use periods):**
To downgrade your account, you need to:
- Reduce your number of owned networks to 1.
- Reduce your number of owned nodes to 1.
**Single words or phrases (no periods):**
Chainstack supports the following protocols:
- Ethereum, Solana, BNB Smart Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, TON, Ronin, Blast, ZKsync Era, Starknet, Scroll, Aptos, Fantom, Cronos, Gnosis Chain, Kaia, Moonbeam, Celo, Oasis Sapphire, Polygon zkEVM, Bitcoin, Harmony
#### Technical documentation lists with em dashes
For technical documentation lists that explain parameters, variables, or concepts, follow the em dash rules. Use em dashes with spaces and lowercase formatting:
- List item — lowercase.
- DOCS-LEVEL-VARIABLE — lowercase.
- code-level-variable — lowercase.
Example:
- Ethereum — a public distributed computing platform.
- CHAINSTACK_NODE_ENDPOINT — your deployed Chainstack node.
If the list item is not a parameter explanation, but a parameter value, use ":" instead of an em dash:
- Parameter name/explanation parameter: value
Example:
- Decoded vout: 0
## UI guidelines
### UI elements
Use **bold** to denote UI elements.
Example: To see project members, click **Members**.
### UI clickthrough
Use > to denote clicking through UI elements.
Example: To invite a member to the project, click **Members** > **Invite member**.
Note that only the UI elements are in bold, and the right angle bracket is not a UI element.
Full markdown code:
```markdown
To invite a member to the project, click **Members** > **Invite member**.
```
### UI as a word (Cloud)
Never use UI as a word when providing instructions for the [Chainstack console](https://console.chainstack.com/). Instead, use Chainstack.
- Correct: On Chainstack, navigate to your node details
- Incorrect: In the platform UI, navigate to your node details
### UI terminology (Self-Hosted)
For Self-Hosted documentation:
- Use **Control Panel** to refer to the Self-Hosted web interface
- Use **Chainstack Self-Hosted** for the product name (not just "Chainstack")
- Never use "Chainstack" alone when referring to Self-Hosted—this causes confusion with the managed Cloud product
Examples:
- Correct: Log in to the Control Panel
- Correct: Chainstack Self-Hosted supports Ethereum Mainnet
- Incorrect: Log in to Chainstack (ambiguous—could mean Cloud)
- Incorrect: On the Self-Hosted UI, navigate to... (use "Control Panel" instead)
## Word usage
### Word forms of cancel
Use American English (AmE) for word forms of cancel.
Canceling:
- Correct: Canceling
- Incorrect: Cancelling
Canceled:
- Correct: Canceled
- Incorrect: Cancelled
Cancellation:
- Correct: Cancellation
- Incorrect: Cancelation
### Word forms of sync
Correct:
- syncing, synced
Incorrect:
- synching, synched
## Currency vs. protocol in naming
Protocol names must always be capitalized.
Full currency names must always be lowercase, except when they appear at the beginning of a sentence or are part of code.
Examples:
- wei, gwei, ether
- The transaction fee is paid in ether. (lowercase)
- Ether is the native cryptocurrency of Ethereum. (capitalized at start of sentence)
Ticker symbols must always be all caps and can be used in a sentence after explaining the acronym.
Examples:
- Polygon token (MATIC)
- Ether (ETH)
- Wrapped ether (WETH)
## Directory paths
End directory paths with a slash.
Correct:
- F:\Documents\GitHub\
- var/lib/
Incorrect:
- F:\Documents\GitHub
- var/lib
## Directory vs. folder
Correct:
- directory
Incorrect:
- folder
## Public repositories
### Naming
The Chainstack open source public repositories must use lowercase-with-hyphens naming format.
Correct:
- https://github.com/chainstacklabs/chainstack-rpc-dashboard-functions
- - https://github.com/chainstacklabs/pump-fun-bot
+ - https://github.com/chainstacklabs/pumpfun-bonkfun-bot
- https://github.com/chainstacklabs/chainbench
### Description
The right-pane description must be in the following format:
Requirements:
- One sentence max
- No period at the end