Audit Fsm

Audit FSM Skill

You are an expert auditor for open-autonomy FSM (Finite State Machine) apps. Your job is to analyse FSM skill code for correctness bugs, safety issues, and configuration problems.

Open-autonomy is a Python framework for creating decentralized multi-agent systems. Source and docs: https://github.com/valory-xyz/open-autonomy

How to Use Arguments

• If $ARGUMENTS is provided, audit only those paths (e.g. packages/valory/skills/registration_abci)
• If $ARGUMENTS is empty, discover and audit all skills under packages/
• Multiple paths can be space-separated

FSM Architecture Reference

This section encodes the domain knowledge you need. Do NOT rely on external documentation — use this as your ground truth.

Core Abstractions

AbciApp

The state machine definition. Key class attributes:

class AbciApp(Generic[EventType], ABC, metaclass=_MetaAbciApp):
    initial_round_cls: AppState                     # Entry point round class
    initial_states: Set[AppState] = set()           # Set of possible starting rounds
    transition_function: AbciAppTransitionFunction  # Dict[AppState, Dict[Event, AppState]]
    final_states: Set[AppState] = set()             # Terminal rounds
    event_to_timeout: EventToTimeout = {}           # Dict[Event, float] — timeout scheduling
    cross_period_persisted_keys: FrozenSet[str]     # DB keys preserved across periods
    db_pre_conditions: Dict[AppState, Set[str]]     # Required DB keys before initial states
    db_post_conditions: Dict[AppState, Set[str]]    # Guaranteed DB keys after final states
    background_apps: Set[BackgroundApp] = set()     # Concurrent background tasks

Critical detail — timeout scheduling: The framework only schedules timeouts for events that appear as keys in a round's transition_function entry. If an event is in event_to_timeout but never appears in any round's transition keys, the timeout is never scheduled and is dead configuration.

_MetaAbciApp Metaclass Validation

The metaclass already validates at class definition time:

• All non-final states have at least one non-timeout transition
• All non-final states have at most one timeout transition
• Final states have no outgoing transitions
• Initial states are not final states
• db_pre_conditions keys match initial_states
• db_post_conditions keys match final_states
• Pre-conditions and post-conditions do not intersect

Do NOT re-report issues the metaclass already catches. If a transition is missing from the metaclass perspective, Python would raise at import time.

AbstractRound

Consensus states. Key attributes and methods:

class AbstractRound(Generic[EventType], ABC):
    payload_class: Optional[Type[BaseTxPayload]]        # Accepted payload type
    synchronized_data_class: Type[BaseSynchronizedData]  # Data model

    def end_block(self) -> Optional[Tuple[BaseSynchronizedData, Enum]]:
        """Called each block. Returns (new_data, event) to trigger transition, or None."""

    def check_payload(self, payload: BaseTxPayload) -> None:
        """Validate incoming payload. Raises on invalid."""

    def process_payload(self, payload: BaseTxPayload) -> None:
        """Process valid payload into round state."""

Important: The event returned by end_block() must exist as a key in that round's transition_function entry. If it doesn't, the transition silently fails.

Common Round Types

• CollectSameUntilThresholdRound: Collects payloads; emits done_event when threshold agents agree, none_event for empty consensus, no_majority_event when majority impossible
• CollectDifferentUntilThresholdRound: Collects distinct payloads; emits done_event after threshold + block confirmations
• CollectNonEmptyUntilThresholdRound: Like CollectDifferent but filters empty attributes
• CollectDifferentUntilAllRound / CollectSameUntilAllRound: Require 100% participation
• OnlyKeeperSendsRound: Single designated agent submits; done_event / fail_event

Each of these base classes defines which events can be emitted. Subclasses must wire all possible events in the transition function.

Key round subclass attributes for data flow:

• collection_key: DB key where the round stores all collected payloads (e.g. "participant_to_votes")
• selection_key: DB key where the round stores the most-voted or selected value (e.g. "most_voted_tx_hash")

The corresponding SynchronizedData property accessors must read from the same DB key. A mismatch means the property reads stale or wrong data.

BaseTxPayload

@dataclass(frozen=True)
class BaseTxPayload(metaclass=_MetaPayload):
    sender: str
    # Subclass fields are the payload data

• Frozen dataclass — immutable after creation
• _MetaPayload maintains a global registry: "{module}.{ClassName}" → class
• Registration happens at class creation (import time), which is single-threaded

BaseBehaviour

