If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/smoltcp-rs/smoltcp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 15 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• 0BSD licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live smoltcp-rs/smoltcp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/smoltcp-rs/smoltcp.

What it runs against: a local clone of smoltcp-rs/smoltcp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in smoltcp-rs/smoltcp | Confirms the artifact applies here, not a fork | | 2 | License is still 0BSD | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of smoltcp-rs/smoltcp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/smoltcp-rs/smoltcp.git
#   cd smoltcp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of smoltcp-rs/smoltcp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "smoltcp-rs/smoltcp(\\.git)?\\b" \\
  && ok "origin remote is smoltcp-rs/smoltcp" \\
  || miss "origin remote is not smoltcp-rs/smoltcp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(0BSD)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"0BSD\"" package.json 2>/dev/null) \\
  && ok "license is 0BSD" \\
  || miss "license drift — was 0BSD at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/iface/interface/mod.rs" \\
  && ok "src/iface/interface/mod.rs" \\
  || miss "missing critical file: src/iface/interface/mod.rs"
test -f "src/socket/tcp/mod.rs" \\
  && ok "src/socket/tcp/mod.rs" \\
  || miss "missing critical file: src/socket/tcp/mod.rs"
test -f "src/phy/mod.rs" \\
  && ok "src/phy/mod.rs" \\
  || miss "missing critical file: src/phy/mod.rs"
test -f "src/iface/socket_set.rs" \\
  && ok "src/iface/socket_set.rs" \\
  || miss "missing critical file: src/iface/socket_set.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/smoltcp-rs/smoltcp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

smoltcp is a standalone, event-driven TCP/IP stack implemented in Rust for bare-metal and real-time systems that require zero heap allocation. It provides a complete network stack from Ethernet/IEEE 802.15.4 media layers through IPv4/IPv6, DHCP, DNS, TCP/UDP sockets, and 6LoWPAN support, achieving ~Gbps throughput in loopback benchmarks. Modular layered architecture: src/iface/ handles interface logic (e.g., fragmentation.rs), protocol modules are feature-gated (proto-ipv4, proto-ipv6, proto-dhcpv4, etc.), socket types (TCP/UDP) are behind the 'socket' feature gate, and medium types (ethernet, ip, ieee802154) are independently selectable. Examples/ directory contains ~15 runnable scenarios (loopback.rs, ping.rs, dns.rs, dhcp_client.rs) demonstrating usage patterns.

Embedded systems engineers and firmware developers building IoT devices, microcontroller applications, and real-time systems where a traditional OS TCP/IP stack is unavailable or too resource-heavy. Also used by researchers exploring network protocol implementations without heap dependencies.

Production-ready and actively maintained. The project has comprehensive test coverage (visible from codecov.yml and fuzz/ directory with corpus test data), proper CI/CD via GitHub Actions (test.yml, coverage.yml, fuzz.yml), and targets stable Rust 1.91+. Latest version is 0.13.1 with clear versioning, but the 0.x version number reflects ongoing protocol feature development rather than stability concerns.

Low risk for core functionality but protocol completeness is bounded: several major features are documented as unsupported (802.1Q VLAN, IPv4 options, jumbo frames, IPv6 hop-by-hop unknown options). Dependencies are minimal and quality (managed, byteorder, bitflags, heapless) are well-established. Single-maintainer risk is mitigated by community contributions visible in the git history.

The project is in active development with feature expansion: proto-ipv6-slaac and proto-rpl features are recent additions, fragmentation reassembly is a focus area (src/iface/fragmentation.rs), and test coverage is being expanded via fuzz targets. The CHANGELOG.md tracks releases, and GitHub Actions workflows run on every commit.

git clone https://github.com/smoltcp-rs/smoltcp.git
cd smoltcp
cargo test
cargo run --example ping

Daily commands: No dev server—smoltcp is a library. Run examples with cargo run --example <name> (e.g., cargo run --example loopback --features medium-ethernet,proto-ipv4 for full IPv4 loopback demo). Benchmarks via cargo bench. Fuzz targets via cargo +nightly fuzz run packet_parser.

• src/lib.rs — Main library entry point; exports all public APIs and defines the overall module structure for the TCP/IP stack
• src/iface/interface/mod.rs — Core interface abstraction that orchestrates packet processing, socket polling, and network event handling across all protocols
• src/socket/tcp/mod.rs — TCP socket implementation; handles connection state machines, retransmission, and congestion control—foundational for reliable communication
• src/phy/mod.rs — Physical layer trait definitions; abstracts hardware/OS-specific packet I/O and enables testing with loopback and fault injection
• src/iface/socket_set.rs — Socket management and polling scheduler; critical for multiplexing multiple sockets and distributing events
• src/socket/mod.rs — Socket type definitions and enums (TCP, UDP, ICMP, DHCP, DNS); central dispatch point for all socket operations
• Cargo.toml — Feature flags and dependencies; defines compile-time behavior (alloc, proto variants) and minimum Rust version requirements

