# Web3, smart contracts and blockchain protocols

Treat this branch as an audit of **deployed state, economic rules and trust assumptions**. Solidity source is only part of the target. A valid finding connects an attacker action to an eligible impact on the correct deployment; an interesting flaw in a repository does not establish that connection.

## Roadmap and entry criteria

| Stage | Work product | Exit criterion |
|---|---|---|
| Execution semantics | Local examples covering storage, calls, delegate calls, revert behavior, token hooks and signing | Explain which address owns state and which actor has authority at every call boundary |
| Protocol accounting | A balance-sheet model for one vault, lending market or exchange | Derive asset, liability, share and fee relationships with explicit units and rounding |
| Stateful research | Deterministic reproductions and a handler-based invariant suite | Reach meaningful sequences of operations without granting unrealistic powers |
| Bounty investigation | Deployment manifest, hypotheses, minimal fork PoC and impact calculation | Reproduce against the eligible version and satisfy the program’s reporting requirements |

This is a suggested competency sequence, not a promise that a particular number of weeks produces paid findings. Start with a compact protocol whose accounting you can explain completely before adding cross-chain messaging or consensus machinery.

## Scope and environment gate

Save the program page, excluded impacts, known issues, audit exclusions and PoC requirements. Record chain name **and chain ID**; proxy address; implementation, beacon or facet addresses where applicable; deployment transaction; repository commit; compiler and optimizer settings; dependencies; fork block number and block hash; roles; external oracle and token addresses. Distinguish currently deployed contracts from proposed upgrades, deprecated deployments and test fixtures. OpenZeppelin documents materially different proxy families and initialization requirements, so resolve the actual architecture instead of assuming every address is a simple implementation. [Proxy documentation](https://docs.openzeppelin.com/contracts/5.x/api/proxy)

Check whether eligibility follows explicit asset/file rules or **primacy of impact**. On Immunefi, some programs allow eligible impacts on project-owned assets beyond the explicit list; that does not make all related organizations, test files or impacts eligible. Apply the exact program’s categories and limitations. [Example program explanation](https://immunefi.com/bug-bounty/immunefi/information/)

**Immunefi currently prohibits testing on mainnet and public testnet contracts.** Use a local fork; do not deploy an exploit or submit transactions to a live network. Its rules also prohibit unauthorized rescue of funds, incomplete required PoCs, and misleading asset or severity claims. A public testnet is therefore not a default alternative. For other programs, use a private development network or the expressly authorized environment. [Immunefi rules](https://immunefi.com/rules/)

Forking reads chain state through an RPC provider but executes the test locally. Keep production signing keys out of the research environment. Separate the read-only upstream RPC configuration from local transaction tooling. An ordinary RPC account and its quotas remain a separate service dependency. Pinning a block makes the result reproducible and prevents a moving head from silently changing the experiment. [Foundry fork testing](https://www.getfoundry.sh/guides/fork-testing)

## Operational playbook

**1. Reconstruct the economic model.** Write down who contributes value, who can withdraw it, who bears losses, and who changes parameters. Follow deposits through shares, debt, collateral, interest, rewards, liquidation and settlement. Mark units on every variable: raw token units, decimals, normalized values, seconds, basis points and shares. Build two ordinary users, a permissionless attacker and the actual administrative roles in the local model. Keep privileged setup separate from attacker actions.

**2. Identify invariants before choosing tools.** Examples are: one claim cannot settle twice; unauthorized users cannot change ownership; liabilities remain covered under documented assumptions; withdrawals burn the correct claim; an operation cannot create value merely through rounding; and a completed cross-chain transfer cannot execute again. These are candidate properties requiring adaptation, not universal formulas. For example, comparing vault assets directly to share supply is invalid when their units or exchange rate differ.

**3. Trace trust transitions.** Review user-to-router, router-to-pool, callback-to-caller, implementation-to-proxy, oracle-to-consumer and message-to-executor boundaries. Reentrancy can involve another function or another contract, rather than only recursion into one withdrawal. Establish what state is observable during external calls and whether a downstream component trusts an inconsistent intermediate value. [Solidity security considerations](https://docs.soliditylang.org/en/latest/security-considerations.html)

**4. Use static findings as hypotheses.** Build with the project’s compatible toolchain and inspect Slither output alongside inheritance, call relationships and deployment configuration. A detector match is not proof of reachable loss. Do not discard a dependency finding solely because it originates under `lib/`; first determine whether the affected behavior reaches an eligible asset. Conversely, a clean static scan does not validate the economics. [Slither usage](https://github.com/crytic/slither/wiki/Usage)

**5. Exercise sequences and adversarial actors locally.** Handlers should prepare valid balances, approvals and positions, then vary operation order and amounts. Inspect successful call counts and discarded inputs: an invariant suite that repeatedly reverts before changing state provides weak evidence. Keep a seed or minimized sequence, configuration and fork snapshot. Use ghost accounting independent of the implementation being tested. [Foundry invariant testing](https://getfoundry.sh/forge/invariant-testing?highlight=invariant)

**6. Minimize the proof and calculate bounded impact.** Show initial state, necessary preconditions, attacker actions, resulting victim/protocol loss and the failed property. Disclose flash liquidity, fees, slippage, collateral, timing and privileges. Do not claim total value locked as loss unless the demonstrated path reaches it. Local balance provisioning is a test convenience; minting arbitrary collateral, impersonating a privileged operator or forcing an impossible oracle state does not demonstrate that an ordinary attacker can do the same.

## Technical checklist

| Area | Investigation | Evidence that advances a report |
|---|---|---|
| Deployment identity | Correct chain, implementation and configuration at the pinned block | Address/commit manifest and the executed call path |
| Authorization | Initializers, role delegation, upgrade authority, emergency controls, arbitrary call permissions | An unprivileged actor crosses the documented permission boundary |
| Accounting | Deposits, redemptions, fees, debt indexes, rewards, donations, empty pools | Before/after balance sheet with explicit units and a violated relationship |
| Token behavior | Supported fee-on-transfer, rebasing, hooks, nonstandard returns and decimal variation | A supported integration produces incorrect accounting or authority |
| Oracle integration | Price denomination, freshness, decimals, failure modes and L2 downtime | Reachable accepted input causes an incorrect economic decision |
| Callbacks | Callback authentication, intermediate state, cross-function and cross-contract reentry | A local trace showing the unexpected state transition and impact |
| Signatures | Domain, signer, nonce, deadline, action binding, chain and verifying contract | A signature authorizes an unintended second action or context |
| Governance | Snapshot voting, quorum, proposal state, timelock, cancellation and execution | A locally demonstrated bypass of the actual governance guarantees |
| Bridges | Source authentication, destination binding, message uniqueness, ordering and finality | A local two-sided model with a duplicated or unauthorized state transition |
| Liveness | Unbounded processing, poisoned queues, dependency failure and recovery | A bounded local test proving eligible user funds or operations become stuck |
| Economic ordering | Slippage, deadlines, quote validity and attacker-controlled order | Loss exceeding intended, documented market behavior under feasible assumptions |
| Regression | Current implementation and known exclusions | Fresh reproduction and comparison with documented known issues |

Oracle checks must be feed-specific. Chainlink exposes answer metadata and timestamps; applications must interpret values and freshness correctly. On supported L2 integrations, evaluate sequencer availability and any required recovery grace period. A missing generic check is only a lead until its concrete consequence is established. [Data Feeds API](https://docs.chain.link/data-feeds/api-reference), [L2 sequencer feeds](https://docs.chain.link/data-feeds/l2-sequencer-feeds)

Vault rounding and donations deserve explicit boundary tests around zero supply, small deposits and conversions. OpenZeppelin’s ERC-4626 discussion illustrates why share arithmetic and inflation defenses require economic reasoning. Signature review likewise needs more than finding EIP-712: the standard itself does not supply replay protection. Inspect application nonces, consumption and action binding. [ERC-4626 security considerations](https://docs.openzeppelin.com/contracts/5.x/erc4626), [EIP-712](https://eips.ethereum.org/EIPS/eip-712)

Governance review must follow the configured module composition: voting and execution may be separated, and a timelock changes which contract executes the action. Bridges introduce additional assumptions about relayers, validators and cross-chain finality. Reproduce these assumptions explicitly rather than replacing their security checks with unconditional mocks. [OpenZeppelin governance](https://docs.openzeppelin.com/contracts/5.x/api/governance), [Ethereum bridges](https://ethereum.org/developers/docs/bridges/)

MEV describes value extracted through transaction inclusion or ordering, including arbitrage and sandwich behavior. Its existence is not automatically a bounty vulnerability. The report must identify an eligible broken guarantee, realistic capital and ordering assumptions, and the resulting harm; reproduce ordering locally. [Ethereum MEV](https://ethereum.org/developers/docs/mev/)

For non-EVM branches, retain the same scope and evidence model but replace the execution harness. Solana research needs account ownership, signer and writable privileges, PDA derivation and CPI boundaries; Sui/Move research needs module authority and object ownership; protocol/client research needs versioned consensus rules, serialization, state transitions and private multi-node reproductions. Treat these as separate specialization tracks, not as Solidity detector configurations. Select the chain’s official SDK and program-specific build requirements before testing. [Solana privileges](https://solana.com/docs/core/cpi/cpi-execution), [Sui Move concepts](https://docs.sui.io/develop/write-move/sui-move-concepts), [Ethereum client architecture](https://ethereum.org/developers/docs/nodes-and-clients/)

## Command cheat sheet

Run these from an isolated, reviewed local checkout with its required dependencies. `CHAIN_RPC_URL` is the permitted read-only state provider and `FORK_BLOCK` is a recorded decimal block number. Commands are examples of documented syntax, not a universal installer or completed PoC.

```bash
git rev-parse HEAD
forge --version
slither --version
forge build
slither . --json slither.json
forge test --match-test '^test_PoC$' \
  --fork-url "$CHAIN_RPC_URL" \
  --fork-block-number "$FORK_BLOCK" -vvvv
forge test --match-test '^invariant_' \
  --fork-url "$CHAIN_RPC_URL" \
  --fork-block-number "$FORK_BLOCK"
```

`test_PoC` and `invariant_*` are harness functions you implement; they are not built-in vulnerability checks. Preserve the harness, minimized inputs, dependency lock state and traces. Review untrusted build scripts before execution. [Foundry testing](https://www.getfoundry.sh/forge/testing), [Forge test reference](https://www.getfoundry.sh/reference/forge/test), [Slither usage](https://github.com/crytic/slither/wiki/Usage)

**Submission gate:** correct eligible deployment; realistic attacker; reproducible local fork; necessary privileges disclosed; precise impact category; bounded loss; known issues checked; private reporting channel used; no real funds moved. Read the current PoC requirements linked by the program before submitting; a toy reimplementation can explain the idea but does not establish deployed impact.

## Governance and non-EVM completion cases

Go beyond a list of keywords for the protocol features actually present. For governance, record proposal identity, voting snapshot, quorum, queue time and execution authority. In a local fixture compare legitimate propose → vote → queue → execute with early execution, cancelled execution and a repeated execution. Check the actual composed modules: an intentionally permissionless timelock executor is different from bypassing its scheduled operation. Preserve roles and a harmless local target event. [OpenZeppelin governance](https://docs.openzeppelin.com/contracts/5.x/api/governance).

For a supported contract-wallet signer, compare ERC-1271's successful return with a different value and a reverting wallet, then test any state-dependent revocation contract. A non-reverting call is not sufficient signature validation. The expanded procedure is in [contract signatures and oracles](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/modules/contract-signatures-oracles.html). [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271).

For non-EVM deployments, make an explicit applicability ledger: signer/owner/writable/PDA/CPI cases for Solana; object ownership, shared-object transitions and capability authority for Move; serialization/state-transition/finality cases for clients and bridges. Mark an unavailable compatible harness as **not tested** rather than inheriting EVM coverage. A genuine bridge proof needs both sides' authentication and replay rules preserved; replacing verification with an unconditional mock only demonstrates the toy model.

- [ ] Governance transitions include early, cancelled and repeated execution controls.
- [ ] Contract-wallet acceptance checks its actual return semantics.
- [ ] Chain-specific unsupported surfaces are visible as coverage limitations.

## Sources

All sources accessed 2026-09-11. Documentation pages are undated unless noted; versioned documentation must be matched to the target’s actual dependency version.

1. Immunefi. [Rules](https://immunefi.com/rules/). Undated, current rules.
2. Immunefi. [Immunefi Bug Bounty: Information](https://immunefi.com/bug-bounty/immunefi/information/). Undated, current program example.
3. Foundry. [Fork Testing](https://www.getfoundry.sh/guides/fork-testing). Undated; search index displays 2026-08-28.
4. Foundry. [Testing](https://www.getfoundry.sh/forge/testing). Undated; search index displays 2026-07-09.
5. Foundry. [forge test](https://www.getfoundry.sh/reference/forge/test). Undated CLI reference.
6. Foundry. [Invariant Testing](https://getfoundry.sh/forge/invariant-testing?highlight=invariant). Undated.
7. Trail of Bits / Crytic. [Slither Usage](https://github.com/crytic/slither/wiki/Usage). Edited 2024-07-23.
8. OpenZeppelin. [Proxy](https://docs.openzeppelin.com/contracts/5.x/api/proxy). Contracts 5.x; undated.
9. Solidity. [Security Considerations](https://docs.soliditylang.org/en/latest/security-considerations.html). Rolling development documentation; undated.
10. Chainlink. [Data Feeds API Reference](https://docs.chain.link/data-feeds/api-reference). Undated.
11. Chainlink. [L2 Sequencer Uptime Feeds](https://docs.chain.link/data-feeds/l2-sequencer-feeds). Undated.
12. OpenZeppelin. [ERC-4626](https://docs.openzeppelin.com/contracts/5.x/erc4626). Contracts 5.x; undated.
13. Ethereum Improvement Proposals. [EIP-712: Typed structured data hashing and signing](https://eips.ethereum.org/EIPS/eip-712). Created 2017-09-12.
14. OpenZeppelin. [Governance](https://docs.openzeppelin.com/contracts/5.x/api/governance). Contracts 5.x; undated.
15. Ethereum.org. [Bridges](https://ethereum.org/developers/docs/bridges/). Undated.
16. Ethereum.org. [Maximal extractable value (MEV)](https://ethereum.org/developers/docs/mev/). Undated.
17. Solana. [CPI Execution and Privileges](https://solana.com/docs/core/cpi/cpi-execution). Undated.
18. Sui. [Move Concepts](https://docs.sui.io/develop/write-move/sui-move-concepts). Undated.
19. Ethereum.org. [Nodes and Clients](https://ethereum.org/developers/docs/nodes-and-clients/). Undated.


## Shared investigation procedures

- [Workflow invariants, replay, idempotency, and races](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/modules/state-business-logic.html) — Find security consequences in workflow ordering and concurrency, with serial controls and durable-state evidence.
- [Contract state: authorization, callbacks and accounting](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/modules/smart-contract-state.html) — Turn protocol promises into explicit invariants and test realistic local operation sequences with independent accounting.
- [Contract signatures and oracles: context, freshness and units](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/modules/contract-signatures-oracles.html) — Test signed-action context and price-consumer assumptions with local keys, mock feeds and explicit negative controls.

## Vulnerability reference

- [Race condition in a security-sensitive transition](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/race-condition-duplicate-transition.html)
- [Workflow order or approval bypass](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/workflow-order-validation-bypass.html)
- [Single-use action or idempotency replay failure](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/single-use-idempotency-replay.html)
- [Contract callback reentrancy violates a state invariant](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-reentrant-state.html)
- [Contract initializer permits unauthorized ownership or configuration](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-unprotected-initializer.html)
- [Contract upgrade authority can be bypassed](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-upgrade-authorization.html)
- [Vault share conversion or rounding breaks entitlement](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-share-accounting.html)
- [Signed contract action can be replayed unexpectedly](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-signature-replay.html)
- [Signed action does not bind its intended context](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-signature-context.html)
- [Oracle freshness or dependency state permits an invalid decision](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-stale-oracle.html)
- [Oracle denomination or decimal conversion is incorrect](https://bug-bounty-field-manual.kmahshooq.chatgpt.site/vulnerabilities/contract-oracle-unit-confusion.html)