biantris / fuels-ts

Fuel v2 TypeScript SDK

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

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:tests

This will run services:run, tests 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!

License

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