Onboarding: FuelLabs/sway

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 48%)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

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

TL;DR

Sway is a domain-specific programming language and compiler toolchain (forc - Fuel Orchestrator) designed for writing smart contracts on the Fuel blockchain VM. It is Rust-inspired and compiles Sway source code to Fuel VM bytecode, providing a full developer toolchain including formatter, LSP server, package manager, and test runner under the 'forc' umbrella CLI. This is a Cargo workspace monorepo: the forc CLI and its sub-commands live in dedicated crates, the Sway compiler pipeline (parsing, IR, codegen) is in separate crates, and docs/book/ contains the mdBook-based Sway Book. CI scripts live under .github/workflows/scripts/ as standalone Rust mini-binaries (e.g., check-dep-versions/src/main.rs).

Who it's for

Smart contract developers targeting the Fuel blockchain who want a Rust-like, type-safe language with modern tooling, as well as compiler/language engineers contributing to the Sway language itself, its standard library, or the forc build toolchain.

Maturity & risk

The repo has an active CI pipeline (.github/workflows/ci.yml), structured issue templates, a spellcheck workflow, and a dedicated Sway Book documentation site. It is under active development with multiple workflow files, a benchmark suite, and nightly cargo audit checks — indicating a production-aspiring but still rapidly evolving project rather than a fully stable release.

The project is tightly coupled to the Fuel blockchain ecosystem, so breaking changes in fuel-core or fuel-vm dependencies can cascade. The CI scripts include version-checking utilities (check-dep-versions, check-forc-manifest-version) hinting at historical dependency drift issues. The large Cargo.lock (workspace with many crates) suggests significant dependency surface area.

Active areas of work

Active work visible includes benchmark infrastructure (benchmark.yml, benchmark.sh), nightly cargo audit for security, a Just-based task runner (justfile with update-contract-ids, update-fuel-dependencies recipes), and ongoing docs work under docs/book/src/advanced/ covering advanced storage and assembly.

Get running

git clone git@github.com:FuelLabs/sway.git && cd sway && rustup default stable && cargo build && cargo run --bin forc -- --help

Daily commands: cargo build (builds all workspace crates); cargo run --bin forc -- build (builds a Sway project); cargo test (runs all tests); ./benchmark.sh (runs benchmarks); just --list (lists all available Just recipes)

Map of the codebase

• Cargo.toml — Root workspace manifest defining all crates, their relationships, and shared dependency versions — the single source of truth for the entire monorepo structure.
• docs/book/src/SUMMARY.md — Master table of contents for the Sway Book; governs the documentation hierarchy and is the entry point for all user-facing language documentation.
• .github/workflows/ci.yml — Primary CI pipeline definition covering build, test, lint, and release gates — must be understood before merging any significant change.
• .github/workflows/scripts/check-dep-versions/src/main.rs — Enforces consistent dependency versions across all workspace crates; breaks the build if version drift is detected.
• .github/workflows/scripts/check-forc-manifest-version/src/main.rs — Validates that forc manifest versions are in sync across the monorepo, preventing silent version skew in published toolchain artifacts.
• docs/book/src/advanced/traits.md — Documents Sway's trait system — the core abstraction mechanism of the language and essential reading for understanding contract interfaces and generics.
• docs/book/src/blockchain-development/storage.md — Defines the storage abstraction layer that underpins all smart contract state management in Sway, load-bearing for understanding the compiler's storage layout pass.

How to make changes

Add a new language feature to the Sway Book

1. Create a new markdown file under the appropriate topic directory (e.g. docs/book/src/advanced/my_feature.md) following the structure of adjacent files. (docs/book/src/advanced/traits.md)
2. Register the new page in the master SUMMARY.md table of contents under the correct section so mdBook can index it. (docs/book/src/SUMMARY.md)
3. Add any new technical terms to the spell-check allow-list to prevent CI spellcheck failures. (docs/book/spell-check-custom-words.txt)
4. Verify the docs build passes locally and in CI by checking the docs workflow configuration. (.github/workflows/docs.yml)

Add a new forc CLI command documentation page

1. Create a new file in docs/book/src/forc/commands/ named forc_<command>.md, mirroring the structure of an existing command page. (docs/book/src/forc/commands/forc_build.md)
2. Add the new command page to SUMMARY.md under the forc/commands section. (docs/book/src/SUMMARY.md)
3. If the command introduces new flags or behavior, update the blockchain-development or basics index as appropriate. (docs/book/src/basics/index.md)

