Skip to content

CLAUDE.md

Latest commit

 

History

History
800 lines (524 loc) · 24.9 KB

CLAUDE.md

File metadata and controls

800 lines (524 loc) · 24.9 KB
Raw

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 (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:

{
  "product": "Cloud",
  "tabs": [{
    "tab": "Guides",
    "groups": [{
      "group": "Platform",
      "pages": ["docs/new-page"]
    }]
  }]
}

Example for Self-Hosted:

{
  "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:

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:

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

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

  2. 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>
  1. 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"

  1. 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:

"result": {
  "type": "object",
  "nullable": true
}

Avoid patterns like:

"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:

<!-- 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:

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

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:

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

Description

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

Requirements:

  • One sentence max
  • No period at the end