The Fuel TypeScript SDK (fuels) — Admin & Architecture Guide

This guide is for the engineers, architects, and contributors who need to understand how fuels-ts is built — its monorepo layout, package dependency graph, the Sway→TypeScript codegen pipeline, the UTXO transaction-assembly engine, the ABI coder, binary management, and the release machinery. For day-to-day SDK usage, see the companion User Guide.

fuels-ts is the official TypeScript SDK for the Fuel network. It is a pnpm + Turborepo monorepo that publishes ~20 scoped @fuel-ts/* packages, an umbrella fuels package (which re-exports them all and carries the CLI), a create-fuels scaffolding tool, and an @fuel-ts/abi-typegen code generator. It is licensed Apache-2.0.

1. Executive Summary

What it is. A client SDK that lets TypeScript applications create wallets, deploy and call Sway programs (contracts, scripts, predicates), and build/submit transactions on a UTXO-based chain. Conceptually it is to Fuel what ethers.js is to Ethereum, plus a build tool that bridges the Sway compiler to typed TypeScript bindings.

Audience inversion note. Although automated classification tags the repo as a web app, it is a library/framework/CLI. Throughout this guide the "operator" is a developer integrating or extending the SDK, and "deployment" means publishing packages and managing the toolchain — not running a server.

2. Architecture

2.1 High-level layers

            ┌─────────────────────────────────────────────────────────┐
            │                     fuels (umbrella)                     │
            │   re-exports every @fuel-ts/* package + the `fuels` CLI  │
            └───────────────┬─────────────────────────┬───────────────┘
                            │                         │
        ┌───────────────────▼──────────┐   ┌──────────▼───────────────┐
        │      High-level objects      │   │         CLI layer        │
        │  account · contract ·        │   │  init/build/deploy/dev/  │
        │  program · script · recipes  │   │  node/typegen/versions   │
        └───────────────┬──────────────┘   └──────────┬───────────────┘
                        │                              │
        ┌───────────────▼──────────────┐   ┌──────────▼───────────────┐
        │     Encoding & protocol      │   │     Codegen + binaries   │
        │  abi-coder · transactions ·  │   │  abi-typegen ·           │
        │  address · math · hasher     │   │  @internal/forc ·        │
        │  crypto · utils · errors     │   │  @internal/fuel-core     │
        └──────────────────────────────┘   └──────────────────────────┘

The dependency direction is strictly downward: high-level objects (Contract, Wallet) build on the encoding/protocol layer (abi-coder, transactions), which builds on primitives (math, crypto, errors). The CLI sits beside the runtime and pulls in abi-typegen plus the binary-management packages.

2.2 Package inventory

Published runtime packages (@fuel-ts/*)

Aggregator & tooling packages

The umbrella's public surface is defined entirely by packages/fuels/src/index.ts, which re-exports every sub-package. This barrel is the authoritative list of what import { … } from 'fuels' exposes.

2.3 Source tree

fuels-ts/
├── packages/          # ~20 published packages, each: src/ (barrel index.ts) + test/
│   ├── fuels/         #   umbrella + CLI (src/cli.ts, src/cli/commands/*)
│   ├── account/       #   Provider, Wallet, Predicate, tx requests (largest)
│   ├── abi-coder/     #   Interface + Coder family
│   ├── abi-typegen/   #   ABI → TS codegen + fuels-typegen CLI
│   ├── contract/ program/ script/ transactions/ address/ math/ …
│   └── create-fuels/  #   scaffolding CLI + templates
├── apps/
│   ├── docs/          # VitePress docs site; src/guide/**/snippets/*.ts are tested
│   ├── docs-api/      # generated API reference
│   └── demo-*/        # runnable example apps (nextjs, react-vite, bun, nodejs-esm)
├── templates/         # create-fuels templates (vite, nextjs)
├── internal/          # @internal/forc, @internal/fuel-core, tsup, check-*
└── scripts/           # release, changeset, forc-version, coverage tooling

Note

Most of the 2,000+ files are Sway test fixtures under packages/*/test/fixtures/forc-projects/** and docs snippets. The actual SDK surface is the packages/*/src/ trees, and the cleanest map to it is each package's src/index.ts barrel.

3. System Requirements

The forc/fuel-core versions are not free-floating: create-fuels writes a fuel-toolchain file pinning forc and fuel-core to the versions exported by @fuel-ts/versions, on the testnet channel. The fuels versions command exists precisely to catch drift between the installed binaries and the SDK's expected versions.

4. Configuration Mastery — fuels.config.ts

The fuels CLI is driven by a single config file resolved (via JoyCon) as fuels.config.{ts,js,cjs,mjs} walking up from the working directory. It is bundled and evaluated at runtime (bundle-require + esbuild), so it can be authored in TypeScript. Define it with createConfig for type-safety. Validation is enforced by a yup schema (output is the only strictly required field).

4.1 Full field reference

