feat(seismic): add opt-in ECSD address screening by aegis-cipherowl · Pull Request #331 · SeismicSystems/seismic-reth

aegis-cipherowl · 2026-03-12T23:42:57Z

Summary

Adds operator-enforced compliance screening for Seismic validators via integration with CipherOwl's ECSD (Ethereum Compliance Screening Daemon). This is an opt-in policy layer that screens transaction addresses against a compliance blocklist before pool admission.

Protocol vs Policy Separation: Screening is a separate ScreeningTransactionValidator wrapper, NOT part of protocol consensus rules
Type Transparency: Uses Either<A, B> to maintain pool type compatibility whether screening is enabled or disabled
Fail-Safe Modes: Configurable behavior (fail-open or fail-closed) when ECSD is unreachable
Production Performance: <1ms overhead per transaction (~470µs avg) with 100ms timeout providing 200x safety margin
Full Observability: Prometheus metrics for latency, throughput, errors, and address extraction

Key Features

Address Extraction

Extracts addresses from transactions for screening:

Transaction-level: sender, recipient, EIP-7702 authorizations, access lists
ERC-20: transfer, approve, transferFrom
ERC-721: safeTransferFrom variants
ERC-1155: safeTransferFrom, safeBatchTransferFrom

Performance: ~18ns per extraction (negligible CPU overhead)

gRPC Client

Persistent HTTP/2 connection with lazy initialization
Configurable timeout (default 100ms)
Fail modes: open (permissive) or closed (restrictive)
Builder pattern with validation

Performance: ~470µs avg latency with real ECSD Docker

CLI Configuration

seismic-reth node \
  --screening.enable \
  --screening.endpoint http://127.0.0.1:9090 \
  --screening.timeout-ms 100 \
  --screening.fail-mode open

Security Fix

✅ Fail-mode validation: Invalid values (typos like close instead of closed) now fail fast at startup
✅ No silent degradation: Previously unwrap_or(Open) could silently use permissive mode when operator intended restrictive mode

Architecture

Transaction → TransactionValidationTaskExecutor → Either<
    SeismicTransactionValidator,                    // No screening (default)
    ScreeningTransactionValidator<                  // With screening (opt-in)
        SeismicTransactionValidator
    >
>

Performance Benchmarks

Benchmarked against real ECSD Docker container:

Metric	Value	Notes
Calldata extraction	~18ns	Negligible CPU overhead
ECSD gRPC latency	~470µs	Per transaction (localhost)
Throughput	~2,100 tx/sec	Sequential screening
Parallel (10 streams)	~20,000 tx/sec	Estimated
Safety margin	200x	100ms timeout vs 470µs avg

Files Changed

New Files (15)

Proto & Build:
- crates/seismic/txpool/proto/ecsd.proto - gRPC service definition
- crates/seismic/txpool/build.rs - Proto compilation
Screening Module (6 files):
- crates/seismic/txpool/src/screening/mod.rs
- crates/seismic/txpool/src/screening/calldata.rs - Address extraction
- crates/seismic/txpool/src/screening/client.rs - gRPC client
- crates/seismic/txpool/src/screening/metrics.rs - Prometheus metrics
- crates/seismic/txpool/src/screening/validator.rs - Validator wrapper
- crates/seismic/txpool/src/screening/README.md - Documentation
Benchmarks (4 files):
- crates/seismic/txpool/benches/calldata_extraction.rs
- crates/seismic/txpool/benches/screening.rs
- crates/seismic/txpool/benches/mock_ecsd.rs
- crates/seismic/txpool/benches/README.md - Documentation
CLI Args:
- crates/node/core/src/args/screening.rs - CLI configuration

Modified Files (8)

Cargo.toml, Cargo.lock - Added tonic, prost dependencies
bin/seismic-reth/src/main.rs - Wired up ScreeningArgs
crates/node/core/src/args/mod.rs - Exported ScreeningArgs
crates/seismic/node/Cargo.toml - Added futures-util
crates/seismic/node/src/node.rs - Conditional screening with Either
crates/seismic/txpool/Cargo.toml - Screening dependencies
crates/seismic/txpool/src/lib.rs - Updated pool type alias

Test Plan

Documentation

✅ Comprehensive README for screening module (src/screening/README.md)
✅ Comprehensive README for benchmarks (benches/README.md)
✅ Inline documentation for all public APIs
✅ CLI help text for all screening flags
✅ Performance analysis and capacity planning

Security Considerations

Fail-Mode Validation: Added value_parser to reject invalid fail-mode values at startup (prevents silent misconfiguration)
Separation of Concerns: Screening is operator policy, NOT consensus (other validators can have different configs)
Fail-Safe Defaults: Default is disabled + fail-open (permissive)
Timeout Safety: 100ms timeout with 200x margin over typical latency

Migration Impact

Zero breaking changes: Screening is opt-in, disabled by default
Backward compatible: Existing deployments unaffected
Type safe: Either maintains pool type compatibility

🤖 Generated with Claude Code

This commit introduces a new `ScreeningArgs` struct for configuring address screening in the Seismic node. The `SeismicNode` struct is updated to optionally include screening arguments, allowing for integration with an ECSD sidecar for address validation. The CLI is also modified to accept these new arguments, enhancing the node's capabilities for address screening during transaction processing. Additionally, various dependencies are updated in the Cargo files to support these changes.

