CLAUDE.md git:20260626.38e31e9A

Immutable. This exact content never changes and is served at /api/v1/blob/1495516cfb0045b8.

# 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.

## 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

### 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

## 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/chainbench

### Description

The right-pane description must be in the following format:

Requirements:
- One sentence max
- No period at the end