You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Rewrite the docs and add repo files for v1.0.0 - #762
Stacked on #761. Rewrites the public documentation for the first release and adds the repo files an open-source project needs. No runtime code changes; the only Go is a small schema-to-markdown generator under tools/.
How to read this PR
Don't review it as a diff; almost every line is new. Read it rendered, the way a user would. GitHub renders Markdown and Mermaid in the branch view, and every link is relative, so you can click through the whole tree from one page:
Use the diff view only for CONTRIBUTING.md (additions under the existing policy), the .graphqls descriptions, and tools/gqldocs.
What to look for: a claim that does not match how the code behaves, a sentence a newcomer would not understand, and anything that reads like filler. Every number carries a date and a source.
What a reader gets
Need
Page
See it work in 15 minutes
docs/getting-started.md (testnet, compose, first queries)
Deploy it
docs/deploy/README.md lists the steps in order: install.md, ingest.md, protocols.md (SEP-41 setup, needed on a fresh install), serve.md, backfill.md. Then upgrading.md, runbook.md, and hiding-tokens.md (the hidden-contracts list from #764, moved here from the old data-migrations doc)
Look up a flag
docs/deploy/configuration.md, checked against --help in CI
Call the API
docs/api/graphql.md (guide), docs/api/schema.md (generated), docs/api/authentication.md (language-neutral JWT spec with a fixed-key worked token), docs/api/go-client.md
Operate it
docs/deploy/observability.md (every metric), runbook sizing from the dev pubnet and testnet deployments (seven days ending 2026-10-06) with provenance
Understand it
docs/architecture/ overview, ingestion (written against the live-persist pipeline that merged on 2026-10-08: stages, buffer sizing, the eight-transaction commit set, crash window, cursor-bounded reads, retry ladders), token tracking, state changes, protocols, GraphQL serving, database, data model, each with validated Mermaid diagrams and a "Where in the code" table
Contribute
docs/contributing/adding-a-protocol.md, integration-tests.md, and new repo-specific sections in CONTRIBUTING.md
Release
docs/contributing/releasing.md (cadence, rc→promote, public ECR + Docker Hub, notes template)
Folders are grouped by reader: deploy/ for operators, api/ for API clients, architecture/ for how it works, contributing/ for maintainers. docs/README.md and the README table use the same groups, so the folder view and the index match. Protocol setup is step 3 of the deploy guide and has its own README row, because a fresh install without it has no SEP-41 data.
README.md is a landing page: badges, requirements, quickstart ending in a working query, docs index, stability policy, support.
Removed
The README architecture section (described a Redis token cache and services that no longer exist), docs/feature-design/data-migrations.md, docs/data-migrations/* (documented a removed validator interface), and internal/serve/graphql/README.md (wrong endpoint, port and auth claims). Nothing kept for continuity.
GraphQL schema
Every type, field, argument, input field, enum value and scalar now has a description: units, encodings, null cases, page limits, ordering. 233 undescribed elements → 0. No type or field changed; generated code is regenerated.
Tooling
tools/gqldocs renders the schema to docs/api/schema.md. make gql-docs / make gql-docs-check.
scripts/check-config-docs.sh diffs docs/deploy/configuration.md against every command's --help.
.markdownlint.yaml, .lychee.toml, make docs-lint, make docs-check.
New CI job docs-check (schema freshness, markdownlint, lychee, config diff) gates complete.
Quickstart fix
stellar-rpc 29 (the current stable image) reads NETWORK as its own network preset and exits when the config file also sets the passphrase and archive URLs. The quickstart's RPC startup script now reads RPC_NETWORK instead. The quickstart also pins stellar/stellar-rpc:29.0.1 instead of :stable, so the next RPC release can't break it without a commit, and the documented requirement is 28.x or 29.x (the integration suite runs 28.0.0). Verified locally: RPC 29.0.1 starts, and ingest reaches healthy after the testnet checkpoint bootstrap.
Repo hygiene
CONTRIBUTING.md keeps the wallet-eng contribution policy from #759 word for word and adds on top: a Contents list, local setup, the release-note label table, schema and migration mechanics, and the docs checks. The diff against main is additive only. New: SUPPORT.md, CODEOWNERS → @stellar/wallet-eng, YAML issue forms replacing the legacy templates with blank issues off.
Writing rules applied
Present behavior only, no history. Plain words, short sentences, tables over prose. Every claim traced to a file; numbers carry date, network and hardware. No internal infrastructure names.
Behavior documented as-is that may deserve a code change
transactionByHash / operationById return null with INTERNAL_SERVER_ERROR on not-found.
TrustlineUpdatedChange.oldLimit is integer stroops while newLimit and TrustlineAddedChange.limit are 7-decimal strings.
/health returns 500 when RPC is unreachable and 503 when unhealthy or lagging; the unsigned lag subtraction also yields 503 when RPC is behind ingest.
SEP-41 transfers add no participants, so a receiver sees the credit in stateChanges but not the transaction in Account.transactions.
Tracked internally.
Verification
make check, make gql-docs-check, scripts/check-config-docs.sh, markdownlint over every page, Mermaid CLI over all 19 diagrams, a relative-link check (0 broken), and the banned-word / stale-token greps all pass.
After merge, the user-owned steps are: flip code-owner review on the protect-main ruleset, delete the develop branch, set repo topics and labels, create the v1.0.0 milestone.
aditya1702
changed the title
Rewrite the documentation and add repo hygiene for the v1.0.0 release
Rewrite the docs and add contributor files for v1.0.0
Oct 5, 2026
docker compose ps incorrectly expects one-shot migrate to be running
CONTRIBUTING.md:25
The compose stack intentionally runs migrate as a one-shot service (restart: "no"), so docker compose ps will show it exited rather than every service running. This verification instruction will report a healthy setup as wrong.
make check modifies files despite being presented as read-only
CONTRIBUTING.md:33
make check is not read-only: its prerequisites include tidy and fix-imports, both of which write files (go mod tidy, gofmt, gofumpt -w, and goimports -w). This verification step can therefore leave a dirty worktree, so the instruction to expect no changed files is misleading.
Ingest environment assignments are not exported
docs/operations/running.md:83
These are shell variables in one code block, but they are not exported, so the later wallet-backend ingest process will not receive them when a reader copies these steps. Use export here or put the assignments directly before the command.
Wallet backend environment assignments are not exported
docs/operations/running.md:158
These assignments are not exported before the separate wallet-backend serve command, so the API will use defaults instead of the configured database, RPC, port, and auth keys. Mark them as exports or show a single command with inline environment assignments.
…ads ledger-entry balances only
The overview splits protocol-setup from protocol-migrate, since only the
latter serves /metrics. The running page and the integration-test suite
table say the checkpoint loads ledger-entry balances and SEP-41 comes
from the current-state migration.
The operator pages no longer assume Kubernetes or name our hardware
classes: pods become processes or instances, probes become traffic and
restart checks, and the sizing provenance names CPU, memory and storage
type only.
Pubnet and testnet figures for the ingester, backfill, API, database
and disk, from seven-day peaks on the measured deployments. The
ingester's first-start checkpoint bootstrap sets its memory minimum.
Live ingestion is now a fetch, process and persist pipeline that writes
each batch through seven sibling transactions plus a coordinating
transaction that commits the cursor last. The ingestion, database,
overview and runbook pages describe that, the configuration reference
gains LIVE_PERSIST_MAX_BATCH_SIZE, the 9-connection minimum and the new
pool default, and the observability page lists the persist batch-size
metric.
Live mode is re-derived from internal/services/ingest_live.go: startup
reconciliation and the pool check, the fetch/process/persist stages
with their channel and buffer sizing, one classification plan per
batch, the eight-transaction commit set in order, durability and the
crash window, cursor-bounded reads, error classification and retry
ladders, how a pipeline error is reported once, lock loss versus
shutdown, and the cleanup order. The indexer section describes the
buffer as keyed by TOID with GOMAXPROCS-based pools. The database,
protocols and serving pages use the same batch commit-set wording.
…g/ for maintainers
Pure moves plus link fixes. Operator pages (running, protocol data
migrations, upgrading, runbook, observability, configuration) move to
docs/deploy/, and contributor pages (adding a protocol, integration
tests, releasing) to docs/contributing/. api/ and architecture/ keep
their paths.
docs/deploy/README.md lists the steps in order and GitHub renders it
under the folder listing: install, ingest, protocols, serve, backfill.
Each step page is one stage of the old running guide with its own
Contents, a Next link and its own code map. Protocol setup is step 3,
so a fresh install no longer leaves SEP-41 data empty by omission.
…grouped indexes
The protocols page opens as step 3 of the deploy guide and says where a
fresh install starts in its order of operations. Getting started gains an
optional last step that turns on SEP-41 history, warns that
protocol-setup runs for a long time on testnet, and says why SEP-41
balances need a data lake. The docs index and the README table group
pages the same way as the folders, and the README links the protocols
page directly.
stellar-rpc 29 reads NETWORK as its own network preset and refuses to
start when the config file also sets the passphrase and archive URLs,
so the quickstart's stellar-rpc exited on the current stable image.
The hidden-contracts how-to lived in the old data-migrations doc, which
this branch replaces. It moves to docs/deploy/hiding-tokens.md, listed
under Keep it running, with the startup log line and every startup error
taken from the loader. configuration.md gains --hidden-contracts-file and
a validation rule.
…elease-note fallback, contract_tokens writer
AccountTransactionEdge.stateChanges keeps a transaction's newest 2,000
rows; the schema description, the GraphQL guide and the state-changes
page say so. The quickstart pins stellar-rpc 29.0.1 instead of :stable
and the requirement reads 28.x or 29.x. The label tables show the Other
changes fallback, the data model lists protocol-setup as a
contract_tokens writer, and the quickstart says why current-state needs
a data lake on testnet.
These are shell assignments in a standalone block, but the wallet-backend ingest command appears later in a different block. Without export, a reader following the guide starts ingestion without the required database, RPC, and network-passphrase environment; prefix these assignments (and the pubnet overrides below) with export or keep them on the command line.
Export server environment variables
docs/deploy/serve.md:22
These assignments are not exported, and the wallet-backend serve command is in a separate shell block. Following this procedure in a shell therefore starts the server without DATABASE_URL, RPC_URL, NETWORK_PASSPHRASE, or PORT; use export (or put the assignments on the command) here and in the authentication step.
Hiding does not expose receiver-only SEP-41 transaction rows
docs/deploy/hiding-tokens.md:22
This overstates the effect of hiding: SEP-41 processing does not add participant rows, so an account that only receives a SEP-41 transfer is not present in Account.transactions or Account.operations at all. Only existing participant rows remain visible after the state changes are filtered. Please qualify this row to match docs/architecture/state-changes.md:134.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
documentationImprovements or additions to documentation
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #761. Rewrites the public documentation for the first release and adds the repo files an open-source project needs. No runtime code changes; the only Go is a small schema-to-markdown generator under
tools/.How to read this PR
Don't review it as a diff; almost every line is new. Read it rendered, the way a user would. GitHub renders Markdown and Mermaid in the branch view, and every link is relative, so you can click through the whole tree from one page:
CONTRIBUTING.md(additions under the existing policy), the.graphqlsdescriptions, andtools/gqldocs.What to look for: a claim that does not match how the code behaves, a sentence a newcomer would not understand, and anything that reads like filler. Every number carries a date and a source.
What a reader gets
docs/getting-started.md(testnet, compose, first queries)docs/deploy/README.mdlists the steps in order:install.md,ingest.md,protocols.md(SEP-41 setup, needed on a fresh install),serve.md,backfill.md. Thenupgrading.md,runbook.md, andhiding-tokens.md(the hidden-contracts list from #764, moved here from the old data-migrations doc)docs/deploy/configuration.md, checked against--helpin CIdocs/api/graphql.md(guide),docs/api/schema.md(generated),docs/api/authentication.md(language-neutral JWT spec with a fixed-key worked token),docs/api/go-client.mddocs/deploy/observability.md(every metric), runbook sizing from the dev pubnet and testnet deployments (seven days ending 2026-10-06) with provenancedocs/architecture/overview, ingestion (written against the live-persist pipeline that merged on 2026-10-08: stages, buffer sizing, the eight-transaction commit set, crash window, cursor-bounded reads, retry ladders), token tracking, state changes, protocols, GraphQL serving, database, data model, each with validated Mermaid diagrams and a "Where in the code" tabledocs/contributing/adding-a-protocol.md,integration-tests.md, and new repo-specific sections inCONTRIBUTING.mddocs/contributing/releasing.md(cadence, rc→promote, public ECR + Docker Hub, notes template)Folders are grouped by reader:
deploy/for operators,api/for API clients,architecture/for how it works,contributing/for maintainers.docs/README.mdand the README table use the same groups, so the folder view and the index match. Protocol setup is step 3 of the deploy guide and has its own README row, because a fresh install without it has no SEP-41 data.README.mdis a landing page: badges, requirements, quickstart ending in a working query, docs index, stability policy, support.Removed
The README architecture section (described a Redis token cache and services that no longer exist),
docs/feature-design/data-migrations.md,docs/data-migrations/*(documented a removed validator interface), andinternal/serve/graphql/README.md(wrong endpoint, port and auth claims). Nothing kept for continuity.GraphQL schema
Every type, field, argument, input field, enum value and scalar now has a description: units, encodings, null cases, page limits, ordering. 233 undescribed elements → 0. No type or field changed; generated code is regenerated.
Tooling
tools/gqldocsrenders the schema todocs/api/schema.md.make gql-docs/make gql-docs-check.scripts/check-config-docs.shdiffsdocs/deploy/configuration.mdagainst every command's--help..markdownlint.yaml,.lychee.toml,make docs-lint,make docs-check.docs-check(schema freshness, markdownlint, lychee, config diff) gatescomplete.Quickstart fix
stellar-rpc 29 (the current
stableimage) readsNETWORKas its own network preset and exits when the config file also sets the passphrase and archive URLs. The quickstart's RPC startup script now readsRPC_NETWORKinstead. The quickstart also pinsstellar/stellar-rpc:29.0.1instead of:stable, so the next RPC release can't break it without a commit, and the documented requirement is 28.x or 29.x (the integration suite runs 28.0.0). Verified locally: RPC 29.0.1 starts, and ingest reaches healthy after the testnet checkpoint bootstrap.Repo hygiene
CONTRIBUTING.mdkeeps the wallet-eng contribution policy from #759 word for word and adds on top: a Contents list, local setup, the release-note label table, schema and migration mechanics, and the docs checks. The diff againstmainis additive only. New:SUPPORT.md,CODEOWNERS→@stellar/wallet-eng, YAML issue forms replacing the legacy templates with blank issues off.Writing rules applied
Present behavior only, no history. Plain words, short sentences, tables over prose. Every claim traced to a file; numbers carry date, network and hardware. No internal infrastructure names.
Behavior documented as-is that may deserve a code change
transactionByHash/operationByIdreturn null withINTERNAL_SERVER_ERRORon not-found.TrustlineUpdatedChange.oldLimitis integer stroops whilenewLimitandTrustlineAddedChange.limitare 7-decimal strings./healthreturns 500 when RPC is unreachable and 503 when unhealthy or lagging; the unsigned lag subtraction also yields 503 when RPC is behind ingest.stateChangesbut not the transaction inAccount.transactions.Tracked internally.
Verification
make check,make gql-docs-check,scripts/check-config-docs.sh, markdownlint over every page, Mermaid CLI over all 19 diagrams, a relative-link check (0 broken), and the banned-word / stale-token greps all pass.After merge, the user-owned steps are: flip code-owner review on the
protect-mainruleset, delete thedevelopbranch, set repo topics and labels, create thev1.0.0milestone.🤖 Generated with Claude Code