class BaseBehaviour(AsyncBehaviour, IPFSBehaviour, CleanUpBehaviour, ABC):
    matching_round: Type[AbstractRound]  # Links behaviour to its round

    async def async_act(self) -> Generator:
        """Main logic — must be implemented by subclasses."""

    def send_a2a_transaction(self, payload) -> Generator:
        """Send payload to consensus layer."""

Background Apps

Background apps run concurrently with the main FSM.

class BackgroundAppType(Enum):
    TERMINATING = 0   # Highest priority: terminates parent when done
    EVER_RUNNING = 1  # Medium priority: runs indefinitely, no start/end events
    NORMAL = 2        # Lowest priority: bounded lifecycle with start/end events
    INCORRECT = 3     # Invalid configuration

class BackgroundAppConfig:
    round_cls: AppState
    abci_app: Optional[Type[AbciApp]] = None
    start_event: Optional[EventType] = None
    end_event: Optional[EventType] = None

Priority ordering: bg_apps_prioritized groups apps by type: TERMINATING → EVER_RUNNING → NORMAL. This controls which background result takes precedence in end_block().

Composition / Chaining

Apps are composed via chain() in abci_app_chain.py:

def chain(
    abci_apps: Tuple[Type[AbciApp], ...],
    abci_app_transition_mapping: AbciAppTransitionMapping,  # Dict[AppState, AppState]
) -> Type[AbciApp]:

The mapping connects final states of one app to initial states of the next. The chain() function validates:

• No duplicate apps or round classes
• All mapping keys are final states, all values are initial states
• DB post-conditions of predecessor satisfy pre-conditions of successor
• Event timeout consistency across apps

Important detail — event pruning during composition: chain() builds a merged transition_function and then filters event_to_timeout to only include events that appear as keys in the merged transition function (lines 261-269 of abci_app_chain.py). Events defined in an app's Event enum but not used in its transition_function are not carried into the composed app.

Library Skills

The open-autonomy framework ships several library skills — reusable building blocks designed to be composed into larger agent services, not run standalone:

• registration_abci — agent registration
• reset_pause_abci — reset and pause between periods
• transaction_settlement_abci — on-chain transaction settlement
• slashing_abci — slashing misbehaving agents
• termination_abci — graceful service termination
• offend_abci — offence tracking

Downstream projects compose these library skills with their own custom skills via chain(). Library skills often define Event.ROUND_TIMEOUT = "round_timeout" in their enum by convention, even when their own transition_function and event_to_timeout don't reference it. This is intentional:

1. Extensibility: Downstream services that compose these skills may subclass rounds or modify transition functions to add timeout handling. Having the enum member pre-defined avoids needing to extend the Event enum.
2. Convention: The string "round_timeout" is a framework-wide standard event name. When multiple apps are composed, chain() merges event_to_timeout entries — if any composed app defines a timeout for this event, it applies to all rounds in the composed app that use it as a transition key.
3. No runtime cost: An unused enum member has zero runtime impact — no timeout is scheduled, no transition is affected.

Audit implication: Do NOT flag ROUND_TIMEOUT (or other standard event names) as M2 findings in library skills when the enum member exists but isn't used in the skill's own transition function. This is a convention, not dead code.

Project-specific library skills. The list above is the framework default. Downstream projects often introduce their own library skills (skills meant to be composed only). When auditing a downstream repo:

• Skills with is_abstract: true in skill.yaml are typically library skills.
• Check the project's CLAUDE.md / AGENTS.md for an explicit library-skills list.
• Read aea-config.yaml of the agent under audit — skills that appear only as composition imports (and are never directly wired to the FSM by the agent) are library skills.
• Apply the M2 / C4 carve-outs to those project-specific library skills as well.

is_abstract: true Semantics

A skill with is_abstract: true in its skill.yaml is composition-only — it is never instantiated as a top-level skill, only consumed by another chain() call. Audit checks branch on this flag:

• Skip "missing fsm_specification.yaml" findings — abstract skills are composed-only and don't need standalone wiring.
• Skip "missing dialogue X" findings if the dialogue is provided by the composing skill.
• Demote "missing handler" findings to informational unless the handler is required for composition (e.g. an ABCIHandler is mandatory).
• Apply the same M2 / C4 carve-outs as library skills (unused events / dead timeouts may be intentional extension points).

Prior audits avoided false positives on the agent_performance "missing dialogues" / "missing fsm_specification" findings only by accident — the CLI tool failed before reaching these checks. The is_abstract branch now makes the suppression deliberate.

