Web3, smart contracts and blockchain protocols

Open canonical module and reverse references

1. 01Write business invariant
2. 02Capture normal transitions
3. 03Change ordering or replay
4. 04Compare serial control
5. 05Try bounded lab concurrency
6. 06Verify committed state

At each step: retain the control → record the observation → continue only while the next boundary is understood.

Setup and invariant

Choose one reversible workflow in a local or nonfinancial sandbox: accepting an invitation, creating one test resource, applying a test credit, approving a draft, or consuming a one-time action. Write the exact invariant, for example: one invitation grants at most one membership, to its intended recipient and role. Record preconditions, state transitions, actor permissions, durable result, retries, and cleanup. Logic findings depend on intended rules, not whether the request is technically valid. Business logic.

Numbered test procedure

1. Draw the normal transition table. List draft → submitted → approved → completed, or the product's actual equivalent. For each edge, record actor, required prior state, immutable fields, and transaction identifier. Perform one normal run with synthetic objects and save before/after state, not just HTTP responses.
2. Test skipped and reordered transitions. On a fresh disposable object, attempt the observed completion request before approval. Then change only a value that should be frozen after approval, such as recipient or test quantity. Compare with a fully approved control and an invalid object ID. If a transition is intentionally optional, adjust the invariant rather than treating missing UI steps as a bug.
3. Test serial replay. Repeat the same completed operation once after it settles. For documented idempotency keys, compare the same key/same body with the same key/different body, using sandbox data. Determine whether keys are scoped by actor, tenant, endpoint, and expiry. Returning the first result again can be correct idempotent behavior.
4. Test boundary values selectively. Use zero, a single negative value, or a precision boundary only where the sandbox permits it. Record server-calculated totals and immutable values. Avoid real billing, inventory, refunds, transfers, or customer notifications. A strange displayed number without a committed consequence is not enough.
5. Test concurrency only in an authorized setting. First demonstrate expected serial behavior. Reset a test object, then send exactly two simultaneous requests as a small experiment. The local example below uses a barrier; it does not guarantee server arrival within the vulnerable interval. If there is no overlap, record inconclusive timing rather than absence of a race. More aggressive synchronization belongs in the isolated lab. Race conditions.
6. Inspect after completion. Wait for both requests and relevant workers. Count durable memberships/resources or inspect the ledger of synthetic events. Two success responses may correspond to one commit. Repeat only to resolve a specific uncertainty, then restore the object and stop at the first demonstrated invariant failure.

Command card

This sends exactly two requests to a disposable local invitation endpoint. Put a valid local test bearer token in A.token, with restrictive permissions, and replace the route with the observed one. Create a fresh invitation for each serial/concurrent comparison. Run against localhost only.

from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from threading import Barrier
from urllib.request import Request, build_opener, ProxyHandler, HTTPRedirectHandler
from urllib.error import HTTPError

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

gate = Barrier(2)
token = Path('A.token').read_text().strip()
def attempt(index):
    req = Request('http://127.0.0.1:8000/api/invitations/TEST-INVITE/accept',
                  data=b'{}', method='POST',
                  headers={'Authorization': 'Bearer ' + token,
                           'Content-Type': 'application/json'})
    gate.wait()
    try:
        with build_opener(ProxyHandler({}), NoRedirect()).open(req, timeout=10) as response:
            return index, response.status, response.read(1024).decode(errors='replace')
    except HTTPError as error:
        return index, error.code, error.read(1024).decode(errors='replace')

with ThreadPoolExecutor(max_workers=2) as pool:
    print(list(pool.map(attempt, range(2))))

Report threshold and checklist

Report a durable violation of the stated rule, with serial controls, initial conditions, minimal request sequence, and final state. Duplicate responses, transient UI counters, expected retries, and intentionally cumulative operations are common false positives. Describe the demonstrated consequence; do not infer financial loss from a sandbox counter alone.

• Business rule and expected actor written down.
• Normal and serial-replay controls completed.
• Fresh fixture used for each experiment.
• Only bounded authorized concurrency used.
• Durable state and asynchronous effects verified.

The Python example disables environment proxies and redirect following. A redirect is captured by the HTTPError branch; inspect its destination before any separate request.