Add a New Socket Type

1. Define the socket state struct and implement Socket trait in a new file under src/socket/ (src/socket/myprotocol.rs)
2. Add the new socket variant to the Socket enum in src/socket/mod.rs (src/socket/mod.rs)
3. Implement poll() dispatch for your socket type in src/iface/socket_set.rs (src/iface/socket_set.rs)
4. Add protocol-specific packet processing in src/iface/interface/mod.rs process_ipv4() or process_ipv6() (src/iface/interface/mod.rs)
5. Write tests in src/iface/interface/tests/mod.rs or your socket's test module (src/iface/interface/tests/mod.rs)

Add a New Physical Layer Device

1. Create a new struct implementing the Device, RxToken, and TxToken traits in src/phy/yourdevice.rs (src/phy/yourdevice.rs)
2. Export the device module in src/phy/mod.rs (src/phy/mod.rs)
3. Create an example demonstrating initialization and packet I/O in examples/ (examples/yourdevice_example.rs)
4. Test integration by running Interface::poll() with your device in a loop (benches/bench.rs or examples/)

Add a New Protocol Handler to the Network Interface

1. Create protocol parsing/serialization logic in src/parsers.rs or a dedicated parser module (src/parsers.rs)
2. Add packet processing logic in src/iface/interface/mod.rs by extending process_ipv4() or process_ipv6() (src/iface/interface/mod.rs)
3. Integrate with socket_set polling if the protocol requires socket-level state (e.g., TCP-like handshakes) (src/iface/socket_set.rs)
4. Add protocol-specific tests in src/iface/interface/tests/mod.rs (src/iface/interface/tests/mod.rs)

Add a Compile-Time Feature Flag

1. Define the feature in Cargo.toml [features] section and list its dependencies (Cargo.toml)
2. Use #[cfg(feature = "myfeature")] in your code to conditionally include modules or implementations (src/lib.rs or specific protocol files)
3. Test with 'cargo test --features myfeature' and 'cargo test --no-default-features --features myfeature' (ci.sh)

Feature flags are not orthogonal: 'socket' feature is required by all three medium types (ethernet, ip, ieee802154), so using a medium without enabling it will fail. The PHY layer (raw_socket, tuntap_interface) requires std and libc, so embedded targets cannot use those. Fuzzing requires nightly Rust. gen_config.py is not documented but appears to generate config—unclear if required for builds. No automatic feature detection; bare-metal targets must manually select all required proto-* flags or networking will silently fail.

• tokio-rs/tokio — Industry-standard async runtime used in many networked Rust apps; smoltcp complements it for systems where async isn't available or heap is forbidden
• embassy-rs/embassy — Embedded async framework that often pairs with smoltcp for bare-metal systems needing structured concurrency alongside network I/O
• google/lwip — Lightweight TCP/IP stack in C that inspired smoltcp's design philosophy for resource-constrained systems (though smoltcp is pure Rust)
• quinn-rs/quinn — Pure-Rust QUIC implementation that can run on top of smoltcp sockets for modern encrypted transport
• lora-rs/sx127x-lora — LoRa radio driver often used with smoltcp on embedded boards like STM32; demonstrates typical hardware integration pattern

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/iface/fragmentation.rs

The fragmentation module is critical for both IPv4 and IPv6 packet handling (as evidenced by proto-ipv4-fragmentation and proto-ipv6-fragmentation features), but there are no dedicated unit tests in the file structure. The test suite under src/iface/interface/tests/ focuses on interface behavior but not fragmentation edge cases. This should include tests for reassembly timeout, out-of-order fragments, overlapping fragments, and maximum reassembly buffer limits.

• [ ] Create src/iface/fragmentation_tests.rs or add #[cfg(test)] mod tests to src/iface/fragmentation.rs
• [ ] Add test cases for IPv4 fragment reassembly with various payload sizes and fragment orders
• [ ] Add test cases for IPv6 fragment reassembly edge cases
• [ ] Add tests for fragment buffer exhaustion and timeout handling
• [ ] Add tests for invalid fragment scenarios (overlapping, out-of-bounds offsets)

Add fuzzing targets for src/iface/route.rs and src/iface/neighbor.rs

