Gaugedocs
Functional alpha v0.1.0-dev GitHub

Rule catalog

Sixteen checks. Seven shipped.

Every rule has a stable kebab-case ID, a written condition and a severity. A finding names the rule, the account, an evidence line and a fingerprint that identifies it. An accepted risk matches on rule and account, not on the fingerprint.

7 live 9 specified Baseline severities until 3.4

The catalog

FamilyRuleFires whenSeverityStatus
Account acct-missing The endpoint answers 404: the account was never created or was merged. HIGH Live
Account acct-network-mismatch The endpoint's passphrase differs from the requested network. HIGH Live
Signers sig-no-signing-weight No signer has weight above zero, so the account can never sign again. HIGH Specified
Signers sig-threshold-unreachable Total signer weight is below a threshold, so that tier can never authorize. HIGH Specified
Signers sig-threshold-order Thresholds do not satisfy low <= medium <= high. WARN Specified
Signers sig-single-key-high One signer alone reaches the high threshold. By role Specified
Signers sig-hashx A hash(x) signer exists; HIGH if it alone reaches medium. WARN or HIGH Specified
Signers sig-unexpected-signer A signer is not in expected_signers, only when the list is declared. By role Specified
Signers sig-missing-expected A declared signer is absent from the chain. HIGH Specified
Signers sig-weight-drift A declared signer's weight differs from the chain. By role Specified
Thresholds thr-drift Declared thresholds differ from the chain. By role Specified
Flags flag-drift A declared flag differs from the chain. WARN* Live
Flags flag-undeclared-clawback Clawback is enabled and the policy declares no clawback value. WARN* Live
Identity id-no-home-domain The policy declares a home domain and the chain shows none. WARN Live
Identity id-toml-unreachable stellar.toml cannot be fetched or parsed under the guard, or an observed home domain was never fetched. WARN Live
Identity id-toml-account-unlisted The account is not listed in its home domain's stellar.toml. WARN Live

* The two live flag rules use WARN for every role today. The specified catalog makes flag drift HIGH for an issuer and clawback WARN, raised to HIGH for an issuer. Role overrides are task 3.4.

The seven live rules

These are registered in internal/rules, covered by positive and negative fixture cases, and exercised end to end by the CLI tests.

acct-missing

HIGH Live

A requested account returned 404. The endpoint answered, so this is a statement about the account, not about the network. The account may never have been created, or it may have been merged into another account. The run continues and reports the other accounts.

Evidence
endpoint URL returned not found
Acceptable
No. An acceptance cannot hide a missing account.
Exit effect
HIGH fails the default --fail-on high and produces exit 1.

acct-network-mismatch

HIGH Live

The endpoint's network passphrase differs from the network the run requested. No account is fetched from that endpoint at all, because an account ID can exist on more than one network and the report would describe the wrong chain. Each requested account is listed as skipped with this finding.

Evidence
expected Test SDF Network ; September 2015, endpoint reports Public Global Stellar Network ; September 2015
Acceptable
No.
Exit effect
HIGH fails the default threshold and produces exit 1. The run did not read an account, but it did complete and name the disagreement.

flag-drift

WARN Live

A flag the policy declares disagrees with the chain. Only declared flags are compared, so an omitted flag can never drift. The comparison runs in a fixed order: auth_required, auth_revocable, auth_immutable, clawback. The evidence lists each disagreement.

Example
auth_required declared false, observed true
Acceptable
Yes, with a reason and an optional expiry. The owner adds accept entries.
Exit effect
WARN is below the default --fail-on high. It produces exit 1 only under --fail-on warn.

flag-undeclared-clawback

WARN Live

Clawback is enabled and the policy says nothing about clawback. A declared value, true or false, suppresses this rule: declared true is a declaration, and declared false that disagrees with the chain is flag-drift instead.

Evidence
clawback observed true, and no clawback expectation is declared
Acceptable
Yes, with a reason and an optional expiry.
Exit effect
WARN. Exit 1 only under --fail-on warn.

id-no-home-domain

WARN Live

The policy declares a home_domain and the account publishes none on chain. The trigger is the declaration, not the role: the role table that would decide which accounts are expected to publish one is task 3.4, and rules may not hardcode a role set. A check run declares nothing, so it cannot raise this rule.

Evidence
home_domain declared "example.org", observed none
Acceptable
Yes, with a reason and an optional expiry.
Exit effect
WARN. Exit 1 only under --fail-on warn.

id-toml-unreachable

WARN Live

The account publishes a home domain and its stellar.toml could not be fetched or parsed under the guard. It fires the same way when a domain was observed and never fetched at all: an identity Gauge could not verify is a warning, never a pass. The evidence names the step that failed, so a domain that resolves to a blocked address is distinguishable from one that serves an oversized or unreadable document. Nothing from the document is quoted; the detail phrase is one this repository wrote. A fetcher that cannot be built at all is a run that did not complete: exit 3, no report.

Evidence
step guard; detail the host name resolves to a private address, which Gauge will not dial; status 0
Acceptable
Yes, with a reason and an optional expiry.
Exit effect
WARN. Exit 1 only under --fail-on warn.

id-toml-account-unlisted

WARN Live

A readable stellar.toml does not name this account in ACCOUNTS. The rule only speaks about a document it could read, so an unreachable domain raises one finding rather than two. Entries that are not account addresses are counted and never echoed, which keeps a malformed or hostile list out of the report. The document's NETWORK_PASSPHRASE is carried in the result but compared by no rule today.

Evidence
home domain example.org lists 2 accounts; this account is not among them
Acceptable
Yes, with a reason and an optional expiry.
Exit effect
WARN. Exit 1 only under --fail-on warn.

What is not shipped

The nine specified rules are a contract for the next phases, not behavior you can rely on today. The signer and threshold rules wait on threshold semantics that task 0.7 could not verify without submitting a transaction, which Gauge forbids itself to do. Role-based severities are task 3.4.

Read the status before trusting a pass. A run evaluates the seven rules above. A clean result means those seven agreed with your policy; it says nothing about signers, thresholds or any rule marked Specified.

Current implementation status · How to declare expectations