xdrlint, run it on
your module, read and acted on a diagnostic, and wired it into CI.
xdrlint is a Go linter for code that reads Stellar ledgers with go-stellar-sdk (xdr, ingest,
processors/token_transfer, strkey). It reports four kinds of ingestion mistakes: trusting fields
stellar-core never validated (XDR1xx), walking self-referential structures with no depth or size bound
(XDR2xx), taking participants from the envelope instead of the meta (XDR3xx), and assuming the ledger’s form,
ranges or outcome (XDR4xx: one meta version, integers that fit, errors that never happen, event shapes, rows
from failed transactions). Every rule has a page in docs/; every diagnostic names the
assumption it found, listed with the input that breaks it in docs/assumptions.md (lint/docs/assumptions.md).
Lint your indexer
1. Install
Building needs Go 1.26 or later; the code you check may use an older Go version.2. Run
From your module’s root:xdrlint needs at least one package that imports go-stellar-sdk’s xdr package; with none it stops with exit 2
rather than report a clean run. The exit status is 0 when nothing at or above -fail-on (default error) is left,
1 when something is, and 2 on a usage, configuration or package-loading error.
3. Read a diagnostic
- The first line is where the problem is, the rule, its severity, and what flows where. A position in another
file of the same package is written as
file.go:N. fix:is the usual fix, in one line.docs:is the rule’s page: what it reports, why it matters, a reported and a compliant example, and its limits. Point the links at a published copy with-docs-base https://…(orXDRLINT_DOCS_BASE); a base that contains{rule}is used as a template.
xdrlint prints on stderr how many problems it found, whether the run fails, and how to
accept a report. -json and -sarif FILE give the same diagnostics, with fix and docs in the JSON.
4. Fix it, or accept it with a reason
Fix the code where you can. If you checked a report and the code is right (the value was validated somewhere the linter cannot see, or the behaviour is intended), accept it and say why:-
inline, on the reported line or on the enclosing function’s doc comment:
-
for code you cannot edit, in a suppression file named by
.xdrlint.ymlat your module root:
.xdrlint.yml also turns rules on or off, changes
severities and declares your own sinks and sanitisers; see Configuration. If a
report is wrong (the linter misread the code), that is a linter bug: report it with the smallest code that shows
it rather than suppress it silently.
5. Run it in CI
GitHub Actions, failing the job on errors and uploading the results to code scanning:<version> to a release so that a new rule does not fail your build unannounced. To fail on warnings too,
add -fail-on warning. xdrlint also runs as a go vet tool and as a golangci-lint module plugin; see
Running it.
Limits
xdrlintreads Go source only, and only code that uses go-stellar-sdk’sxdrpackage. Code that decodes XDR another way is not checked.- It follows values within a package. A value checked in another package, or through an interface it cannot resolve, can be reported although it is safe: accept it with a reason. Each rule’s page lists its own limits.
- A clean run is not proof of correct ingestion. Replay the corpus through the indexer as well (go/adapters/minimal).