Add a new workspace crate to the monorepo

1. Create the new crate directory and Cargo.toml, then add it to the [workspace] members list in the root Cargo.toml. (Cargo.toml)
2. Run the check-dep-versions script locally to ensure your new crate's dependency versions align with the rest of the workspace. (.github/workflows/scripts/check-dep-versions/src/main.rs)
3. If the new crate is a forc plugin, update check-forc-manifest-version to include it in version consistency checks. (.github/workflows/scripts/check-forc-manifest-version/src/main.rs)
4. Add any necessary CI steps (build, test, lint) to the main CI workflow. (.github/workflows/ci.yml)

Add a new contract example to the documentation

1. Create a new markdown file in docs/book/src/examples/ with the contract code inline and explanation following the style of counter.md. (docs/book/src/examples/counter.md)
2. Register the example in SUMMARY.md under the Examples section. (docs/book/src/SUMMARY.md)
3. Link to the Sway Applications repository or inline the example in the sway_applications index if it is a full application. (docs/book/src/examples/sway_applications.md)

Why these technologies

• Rust — Provides memory safety without a GC, strong type system for compiler internals, and a mature ecosystem (cargo, crates.io) — ideal for building a production-grade language toolchain.
• FuelVM — Purpose-built UTXO-based VM with native asset support and parallel transaction execution; Sway is designed as the first-class language for this VM.
• mdBook — Lightweight Rust-native static site generator enabling the Sway Book to be version-controlled as Markdown and built/deployed via CI with minimal tooling.
• GitHub Actions — Tight integration with the GitHub-hosted repo enables matrix builds, automated releases, and dependency audits without external CI infrastructure.
• Cargo workspaces — Allows the compiler, standard library, forc CLI, LSP server, and test harnesses to share dependency versions and be built/tested as a single coherent unit.

Trade-offs already made

• Monorepo workspace for all Sway toolchain crates
  • Why: Enables atomic cross-crate refactors, shared CI, and single-version lockfile ensuring
  • Consequence: undefined

Traps & gotchas