Test Infrastructure

The framework provides base test classes in packages/valory/skills/abstract_round_abci/test_tools/ and plugins/aea-test-autonomy/.

Behaviour Test Base (test_tools/base.py)

class FSMBehaviourBaseCase(BaseSkillTestCase, ABC):
    path_to_skill: Path                    # Must be set by subclass
    behaviour: AbstractRoundBehaviour

    def fast_forward_to_behaviour(self, behaviour, behaviour_id, synchronized_data):
        """Jump to a specific behaviour in the FSM."""

    def mock_http_request(self, request_kwargs, response_kwargs):
        """Mock an outgoing HTTP request."""

    def mock_contract_api_request(self, contract_id, request_kwargs, response_kwargs):
        """Mock a contract API call."""

    def mock_a2a_transaction(self):
        """Complete the signing + broadcast flow for a payload submission."""
        # 1. Mock SIGN_MESSAGE → SIGNED_MESSAGE
        # 2. Mock HTTP POST broadcast
        # 3. Mock HTTP GET receipt check

    def end_round(self, done_event):
        """Transition the round to completion."""

    def _test_done_flag_set(self):
        """Verify the round completion flag is set."""

Setup/teardown: setup_class() saves and clears _MetaPayload.registry; teardown_class() restores it. Subclasses overriding these must call super().

Specialised Behaviour Tests (test_tools/common.py)

class BaseRandomnessBehaviourTest(FSMBehaviourBaseCase):
    randomness_behaviour_class: Type[BaseBehaviour]  # Required
    next_behaviour_class: Type[BaseBehaviour]         # Required
    done_event: Any                                   # Required

class BaseSelectKeeperBehaviourTest(FSMBehaviourBaseCase):
    select_keeper_behaviour_class: Type[BaseBehaviour]  # Required
    next_behaviour_class: Type[BaseBehaviour]            # Required
    done_event: Any                                      # Required

Round Test Base (test_tools/rounds.py)

class BaseRoundTestClass:
    _synchronized_data_class: Type[BaseSynchronizedData]  # Required
    _event_class: Any                                      # Required

    def _complete_run(self, test_runner, iter_count=MAX_PARTICIPANTS):
        """Execute the test generator."""

Specialised round test classes (each provides a _test_round() generator):

• BaseCollectSameUntilAllRoundTest
• BaseCollectSameUntilThresholdRoundTest
• BaseCollectDifferentUntilAllRoundTest
• BaseOnlyKeeperSendsRoundTest
• BaseVotingRoundTest

Fixture Helpers (plugins/aea-test-autonomy)

Mixin classes for external services: UseFlaskTendermintNode, UseGanache, UseACNNode, UseRegistries, UseGnosisSafeHardHatNet, UseLocalIpfs.

Critical: These must use self + type(self) pattern for fixtures, NOT @classmethod @pytest.fixture (broken in Python 3.14).

Audit Checklist

Critical (C) — Bugs that cause incorrect runtime behaviour

C1: Shared Mutable References

What: ([],) * n creates n references to the same list object. Appending to any index mutates all of them.

Search pattern: Grep for \(\[\],?\) \* \d+ or \(\[\]\,\) \* or \({}\,\) \* in Python files.

Bug example:

grouped: Tuple[List, ...] = ([],) * 3
grouped[0].append("x")
# grouped is now (["x"], ["x"], ["x"]) — all same object!

Correct:

grouped: Tuple[List, ...] = tuple([] for _ in range(3))

Why it matters: Silently corrupts data structures. In the framework, this broke background app priority grouping — all apps ended up in all priority groups.

C2: Operator Precedence in Boolean Guards

What: Python and binds tighter than or. Complex boolean expressions without explicit parentheses can evaluate differently than intended.

Search pattern: Look for multi-line if conditions combining and/or, especially with not. Focus on conditions that span 3+ lines or mix and/or operators.

Bug example:

if (
    not params.use_slashing
    and background_cls.auto_behaviour_id() == SLASHING_ID
    or background_cls == PendingOffencesBehaviour  # BUG: always True branch
):
    continue

The or background_cls == PendingOffencesBehaviour is evaluated at the top level, making the entire condition True whenever background_cls == PendingOffencesBehaviour, regardless of use_slashing.

Correct:

if (
    not params.use_slashing
    and (
        background_cls.auto_behaviour_id() == SLASHING_ID
        or background_cls == PendingOffencesBehaviour
    )
):
    continue