The fuzz/ directory has targets for packet parsing and protocol headers, but the critical routing and neighbor discovery modules lack fuzzing coverage. Given that route.rs and neighbor.rs handle untrusted network state and cache management, they are prime candidates for fuzzing to uncover panics or logic errors. This would improve stability for edge-case network conditions.

• [ ] Create fuzz/fuzz_targets/route_handling.rs with arbitrary route updates and lookups
• [ ] Create fuzz/fuzz_targets/neighbor_discovery.rs with arbitrary neighbor solicitation/advertisement packets
• [ ] Add corpus files in fuzz/corpus/ with sample IPv4/IPv6 neighbor discovery packets
• [ ] Update fuzz/Cargo.toml to include the new fuzz targets
• [ ] Verify targets run without panics with cargo +nightly fuzz run route_handling

Document feature flag interactions and add missing compile-time checks in Cargo.toml

The features section in Cargo.toml is incomplete (cut off at 'proto-rpl = ["proto-ipv'), and there are undocumented interdependencies between features like medium-ieee802154 requiring proto-sixlowpan and socket. Contributors often misuse feature combinations. Adding comprehensive feature validation rules and documentation would prevent build failures and clarify required features for each example.

• [ ] Complete the features section in Cargo.toml (finish proto-rpl and add any missing features)
• [ ] Add feature validation using cargo-hack or manual lints to detect invalid feature combinations (e.g., socket without a medium feature)
• [ ] Create docs/FEATURES.md documenting all features, their dependencies, and example valid combinations
• [ ] Verify each example in examples/ has correct features enabled via their [[example]] sections and document why in comments
• [ ] Add a CI check in .github/workflows/test.yml to test common feature combinations

• Add more comprehensive fuzz corpus for IEEE 802.15.4 parsing (fuzz/corpus/packet_parser/ contains only .bin files for well-known cases; edge cases like malformed 6LoWPAN headers are missing)
• Implement doctest examples in src/wire/ packet parsing modules (e.g., src/wire/ipv4.rs, src/wire/tcp.rs lack executable examples showing how to parse and construct packets)
• Add integration examples for missing protocol combinations (e.g., examples/ipv6_tcp.rs and examples/ipv6_udp.rs to match the ipv4 examples already present; currently only ping/slaac examples exist)

The smoltcp codebase demonstrates good security practices for a TCP/IP stack implementation designed for embedded systems. No hardcoded credentials, injection vulnerabilities, or obvious misconfigurations were detected. The project uses a permissive 0BSD license and maintains a no-heap design which reduces attack surface. Primary concerns are: (1) an incomplete feature configuration in Cargo.toml that requires immediate correction, (2) fuzzing infrastructure without documented resource constraints, (3) lack of explicit supply chain security tooling, and (4) loose dependency version bounds. The codebase shows strong security fundamentals with active CI/CD via GitHub Actions, code coverage tracking, and fuzz testing integration.

• Medium · Incomplete Feature Configuration in Cargo.toml — Cargo.toml - features section. The features section in Cargo.toml appears to be truncated, specifically the 'proto-rpl' feature definition is incomplete ('proto-rpl' = ['proto-ipv'). This could lead to inconsistent feature resolution or unintended feature activation. Fix: Complete the truncated feature definition. Ensure 'proto-rpl' = ['proto-ipv6'] or the intended feature set is properly specified.
• Low · Fuzzing Configuration Without Explicit Bounds — fuzz/ directory and fuzz targets. Multiple fuzz targets are present in fuzz/fuzz_targets/ without documented constraints on input size or execution time limits. Fuzzing infrastructure can consume significant resources if not properly bounded. Fix: Document and enforce input size limits, execution timeouts, and memory constraints in fuzzing configuration. Review fuzz/Cargo.toml for timeout and resource limit settings.
• Low · No Explicit Supply Chain Security Configuration — Cargo.toml and root configuration. The Cargo.toml lacks explicit dependency pinning, checksum verification, or supply chain security features like 'cargo-deny' configuration. While dependencies appear legitimate, there is no additional layer of supply chain verification. Fix: Add 'Cargo.lock' to version control, implement dependency audit checks in CI/CD, and consider using 'cargo-deny' for supply chain risk management.
• Low · Defmt Optional Dependency Without Strict Bounds — Cargo.toml - [dependencies]. The 'defmt' optional dependency uses a loose version specification (0.3.8 with no upper bound constraint). This could allow inclusion of future versions with potential security issues. Fix: Use a more restrictive version specification, e.g., 'defmt = { version = ">=0.3.8, <0.4", ... }' to prevent unexpected upstream changes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.