Events that arrive after the request

Apply the same invariant to workers and integration events, not only the HTTP endpoint. Record a deduplication key's scope and when it becomes durable relative to the protected effect. A claim written before a worker fails can lose work; a claim written after the effect can permit duplicates. Use an instrumented fault point in the replica to distinguish these cases, and inspect committed state after retry. Then run the webhook event integrity procedure for signature, event ownership and out-of-order delivery checks. Do not assume provider delivery time is a reliable object version or that an HTTP acknowledgement proves processing completed.

Open canonical module and reverse references

1. 01Resolve implementation
2. 02Write unit-aware invariants
3. 03Build actor baseline
4. 04Exercise sequences
5. 05Minimize state trace

At each step: retain the control → record the observation → continue only while the next boundary is understood.

Setup and security invariant#

Prepare a reviewed local checkout with dependencies and compiler already available. Use a private local EVM test harness; keep wallet secrets absent and review configuration for FFI, RPC endpoints and fork creation before execution. Record commit, compiler settings, proxy family, implementation, initialized roles and supported token behavior. A local reproduction against a simplified model explains an idea; an eligible report must establish that the same path exists in the relevant deployed implementation.

Write properties using explicit units: assets, shares, debt, fees and time. For example, redeeming a claim cannot pay more assets than its defined entitlement, and an ordinary actor cannot change the implementation or initialize an already initialized proxy. Do not equate token balance and share supply. Reuse the authorization matrix for actors and protected transitions. OpenZeppelin documents proxy-specific initialization and upgrade behavior, so inspect the actual family and version. OpenZeppelin proxies

Controlled procedure#

1. Build realistic actors. Separate setup administrator, ordinary depositor A, depositor B and callback receiver. Setup may allocate synthetic tokens, but record each privilege and stop using administrator impersonation before the candidate sequence. Verify a normal deposit/redemption round trip and expected privileged-operation rejection.
2. Trace callbacks. Mark every external call and the state visible at that instant. Give an owned callback contract one bounded reentry attempt into the original or a related function. Compare with a receiver that accepts the callback without reentry. Solidity warns that reentrancy concerns external contract calls and interacting contracts, not only Ether transfers. Solidity security considerations
3. Track independent accounting. Record user assets, shares, protocol holdings, debts and fees before and after every action. Calculate the expected relationship independently of the implementation under test. For rounding, test zero supply, minimal amounts, mixed decimals, partial redemption and a direct donation, using only supported tokens. Quantify attacker cost as well as victim loss. ERC-4626 conversions and donations can expose rounding-sensitive states. OpenZeppelin ERC-4626
4. Exercise ordering. Try short valid sequences: deposit → transfer shares → redeem; deposit → donate → second deposit; callback → related read/write; initialize → initialize again. Change one amount, role or order at a time. Count successful state-changing calls so an all-revert fuzz run cannot be mistaken for coverage.
5. Minimize the failure. Reduce the sequence and amounts while preserving the violated property. Run the identical sequence with the benign callback or corrected authorization as a control. Preserve the earliest inconsistent state as well as the final balance difference.

Harness and command cheat sheet#

Create target-specific test functions; the names below are a suggested harness contract, not built-in Foundry scans.

git rev-parse HEAD
forge --version
rg -n 'ffi|rpc_endpoints|createFork|createSelectFork' foundry.toml test
forge test --match-test '^test_BaselineRoundTrip$' -vvvv
forge test --match-test '^test_CallbackInvariant$' -vvvv
forge test --match-test '^test_MinimizedSequence$' -vvvv

Run only after the named local tests exist and their setup has been reviewed. --match-test selects your tests; verbosity exposes local traces. These commands do not broadcast transactions, but test code can explicitly access external resources, which is why harness review matters. Foundry test reference

Evidence, false positives and completion#

Provide the implementation identity, exact harness, trace, initial capital, privileges, unit-aware balance sheet and bounded impact. Exclude unsupported malicious-token assumptions, fabricated oracle authority, admin-only behavior working as designed, and a callback that cannot occur in the real path.