Two derived fields are computed at load time and merged into the in-memory config: basePath (the config dir), configPath (the resolved file), and buildMode ('release' if --release is in forcBuildFlags, else 'debug'). The buildMode selects the artifact directory the CLI reads from: out/{buildMode}/{name}.bin, …-abi.json, and …-storage_slots.json.

Important

output must be a valid string or validateConfig rejects the file. workspace must point at a directory whose Forc.toml declares [workspace]; pointing it at a single program throws WORKSPACE_NOT_DETECTED and suggests using contracts/scripts/predicates instead.

4.2 Environment variables

The CLI and examples read a handful of env vars:

Caution

The default privateKey is the well-known local consensus key — convenient for fuels dev against a local node, never for testnet/mainnet. Always inject a real key via MY_PRIVATE_KEY (or another secret source) for non-local deployments.

5. The Sway → TypeScript Codegen Pipeline

This is the SDK's signature subsystem: turning compiled Sway programs into typed TypeScript.

5.1 The build/deploy flow (fuels build, fuels deploy)

forc build (Sway compiler)
   └─ out/{debug|release}/{name}.bin
      out/{debug|release}/{name}-abi.json
      out/{debug|release}/{name}-storage_slots.json
        │
        ▼
abi-typegen  →  typed TS classes  (Contract/Factory, Script[+Loader], Predicate[+Loader])
        │
        ▼
fuels deploy → deploys, writes contract-ids.json, regenerates factory classes with loader code

forcUtils.ts is the glue: it reads each program's Forc.toml to discover the project name, the Sway program type (contract/script/predicate/library), and computes the .bin/-abi.json/-storage_slots.json paths from buildMode. findPrograms() globs for *.toml, filters out the workspace root and libraries, and classifies the rest by reading the ;-terminated program-type line in each src/main.sw.

deploy() (in cli/commands/deploy) runs in order: deploy contracts → save contract-ids.json → deploy scripts → save script files → deploy predicates → save predicate files → fire the onDeploy callback → regenerate factory classes so they embed loader bytecode.

5.2 abi-typegen internals

The generator (AbiTypeGen) consumes the new ABI JSON shape (JsonAbiNew; an older shape is transpiled forward via transpileAbi). For each program it builds an Abi model exposing types, functions, configurables, commonTypesInUse, and bytecode, then renders Handlebars (.hbs) templates:

• Contract → renderMainTemplate emits the typed contract class with per-function encoders/decoders, struct/enum typedefs, the embedded ABI JSON, and storage slots. Base members imported: FunctionFragment, InvokeFunction.
• Predicate → requires a main() function (else ABI_MAIN_METHOD_MISSING); imports Predicate, Provider, InputValue, PredicateParams, decompressBytecode; embeds compressed bytecode.
• Script → also requires main(); imports Script, Account, decompressBytecode.
• index → renderIndexTemplate re-exports the generated members.

Struct/enum/import formatting is handled by formatStructs/formatEnums/formatImports. The CLI surface (fuels-typegen) is a commander program with -i/--inputs, -o/--output, mutually-exclusive -c/-s/-p, and -S/--silent; resolveProgramType defaults to CONTRACT when none is specified.

Note

Predicates and scripts can be deployed as reusable loader bytecode. After fuels deploy, the generator re-emits *Loader classes that reference the on-chain blob, keeping per-transaction payloads small. This is why deploy regenerates types as its final step.

6. The Transaction-Assembly Engine (UTXO)

Fuel is UTXO-based, so the hardest problems in the SDK are coin selection and fee estimation. This logic lives in @fuel-ts/account under providers/.

6.1 Transaction request types

providers/transaction-request/ defines a request hierarchy, each a coder over the wire format:

Requests expose addCoinOutput, addContractInputAndOutput, addResources, addWitness/updateWitness, setData, and getTransactionId(chainId).

6.2 assembleTx — the modern funding API

provider.assembleTx({ request, feePayerAccount, accountCoinQuantities }) is the recommended way to fund and estimate any hand-built request. The caller declares which account supplies which { amount, assetId } and where change goes (changeOutputAccount); the engine selects coins, estimates gas/fee, and returns a ready-to-send assembledRequest. Because assembly can mutate the request (adding inputs/outputs and changing the tx ID), signatures must be (re)applied after assembly — see the signing flow in the User Guide.

6.3 Coin management utilities

@fuel-ts/account exports UTXO-shaping helpers:

The Provider carries an optional resource cache (resourceCacheTTL) to prevent the same coin from being selected by two in-flight transactions (double-spend protection at the client level). Provider.ENABLE_RPC_CONSISTENCY toggles a cross-node consistency check.

6.4 Transaction lifecycle

build request → assembleTx (select coins, estimate fee)
   → sign (if required) → sendTransaction / .call()
   → TransactionResponse → waitForResult()
   → TransactionSummary (status, receipts, fee, decoded logs)

transaction-summary/ assembles human-readable summaries from raw receipts, including operation classification and fee calculation. transaction-response/getDecodedLogs and getAllDecodedLogs turn receipts into typed log values (and the grouped-by-contract logs the User Guide demonstrates).

