Add AGPL LICENSE + CONTRIBUTING + Code of conduct

CODE_OF_CONDUCT.md

@@ -0,0 +1,127 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement on [Telegram](t.me/openzeppelin_tg/2).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,205 @@
+# Contributing
+
+Thanks for your interest in contributing! This guide explains how to set up your environment, make changes, run checks locally, and submit high‑quality pull requests that pass CI.
+
+---
+
+## Project Overview
+
+`event-scanner` is a Rust library for monitoring EVM-based smart contract events. It is built on the `alloy` ecosystem and provides in-memory scanning with retry-aware callback execution. See `README.md` for features, usage, examples, and testing notes.
+
+- Workspace manifest: `Cargo.toml`
+- Library code: `src/`
+- Examples: `examples/simple_counter`, `examples/historical_scanning`
+- Integration tests: `tests/`
+- Formatting: `rustfmt.toml`
+- Toolchain pin: `rust-toolchain.toml`
+- CI: `.github/workflows/check.yml` and `.github/workflows/test.yml`
+
+---
+
+## Prerequisites
+
+- Rust toolchains via `rustup`
+  - Minimum supported Rust version (MSRV): 1.89 (see `rust-toolchain.toml`)
+  - Formatting uses nightly `rustfmt` in CI
+- Recommended tooling
+  - `cargo-nextest` for fast, reliable test runs: `cargo install cargo-nextest`
+  - `typos` for spell checking: `cargo install typos-cli` (or `brew install typos`)
+  - A recent `rust-analyzer` for IDE support
+- Runtime/dev tools
+  - For examples and some tests, you’ll need an Ethereum dev node such as Foundry’s `anvil`
+
+---
+
+## Repository Layout
+
+- `src/` – core library
+- `examples/` – runnable examples that deploy a demo contract and scan events
+- `tests/` – integration tests covering live, historical and hybrid flows
+- `.github/workflows/` – CI configuration (build, fmt, clippy, typos, tests)
+
+---
+
+## Getting Started
+
+1. Fork the repository and clone your fork.
+2. Ensure toolchains are installed:
+   - `rustup toolchain install 1.89` (MSRV)
+   - `rustup toolchain install nightly` (for rustfmt parity with CI)
+3. Optional helpers:
+   - `cargo install cargo-nextest`
+   - `cargo install typos-cli`
+
+Build the workspace:
+
+```bash
+cargo build --locked --all-targets --all-features
+```
+
+Run the test suite (we recommend nextest):
+
+```bash
+cargo nextest run
+# or
+cargo test
+```
+
+Run examples:
+
+```bash
+RUST_LOG=info cargo run -p simple_counter
+# or
+RUST_LOG=info cargo run -p historical_scanning
+```
+
+Note: Examples start a local `anvil` instance and deploy a demo contract.
+
+---
+
+## Code Style & Linting
+
+- Formatting is enforced by `rustfmt` with the settings in `rustfmt.toml`.
+  - CI runs formatting on nightly. To match CI locally:
+    ```bash
+    cargo +nightly fmt --all --check
+    ```
+  - To apply formatting locally:
+    ```bash
+    cargo +nightly fmt --all
+    ```
+- Linting is enforced with `clippy` and pedantic lints are denied.
+  - To check locally (matches CI):
+    ```bash
+    cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic
+    ```
+  - To apply automatic fixes where possible:
+    ```bash
+    cargo clippy --all-targets --all-features --fix --allow-dirty --allow-staged -- -D warnings -D clippy::pedantic
+    ```
+- Spelling/typos:
+  - CI uses `typos`. Locally:
+    ```bash
+    typos
+    ```
+
+---
+
+## Local CI Parity Checklist
+
+Before opening a PR, please ensure the following commands succeed locally:
+
+```bash
+# Build (all targets & features)
+cargo build --locked --all-targets --all-features
+
+# Format (nightly to match CI)
+cargo +nightly fmt --all --check
+
+# Lint (deny warnings, pedantic)
+cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic
+
+# Spelling
+typos
+
+# Tests (prefer nextest)
+cargo nextest run
+```
+
+---
+
+## Branching, Commits, and PRs
+
+- Branch from `main` with a descriptive name, e.g. `feat/reorg-handling`, `fix/rpc-retries`, `docs/contributing`.
+- Keep PRs focused and reasonably small; large changes are harder to review.
+- Write clear commit messages that explain the why and the what. Conventional Commits are welcome but not required.
+- Include tests for new functionality or bug fixes where applicable.
+- Update documentation and examples as needed.
+- Ensure CI passes. Required checks include:
+  - Build: cargo build
+  - Format: rustfmt (nightly)
+  - Lint: clippy (pedantic, warnings denied)
+  - Typos: typos
+  - Tests: see `.github/workflows/test.yml`
+- CODEOWNERS: reviewers may be auto-assigned based on `CODEOWNERS`.
+
+PR description template (suggested):
+
+```markdown
+## Summary
+Short summary of the change and context.
+
+## Motivation
+Why is this change needed?
+
+## Approach
+Key implementation details, trade-offs, and alternatives considered.
+
+## Checklist
+- [ ] Builds locally with `--all-targets --all-features`
+- [ ] `cargo +nightly fmt --all --check`
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings -D clippy::pedantic`
+- [ ] `typos`
+- [ ] Tests pass (`cargo nextest run`)
+- [ ] Docs/README/examples updated (if applicable)
+```
+
+---
+
+## Testing Notes
+
+- Integration tests live under `tests/` and cover live, historical, and hybrid flows.
+- Prefer `cargo-nextest` for speed and improved output.
+- Where practical, add regression tests when fixing bugs.
+
+---
+
+## Design & Architecture
+
+- High-level architecture and core traits/components are described in `README.md`.
+- For non-trivial changes (new abstractions, public API changes), please open an issue first to discuss design direction before implementation.
+
+---
+
+## Filing Issues
+
+- Use GitHub Issues for bug reports and feature requests.
+- Include reproduction steps, expected vs actual behavior, logs, and environment details.
+- Security-related reports: please follow `SECURITY.md`.
+
+---
+
+## Release & Versioning
+
+- Public crates follow semver. Breaking changes to the public API should be noted clearly in PRs and release notes.
+- New features and fixes may be released in pre-releases before a stable cut.
+
+---
+
+## Community Standards
+
+- Be respectful and constructive.
+- Prefer clear, actionable feedback.
+- Assume good intent and collaborate to reach the best solution.
+
+Thanks again for contributing to Event Scanner!