• Baseline exercises the same implementation and setup.
• Actor powers match the claimed attack model.
• Successful transitions and reverts are counted.
• Loss is demonstrated independently of total value locked.
• Reproduction stays entirely in the local EVM.

Open canonical module and reverse references

1. 01Record trust contract
2. 02Prove valid baseline
3. 03Vary one binding
4. 04Vary feed metadata
5. 05Calculate consequence

At each step: retain the control → record the observation → continue only while the next boundary is understood.

Setup and invariants#

Create two locally deployed verifier instances, a local-only signer, two ordinary actors and a mock feed whose state you can vary. Write the expected signed action as a tuple: signer, action type, recipient, amount, nonce, deadline, chain and verifying contract. Record which fields the application intentionally binds. The invariant is: a signed instruction permits only its intended action and replay policy. EIP-712 defines typed hashing and domain separation; replay protection remains the application's responsibility. EIP-712

For price consumers, record base/quote currency, feed decimals, token decimals, supported price range, freshness policy and dependency-failure behavior. The invariant is: an accepted observation has the meaning and validity required for the resulting economic decision. Chainlink exposes round metadata and timestamps; consumers must interpret them in their own integration. Chainlink data-feed API

Controlled procedure#

1. Prove both baselines. A valid local signature executes its harmless ledger action once. A fresh positive-price feed produces the expected collateral or quote calculation. Verify an invalid signature and an explicitly disallowed stale observation are rejected, where that policy is part of the product's contract.
2. Vary one signature dimension. After the valid action, replay exactly the same bytes. Then use fresh baselines to vary only the recipient, amount, action type, verifier instance, chain context or expired timestamp. Record the recovered signer and nonce-consumption point. A reverting transaction normally rolls back its state; prove whether the replay state survives a successful action rather than assuming a pre-revert write consumed the nonce.
3. Check alternate signer paths. If contract wallets are supported, compare an owned wallet returning the ERC-1271 success value 0x1626ba7e, a wallet returning a different value, and a reverting wallet. A non-reverting call alone does not establish a valid signature. ERC-1271 validity can depend on current contract state: change the authorized local signer after a valid baseline and repeat only where the consumer promises current authorization. Record validation at execution versus an intentionally earlier irrevocable authorization. Do not classify unsupported signature formats as a vulnerability. Reuse identity and session binding for off-chain issuance. ERC-1271.
4. Vary feed metadata. Starting from a valid response, test an old timestamp, zero or negative answer where the feed type can produce it, changed decimals, failed feed call and mismatched quote currency. Keep all other fields realistic. Demonstrate the consumer's accepted result and economic effect; an artificial impossible feed response is a robustness result until reachable conditions are shown.
5. Test L2 recovery if applicable. Model sequencer down, just restarted and beyond the configured grace period separately. This is integration-specific: not every chain or feed uses identical checks. Chainlink's L2 guidance explains uptime signals and post-recovery grace periods. L2 sequencer feeds
6. Calculate the consequence. Compare collateral, debt, quote or liquidation outcome with an independently calculated expectation. Include price units, rounding, capital, timing, fees and user constraints. A missing named check without a reachable incorrect decision remains a review lead.

Local cheat sheet and case matrix#

Implement these names in your reviewed local Foundry harness; they are not scanner features. The signer key must be generated or hard-coded solely for this disposable local fixture.

rg -n 'ecrecover|nonces|deadline|DOMAIN_SEPARATOR|latestRoundData|decimals' src
forge test --match-test '^test_ValidSignature$' -vvvv
forge test --match-test '^test_ReplayRejected$' -vvvv
forge test --match-test '^test_WrongDomainRejected$' -vvvv
forge test --match-test '^test_StaleFeedRejected$' -vvvv
forge test --match-test '^test_PriceUnitInvariant$' -vvvv

--match-test selects target-specific tests and trace verbosity helps identify the accepted transition. Use preinstalled compiler/dependencies and no RPC/fork/FFI setup for these local fixtures. Foundry test reference

Evidence and checklist#

• Exact message schema, domain and successful baseline are saved.
• Only one context field changes in each negative case.
• Mock feed deviations are separated from reachable attacker powers.
• Nonces, timestamps, units and downstream decisions appear in evidence.
• No real signatures, transactions or funds are used.