> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xdrcheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# xdrlint

> Install xdrlint, run it, read a diagnostic, suppress with a reason and run it in CI.

For teams that write Go ingestion code on go-stellar-sdk. After this page you have installed `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/](https://docs.xdrcheck.dev/reference/lint-rules.md); 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.

```sh theme={null}
go install github.com/OWNER/REPO/lint/cmd/xdrlint@<version>
```

or, from a checkout of this repository:

```sh theme={null}
cd lint && go build -o bin/xdrlint ./cmd/xdrlint    # then use lint/bin/xdrlint
```

### 2. Run

From your module's root:

```sh theme={null}
xdrlint ./...
```

`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

```text theme={null}
internal/store/memo.go:32:19: XDR103 (error): xdr.Memo.GetText() (line 28) carries submitter- or contract-controlled bytes into sql.DB.Exec() without a UTF-8 and NUL check
	fix: check utf8.ValidString and reject or strip NUL before storing as text, or store the bytes as bytea, hex or base64
	docs: lint/docs/XDR103.md
```

* 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://…` (or `XDRLINT_DOCS_BASE`); a base that
  contains `{rule}` is used as a template.

After the diagnostics, `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:

  ```go theme={null}
  //xdrlint:ignore XDR103 the column is bytea; the driver sends the string as bytes
  ```

* for code you cannot edit, in a suppression file named by `.xdrlint.yml` at your module root:

  ```yaml theme={null}
  # .xdrlint.yml
  suppressions: xdrlint-suppressions.yml
  ```

  ```yaml theme={null}
  # xdrlint-suppressions.yml
  - rule: XDR103
    file: internal/store/memo.go
    line: 32
    reason: "the column is bytea; the driver sends the string as bytes"
  ```

A suppression without a reason, one naming an unknown rule, and one that matches nothing are themselves
reported (XDR000), so stale suppressions do not pile up. `.xdrlint.yml` also turns rules on or off, changes
severities and declares your own sinks and sanitisers; see [Configuration](https://docs.xdrcheck.dev/reference/lint-rules.md#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:

```yaml theme={null}
name: xdrlint
on: [push, pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  xdrlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.26"
      - run: go install github.com/OWNER/REPO/lint/cmd/xdrlint@<version>
      - run: xdrlint -sarif xdrlint.sarif ./...
      - if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: xdrlint.sarif
```

Pin `<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](https://docs.xdrcheck.dev/reference/lint-rules.md#running-it).

## Limits

* `xdrlint` reads Go source only, and only code that uses go-stellar-sdk's `xdr` package. 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](https://docs.xdrcheck.dev/guides/go-indexer.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.