fuels-ts is a library for interacting with Fuel v2.

Table of contents

• SDK documentation
• Features
• Usage
  • Installation
  • Calling Contracts
  • Deploying Contracts
  • Generating Contract Types
• Contributing
  • Setup
  • Testing
• License

Features

• Deploy and call contracts
• Generate contract types with TypeChain
• Build and send transactions
• Encode/decode contract ABI
• Transfer coins
• Inspect contract storage
• Manage wallets
• Run scripts
• Query and subscribe to events

Usage

Installation

yarn add fuels
# or
npm add fuels

Calling Contracts

// typescript file
import { Provider, Contract } from "fuels";
import abi from "./abi.json";

const provider = new Provider("http://127.0.0.1:4000/graphql");

const contractId = "0x...";
const contract = new Contract(contractId, abi, provider);
const result = await contract.submit.foo("bar");

Deploying Contracts

// typescript file
import { Provider, Contract } from "fuels";
import bytecode from "./bytecode.bin";

const provider = new Provider("http://127.0.0.1:4000/graphql");

const { contractId } = await provider.submitContract(bytecode);

Generating Contract Types

For defined Sway types, we offer a Typechain target to generate types from an ABI file.

For Sway types, the mapping is as follows to Typescript types:

Sway type	Typescript type
u8/64	number or BigNumber
b256	'0x'-prefixed-string or Uint8Array
str[]	'0x'-prefixed-string or Uint8Array
struct	Object
enum	Partial
tuple	Array

# console
yarn add -D typechain typechain-target-fuels
yarn exec typechain --target=fuels --out-dir=types abi.json

// typescript file
import { Provider } from "fuels";
import { MyContract__factory } from "./types";

const provider = new Provider("http://127.0.0.1:4000/graphql");

const contractId = "0x...";
const contract = MyContract__factory.connect(contractId, provider);

Contributing

Setup

git clone [email protected]:FuelLabs/fuels-ts.git
cd fuels-ts
pnpm install
pnpm build

Testing

In order to run tests locally, you need fuel-core running as a docker container. To do that you can run these commands in your terminal:

pnpm services:run

And then run tests in another terminal tab:

# run all tests
pnpm test
# run tests and get coverage
pnpm test:coverage
# run tests for a specific package
pnpm --filter @fuel-ts/contract run test

Or if you want to run docker and all tests serially you can do:

pnpm ci:test

This will run services:run, test and then services:clean

Some times if you're running your tests locally using services:run in a separated terminal, maybe you need to run services:clean after tests to clean docker containers and volumes. Because this can break your tests sometimes!

Build and watch all packages

If you want to work locally using realtime builds, open in one terminal tab build in watch mode on all packages from the root directory:

pnpm build:watch

This command you run tsup --watch on all packages using Turborepo

Using linked packages

This will link all packages inside our monorepo in your global pnpm store, enabling you to us fuels-ts packages via links in your local projects.

On fuels-ts root directory

pnpm -r exec pnpm link --global --dir ./

You can use build watch.

On your project root directory

pnpm link --global fuels

Or for specfic packages just use pnpm link @fuel-ts/<pkg-name>, ex;

pnpm link --global @fuel-ts/wallet

Troubleshooting

If you're linking for the first time, you might need:

  pnpm setup

If it still have problems, you might need to setup again (As pnpm releases new version, the global folder structure may change)

  pnpm setup

Updating Forc version

The following script will upgrade Forc to the latest version on GitHub, remove all lockfiles so the latest stdlib can be used, and rebuild all projects:

pnpm forc:update

After this you should run tests and fix any incompatibilities.

License

The primary license for this repo is Apache 2.0, see LICENSE.

FAQ

Why is the prefix fuels and not fuel?

In order to make the SDK for Fuel feel familiar with those coming from the ethers.js ecosystem, this project opted for an s at the end. The fuels-* family of SDKs is inspired by The Ethers Project.