Resolves all CI check failures in PR SeismicSystems#331: 1. **rustfmt**: Reformatted .expect() call in node.rs to multi-line format per nightly rustfmt preferences 2. **protoc dependency**: Added protobuf-compiler installation to 5 CI jobs (warnings, clippy, unit-test, integration-test, viem) required by tonic-build for proto compilation 3. **clippy expect_used**: Added #[allow(clippy::expect_used)] annotations with justification: - calldata.rs: array length checked immediately before - node.rs: fail_mode validated by clap value_parser All .expect() calls are justified and fail-fast is intentional.

Eliminates the protobuf-compiler (protoc) dependency by checking in the generated gRPC client/server code, simplifying the build process and CI configuration. Changes: - Add crates/seismic/txpool/src/screening/proto.rs (407 lines) Generated code from ecsd.proto with regeneration instructions - Remove crates/seismic/txpool/build.rs No longer need tonic-build at compile time - Remove [build-dependencies] from Cargo.toml Eliminates tonic-build = "0.12" dependency - Update client.rs and mock_ecsd.rs Use super::proto instead of include_proto! macro - Remove protoc installation from CI Deleted protoc setup from 5 jobs: warnings, clippy, unit-test, integration-test, viem Benefits: - No protoc installation required for developers or CI - Faster builds (no proto compilation step) - Simpler CI configuration (removed 10 lines across 5 jobs) - Works on all platforms without protobuf-compiler package - Generated code is version-controlled and reviewable The proto source file remains at crates/seismic/txpool/proto/ecsd.proto for reference. If it changes, proto.rs can be regenerated following the instructions in its header comment. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

daltoncoder

Looks good to me. Going to test some more on some of our testnets. A couple comments:

Fixes 43 clippy warnings across calldata.rs, client.rs, and proto.rs: calldata.rs: - Combine trait bounds: T: PoolTransaction + alloy_consensus::Transaction - Add #[allow(clippy::indexing_slicing)] for length-checked slicing operations (all slices are validated before use) client.rs: - Make builder methods const: timeout() and fail_mode() proto.rs (generated code): - Add module-level #[allow] for generated code patterns: unreachable_pub, missing_const_for_fn, doc_markdown - Add Eq to all PartialEq derives (ExtendedHealthRequest, ExtendedHealthResponse, BatchCheckRequest, BatchCheckResponse) - Change visibility to pub (needed for benches to access) benches/calldata_extraction.rs: - Replace std::iter::repeat().take() with repeat_n() (clippy::manual_repeat_n) screening.rs tests: - Replace #[should_panic] with explicit error checking (panic message from clap doesn't match expected string exactly) All changes maintain functionality while satisfying strict clippy lints enabled in CI (-D warnings with custom lint configuration).

cdrappi

Hey guys. I stopped reviewing the whole thing after finding one super critical issue, detailed below

TLDR: we have some work to get our seismic tx pipeline in a spot where you can actually screen on encrypted calldata. right now, this code as executed on seismic transactions will not screen anything, defeating the purpose entirely

Right now, this is more of an us problem than a you problem; when we've got our ducks in line we will circle back with some instructions on correctly wiring in Seismic transactions to screening

fix: Add decryption to screening

Address clippy lints (checked arithmetic, derive Default, const fn, allow attributes) and add missing Debug derive for test helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…eening # Conflicts: # bin/seismic-reth/src/main.rs

- Remove Mutex around tonic gRPC client; clone per-request instead to allow concurrent screening via HTTP/2 multiplexing - Return generic error on flagged transactions to avoid leaking which addresses are on the blocklist Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

aegis-cipherowl requested a review from cdrappi as a code owner March 12, 2026 23:42

aegis-cipherowl and others added 2 commits March 13, 2026 11:24

daltoncoder reviewed Mar 17, 2026

View reviewed changes

Comment thread crates/seismic/txpool/src/screening/client.rs Outdated

Comment thread crates/seismic/txpool/src/screening/validator.rs Outdated

cdrappi requested changes Mar 23, 2026

View reviewed changes

Comment thread crates/seismic/txpool/src/screening/validator.rs Outdated

HenryMBaldwin mentioned this pull request Mar 30, 2026

fix: Add decryption to screening cipherowl-ai/seismic-reth#2

Merged

HenryMBaldwin and others added 8 commits March 30, 2026 11:37

fix: Add decryption to cipher owl screening.

536d9f1

Cargo fmt.

74fa442

Comments.

f7fec5a

pub -> pub(crate)

e5dea01

Merge pull request #2 from SeismicSystems/h/decryption-for-cipherowl

fbea00e

fix: Add decryption to screening

fix: resolve clippy warnings and test compilation in screening

d00c9e9

Address clippy lints (checked arithmetic, derive Default, const fn, allow attributes) and add missing Debug derive for test helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Merge remote-tracking branch 'upstream/seismic' into ecsd-address-scr…

3da6696

…eening # Conflicts: # bin/seismic-reth/src/main.rs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(seismic): add opt-in ECSD address screening#331

feat(seismic): add opt-in ECSD address screening#331
aegis-cipherowl wants to merge 12 commits intoSeismicSystems:seismicfrom
cipherowl-ai:ecsd-address-screening

aegis-cipherowl commented Mar 12, 2026

Uh oh!

daltoncoder left a comment

Uh oh!

Uh oh!

Uh oh!

cdrappi left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

aegis-cipherowl commented Mar 12, 2026

Summary

Key Features

Address Extraction

gRPC Client

CLI Configuration

Security Fix

Architecture

Performance Benchmarks

Files Changed

New Files (15)

Modified Files (8)

Test Plan

Documentation

Security Considerations

Migration Impact

Uh oh!

daltoncoder left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cdrappi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants