xdr, ingest,
processors/token_transfer and strkey packages): what each xdrlint rule reports, how to run the linter, and how
to configure it or accept a report.
Each rule has a page with what it reports, why, a reported and a compliant example taken from the linter’s own
fixtures, and its limits. The guide sections are in guide/indexer-hardening.mdx.
Running it
Building
xdrlint needs Go 1.26 or later; the code it checks may declare an older Go version.
A five-minute walk-through (install, run, read a diagnostic, suppress with a reason, run in CI) is in
lint/README.md.
Output:
Configuration
.xdrlint.yml in the module (or a file named with -config), over a shipped profile named with -profile
(default, wallet-backend, or a path). Keys are flat and lower-case so that golangci-lint can pass them through:
A configured name that does not exist in a loaded package stops the run, so a misspelt sink cannot silently check
nothing.
Configuring and suppressing
Every report can be accepted with a reason:- Inline, on the reported line or on the enclosing function’s doc comment:
//xdrlint:ignore XDR201 linear walk over a tree the decoder bounded. Under golangci-lint,//nolint:xdrlint // <reason>works too (enablenolintlintwithrequire-explanationandrequire-specific). - An external suppression file, for code you cannot edit: a YAML list of entries with
rule,file(module-relative), one or more offunction(ForType.Method),anchor(a substring of the reported line),line(the reported line) andmessage(the report’s message), andreason; optionallyfinding,issue,commit,revieweranddate. Every key given must match. An entry with a function only survives line drift but also accepts any new report of its rule in that function; an anchor or a line narrows it to one site, which is what a list frozen against one commit should use.functionwithmessageis the baseline key that survives code moving within the file: the message is compared without the line numbers it names (line 28,events.go:12), so it names one report without naming a line.
assumption (JSON, SARIF result properties and -report rows), the assumption about
the ledger the reported code makes, as a stable key such as meta-version:v4-only or narrowing:u64->int64.
lint/docs/assumptions.md lists every key with the input that violates it. Suppressed reports are not printed, but -report, -json and -sarif
keep them, marked as suppressed.
Suppression hygiene
XDR000
Suppression without a reason, naming an unknown rule, or suppressing nothing.
What it reports
A suppression that cannot be trusted:
- an inline directive (
//xdrlint:ignore) with no reason, naming an unknown rule, malformed, or naming XDR000; - an entry of an external suppression file with no reason, an unknown rule, none of a function, an anchor and a line, or an unknown key;
- any suppression, inline or external, that suppresses nothing.
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR000 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
Mistake 1: trusting fields stellar-core does not validate
XDR101
Address built from a memo.
What it reports
A value derived from a transaction memo reaches the construction of a muxed address: an
xdr.MuxedAccountMed25519, xdr.MuxedEd25519Account or xdr.MuxedContract literal, strkey.MuxedAccount.SetID,
strkey.MuxedContract.SetID, strkey.Encode with a muxed version byte, xdr.NewMuxedAccount or
xdr.MuxedAccountFromAccountId.
Sources are the memo accessors (xdr.Memo.Id, Text, Hash, RetHash and their Get…/Must… forms,
TransactionEnvelope.Memo(), ingest.LedgerTransaction.Memo()), the token transfer processor’s MuxedInfo
getters, and any value assigned on a path where a type switch chose the text or hash arm of a MuxedInfo.
Why it matters
stellar-core never checks what a memo contains, and since CAP-67 it copies the memo of a classic payment into
the event’s to_muxed_id, which can therefore be a 64-bit ID, a text string or 32 bytes. A text or hash memo is
not a routing ID, and an address built from one names an account that nobody controls. Store a memo-derived ID
as an ID, next to the base account, and never turn it into an M… address.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR101 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR102
Unnormalised address used as an identity key.
What it reports
An address string taken from a value that can be muxed, a signed payload, or a non-account kind is used as a
participant or account key without being reduced to its base account or having its kind checked.
Sources are
(*xdr.MuxedAccount).Address() and GetAddress() (also through TransactionEnvelope.SourceAccount(),
FeeBumpAccount(), Operation.SourceAccount and operation destinations), ingest.LedgerTransaction.AccountMuxed()
and FeeAccountAddress(), xdr.ScAddress.String(), (*xdr.SignerKey).Address() and the keys of
AccountEntry.SignerSummary(). Sinks are participant sets and configured account-key types and functions
(sinksparticipant, sinksaccountkey).
An address can be wrong in two ways, and each is checked on its own: it can be in muxed form (M…, W…), or it
can be of a kind that is not an account (B… claimable balance, L… liquidity pool, P…, T…, X… signers).
The report is silent when the value went through MuxedAccount.ToAccountId(), when a dominating switch or if on
ScAddress.Type handles the muxed kinds and excludes or routes the claimable-balance and liquidity-pool kinds,
when a configured normaliser (sanitizersaddress) produced it, or when the address is the contract of a contract
data entry the host wrote into meta (never a muxed kind). Besides:
- A sink that normalises. An account-key type whose own
Value()decodes the strkey, reduces the muxed account kind and refuses any payload that is not a 32-byte key (asAddressBytea.Value()does) stores a muxed address as its base key; so does a function whose string parameter only becomes such a type (a builder’sWithAccount). Only the non-account kinds are reported there, because that type refuses them with a write error. The property is read from theValue()body, in whichever package declares it. - A re-parse of the same entry. A sink on the passing branch of
sac.ContractBalanceFromContractData(entry, …)(ok only when the balance key’s holder is a contract) is kind-checked, when the address was read from the same ledger entry. - Contract storage. The host refuses to store a claimable-balance, liquidity-pool or muxed address, so an
address read from the key or value of a contract-data entry is a
G…orC…address. This is decided per call of a shared helper:addrString(entry.Key)is exempt,addrString(topics[1])is not. - Where
B…andL…come from. A contract can never store, return or emit a claimable-balance or pool address: the host refuses to convert one to a contract value. Such an address reaches a reader only in events the host emits for the Stellar Asset Contract, or in the envelope (invocation arguments, the authorization tree), which is submitter bytes. The non-account kind is reported only for an address that may have been read from a contract event’s topics or data or from those envelope fields, and not for one decoded on the branch where the event’s name is one the Stellar Asset Contract never emits (case "supply": decode(topics)).
M…
form as identity splits one account into as many accounts as there are IDs, and fixed-width columns truncate
M…, P… and B… strkeys. ScAddress.String() renders every kind SEP-23 defines, including claimable
balances (B…) and liquidity pools (L…), which are not accounts at all.
Example
Reported: the operation source is used as identity in its muxed form.
map[string]interface{} are not followed. Sinks in another module are seen only when configured.
Values decoded from bytes (an RPC response, base64 topics) are not recognised as events or envelope fields, so an
address read from them loses the non-account-kind aspect (a false negative). The event-name exemption trusts that a contract’s event called
supply is not a Stellar Asset Contract event, which holds for every event name the SAC does not use.
Configure and suppress
Turn the rule off by leaving XDR102 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR102 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR103
Unvalidated bytes or string into text storage.
What it reports
Bytes or a string that a submitter or a contract controls reach text storage without UTF-8 and NUL handling.
Sources are
xdr.Memo.Text and its accessors, ingest.LedgerTransaction.Memo(), xdr.ScVal.Str,
ScVal.ExecutableTag, ContractExecutableExternalRef.Tag, ScBytes, ManageDataOp.DataValue,
DataEntry.DataValue and the text arm of a token transfer MuxedInfo. Text sinks are the arguments of
database/sql and pgx Exec, Query and CopyFrom, string struct fields tagged db:"…", proto3 string
fields of the reader’s own message types, and any field named in sinkstext (all errors), and string fields
tagged json:"…" (a warning: encoding/json writes invalid UTF-8 as U+FFFD and NUL as \u0000, so the
stored text silently differs from the bytes on chain, and a PostgreSQL jsonb column rejects the NUL).
Not sources: SetOptionsOp.HomeDomain and ManageDataOp.DataName, which stellar-core validates as printable
ASCII. ScSymbol is restricted by the host.
The report is silent after a dominating utf8.ValidString check together with a NUL check, after
strings.ToValidUTF8 with NUL stripping, after base64 or hex encoding, after conversion to []byte for a bytes
column, or after a configured sanitiser (sanitizerstext). A value that parsed as an integer
(strconv.ParseUint, ParseInt, Atoi with a nil error) or that a dominating comparison or switch fixed to
one of a few clean string literals carries no text either.
Why it matters
A text memo has only an XDR length bound: stellar-core accepts a memo that is not valid UTF-8 and copies it
verbatim into the transaction’s events. An ScString is arbitrary bytes. PostgreSQL rejects invalid UTF-8 and
NUL in text columns, so one such value fails the whole persist transaction; for a reader that commits a ledger
at a time, that stops ingestion.
Example
Reported:
bytea is reported until it is configured or
the value is converted to []byte. SQL built by string concatenation is not followed. Fields are followed one by
one through struct values and through struct pointers passed to or returned from functions of the same package (a
builder’s methods); what a pointer field points to, and a callee’s writes through a pointer, are not. A helper of the
same package called at several sites returns at each site only what that site passed in.
Configure and suppress
Turn the rule off by leaving XDR103 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR103 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR105
Must<Arm>() on a multi-arm union without a dominating discriminant check.
What it reports
Must<Arm>() on a union with more than one arm, at a point not dominated by a check of the same value’s
discriminant (a switch on its type, a comparison, or the ok result of the matching Get<Arm>()).
Why it matters
The Must… accessors panic when the value holds another arm. Which arm a field of a ledger holds is chosen by the
submitter or a contract wherever the protocol allows several, so an unchecked Must… lets a ledger crash the
reader.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR105 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
Mistake 2: no depth or size cap on recursive structures
XDR201
Recursion over a self-referential xdr type with no depth bound.
What it reports
A function or closure that recurses, directly or through other functions of the same package, passing a value of a
self-referential xdr type (after dereference, slice element or range element), with no depth bound. The
self-referential types are computed from the loaded
xdr package: SorobanAuthorizedInvocation,
SorobanDelegateSignature, the ScVal group, ClaimPredicate and the ScSpecTypeDef group at go-stellar-sdk
v0.9.0. The report is an error when a level merges its children’s results (Union, append(x, ys...)), and a
warning otherwise.
A bound is an integer parameter, receiver field or captured variable that every recursive call changes by a
constant and that is compared with a limit before recursing, leading to a return or break; or a configured budget
method (budgetmethods) called and error-checked first.
Why it matters
The host checks only the authorization entries that a require_auth call matched. Unmatched entries, nested trees included, are never examined, and a transaction carrying them succeeds, so the shape of the tree is the submitter’s choice.
A bound silences this rule only. A constant bound on a path fed from ledger meta is then examined by XDR207, which
reports it when it is below what stellar-core admits, and the behaviour past the bound by XDR206. A low fixed cap
is never the quiet option.
Example
Reported:
fmt and Stringer (ScVal.String), or across packages is not seen. Walkers over structures
that stellar-core bounds itself (ClaimPredicate, at most 4 levels) are reported and can be suppressed with that
reason.
Configure and suppress
Turn the rule off by leaving XDR201 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR201 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR202
Iterative walker with an unbounded worklist.
What it reports
A loop that pops values of a self-referential xdr type from a slice and appends their children, with no comparison
of the worklist length or of a counter incremented in the loop against a bound.
Why it matters
Rewriting a recursive walk as a loop with an explicit stack removes the recursion but not the problem: the work
still grows with a tree the submitter shaped (see XDR201). The bound has to be there in either form.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR202 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR203
Decoded integer used as an allocation size or loop bound.
What it reports
An integer read from a decoded xdr value used as an allocation size (
make, strings.Repeat, bytes.Repeat) or a
loop bound with no dominating upper-bound comparison. len of a decoded slice is not reported: the decoder
already materialised it, and go-xdr caps its own pre-allocation and checks lengths against the remaining input.
Why it matters
A u32 in a contract value or an operation is any number the submitter chose. Using it as a size lets one
transaction make the reader allocate gigabytes or spin for billions of iterations.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR203 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR204
Persisted serialisation of a recursive value with no length check.
What it reports
A serialisation of a value of a self-referential xdr type (
MarshalBinary, MarshalBase64, xdr.MarshalBase64,
xdr.MarshalHex, fmt.Sprint…) passed to the database with no check of its length.
Why it matters
Contract values in events and contract data can be large and deeply nested within the network’s limits. Persisting
their serialised form without a size check moves an unbounded value into a column, an index or a message that may
have a limit of its own.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR204 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR205
Decoder with limits disabled.
What it reports
- An error for any use of go-xdr’s
DecodeUnlimitedDepth, or aDecodeOptionsliteral whoseMaxDepthis an unlimited sentinel. - A warning for
xdr.Unmarshalorxdr.UnmarshalWithOptionson a reader without aLen() intmethod (a network body, a decompression stream) whenMaxInputLenis not set.
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR205 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR206
Behaviour at a bound differs from the declared overflow policy.
What it reports
For a walk that has a bound (XDR201 or XDR202 accepted it), the branch taken past the bound does something other
than what the project declared in
overflowpolicy:
- under any policy, it ends the process:
panic,log.Fatal…,os.Exitor a configuredhaltingfuncsentry; - under
halt-ledger, it returns without an error (return nil,continue,break), silently truncating; - under
skip-and-flag, it returns or continues without setting one of the configuredoverflowflags.
halt-ledger:
halt-ledger really stops the ledger, or a caller swallows it, is not decided
locally.
Configure and suppress
Turn the rule off by leaving XDR206 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR206 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR207
Bound below what stellar-core admits, on a path fed from ledger meta.
What it reports
A depth bound that is a compile-time constant, in a walk fed from ledger meta, below what stellar-core admits
for that structure; or, for a structure with no established limit, any such constant (as info). A bound read from
configuration is not examined: the project owns that number.
Floors shipped with the linter (
floors in the configuration overrides or extends them):
Why it matters
“Add a cap” is the first fix a team reaches for, and a cap below what stellar-core admits makes a reader of
consensus meta reject or mangle a valid ledger. A low fixed cap trades an XDR201 report for this one; it is never
the quiet option. Readers of untrusted input before submission (for example
net/http handlers) are not
reported: a tighter cap there is legitimate.
Example
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR207 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
Mistake 3: participants from the envelope instead of the meta
XDR301
Participants harvested from the authorization tree or invocation arguments.
What it reports
A value read from an authorization entry or from invocation arguments reaches a participant sink (or a configured
state-change sink) without corroboration from meta. Sources are the credential addresses of
SorobanAuthorizationEntry, delegate addresses, RootInvocation and SubInvocations, the contract address and
create-contract preimages of a SorobanAuthorizedFunction, InvokeContractArgs.ContractAddress and Args, and
create-contract preimages.
The report is silent when the value is used only as a key into, or compared with, a set built from meta, and the
sink depends on that membership test.
Why it matters
The host authenticates only the authorization entries a require_auth call matched; a successful transaction can
carry any number of others, naming any address. The proof that an address authorised an operation is the nonce
entry the host wrote for it in the meta. A reader that adds every address in the tree lets a submitter write into
anyone’s history.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR301 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR302
Envelope operation fields used as participants without a success gate.
What it reports
An operation source or an account named in an operation body (payment and path-payment destinations,
CreateAccountOp.Destination, claimants, trustors, the clawback source, the sponsored account, revoked
sponsorship owners) reaches a participant sink at a point not dominated by a success check
(LedgerTransaction.Successful(), TransactionResult(Pair).Successful(), or a variable holding one). A helper
that returns such accounts without checking success is silent; its unguarded call sites are reported.
Why it matters
A failed transaction still lands in the ledger and its fee is charged, so the transaction source and the fee
source are always participants. Operation accounts are participants only when the operation was applied: a
failed payment never touched its destination. Adding them anyway lets anyone place entries in another account’s
history for the price of a fee.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR302 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR303
Participant builder that never reads meta.
What it reports
A function that writes a participant sink where neither it, its same-package callees, nor a same-package caller
reads any meta: fee changes, operation changes,
UnsafeMeta, GetChanges and its variants, contract events,
xdr.TransactionMeta…, xdr.LedgerEntryChange… or ingest.Change.
Why it matters
Some participants exist only in the meta: the holder of a trustline the Stellar Asset Contract created, an
account a contract paid, an authorizer recorded by its nonce entry. A participant builder that reads only the
envelope misses all of them. It is a coarse backstop with little noise, since a real indexer reads at least the
fee changes.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR303 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR304
Token-shaped contract event trusted without checking the emitting contract.
What it reports
A value read from the topics or data of a contract event reaches a participant sink, or is parsed into an asset
(an
xdr.Asset, a catalogued asset constructor, a split on ":", a configured sinksmovement call), at a point
not dominated by a comparison of the event’s ContractId with an expected contract ID.
The report is silent after ev.ContractId is compared with a contract ID derived from the asset and the network
passphrase (asset.ContractID(passphrase), the shape go-stellar-sdk’s token transfer processor uses), after a
configured verifier (sanitizersevent), and for a sink keyed by the event’s contract ID: a configured movement
sink that takes it as an argument, or a configured sink (sinksparticipant, sinksmovement) called on a builder
that was given it earlier in the chain, such as b.WithToken(contractID).WithAccount(to), directly or through a
variable or a helper that renders the ID. A record kept explicitly “for contract C” is not a claim
about another contract’s asset.
Why it matters
The host fills an event’s contract ID from the executing contract; the topics and data are whatever that contract
passes (soroban-env-host v30.0.0, src/host.rs and src/events/mod.rs). Anyone can deploy a contract that emits
a four-topic transfer naming a victim account and a real classic asset. A reader that credits the asset or adds
the named account as a participant lets a stranger write into another user’s history.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR304 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
Beyond the three: assumptions about the ledger’s form, ranges and outcomes
XDR401
One meta version assumed: an arm read without a version check, or a version check that halts on the others.
What it reports
Code that assumes one version of a versioned meta union,
xdr.TransactionMeta or xdr.LedgerCloseMeta:
- an arm read with no version check of the same value:
meta.MustV3(),tx.UnsafeMeta.V4.SorobanMeta,lcm.V1, where no enclosing or earlieriforswitchtestsmeta.V,meta.GetV3()or a variable bound to them; - a version check that halts the job on the versions it does not accept:
if meta.V != 4 { return err },if lcm.V != 1 { panic(…) }, or aswitch meta.Vwhose default returns an error or panics, when the accepted versions leave out a version the rule takes as emitted by a current stellar-core (TransactionMeta v2–v4, LedgerCloseMeta v0–v2; see Limits).
switch that handles every version the SDK declares and
stops above them with a typed error is the reviewed-version policy and is not reported. Writes to an arm (a test
helper building meta) are not reads.
Why it matters
Which meta version a reader receives depends on where its ledgers come from, not only on the protocol. The public
data lake serves TransactionMeta v4 for all of history; captive core and older datastores emit v2 for ledgers
before protocol 20 and v3 for protocols 20 to 22, and LedgerCloseMeta v0 before protocol 20. A reader tested on
one source stops on the first ledger from another: export_token_transfer failing with “expected version 4 got
3” is this mistake. A later protocol can add a version too.
Example
Reported:
tx.UnsafeMeta), within one function: a check made by the
caller before it passes the meta on is not seen. An else-if chain (GetV1, then GetV2, then V == 0, else
an error) is not judged. The rule assumes that a current stellar-core emits TransactionMeta v2 to v4 and
LedgerCloseMeta v0 to v2, and treats TransactionMeta v0 and v1 as historical forms: a check that rejects only
them is not reported. That table is an assumption of the rule, not a statement checked against stellar-core. Files of test support code (names
containing test or mock, integration-test and load-test directories) are skipped.
Configure and suppress
Turn the rule off by leaving XDR401 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR401 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR402
Wide integer narrowed without a range check and stored.
What it reports
A conversion that cannot hold every value of a ledger integer, whose result is stored:
uint64(muxed IDs, offer IDs, time bounds, sequence ages:xdr.Uint64,xdr.TimePoint,xdr.Duration) toint64,int, a 32-bit or smaller type, orfloat64;int64toint32or smaller;uint32orint32toint16or smaller;(*big.Int).Int64()orUint64()without a dominatingIsInt64(),IsUint64(),BitLen()orCmp()on the same value (an i128 amount narrowed to 64 bits);strconv.ParseFloatof a token amount read from an SDK field or method (an i128 rounded tofloat64, a warning).
xdr package, an integer field of an SDK struct, or the result of an
SDK function. Stored means written to a struct field, a map, a slice element or an escaping variable, appended,
or passed to a database call or a builder (With…, Set…, Add…), possibly after more arithmetic or a
conversion to text or a nullable wrapper (null.IntFrom). A relational comparison (<, <=, >, >=) of the
value, or of a value it was computed from, with a constant that dominates the conversion counts as a range check;
a nil or equality check does not. Ledger close times stellar-core writes (SeqTime, CloseTime) are not
reported, nor is a minimum sequence age (PreconditionsV2.MinSeqAge, TransactionEnvelope.MinSeqAge()) stored in
a 64-bit type: stellar-core admits a transaction only while that age is at most the ledger’s close time
(txBAD_MIN_SEQ_AGE_OR_GAP), so no value in a ledger reaches 2^63. uint32 to int32 is not reported: ledger sequences and
indexes stay far below 2^31.
Why it matters
The ledger’s integers are wider than many readers’ columns. Muxed IDs reach 2^64−1 on mainnet, SAC balances above
2^63 exist, and a uint64 written to a signed 64-bit warehouse column made a load reject tens of thousands of rows.
A narrowing conversion does not fail: it stores a negative or rounded number that looks real.
Example
Reported:
interface{} (a details map) is not followed. A result returned to the caller and stored
there is not followed. A range check is any dominating comparison with a constant, not one that proves the bound.
Splitting a big integer into 64-bit halves after Rsh or And is not reported.
Configure and suppress
Turn the rule off by leaving XDR402 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR402 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR403
Error or ok result discarded on a value that is then stored.
What it reports
v, _ := f(…), where f returns an error as its last result and is a function of the SDK module (xdr,
strkey, amount, ingest, processors, …), strconv, encoding/hex, encoding/base64, encoding/json,
math/big or time (or is big.Int.SetString, with its ok result), and v is later stored in the same
function: part of a composite literal, assigned to a field, map entry or slice element, appended, or passed to a
database call or a builder. A variable tested in a condition first (if v == "" { … }) counts as checked.
Not reported: strkey.Encode of a 32-byte array (an ID; it cannot fail), and a parse of a string field of an SDK
struct (the SDK formatted it).
Why it matters
A discarded error leaves the zero value in its place: an empty address, amount 0, a zero ID. Stored, it cannot be
told apart from a real value, and nothing records that the row is wrong.
Example
Reported:
ok of an xdr Get<Arm>() accessor is not reported: one wide row per union, with the other arms left
at zero, is a common and deliberate layout (XDR105 covers arm reads that panic). Uses in another function are not
followed.
Configure and suppress
Turn the rule off by leaving XDR403 out of rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR403 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR404
Contract event topics or data trusted by position or kind without a shape or emitter check.
What it reports
A contract event’s topics or data read by position or kind with no shape check and no check of the emitting
contract:
topics[k]with a constantk, with no enclosing or earlier check that mentionslen(topics)(directly, or through a variable set under such a check);v.Must<Arm>()on a topic, the data or a value read from them, with no check ofv.Typeorv.Get<Arm>().
Topics and Data fields of xdr.ContractEventV0 and what is read from them, and
parameters named topics or data of type xdr.ScVal, []xdr.ScVal or xdr.ScVec. A dominating comparison of
the event’s ContractId with something other than nil fixes the shape to that contract’s and silences the
report.
Why it matters
Any contract can emit any number of topics of any type. A reader that indexes topics[2] or calls MustSym()
panics on the first event that does not have the shape it expected; a reader that stops on a panic halts the
whole pipeline on an event anyone can emit.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR404 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR405
Rows from diagnostic events without a success gate, or from transaction-level changes in operation scope.
What it reports
Rows built from meta that does not mean what the row says:
LedgerTransaction.GetDiagnosticEvents(), or aDiagnosticEventsfield of the SDK’s meta and event types, feeding rows with no success check (Successful(),TransactionResultCodeTxSuccess, a variable holding one) in the function or in every same-package caller (an error);LedgerTransaction.GetChanges()or theTxChangesBefore/TxChangesAfterfields read in a function that works on one operation (an integer parameter named like an operation index, or an operation wrapper type) and feeding rows (a warning).
Successful()), and an accessor that copies the events into a DiagnosticEvents field.
Why it matters
A failed Soroban transaction still carries the diagnostic events of the calls that ran before it failed, some with
InSuccessfulContractCall set, but the transaction rolled them back. Rows built from them describe transfers that
never happened. GetChanges() holds the fee, sequence-number and transaction-level changes as well as every
operation’s, so reading it for one operation attributes changes the operation did not make.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR405 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.
XDR406
Closed switch over an xdr enum that writes rows, with no default or a panicking default.
What it reports
A
switch over an enum of the SDK’s xdr package (OperationType, LedgerEntryType, ScValType, …) whose
cases write rows (append, assign to a field or map entry, build a composite literal, call a builder or database
method) and that has no default, or a default that panics or exits. The message lists the values the SDK declares
that the switch does not handle; when it handles all of them, a value a later protocol adds still falls through.
This rule is opt-in.
Why it matters
Protocol upgrades add enum values: operations, entry types, value types, address kinds. A closed switch drops the
new value without a trace, or halts the job on it, on upgrade day. A default that records the unknown value (an
error the operator sees, a counter, a typed skip) turns a silent loss into a decision.
Example
Reported:
rules in .xdrlint.yml or a profile. To accept one report, put //xdrlint:ignore XDR406 <reason> on the reported line or on the enclosing function’s doc comment (under golangci-lint, //nolint:xdrlint // <reason>), or add an entry to an external suppression file for code you cannot edit. A suppression needs a reason, and one that suppresses nothing is itself reported (XDR000). See Configuring and suppressing.