You must use Rust stable (not nightly) as the default toolchain per README — some contributors mistakenly assume nightly. The Just task runner (https://github.com/casey/just) is required for many dev workflows and is not installed by default. CI version-check scripts (check-dep-versions, check-forc-manifest-version) will fail the build if crate versions drift, which is a non-obvious failure mode when bumping dependencies piecemeal.

Architecture

Concepts to learn

• Fuel VM (FuelVM) — Sway compiles to FuelVM bytecode, not EVM — understanding FuelVM's UTXO-based execution model is essential for understanding why Sway makes the design choices it does.
• Predicate (Fuel transaction type) — Sway has a distinct 'predicate' program type (alongside contracts and scripts) that executes statelessly to validate transactions — a concept unique to Fuel with no direct EVM equivalent.
• Abstract Syntax Tree (AST) to IR lowering — The Sway compiler pipeline transforms parsed AST through a typed IR before codegen — understanding this multi-stage lowering is essential for contributing to the compiler.
• Cargo Workspace — The entire repo is a Cargo workspace of many crates sharing a single Cargo.lock — changes to one crate version can affect all others, which is why check-dep-versions CI scripts exist.
• Language Server Protocol (LSP) — Sway ships an LSP server crate enabling IDE features (autocomplete, go-to-definition) — contributors to the language must understand how type information is exposed via LSP.
• UTXO-based smart contracts — Unlike Ethereum's account model, Fuel uses a UTXO model for assets, which fundamentally shapes how Sway contracts handle asset transfers and state.

Related repos

• FuelLabs/fuel-core — The Fuel blockchain node that executes Sway-compiled bytecode — direct runtime counterpart to this compiler.
• FuelLabs/fuels-rs — The Rust SDK for interacting with Fuel contracts, used alongside forc for integration testing Sway contracts.
• FuelLabs/sway-libs — Official reusable Sway library crates that extend the standard library, directly consumed by Sway contract developers.
• ethereum/solidity — The dominant smart contract language this project competes with/draws lessons from in the EVM ecosystem.
• rust-lang/rust — Primary design inspiration for Sway's syntax, type system, and ownership semantics.

PR ideas

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 missing documentation page for never_type in the Sway Book

The file docs/book/src/advanced/never_type.md exists in the file structure, and docs/book/src/SUMMARY.md likely references it, but the never type is a nuanced feature (similar to Rust's ! type) that deserves thorough documentation with examples covering exhaustive match arms, diverging functions, and use in error handling. Given Sway's Rust inspiration, clear documentation here reduces confusion for Rust developers migrating to Sway.

• [ ] Open docs/book/src/advanced/never_type.md and audit its current content for completeness
• [ ] Add a clear definition of the never type (!) and when it is used in Sway
• [ ] Add concrete code examples showing diverging functions (e.g., functions that always revert or loop forever)
• [ ] Add an example showing the never type used in exhaustive match expressions alongside enums
• [ ] Cross-reference with docs/book/src/advanced/traits.md and docs/book/src/basics/error_handling.md where relevant
• [ ] Verify the page appears correctly in docs/book/src/SUMMARY.md and renders with mdbook build

Add a GitHub Actions workflow to spell-check Rust doc comments (///) in source files

The repo already has .github/workflows/spellcheck.yml and .typos.toml for general typo checking, and docs/book/.spellcheck.yml for the book. However, there is no dedicated workflow step that runs typos or a similar tool scoped specifically to Rust inline doc comments across the compiler and tooling crates. Rust doc comments are the primary API documentation surface (visible on docs.rs) and typos there are highly visible to end users. Adding a targeted CI check prevents regressions.

• [ ] Review the existing .github/workflows/spellcheck.yml to understand the current scope and tool used
• [ ] Review .typos.toml to understand existing ignore rules and custom word lists
• [ ] Add a new job (or extend spellcheck.yml) that runs typos --type rust targeting sway-core/, sway-lsp/, forc/, and other key crates
• [ ] Add any Sway-specific technical terms (e.g., FuelVM, forc, WordAligned) to .typos.toml under [default.extend-words] to prevent false positives
• [ ] Test the workflow locally with act or by pushing to a draft PR branch
• [ ] Document the new check in CONTRIBUTING.md or the relevant CI docs

Add a check-dep-versions unit test suite for the version-checking script itself

The file .github/workflows/scripts/check-dep-versions/src/main.rs is a custom Rust binary used in CI to enforce dependency version consistency across the workspace. This script is critical infrastructure — a bug in it could silently allow version mismatches to ship. However, there are no test files visible in .github/workflows/scripts/check-dep-versions/src/, meaning the logic is untested. Adding unit tests directly in main.rs (or a companion lib.rs) would make this CI guard more trustworthy.

• [ ] Open .github/workflows/scripts/check-dep-versions/src/main.rs and identify the core parsing and comparison functions
• [ ] Refactor any monolithic logic into smaller, testable functions (e.g., parse_version_from_toml, find_mismatched_deps) if not already done
• [ ] Add a #[cfg(test)] module at the bottom of main.rs (or create lib.rs and move logic there)
• [ ] Write unit tests covering: matching versions (should pass), mismatched versions (should fail), missing dependency keys (edge case), and mal

Good first issues

1. Add missing test coverage for the advanced storage patterns documented in docs/book/src/advanced/advanced_storage.md — the doc exists but test parity is often incomplete. 2. Improve spellcheck custom word list at docs/book/spell-check-custom-words.txt for Sway/Fuel-specific terminology that currently triggers false positives. 3. Add inline code examples to docs/book/src/advanced/assembly.md to demonstrate concrete Sway inline assembly usage patterns, which the file documents abstractly.

Top contributors

• @ironcev — 41 commits
• @xunilrj — 25 commits
• @JoshuaBatty — 8 commits
• [@Vaivaswatha N](https://github.com/Vaivaswatha N) — 6 commits
• @kayagokalp — 5 commits

Recent commits

• c53e7e0 — Fix tuple codec helpers to avoid LSP stack overflows (#7611) (JoshuaBatty)
• 27f3d99 — Increase test coverage for dynamic_storage (#7608) (ironcev)
• 3005dcb — Implement reassignment for arrays declared using const generics (#7601) (ironcev)
• fe31b4a — Implement dynamic storage for storage declaration and std (#7598) (ironcev)
• e12e611 — Implement dynamic storage intrinsics (#7597) (ironcev)
• fbb524c — Implement dynamic storage opcodes in the compiler (#7595) (ironcev)
• f9b8158 — Bump to 0.71.0 (#7594) (ironcev)
• 011b751 — Fix default gas costs and add perf diff scripts to storage_benchmarks (#7593) (ironcev)
• 4382e71 — Promote const_generics to a standard feature (#7592) (ironcev)
• 0507c2c — Update fuel-vm and fuels dependencies in sdk-harness tests (#7591) (ironcev)

Security observations

• Medium · Unpinned Dependency Versions in CI/CD Scripts — .github/workflows/scripts/check-dep-versions/Cargo.toml. The check-dep-versions utility uses 'regex = "1"' and 'toml = "0.8"' as dependency constraints, which allows any compatible minor/patch version to be resolved. While not immediately exploitable, supply chain attacks via compromised crate versions in these ranges could affect the build tooling. The 'toml' crate (0.8.x) has had past parsing edge cases, and the broad version range increases exposure window. Fix: Pin dependencies to exact versions (e.g., 'regex = "=1.10.x"' and 'toml = "=0.8.x"') or use a lockfile (Cargo.lock) that is committed and verified in CI. Regularly audit Cargo.lock for known vulnerabilities using 'cargo audit'.
• Medium · Nightly Cargo Audit Workflow May Miss Timely Vulnerability Detection — .github/workflows/nightly-cargo-audit.yml. The repository has a 'nightly-cargo-audit.yml' workflow that performs security audits only on a nightly basis. Security vulnerabilities disclosed in dependencies during the day would not be caught until the next scheduled run, potentially leaving a window of exposure in CI-built artifacts or published releases. Fix: Consider also running 'cargo audit' as part of every CI pipeline (ci.yml) to ensure vulnerabilities in dependencies are caught immediately on every push or pull request, rather than only nightly.
• Medium · Shell Scripts in CI Workflows Without Strict Error Handling — .github/workflows/scripts/check-sdk-harness-version.sh, .github/workflows/scripts/verify_tag.sh. The shell scripts 'check-sdk-harness-version.sh' and 'verify_tag.sh' are used in CI workflows. Without visibility into their contents, common issues include lack of 'set -euo pipefail', unquoted variables, and command injection risks if external input (e.g., tag names, branch names from GitHub context) is passed directly into shell commands without sanitization. Fix: Ensure all shell scripts use 'set -euo pipefail' at the top. Sanitize and quote all variables, especially those derived from GitHub Actions contexts (github.ref, github.event inputs). Use shellcheck in CI to statically analyze shell scripts for common vulnerabilities.
• Low · Dockerfile Present Without Visible Security Hardening — deployment/Dockerfile. A Dockerfile exists in the 'deployment/' directory. Without visibility into its contents, common Docker security issues include running as root, using 'latest' tags for base images, not using multi-stage builds to minimize attack surface, not setting USER directive, and not scanning for vulnerabilities in the base image. Fix: Ensure the Dockerfile: (1) uses a specific, pinned base image version rather than 'latest', (2) runs the application as a non-root user via the USER directive, (3) uses multi-stage builds to minimize the final image size and attack surface, (4) is regularly scanned with tools like Trivy, Snyk, or Docker Scout for known CVEs.
• Low · Devcontainer Configuration May Include Overly Permissive Settings — .devcontainer/devcontainer.json. The '.devcontainer/devcontainer.json' file configures the development environment. Devcontainer configurations can inadvertently expose mounts, set overly permissive capabilities, or forward ports that could be exploited in shared or cloud-based development environments (e.g., GitHub Codespaces). Fix: Review devcontainer.json to ensure no sensitive host directories are mounted unnecessarily, no extra Linux capabilities are granted (e.g., '--cap-add SYS_PTRACE' should only be added if strictly required), and any forwarded ports are documented and justified. Avoid storing any credentials or secrets within the devcontainer configuration.
• Low · GitHub Actions Workflow Permissions Not Explicitly Restricted — .github/workflows/. Based on the presence of multiple workflow files (ci.yml, benchmark.yml, docs.yml, gh-pages.yml, etc.), if these workflows do not explicitly set 'permissions' at the workflow or job level to the minimum required, they default to broad repository permissions. This can allow a compromised action or a pull request from a fork to perform unintended operations such as writing to the repository or packages. Fix: undefined

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

Where to read next

• 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.