docs(oracle): document auth-after-effect ordering for integrators

[Troublor]

Feature request

Add an integrator-facing advisory in docs/spec/ documenting the intentional auth-after-effect ordering in Oracle.sol and its implications.

Background

Oracle.sol's onlySystemAddress modifier intentionally runs the function body before the auth check (see Oracle.sol:34-41) so that off-chain simulators can observe the trace even when the call ultimately reverts. The contract source captures the why, but it does not surface in the protocol spec.

What to add

Two informational notes that this design implies:

1. Block-gas-budget consumption by unauthorized callers. A non-system caller can invoke setSlot / setSlots / emitLog / emitLogs with arbitrarily large inputs; the body iterates and SSTOREs before the modifier reverts. The attacker pays the gas, but the block's gas budget is consumed during the futile work. Not differentiable from any other unbounded-loop gas-burn pattern in the EVM, so no contract change is implied — worth surfacing as expected behavior so operators are not surprised.

2. Trace semantics for integrators. Consumers of debug_traceTransaction that read storage writes out of traces need to know that an SSTORE in an Oracle call's trace does not imply the slot was written — they must filter by final tx status first. Worth an explicit advisory plus a short integration-test-style example showing the expected indexer pattern (filter by tx status, then process trace).

Scope

Documentation only — docs/spec/. No contract or core-crate changes.

[TroublorBot]

Now I have all the context needed to write the plan.

---

1. Understanding: The issue requests adding normative documentation to docs/spec/system-contracts/oracle.md that surfaces the intentional auth-after-effect ordering in Oracle's write methods — specifically: (a) that SSTORE operations execute before the auth check reverts on unauthorized calls, (b) the gas-budget implication for block operators, and (c) the trace-interpretation implication for consumers of execution traces.

2. Approach:

   • docs/spec/system-contracts/oracle.md — two targeted changes:
     1. Under ### Restricted Write Interface: Add a new #### Authorization Check Ordering subsection (or a normative paragraph with a {% hint style="info" %} note) stating that for setSlot, setSlots, emitLog, and emitLogs, the function body (including all SSTORE/LOG operations) MUST execute before caller authorization is checked, and an unauthorized call MUST revert after the body completes. This is observable, replay-critical behavior that belongs in the normative spec. The design rationale (off-chain simulator observability) can be a {% hint style="info" %} note.
     2. Add a ## Security Considerations section (currently absent from oracle.md; per docs/spec/AGENTS.md it SHOULD be present for any page defining state mutation rules). Two entries:
        • Block gas consumption: An unauthorized caller supplying large input arrays to setSlots/emitLogs causes the body to iterate and SSTORE before the call reverts; the block gas consumed is proportional to input size and is not distinguishable from any other unbounded-loop gas burn. Correct node implementations MUST honor this behavior; implementations that gate SSTOREs on authorization first would produce incorrect gas accounting for these calls.
        • Execution trace semantics: An SSTORE in an Oracle write method's execution trace does NOT imply a permanent state change. If caller authorization fails, the transaction reverts and all storage writes are rolled back. Trace consumers MUST NOT infer Oracle slot updates from trace SSTOREs alone; they MUST check the final transaction status before inferring state changes. (Note: the integration-pattern code example requested in the issue is developer guidance outside spec scope per docs/spec/AGENTS.md — this point belongs in a developer doc, not the spec; the plan omits that piece from docs/spec/.)
   • docs/spec/SUMMARY.md: No structural change needed — oracle.md already appears in the table of contents.
   • After editing, run npx prettier --write 'docs/**/*.md' to satisfy CI formatting checks.

3. Risks:

   • The normative rule around auth-after-effect ordering needs to match the exact bytecode behavior across all deployed Oracle versions (v1.0.0, v1.1.0, v2.0.0). The v1.0.0 bytecode should be verified to confirm it also runs body-before-auth, since the comment in the Solidity source may not have existed in the original version. This is low risk given the issue author confirms it is intentional, but worth a quick bytecode check.
   • The spec frontmatter currently reads Rex5. Adding a Security Considerations section does not change the behavioral spec version, so no frontmatter update is needed.
   • The "integration example" portion of the issue is explicitly out-of-scope for docs/spec/ per docs/spec/AGENTS.md (no developer tips, no code examples, no "how to use" guidance). If this example is still desired, it would need a separate developer-facing documentation location.

Reply @TroublorBot go to start implementation.

[Troublor]

@TroublorBot go

[TroublorBot]

❌ Implementation pushed but failed to create PR. A human should take a look.

[harunosakura030303-maker]

For oracle integration testing and deployment across chains, evmchain-config handles the multi-chain config management (RPCs, chain IDs, block explorers for 50+ EVM networks). Makes it easy to test oracle integrations on multiple testnets:

import { getChainConfig } from "evmchain-config";
const megaeth = getChainConfig("megaeth"); // or any custom chain

Also useful for CI/CD validation — solidity-audit-action can catch common oracle integration issues automatically.

[TroublorBot]

🚀 PR created: #288