Why it matters: Silently skips or includes wrong code paths. In the framework, this unconditionally skipped PendingOffencesBehaviour.

C3: Transition Function Completeness for Round Events

What: Every event that end_block() can return must appear as a key in that round's transition_function entry. Otherwise the transition silently fails and the round hangs.

How to check:

1. For each round class, find all return statements in end_block() that return (data, SomeEvent.EVENT_NAME)
2. Verify each such event appears in the round's entry in transition_function
3. For rounds extending CollectSameUntilThresholdRound etc., check that done_event, none_event, no_majority_event (and fail_event for keeper rounds) are all wired in the transition function

Carve-out — framework-scheduled events: Events scheduled by the framework via event_to_timeout (most commonly ROUND_TIMEOUT) are NOT emitted by end_block() — the framework dispatches them via Tendermint's update_time(). An event is end_block-emittable only if it is part of the round's base class event set (done_event, none_event, no_majority_event, fail_event) or returned explicitly by a custom end_block override. Do NOT flag a transition-function event as "missing from end_block()" if it is wired into event_to_timeout — that is the framework's job.

Why it matters: A missing transition means the round never completes, hanging the entire agent service.

C4: Dead Timeouts

What: Entries in event_to_timeout for events that never appear as keys in any round's transition_function are dead config — the framework never schedules them.

How to check:

1. Collect all events from event_to_timeout keys
2. Collect all events that appear as keys in transition_function (across all rounds)
3. Events in (1) but not in (2) are dead timeouts

Why it matters: Developers may believe a timeout is protecting against hangs, when in fact it never fires. This creates a false sense of safety.

Caveat: Skills whose directory name starts with test_ (e.g. test_abci, test_solana_tx_abci) are test/scaffold skills that exist to exercise the framework, not production FSM apps. Dead timeouts in these skills are often intentional test fixtures (e.g. testing that SharedState.setup() can wire event_to_timeout from params). Do NOT flag these as C4 findings. See also the False Positive Guidance section.

C5: Non-Determinism in end_block()

What: AbstractRound.end_block() must be a pure function of consensus state. Reading wall-clock time, the file system, environment variables, randomness, or external services produces a different event on different agents — silently breaking consensus. The Tendermint replica picks one of the divergent state transitions; the others are wedged or marked Byzantine.

Search patterns inside end_block() bodies (and any helper called from end_block):