7. The ABI Coder

@fuel-ts/abi-coder is the binary serialization layer. The Interface class wraps an ABI and exposes functions.<name>.encodeArguments(...) / decodeOutput(...). Encoding is delegated to a family of Coder subclasses, one per Sway type:

ArrayCoder, B256Coder, B512Coder, BigNumberCoder, BooleanCoder, ByteCoder, EnumCoder, NumberCoder, OptionCoder, RawSliceCoder, StdStringCoder, StrSliceCoder, StringCoder, StructCoder, TupleCoder, VecCoder.

It also exports the protocol size constants (WORD_SIZE, BYTES_32, ASSET_ID_LEN, CONTRACT_ID_LEN, INPUT_COIN_FIXED_SIZE, SCRIPT_FIXED_SIZE, calculateVmTxMemory) and the encoding version flag ENCODING_V1. The new ABI type (JsonAbi, from types/JsonAbiNew) is the canonical shape; legacy ABIs are transpiled.

Note

The coder family is the lowest-level public contract in the SDK. If you ever need to encode/decode against a raw ABI without a generated class, construct an Interface directly — this is what the generated classes do under the hood.

8. Binary Management — forc & fuel-core

The SDK does not bundle the Rust binaries; the @internal/forc and @internal/fuel-core packages download the correct binary per platform/architecture at install time (lib/install.js, lib/shared.js). They detect the architecture and throw Unsupported arch ${process.arch} for unsupported platforms, and validate the version string.

At runtime the CLI's tryFindBinaries resolves forcPath/fuelCorePath either from config or the system PATH; if a binary is missing it throws with a message listing each missing binary and a link to the installation guide. autoStartFuelCore (in the dev/node commands) spawns a fuel-core child process on fuelCorePort and tears it down on config change or shutdown.

Tip

For consumers, the recommended install path is fuelup, which manages matched forc/fuel-core toolchains by channel. The @internal/* download packages exist mainly so the monorepo's own tests and the scaffolded templates get a known-good binary without a manual fuelup step.

9. Security

Caution

Treat fuels.config.ts as code: it is bundled and executed by the CLI. Do not commit real privateKey values into it — read them from the environment.

10. Operations — the CLI dev loop

The fuels CLI (packages/fuels/src/cli.ts) is a commander program named fuels with global -D/--debug and -S/--silent flags (wired through a preAction hook into configureLogging). Commands:

The dev/node commands wrap their actions in withConfig/withProgram/withBinaryPaths higher-order handlers that load + validate config and resolve binaries before running, and route failures through withConfigErrorHandler (which can invoke the onFailure hook).

10.1 Local development workflow

pnpm install          # install workspace
pnpm build:packages   # turbo build all publishable packages (excludes docs/templates)
pnpm test:node        # vitest node project
pnpm test:browser     # vitest browser project (Playwright-backed)
pnpm lint             # type-check + eslint + prettier

The root package.json exposes the full operational surface: turbo run build for the dependency-aware build graph; vitest split into node and browser projects with separate configs; coverage merge/diff scripts; forc:check/forc:verify/forc:update to keep the Sway toolchain pinned; and changeset:* scripts for release.

11. Testing Strategy

The docs-as-tests approach is notable: the user-facing examples cannot drift from the API, because they are typechecked and run in CI. expectToThrowFuelError (from @fuel-ts/errors/test-utils) asserts a specific FuelError code is thrown.

12. Error Code Reference

All SDK errors are FuelError instances with a stable string code from the ErrorCode enum (packages/errors/src/error-codes.ts). FuelError also carries metadata, rawError, and VERSIONS (the SDK/binary versions at throw time), and FuelError.parse() rehydrates a serialized error (rejecting unknown codes). Selected codes by domain:

Tip

Branch on error.code, never the message — messages are human-facing and may change; codes are part of the contract. The full enum is the canonical, exhaustive list.

13. Known Issues, Tech Debt & Roadmap

Drawn from the project's own issue tracker at analysis time:

These reflect the SDK's direction: smoother UTXO management (auto-consolidation), richer log handling, ESM-correct codegen, and package consolidation (hasher→crypto, script→program) to shrink the dependency graph.

14. Release & Distribution

Because every @fuel-ts/* package is published in lock-step and the umbrella fuels re-exports them, a consumer almost always depends on a single fuels version and gets a consistent set of sub-packages.

15. Quick Reference

Package dependency direction

fuels  →  account · contract · program · script · recipes   (high-level)
           │
           ▼
        abi-coder · transactions · address                   (encoding/protocol)
           │
           ▼
        math · crypto · hasher · merkle · utils · errors      (primitives)

CLI(fuels)  →  abi-typegen · @internal/forc · @internal/fuel-core

Key files for contributors

Operational commands

pnpm install && pnpm build:packages   # bootstrap + build
pnpm test:node                         # run node tests
pnpm lint                              # type + eslint + prettier
pnpm changeset                         # record a release note
npx fuels versions                     # check forc/fuel-core compatibility