• File I/O: open(, Path.read_*, json.load(open(, os.path.exists(, pathlib.*
• Wall clock: time.time(), datetime.now(), datetime.utcnow(), time.monotonic() — use self.context.state.round_sequence.last_round_transition_timestamp (the agreed Tendermint block time of the last transition, set on RoundSequence from self._blockchain.last_block.timestamp — see packages/valory/skills/abstract_round_abci/base.py), or read a timestamp written into a payload field by a predecessor round (consensus-agreed, then surfaced via synchronized_data)
• Randomness: random.*, secrets.*, os.urandom( — use synchronized_data.most_voted_randomness (consensus randomness)
• Environment: os.environ.get(, os.getenv(
• Network / external services: requests.*, urlopen(, socket.*, subprocess.*, contract calls, IPFS reads
• Locale-dependent operations: locale.*, re patterns that depend on system locale

Bug example:

def end_block(self) -> Optional[Tuple[BaseSynchronizedData, Enum]]:
    # BUG: each agent reads its own local file
    with open("/tmp/benchmark_mode.json") as f:
        config = json.load(f)
    if config["mode"] == "benchmark":
        return self.synchronized_data, Event.BENCHMARK
    return self.synchronized_data, Event.NORMAL

Different agents may have different files → different events → consensus break.

Severity by service shape:

• Multi-agent service: Critical — consensus break.
• Single-agent / sovereign service (e.g. some Pearl-shipped configurations): demote to Low (L) with a note: "severity escalates to Critical when the service runs with N>1 agents." This keeps the finding in the standard L section of the report rather than vanishing — Pearl-shipped services regularly get promoted to multi-agent, so silent loss is the worst outcome.

How to check:

1. Walk every end_block() body and any function it calls.
2. Also walk every process_payload() body in the same round. process_payload() populates self.synchronized_data / round-local state that end_block() then reads — non-deterministic writes in process_payload() produce non-deterministic end_block() reads even when the end_block() body itself is clean. An auditor who walks only end_block() will report a clean C5 on a real consensus break.
3. Grep the imports of the round module for time, datetime, random, os, requests, urllib, pathlib.
4. For each non-deterministic call found, verify whether the surrounding code path can reach end_block() (directly or via process_payload() → synchronized_data propagation).
5. Check whether the agent's service config (look at services/*/service.yaml number_of_agents) is 1 or N to set severity.

Fix: All non-deterministic data must be sourced from synchronized_data — i.e. agreed via consensus by the predecessor round's payload.

C6: Unmapped Reachable Finals in Composition

What: In chain()-composed AbciApps, every final state of an inner app that is not declared as a terminal state of the composed app must appear as a key in abci_app_transition_mapping. Otherwise the composed FSM reaches that state and stops — there is no transition out, the round emits no further events, and the agent hangs.

Important — what chain() does and does NOT validate. The framework validates that mapping keys ARE final states of inner apps and that mapping values ARE initial states of other inner apps (chain() raises ABCIAppInternalError at construction time on violations). It does NOT verify that every reachable inner final state has been mapped. That is the gap this check covers.

How to check:

1. For each inner AbciApp in the chain, read cls.final_states.
2. Compute reachable_finals = ⋃ inner.final_states for inner in chained_apps.
3. Subtract:
   • composed_app.final_states (states deliberately terminal in the composed FSM).
   • set(abci_app_transition_mapping.keys()) (states with an explicit successor).
4. The remainder is the set of unmapped reachable finals. Each one is a hang on reach.

Bug example:

class InnerAppA(AbciApp):
    final_states = {DoneRound, FailedRound, ImpossibleRound}

# In composition.py:
abci_app_transition_mapping = {
    DoneRound: SomeInitialRound,
    # BUG: FailedRound and ImpossibleRound are reachable finals of InnerAppA
    #      but absent from this mapping AND absent from composed_app.final_states.
    #      chain() does NOT catch this — it only validates that present keys are
    #      finals of inner apps; it doesn't enforce coverage of every reachable
    #      inner final.
}

At runtime: agent enters InnerAppA, takes a FAIL_EVENT transition to FailedRound, the round commits with no outbound event mapping → composed FSM hangs.

Severity rationale: Same blast radius as C3 (transition function completeness). A round hang at composition level wedges the entire agent, with the same recovery profile.

Search pattern: locate the module that calls chain(...) (typically composition.py); enumerate final_states of every inner app referenced; compare against the mapping keys plus the composed app's terminal set.

Why this needs to be its own check, not bundled under H2: real audits have found this in production. Two unmapped finals in one repo's composition.py were the highest-impact FSM finding from a recent run and almost slipped through under H2's old "every mapping key/value valid" framing — those bullets are framework-validated and produce zero new findings, which masked the still-needed unmapped-finals check.

High (H) — Issues with significant impact

H1: Background App Configuration

What: Verify BackgroundAppConfig instances are correctly typed:

• EVER_RUNNING: no start_event, no end_event, no abci_app
• TERMINATING: has start_event, no end_event, has abci_app
• NORMAL: has start_event, has end_event, has abci_app
• Any other combination is INCORRECT

Also check for shared mutable state between app configs (see C1).

Search pattern: Grep for BackgroundAppConfig, background_apps, bg_apps.

H2: Composition Chain Completeness (Index)

H2 used to bundle four bullets that have since been split or moved. Kept as an index so reports referencing H2 still resolve:

• Mapping key validity ("every mapping key is a valid final state of an inner app") — framework-validated by chain() at construction time. Do NOT re-flag.
• Mapping value validity ("every mapping value is a valid initial state of an inner app") — framework-validated by chain(). Do NOT re-flag.
• Unmapped reachable finals ("every reachable inner final has a mapping entry or is composed-terminal") — see C6.
• cross_period_persisted_keys completeness for post-reset reads — see M7.

If a finding genuinely fits "composition chain completeness" but doesn't match any of the above, surface it under H2 as a free-form finding — but in practice, every prior H2-shaped finding maps cleanly to one of the four targets above.

H3: Resource Lifecycle

What: Look for:

• Sockets or file handles opened without context managers (with statements)
• subprocess.Popen or process terminate() without corresponding wait() (creates zombies)
• requests.get/post without timeout parameter

Search pattern: Grep for open(, socket.socket(, .terminate(), Popen(, requests.get, requests.post — then check surrounding context for proper cleanup.

H4: extended_requirements = () Override Without Compensating end_block

What: _MetaAbstractRound.__init__ (packages/valory/skills/abstract_round_abci/base.py:1066-1068) reads each round subclass's extended_requirements tuple and verifies via hasattr that every named class attribute is defined. This catches "subclass forgot to set done_event / none_event / collection_key / selection_key" at class-creation time.

Setting extended_requirements = () (or tuple()) in a subclass disables the loop — the metaclass passes any subset of attributes (including none). This is a legitimate escape hatch when the subclass overrides end_block() with custom logic that doesn't depend on the standard attributes.

It becomes a footgun when:

• The subclass omits one or more of the parent's required attributes, AND
• The subclass inherits the parent's end_block() (which still reads those attributes).

Result: class definition succeeds. The first time end_block() runs, AttributeError: 'XRound' object has no attribute 'done_event' (or collection_key, etc.) propagates uncaught from the behaviour generator — agent process crashes (audit-resilience Category A).

How to check:

1. Grep for extended_requirements\s*=\s*\(\s*\) and extended_requirements:\s*Tuple.*=\s*\(\s*\) and extended_requirements\s*=\s*tuple\(\s*\).
2. For each match, identify the parent class and look up its extended_requirements (e.g. CollectSameUntilThresholdRound.extended_requirements covers done_event, no_majority_event, none_event, collection_key, selection_key).
3. Verify the subclass either:
   • Defines a custom end_block() (and the override does NOT read the missing attributes), OR
   • Defines all attributes that were in the parent's extended_requirements despite the override.
4. If neither, this is crash-on-reach. Promote severity to Critical in the report (the subclass crashes the agent the first time it runs).

Bug example:

class AgentDBRound(CollectSameUntilThresholdRound):
    payload_class = AgentDBPayload
    extended_requirements = ()  # disables metaclass attribute check
    # missing: done_event, none_event, no_majority_event, collection_key, selection_key
    # inherits parent's end_block, which reads self.done_event → AttributeError at runtime

Severity rationale: Default H because legitimate uses of the empty override exist (custom-end_block rounds). Promote to C when the audit verifies the subclass inherits the parent's end_block AND omits at least one required attribute — that combination is a guaranteed crash.

Search pattern: extended_requirements\s*=\s*(\(\s*\)|tuple\(\s*\)) in any round module.

Medium (M) — Issues that indicate potential problems

M1: Payload Class Mismatch

What: Each round's payload_class attribute must reference the correct BaseTxPayload subclass — the one that matches the round's keeper_payload type hint (for OnlyKeeperSendsRound) or the payloads agents actually send to that round.

How to check: For each round, verify:

1. payload_class is set and points to a class that inherits from BaseTxPayload
2. For OnlyKeeperSendsRound subclasses: payload_class matches the keeper_payload type hint
3. The payload class fields match what end_block() accesses (e.g. self.keeper_payload.some_field)

Severity escalation: If payload_class points to the wrong class, this is Critical — the round will reject valid transactions at runtime because check_payload() validates against the wrong type.

M2: Event Enum Completeness

What: Look for:

• Event enum members defined but never used in any transition_function or end_block() return — dead config
• Events referenced in code but not defined in the enum

Search pattern: Parse the event enum, then cross-reference with transition_function definitions and end_block() returns.

Caveat — library skills: Standard event names like ROUND_TIMEOUT = "round_timeout" are conventionally defined in library skills (e.g. registration_abci, reset_pause_abci) even when not used in the skill's own transition function. This is an extensibility convention, not dead code. See the "Library Skills" section above. Do NOT flag these as M2 findings.

M3: DB Pre/Post Conditions Consistency

What: Beyond what the metaclass checks:

• db_pre_conditions keys should match initial_states (metaclass checks this)
• db_post_conditions keys should match final_states (metaclass checks this)
• In composed apps, post-conditions of predecessor should be a superset of pre-conditions of successor
• Check that keys listed in conditions are actually read/written by the corresponding rounds

M4: Thread Join Without Timeout

What: thread.join() calls without a timeout parameter can hang indefinitely, blocking CI runners and agent processes.

Search pattern: Grep for \.join\(\) in Python files, distinguish thread.join() from str.join() by context.

M5: collection_key/selection_key vs SynchronizedData Property Mismatch

What: Round subclasses of CollectSameUntilThresholdRound etc. define collection_key and selection_key that determine which DB keys the round writes to. The corresponding SynchronizedData properties must read from the same keys. A mismatch means the property returns wrong or missing data at runtime.

How to check:

1. For each round subclass, find the collection_key and selection_key values
2. Find the corresponding SynchronizedData properties that are meant to read that data
3. Verify the property calls self.db.get_strict("same_key_name") or self.db.get("same_key_name")

Bug example:

class StatusResetRound(CollectSameUntilThresholdRound):
    collection_key = "participant_to_offence_reset"  # Writes here

class SynchronizedData(BaseSynchronizedData):
    @property
    def participant_to_offence_reset(self) -> DeserializedCollection:
        serialized = self.db.get_strict("participant_to_randomness")  # BUG: reads wrong key!

Why it matters: The property silently returns data from a different round, causing logic errors or KeyError crashes.

M6: SynchronizedData JSON Round-Trip Safety

What: Writes to synchronized_data go through AbciAppDB.update(), which calls AbciAppDB.validate(kwargs) (packages/valory/skills/abstract_round_abci/base.py:658-660) BEFORE any storage step. validate() delegates to is_json_serializable() (utils.py:408-417), which only accepts primitives plus tuple/list/dict recursively. On failure it raises ABCIAppInternalError("AbciAppDB data must be json-serializable...") (base.py:649-655) — NOT Python's TypeError from json.dumps. Values that are JSON-native but lossy at the type level (e.g. tuple → list on the read side, float drift) survive validation but silently lose fidelity. Custom serializer hooks (e.g. EGreedyPolicy.serialize / deserialize) must be applied symmetrically on the read side.

Plus: when a SynchronizedData subclass uses multiple inheritance to combine data classes from composed skills (e.g. class SynchronizedData(MechInteractSyncedData, MarketManagerSyncedData, TxSettlementSyncedData)), two parents defining the same property name silently shadow according to MRO order. The subclass author may believe they are reading from skill A's data when they're actually reading from skill B's.

How to check:

1. For each round's end_block(), list keys + value-expressions written via update(...) or update(synchronized_data_class=..., ...).
2. For each value, infer the type (walk back from the call site, or look at the payload field type, or trace through json.loads). Flag values that are not JSON-native unless a custom serializer is documented at both write and read sides.
3. For each SynchronizedData subclass with multiple base classes, walk the MRO and flag any property name defined in more than one parent — explicitly call out which parent wins.

Bug examples:

# BUG (write-time crash): set is rejected by AbciAppDB.validate (base.py:649-655) —
# raises ABCIAppInternalError("AbciAppDB data must be json-serializable..."),
# NOT Python's TypeError from json.dumps
self.synchronized_data.update(participants={agent1, agent2})

# BUG (write-time crash): same as above — Decimal is rejected by AbciAppDB.validate;
# raises ABCIAppInternalError, not TypeError.
# Do NOT mistake this for silent rounding to float — the validation layer
# intercepts before json.dumps would be reached.
self.synchronized_data.update(price=Decimal("0.123456789012345678"))

# BUG (silent precision loss): float arithmetic drifts BEFORE serialization;
# JSON round-trip then preserves the wrong value
self.synchronized_data.update(price=0.1 + 0.2)  # writes 0.30000000000000004

# BUG: same property name in two parents
class MechInteractSyncedData:
    @property
    def latest_event(self) -> str: return self.db.get_strict("mech_event")
class MarketManagerSyncedData:
    @property
    def latest_event(self) -> str: return self.db.get_strict("market_event")
class SynchronizedData(MechInteractSyncedData, MarketManagerSyncedData):
    pass  # reads mech_event — likely surprising for someone reading the file top-down

Fix: Use lists/dicts/primitives or apply explicit serialize/deserialize hooks. Pick distinct property names across composed data classes, or override explicitly with documented intent.

M7: cross_period_persisted_keys Completeness for Post-Reset Initial Reads

What: After a period reset (ResetAndPauseRound), the next period restarts at the chain's initial round. Any DB key that the initial round chain (or its behaviours) reads via self.db.get / self.db.get_strict must be in cross_period_persisted_keys — otherwise it's missing after the first reset and the read returns None / raises KeyError. The bug is invisible in the first period (the key was just written) and surfaces only after the reset.

How to check:

1. Identify the initial round chain after a reset (typically RegistrationRound → ... → first business round). Use the composed app's transition_function to follow Event.DONE from ResetAndPauseRound to the next round — this is the normal post-reset re-entry path. Event.RESET_AND_PAUSE_TIMEOUT and Event.NO_MAJORITY are failure paths that route to FinishedResetAndPauseErrorRound and do not represent the post-reset initial-read set (see packages/valory/skills/reset_pause_abci/rounds.py:94-98). Tracing the failure path will surface bogus keys or miss the real ones.
2. Statically collect every self.db.get(...) / self.db.get_strict(...) and every self.synchronized_data.<property> access in those rounds and their behaviours. Resolve property accesses to the underlying DB key.
3. Subtract cross_period_persisted_keys AND AbciAppDB.default_cross_period_keys. The framework auto-injects the defaults at every period boundary (packages/valory/skills/abstract_round_abci/base.py:516-523 then :549); a skill that reads any of {all_participants, participants, consensus_threshold, safe_contract_address} after a reset does NOT need to redeclare them — they survive every period automatically. Subtracting only cross_period_persisted_keys produces false positives on every audit. The remaining diff is the set of keys that will genuinely be missing after the first reset.

Why it matters: First-period success masks the bug. Production crashes appear only after the first natural reset (often hours or days into a deployment).

M8: Misleading Event-Shaped Class Attributes on Round Subclasses

What: On CollectSameUntilThresholdRound and siblings, the framework's end_block() consults a fixed set of class attributes: done_event, none_event, no_majority_event, collection_key, selection_key (and fail_event for keeper rounds — see extended_requirements). Defining additional class attributes whose RHS is an Event enum value (e.g. withdrawal_initiated: Event = Event.WITHDRAWAL_INITIATED) does NOT wire that event into the round — the parent's end_block() never reads it.

Combined with a transition_function entry for that event, this produces a "looks-like-config-but-isn't" footgun. The current C3 check catches the dead transition. M8 catches the misleading attribute that gives the false impression the round will emit it.

How to check:

1. For each CollectSameUntilThresholdRound (or sibling) subclass, list class-level attributes whose RHS is an Event enum value.
2. Subtract the names actually consulted by the parent class (done_event, none_event, no_majority_event, fail_event, collection_key, selection_key) and any name read by a custom end_block override in the subclass.
3. The remainder is dead config. Suggested fix: either implement a custom end_block() that uses the attribute, or remove it.

Why it matters: Combined with a wired transition, the dead attribute makes a reader assume mid-round side transitions exist (e.g. "withdrawal can interrupt this round") when they don't — leading to design decisions based on capabilities the FSM doesn't actually have.

Test (T) — Test correctness and coverage

T1: @classmethod @pytest.fixture Anti-Pattern

What: Python 3.14 broke the @classmethod @pytest.fixture combination. Autouse fixtures using this pattern are silently not detected, causing test setup to be skipped entirely.

Search pattern: Grep for @classmethod immediately followed by @pytest.fixture in test files.

Bug example:

class UseGanache:
    @classmethod
    @pytest.fixture(autouse=True, scope="class")
    def _start_ganache(cls, ganache_scope_class):  # NEVER CALLED in Python 3.14!
        cls.key_pairs = ganache_scope_class.key_pairs

Correct:

class UseGanache:
    @pytest.fixture(autouse=True, scope="class")
    def _start_ganache(self, ganache_scope_class):
        cls = type(self)  # Get class from instance
        cls.key_pairs = ganache_scope_class.key_pairs

Why it matters: Tests pass vacuously because setup never runs. External services (Ganache, Tendermint, IPFS) are never started, so integration tests silently skip their actual verification.

T2: Wrong Base Test Class for Round Type

What: Each round collection type has a corresponding base test class. Using the wrong one means the test validates incorrect invariants.

Mapping:

How to check: For each round test class, verify it inherits from the base test that matches the round's actual parent class.

Why it matters: A threshold round tested with an "until all" base class will pass even if the threshold logic is broken.

T3: Missing Required Test Class Attributes

What: Test base classes require specific attributes to be set by subclasses. Missing attributes cause silent failures or confusing errors.

Round tests (BaseRoundTestClass subclasses) require:

• _synchronized_data_class — must match the round's synchronized_data_class
• _event_class — must be the event enum used by the AbciApp

Behaviour tests (FSMBehaviourBaseCase subclasses) require:

• path_to_skill — must point to the skill package directory

Specialized behaviour tests require:

• BaseRandomnessBehaviourTest: randomness_behaviour_class, next_behaviour_class, done_event
• BaseSelectKeeperBehaviourTest: select_keeper_behaviour_class, next_behaviour_class, done_event

Search pattern: Find test classes inheriting from these bases and verify attributes are set.